a2spa

Helper-only Node package for building A2SPA request payloads.

• Canonicalizes payloads to match the Python verifier for supported JSON values.
• Computes hash.
• Signs RSA/SHA-256 requests with Node crypto.
• Builds policy-relevant input fields and state-continuity claims.
• Provides isAuthorizedResult / requireAuthorizedResult helpers so HTTP 200 refer_hold responses are not mistaken for authorization.
• A2SPA 2.1 deployments still need target-side enforcement at the protected target, trusted gateway, service, or executor; a caller-side helper result is not enough if another route can commit the same consequence.
• Does not fake ML-DSA signing; use the Python payload helpers or a vetted Node PQ dependency for a2spa.pq.mldsa.v1 signing.
• For cross-language stability, send decimal amounts as strings. The Node helper accepts safe integer JSON numbers and rejects decimals instead of producing mismatched signatures.

Install

npm install a2spa

Basic Usage

const fs = require("node:fs");
const { buildPayloadFields, buildSignedRequest, policyInput } = require("a2spa");

const privateKeyPem = fs.readFileSync("sender.priv.pem", "utf8");

const payload = buildPayloadFields({
  agentId: "user-123_sender",
  targetAgentId: "user-123_receiver",
  input: policyInput({ action: "deliver", workflowScope: "messages:deliver" }),
});

const requestBody = buildSignedRequest(payload, privateKeyPem);

Send requestBody to POST /api/verify_payload with your account API key in the x-api-key header.

Signed Bytes

Current helper compatibility signs Python-compatible JSON bytes. Do not reimplement canonicalization unless your bytes match canonicalizeA2spaPayload(...) exactly.

Private keys must stay in a secret manager, server environment, or deployment secret. Do not put private keys in browser code.