# wasmforge Host API Contract

This document is the source of truth for `env.*` imports exposed to WASM.
Adding a new export requires adding a row here with rationale, classified
under one of categories A/B/C below. Category D ("Unjustified") is a CI failure.

The contract is CI-enforced by `internal/hostmod/contract_test.go`.

## Categories

- **A. Foundation primitive** — generic dispatch / memory / handle operations
  that nothing higher up can replicate. Examples: `mod_invoke`, `mem_alloc`,
  `mod_hread`. WASM cannot do these.
- **B. OS proxy** — direct syscall passthrough where the OS API has no
  equivalent representation inside the WASM sandbox. Examples: `sock_open`,
  `fd_open`, `os_hostname`, `darwin_call`. WASM cannot reach the kernel
  on its own.
- **C. Atomic composite (host-thread-affinity)** — a multi-step Win32 dance
  that legitimately needs host thread/process state (SYSTEM impersonation,
  COM STA-thread affinity, or both). Examples: `lsa_kerbop`. Cannot be
  replicated by `wf_call` chains in WASM.
- **D. Unjustified** — should be migrated to WASM via `wf_call`. CI fails
  if anything in this category lands.

---

## NativeAOT-WASI active surface (Rubeus / Seatbelt path)

Functions registered in `internal/hostmod/nativeaot.go` and exercised by
the Rubeus/Seatbelt parity test suite. Probe-verified against Rubeus.wasm.

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_syscalln | mod_invoke | A | Generic wf_call dispatch — foundation |
| win32_load_library | mod_load | A | DLL loading — foundation |
| win32_get_proc_address | mod_resolve | A | Symbol resolution — foundation |
| win32_host_read_bytes | mod_hread | A | Cross-boundary memory read — foundation |
| win32_register_funcptr | mod_regptr | A | Callback infrastructure — foundation |
| win32_lsa_kerberos_op | lsa_kerbop | C | SYSTEM impersonation + COM STA + LSA on same thread; cannot reproduce via wf_call chains in WASM |
| win32_crypto_op | xc_op | C | Generic crypto dispatcher. Runs the iteration loop of MS-PBKDF2 (Windows DPAPI master-key derivation), RFC PBKDF2, HMAC, plain hash, and AES-CBC host-side via BCrypt. The in-bridge alternative (looping `wf_call` per HMAC) costs ~32k wf_calls per master key (~40 min); the dispatcher is one wf_call per derivation. Designed as the **landing pad for future complex/looped crypto** so we don't grow the host export surface per new primitive. Opcode catalog: sha1/sha256/sha512, hmac1/256/512, pbkdf2_1/256/512, mspbkdf2_1/mspbkdf2_512, aescbcdec |
| win32_io_op | xi_op | B | Generic IO dispatcher. Sibling to xc_op for filesystem operations. Replaces the 6-8 wf_call CreateFile+ReadFile+CloseHandle chain in `fs_read_all` (~46ms per file) with a single host trip via Go's `os.ReadFile` (~<1ms per file). Opcode catalog: read, stat, list. Same wire format as xc_op (opcode string + length-prefixed packed byte fields). Future filesystem ops add opcodes, not exports. |
| win32_reg_search | reg_search | C | Host-side BFS walker for SharpDPAPI's `search` verb. Walks the supplied hive enumerating every value and matches against SharpDPAPI's DPAPI provider GUID + 4 base64/hex string signatures. Doing this in WASM costs ~4 wf_calls per visited key × ~500K HKLM keys → exceeds the lab's 5-minute exec timeout. Host-side BFS uses parent-handle propagation at native Win32 speed (`RegOpenKeyEx(parent, child, …)` — no full-path lookup per key) and completes both hives in seconds. Wire format: NUL-separated UTF-8 records, first record is the "Root:" line matching native FindRegistryBlobs |
| win32_dpapi_backupkey | dpapi_bkey | C | Host-side DsGetDcNameW + LsaOpenPolicy + 2× LsaRetrievePrivateData chain for SharpDPAPI's `backupkey` verb. DsGetDcName writes a `DOMAIN_CONTROLLER_INFOW*` (host pointer) to its OUT param; LsaRetrievePrivateData writes a `LSA_UNICODE_STRING*` (host pointer) whose Buffer field is also a host pointer. wasm32 C# would truncate both via Marshal.PtrToStructure on a 32-bit IntPtr → OOB trap. Single wf_call returns the materialised DC FQDN + 16-byte preferred-key GUID + raw key blob; C# assembles the kirbi (PVK wrapping + base64). Wire format: packed (status u32, dc_name length-prefixed, guid length-prefixed, key_blob length-prefixed) |
| win32_x509_match | x509_match | C | Host-side X.509 store walker for SharpDPAPI's `machinetriage` cert-matching path. Native walks `CurrentUser\MY` + `LocalMachine\MY` then for each cert calls `cert.PublicKey.Key.ToXmlString` (System.Security.Cryptography PNS on NativeAOT-WASI) to compare against a private-key XML derived from the decrypted blob. The bridge takes raw big-endian RSA modulus bytes (extracted by manual byte slicing on the C# side — no crypto calls), walks both stores via `CertEnumCertificatesInStore`, parses each cert's SubjectPublicKeyInfo via `crypto/x509`, compares moduli, and on match returns packed metadata (thumbprint, issuer, subject, dates, EKUs, cert DER) for C# to format the multi-line output + PEM-wrap. Wire format: status u32, then on match 7 length-prefixed records |
| win32_virtual_alloc | mem_alloc | A | Host memory allocation — foundation |
| win32_virtual_free | mem_free | A | Host memory free — foundation |
| win32_hmem_read | mem_read | A | Cross-boundary memory read — foundation |
| win32_hmem_write | mem_write | A | Cross-boundary memory write — foundation |
| win32_hmem_write32 | mem_write32 | A | Cross-boundary u32 write — foundation |
| win32_hmem_write64 | mem_write64 | A | Cross-boundary u64 write — foundation |
| win32_hmem_addr | mem_addr | A | Host VA retrieval — foundation |
| win32_wmi_query_restricted | wmi_query_r | C | Atomic WMI query for restricted namespaces (root\SecurityCenter2, ROOT\Subscription) that fire IUnknown auth callbacks during ConnectServer. The host implementation calls CoSetProxyBlanket and runs the entire IWbemServices chain on a COM STA thread so callbacks never cross the WASM FFI boundary. Seatbelt AntiVirus and WMIEventConsumer parity require this; cannot trivially replicate in WASM-side wf_call chains |

---

## Foundation primitives — socket / networking (all targets)

Registered in `internal/hostmod/module.go`, `tcp.go`, `udp.go`, `io.go`,
`dns.go`, `sockopt.go`. Used by all WASM targets (Go and NativeAOT alike).

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| sock_open | fd_open | B | Socket creation — WASM has no kernel socket syscall |
| sock_bind | fd_bind | B | Bind to local address |
| sock_listen | fd_listen | B | Mark socket as listening |
| sock_connect | fd_connect | B | TCP/UDP connect |
| sock_accept | fd_accept | B | Accept incoming connection |
| sock_read | fd_read2 | B | Non-blocking socket read |
| sock_write | fd_write2 | B | Non-blocking socket write |
| sock_close | fd_close2 | B | Socket close |
| sock_sendto | fd_sendto | B | UDP datagrams — sendto |
| sock_recvfrom | fd_recvfrom | B | UDP datagrams — recvfrom |
| sock_shutdown | fd_shutdown | B | Graceful socket shutdown |
| sock_setsockopt | fd_setsockopt | B | Socket option set |
| sock_getsockopt | fd_getsockopt | B | Socket option get |
| sock_getpeername | fd_getpeername | B | Remote address query |
| sock_getsockname | fd_getsockname | B | Local address query |
| sock_getaddrinfo | addr_resolve | B | DNS resolution — WASM has no getaddrinfo |

---

## Foundation primitives — raw sockets (requires --raw-sockets)

Registered in `internal/hostmod/raw.go`.

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| raw_sock_open | fd_raw_open | B | SOCK_RAW creation — requires CAP_NET_RAW, not available in WASM |
| raw_sock_send | fd_raw_send | B | Raw packet send |
| raw_sock_recv | fd_raw_recv | B | Raw packet receive |

---

## Foundation primitives — OS proxies (all targets)

Registered in `internal/hostmod/os_host.go` and `os_exec.go`.

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| os_hostname | sys_hostname | B | gethostname — not available in wasip1 |
| os_getwd | sys_getwd | B | getcwd — WASI path mapping doesn't expose host cwd |
| os_chdir | sys_chdir | B | chdir — host working directory change |
| os_user_current | sys_user | B | getpwuid / GetCurrentUser — not available in WASM |
| os_getpid | sys_pid | B | getpid — WASI has no process ID concept |
| os_process_list | sys_procs | B | Process enumeration — OS-specific, no WASM equivalent |
| os_exec | proc_exec | B | CreateProcess/exec with output capture |
| os_start_process | proc_start | B | Non-blocking process start |
| os_wait4 | proc_wait | B | Wait for child process completion |
| net_interfaces | sys_netifs | B | Network interface enumeration — no WASM equivalent |

---

## Foundation primitives — pipes (all targets)

Registered in `internal/hostmod/pipe.go`.

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| os_pipe | fd_pipe | B | Host pipe pair creation — os.Pipe() returns ENOSYS on wasip1 |
| pipe_read | fd_pread | B | Read from host pipe |
| pipe_write | fd_pwrite | B | Write to host pipe |
| pipe_close | fd_pclose | B | Close host pipe |

---

## --win32-apis Go-side surface (non-NativeAOT)

Functions used by `wasmforge build --win32-apis` with Go source input
(Sliver, goffloader, etc.). Registered via
`internal/hostmod/win32.go`. Not exercised by the Rubeus/Seatbelt parity
tests, but kept for the broader product surface.

### Dispatch / module loading

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_available | mod_available | B | Feature-gate check — thin flag check |
| win32_load_library | mod_load | A | LoadLibraryA — also registered by nativeaot.go |
| win32_get_proc_address | mod_resolve | A | GetProcAddress — also registered by nativeaot.go |
| win32_call | mod_call | B | Call proc (≤6 uint32 args) — thin DLL wrapper for Go programs |
| win32_syscalln | mod_invoke | A | SyscallN (≤15 i64 args) — also registered by nativeaot.go |
| win32_free_library | mod_free | B | FreeLibrary |
| win32_close_handle | mod_close | B | CloseHandle (generic) |
| win32_proc_addr | mod_addr | A | Native address of loaded proc — foundation |
| win32_proc_from_hmem | mem_proc | B | Proc from host memory handle — goffloader pattern |
| win32_register_funcptr | mod_regptr | A | Callback registration — also registered by nativeaot.go |
| win32_host_read_bytes | mod_hread | A | Host memory read — also registered by nativeaot.go |
| win32_new_callback | ext_callback | B | NewCallback (function pointer thunk for Go closures) |

### Registry

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_reg_open_key | win32_reg_open_key | B | RegOpenKeyExW — thin wrapper |
| win32_reg_close_key | win32_reg_close_key | B | RegCloseKey — thin wrapper |
| win32_reg_query_value | reg_query | B | RegQueryValueExW |
| win32_reg_set_value | reg_set | B | RegSetValueExW |
| win32_reg_delete_value | reg_delete | B | RegDeleteValueW |
| win32_reg_enum_key | win32_reg_enum_key | B | RegEnumKeyExW — thin wrapper |

### Filesystem

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_create_file | fs_create | B | CreateFileW |
| win32_read_file | fs_read | B | ReadFile |
| win32_write_file | fs_write | B | WriteFile |
| win32_get_file_attrs | fs_getattr | B | GetFileAttributesW |
| win32_set_file_attrs | fs_setattr | B | SetFileAttributesW |
| win32_find_files | fs_findfiles | B | FindFirstFileW + FindNextFileW enumeration |

### Process

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_get_computer_name | sys_compname | B | GetComputerNameW |
| win32_create_process | proc_create | B | CreateProcessW |
| win32_open_process | proc_open | B | OpenProcess |
| win32_terminate_process | proc_term | B | TerminateProcess |

### Security / tokens

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_open_process_token | sec_opentoken | B | OpenProcessToken |
| win32_get_token_info | sec_tokeninfo | B | GetTokenInformation |
| win32_open_sc_manager | svc_open | B | OpenSCManagerW |
| win32_query_service_status | svc_status | B | QueryServiceStatus |

### Host memory (VirtualAlloc proxy for goffloader/COFF)

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_virtual_alloc | mem_alloc | A | VirtualAlloc on host — also registered by nativeaot.go |
| win32_virtual_protect | mem_protect | B | VirtualProtect — change host memory protection |
| win32_virtual_free | mem_free | A | VirtualFree — also registered by nativeaot.go |
| win32_hmem_write | mem_write | A | WASM→host memory copy — also registered by nativeaot.go |
| win32_hmem_read | mem_read | A | Host→WASM memory copy — also registered by nativeaot.go |
| win32_hmem_write32 | mem_write32 | A | u32 write at host offset — also registered by nativeaot.go |
| win32_hmem_write64 | mem_write64 | A | u64 write at host offset — also registered by nativeaot.go |
| win32_hmem_read32 | mem_read32 | B | u32 read from host offset |
| win32_hmem_read64 | mem_read64 | B | u64 read from host offset |
| win32_hmem_addr | mem_addr | A | Host VA retrieval — also registered by nativeaot.go |
| win32_wmi_query_restricted | wmi_query_r | C | Atomic WMI query for restricted namespaces (root\SecurityCenter2, ROOT\Subscription) that fire IUnknown auth callbacks during ConnectServer. The host implementation calls CoSetProxyBlanket and runs the entire IWbemServices chain on a COM STA thread so callbacks never cross the WASM FFI boundary. Seatbelt AntiVirus and WMIEventConsumer parity require this; cannot trivially replicate in WASM-side wf_call chains |

### Extension API (COFF/BOF callbacks)

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| win32_ext_get_func | ext_getfunc | A | Native address of extension callback — foundation for goffloader |
| win32_ext_read_output | ext_readout | B | Read accumulated extension output |
| win32_ext_reset_output | ext_resetout | B | Clear extension output buffer |

### Shadow memory (VirtualAlloc interception)

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| shadow_virtual_alloc | shm_alloc | A | Shadow VirtualAlloc — intercepts guest allocations for WASM pointer translation |
| shadow_virtual_protect | shm_protect | A | Shadow VirtualProtect — tracks protection changes in shadow map |
| shadow_virtual_free | shm_free | A | Shadow VirtualFree — removes allocation from shadow map |

---

## macOS framework bridge (auto-detected from GOOS=darwin)

Registered in `internal/hostmod/darwin.go`. Only functional on macOS hosts.

| Canonical (Go-side) | Anonymized (WASM import) | Category | Rationale |
|---|---|---|---|
| darwin_available | fw_available | B | Feature-gate check |
| darwin_load | fw_load | B | dlopen — load macOS framework or dylib |
| darwin_get_symbol | fw_sym | B | dlsym — get symbol address |
| darwin_call | fw_call | B | Call C function via assembly trampoline (SysV ABI) with WASM pointer translation |
| darwin_call_masked | fw_call_m | B | Call C function with bitmask-controlled pointer translation |
| darwin_call_raw | fw_call_raw | B | Call C function without pointer translation (remote process addresses) |
| darwin_mem_read | fw_mem_r | B | Read host memory into WASM linear memory |
| darwin_mem_write | fw_mem_w | B | Write WASM data to host memory |
| darwin_callback_create | fw_cb_create | A | Create native callback thunk for WASM closure — foundation for macOS delegate patterns |
| darwin_callback_addr | fw_cb_addr | A | Get native address of callback thunk |
| darwin_callback_wait | fw_cb_wait | A | Block until callback fires (cooperative yield) |
| darwin_callback_return | fw_cb_ret | A | Signal callback completion |
| darwin_callback_free | fw_cb_free | A | Release callback thunk |
| darwin_read_cstring | fw_cstr_r | B | Read null-terminated C string from host memory into WASM |
| darwin_block_create | fw_blk_create | A | Create Objective-C Block literal on host — foundation for ObjC API patterns |
| darwin_block_release | fw_blk_release | A | Release Objective-C Block |
| darwin_block_addr | fw_blk_addr | A | Get native address of Block literal |

---

## Retired / out-of-scope re-migration candidates

These functions appeared in nativeaot.go's earlier registration but were
removed because the C# side migrated to WASM-side wf_call chains:

| Former canonical | Former anonymized | Removed in | Notes |
|---|---|---|---|
| win32_wmi_query | wmi_query | Phase B | WASM-side stub |
| win32_wmi_method | wmi_method | Phase B | WASM-side stub |
| win32_get_sddl | (none) | Phase B | WASM-side via wf_call |
| win32_enum_user_rights | (none) | Phase B | WASM-side stub |
| win32_enum_rpc_endpoints | (none) | Phase B | WASM-side stub |
| win32_enum_network_adapters | (none) | Phase B | WASM-side via wf_call |
| win32_get_file_version_info | (none) | Phase B | WASM-side via wf_call |
| win32_enum_reg_values | (none) | Phase B | WASM-side via wf_call (advapi32) |
| win32_parse_sddl_acl | (none) | Phase B | WASM-side passthrough |
| win32_reg_enum_key (nativeaot path) | (none) | Phase B | WASM-side via wf_call |

If a future feature exercises any of these, the migration follows the Phase 2
pattern: write the WASM-side pinvoke_env_ext.c replacement, remove the
`import_module` attribute in `wf_bridge.h`, retire the Go-side Export.