Invoke security

Forst invoke is a local process boundary. It is designed for a Node application and its local Forst server. Do not expose the invoke listener directly to the public network.

​

Default protections

On Unix, the invoke server listens on a mode 0600 Unix domain socket at .forst/invoke.sock by default. Windows and FORST_INVOKE_TRANSPORT=tcp use HTTP over loopback TCP instead. The server also checks the request Host header, requires JSON for POST /invoke, limits concurrent invoke work, and returns sanitized errors. HMAC challenge-response auth is on by default. Set FORST_INVOKE_AUTH=off only for local debugging. The server and Node clients log a startup warning every time auth is disabled. When Forst writes .forst/invoke.ready, it uses mode 0600. The file contains server metadata such as the URL, socket path, and auth generation. It does not contain the token.

​

Local transports

​

Authentication flow

Invoke RPC requests use a single-use challenge and an HMAC proof. The client first requests GET /invoke/challenge. It then sends the nonce, current generation, and an HMAC-SHA256 proof on the RPC request. The proof binds the protocol version, generation, and nonce. A replayed nonce, wrong generation, malformed proof, or proof from another token is rejected. The server applies an exponential backoff for repeated failures from the same peer. The secret is a 32-byte token. Connect mode delivers it through the FORST_INVOKE_TOKEN environment variable (base64url). The server sets this on the forst dev process when it starts. Worker processes that attach to an existing dev server must inherit FORST_INVOKE_TOKEN from the parent or receive it explicitly. In sidecar spawn mode, the child sends the secret through an inherited FORST_INVOKE_AUTH_FD file descriptor instead. This keeps the secret out of the ready file and avoids writing it to disk. When node.hostMode is enabled, the Node app process (the host) may start before the embedded invoke server inside the compiled Go program is ready. The forst dev parent process opens a pipe, passes the read end into the Node host as an inherited file descriptor (an open pipe handle the child receives at startup), and relays auth lines from the Go program’s FORST_INVOKE_AUTH_FD write end to the host’s FORST_INVOKE_AUTH_RECV_FD read end. That way the host never reads a token file. .forst/invoke.ready includes tokenDelivery (env or handoff) so clients know which channel to use. In a Node host process, call prepareInvokeConnect() from @forst/cli/invoke at startup. It sets connect-mode env and listens on FORST_INVOKE_AUTH_RECV_FD. Use getInvokeAuthHandoff() with your generated client’s resolveAuth option when auth arrives over the pipe.

​

Reserved request headers

The client owns these headers:

• X-Forst-Invoke-Nonce
• X-Forst-Invoke-Generation
• X-Forst-Invoke-Proof
• X-Forst-Invoke-Token

Forst removes caller-provided values for these names before it merges default or per-request headers. This prevents application configuration from replacing the authenticated proof. You may still send application headers such as Authorization, X-Request-Id, and X-Tenant-Id.

​

TLS and the local threat model

TLS is intentionally not used for the local invoke transport. A mode-0600 Unix socket plus same-user peer checks and proof authentication covers the normal local development threat model. Loopback TCP still uses proof authentication. Revisit TLS if invoke must bind beyond localhost or a deployment requires encryption on loopback traffic.

​

Test-only escape hatch

Set FORST_INVOKE_AUTH=off only for isolated tests or controlled CI fixtures. It disables proof verification. The invoke server and Node transport log a warning on startup whenever auth is off. Do not set it in development or production application environments.

​

Related