Docs · NukezAgent

NukezAgent

Signing bridge

Overview Signing bridge Framework adapters Examples

Request and envelope signatures

NukezAgent can interpret storage tasks and prepare gateway operations, but owner identity and operation approval remain client-controlled. This page defines the exact boundary adapters must preserve.

request signature

Authenticates one private HTTP request from the owner identity.

envelope signature

Authorizes a specific provision, write, read, or list operation.

signing_needed

Signals that the hosted service needs local owner approval to continue.

Signing model

Request auth is not storage authorization

Treat request signatures and envelope signatures as two different controls.

text

Request signature:- Header-level auth on private HTTP calls- Proves owner identity- Binds method, path, nonce, timestamp, body hash- Prevents replay and body tampering Envelope signature:- Returned only when an operation needs owner authorization- Signs a concrete storage envelope- Authorizes provision, write, list, or read scopes- Submitted back with signing_request_id

Code notes

NukezAgent uses request signatures for caller authentication and envelope signatures for operation authorization. The two signatures protect different parts of the flow and should be implemented separately.

A request signature does not grant the agent durable key access. It authorizes one HTTP request.

Request auth

Canonical request message

Build this message exactly before attaching the X-Nukez request headers.

text

nukez-request:v1method=<HTTP_METHOD>path=<PATH_WITH_QUERY>identity=<PUBKEY_OR_ADDRESS>nonce=<32_BYTE_RANDOM_HEX>timestamp=<UNIX_SECONDS>body_sha256=<SHA256_HEX_OF_BODY> Headers:X-Nukez-Identity: <PUBKEY_OR_ADDRESS>X-Nukez-Nonce: <32_BYTE_RANDOM_HEX>X-Nukez-Timestamp: <UNIX_SECONDS>X-Nukez-Signature: <SIGNATURE>

Code notes

The canonical request message is newline-joined text with no trailing newline. The body hash is the SHA-256 hex digest of the request body, or the empty-body hash when there is no body.

The server accepts request timestamps within plus or minus 300 seconds and rejects replayed nonces.

Boundary

Public routes versus owner routes

Keep discovery and quote routes open; sign everything that acts on owner state.

text

Unsigned:GET  /healthGET  /v1/cardGET  /.well-known/*GET  /v1/service/requestPOST /v1/provision/challengePOST /v1/provision/verify Signed:POST /v1/service/confirmGET  /v1/statusPOST /v1/delegateGET  /v1/service/expand?units=NPOST /v1/service/expand/confirmGET  /v1/portal/filesGET  /v1/portal/ops-logGET  /v1/portal/usage

Code notes

Only discovery, health, and initial provisioning helpers are public. Owner-scoped status, service confirmation, delegate, portal, expansion, and audit-style reads require request signatures.

The X402-TX header proves payment execution during confirm. It does not replace the request signature.

Envelope signing

Complete the bridge loop

When the agent returns signing_needed, sign the returned envelopes outside the service.

python

def sign_envelopes(envelopes: list[dict]) -> list[str]:    out = []    for item in envelopes:        payload = item.get("envelope_json")        if payload is None:            payload = json.dumps(item["envelope"], separators=(",", ":"), sort_keys=True)        sig = base58.b58encode(_sk.sign(payload.encode()).signature).decode()        out.append(sig)    return out def complete_if_signing(result: dict) -> dict:    while result.get("status") == "signing_needed":        result = agent_post("/v1/delegate", {            "signing_request_id": result["signing_request_id"],            "signatures": sign_envelopes(result["envelopes"]),        })    return result

Code notes

The hosted agent can construct envelopes for writes, but it cannot sign them. The client signs each returned payload and posts the signatures back with the signing_request_id.

This loop belongs in the local app, CLI, wallet bridge, passkey bridge, or adapter helper; it should not be hidden in model prompt text.

Validation

Failure modes to preserve

These are the request-auth tests that keep retries and adapter wrappers honest.

text

Expected failures:- Missing request headers -> 400 or 401- Expired timestamp -> 401- Replayed nonce -> first request may pass, second fails- Tampered body after signing -> 401- Signature from a different public key -> 401 Expected response hygiene:- Verification summaries stay concise- Evidence lives in structured fields- token_usage and tool_calls_made are opt-in metrics

Code notes

The usage guide and notebook exercise the important failure modes. These checks are what make the bridge viable for agent runtimes that may retry, redact, or transform requests.

These failures should be visible in adapter tests, not only in the standalone notebook.

§ next

Run

NukezAgent

Signing bridge

Request and envelope signatures

Examples

Adapters

NukezAgent