Plaintext to seal
Build the HTTP request the node should replay as JSON, then seal it tobox_pubkey
from /v1/resolve with a libsodium sealed box (crypto_box_seal, X25519).
Generate an ephemeral X25519 keypair for this request. Put the public key in
both the sealed plaintext and the POST body (the relay cannot read the envelope, so
it needs the metadata copy for claim challenges).
https://<hostname>/mcp (same headers as a live call). Prefer
body as the exact string of bytes you signed (Content-Digest must match). Keep
the sealed envelope ≤ 64 KiB (stricter than live MCP’s 256 KiB).
Signatures still use a ≤ 300 s validity window. The node validates them as of
queue receive time, not replay time, so overnight delivery works.
Enqueue
hostname is the full FQDN from resolve (e.g. n….relay.fau.run). reply_pubkey
is required and must match the key inside the sealed plaintext.
Response 202:
request_id yourself and write it, the reply private key, user, hostname,
and tool to your outstanding request store before enqueueing. This ordering
survives a process crash or an ambiguous POST timeout. Limits: 32 envelopes per
node, TTL 24 h, at-least-once. request_id makes retries idempotent.
Poll for a reply
reply_pubkey, the first response is 401:
challenge with your reply private key (crypto_box_seal_open). Retry:
wait=N long-polls while the request is pending. The relay caps N at 60
seconds. Omit it or use 0 for an immediate status check. A timeout still returns
204; reconnect and poll again with the same outstanding-request entry and claim flow.
Decrypt the
200 envelope with the same reply private key. The claim is consumed
when the answer is ready. Delete the outstanding-request entry only after the reply has been
successfully decrypted and durably handled.