{"_id":"x-agent-trust","name":"x-agent-trust","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"x-agent-trust","version":"1.0.0","description":"Reference implementation of the x-agent-trust signing scheme (ECDSA P-256) registered in the OpenAPI Extensions Registry and specified in IETF draft-sharif-agent-payment-trust.","main":"src/index.js","scripts":{"test":"node test/sign.test.js"},"keywords":["x-agent-trust","agent-signature","ecdsa","p-256","es256","openapi-extension","ietf","agent-identity","agent-payments","mcp","mcps","agentpass","signing","reference-implementation"],"author":{"name":"CyberSecAI Ltd"},"license":"Apache-2.0","homepage":"https://spec.openapis.org/registry/extension/x-agent-trust.html","repository":{"type":"git","url":"git+https://github.com/cybersecai-uk/x-agent-trust-reference.git"},"bugs":{"url":"https://github.com/cybersecai-uk/x-agent-trust-reference/issues"},"engines":{"node":">=18.0.0"},"dependencies":{},"devDependencies":{},"_id":"x-agent-trust@1.0.0","gitHead":"8dc42a5804906dc61574719274977c9e6f5f24a3","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-1kPRhepgQ67AlQu8SnJiY7gwrt2SJtrewZkEDjbtog/PngwKL2qitep9wEIyvh3KKNd9wE+4NT5znUCjaiswXw==","shasum":"9abed3cfe0d1b59d340f67fc4176e7c6980d0952","tarball":"https://registry.npmjs.org/x-agent-trust/-/x-agent-trust-1.0.0.tgz","fileCount":5,"unpackedSize":25214,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDI0WAo5FQ+VsFFuxrSpf4AaOegUmrJKpv8zdVkbe6iQQIgKNvPnWN4mB1WUQdvg2lzRbrXETzVfC2M9re1ydGtJHE="}]},"_npmUser":{"name":"proofxhq","email":"contact@proofx.co.uk"},"directories":{},"maintainers":[{"name":"proofxhq","email":"contact@proofx.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/x-agent-trust_1.0.0_1776195981175_0.7102274112418878"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-14T19:46:21.096Z","1.0.0":"2026-04-14T19:46:21.328Z","modified":"2026-04-14T19:46:21.634Z"},"maintainers":[{"name":"proofxhq","email":"contact@proofx.co.uk"}],"description":"Reference implementation of the x-agent-trust signing scheme (ECDSA P-256) registered in the OpenAPI Extensions Registry and specified in IETF draft-sharif-agent-payment-trust.","homepage":"https://spec.openapis.org/registry/extension/x-agent-trust.html","keywords":["x-agent-trust","agent-signature","ecdsa","p-256","es256","openapi-extension","ietf","agent-identity","agent-payments","mcp","mcps","agentpass","signing","reference-implementation"],"repository":{"type":"git","url":"git+https://github.com/cybersecai-uk/x-agent-trust-reference.git"},"author":{"name":"CyberSecAI Ltd"},"bugs":{"url":"https://github.com/cybersecai-uk/x-agent-trust-reference/issues"},"license":"Apache-2.0","readme":"# x-agent-trust — reference implementation\n\nCanonical ECDSA P-256 signing and verification for the **`x-agent-trust`** OpenAPI extension and the IETF draft **`draft-sharif-agent-payment-trust`**.\n\nThis is a **reference implementation** of the signing primitive only. It has zero dependencies, zero network calls, and exposes a tiny surface. Use it to produce or verify `Agent-Signature` headers in any language ecosystem that speaks ECDSA P-256 (which is all of them).\n\n> **Standards status**\n> - ✅ `x-agent-trust` is registered in the [OpenAPI Extensions Registry](https://spec.openapis.org/registry/extension/x-agent-trust.html).\n> - ✅ IETF Internet-Draft: [`draft-sharif-agent-payment-trust`](https://datatracker.ietf.org/doc/draft-sharif-agent-payment-trust/)\n> - ✅ Companion draft (transport-layer): [`draft-sharif-mcps-secure-mcp`](https://datatracker.ietf.org/doc/draft-sharif-mcps-secure-mcp/)\n\n## The scheme in one paragraph\n\nEvery request carries an `Agent-Signature` header. The signature is **ECDSA P-256** over a canonical string:\n\n```\n<METHOD> <path>\\n<unix-ts>\\n<sha256-hex(body)>\n```\n\nHeader format:\n\n```\nAgent-Signature: keyid=\"<agent-id>\",alg=\"ES256\",ts=\"<unix>\",sig=\"<base64>\"\n```\n\nServers verify the signature, check the timestamp is within a ±300-second clock-skew window, and reject otherwise. That's the whole primitive.\n\n## Install\n\n```bash\nnpm install x-agent-trust\n```\n\n## Quick start\n\n### Sign a request (client side)\n\n```js\nconst { generateKeyPair, signRequest } = require('x-agent-trust');\n\nconst { privateKey, publicKey } = generateKeyPair();\n\nconst body = JSON.stringify({ to: 'acme', amount: 2500, currency: 'USD' });\nconst { header } = signRequest({\n  method: 'POST',\n  path: '/api/payments',\n  body,\n  keyid: 'my-agent-001',\n  privateKeyPem: privateKey\n});\n\n// Send:\n//   POST /api/payments\n//   Agent-Signature: keyid=\"my-agent-001\",alg=\"ES256\",ts=\"...\",sig=\"...\"\n//   Content-Type: application/json\n//   <body>\n```\n\n### Verify a request (server side)\n\n```js\nconst { verifyRequest } = require('x-agent-trust');\n\nconst result = verifyRequest({\n  headerVal: req.headers['agent-signature'],\n  method: req.method,\n  path: req.url,\n  body: rawRequestBody,\n  publicKeyPem: lookUpPublicKeyFor(parsedKeyId)\n});\n\nif (!result.valid) {\n  return res.status(401).json({ error: result.error });\n}\n// result.keyid, result.alg, result.ts are trustworthy.\n```\n\n## API\n\n| Function | Purpose |\n|---|---|\n| `generateKeyPair()` | Fresh P-256 keypair as PEM strings. |\n| `signRequest(opts)` | Produce `Agent-Signature` header + components. |\n| `verifyRequest(opts)` | Verify a signed request; enforces clock skew and algorithm. |\n| `buildSigningString(method, path, ts, body)` | Low-level canonical string builder. |\n| `parseSignatureHeader(header)` | Structured parse of the header into its fields. |\n\nFull type definitions: see `src/index.js`.\n\n## Running the tests\n\n```bash\nnode test/sign.test.js\n```\n\n20+ tests covering keypair generation, canonical signing-string shape, round-trip verification, tamper detection (body/path/method), clock-skew enforcement, algorithm enforcement, malformed header rejection.\n\n## What this library is NOT\n\nThis repo contains only the **signing primitive**. It does not include:\n\n- Trust scoring (L0–L4 agent reputation)\n- Sanctions screening (OFAC / UK HMT)\n- AML checks\n- Payment rail adapters (x402, Stripe, AP2, ACP, MPP, Mastercard Agent Pay, Visa TAP, L402)\n- Audit / hash-chain storage\n- Key management / CA / revocation\n\nThose are the job of the full **[AgentPass SDK](https://agentpass.co.uk/rails)** — the commercial library that layers trust, compliance, and multi-rail payment orchestration on top of this signing primitive.\n\n| Use case | Library |\n|---|---|\n| I need to sign/verify an Agent-Signature header | **This repo** (Apache 2.0) |\n| I need trust scoring, sanctions, AML, and rail adapters | [AgentPass SDK](https://agentpass.co.uk/rails) (BSL 1.1) |\n| I need MCP transport boundary security | [MCPS](https://mcpsaas.co.uk) (BSL 1.1) |\n\n## Why this exists\n\nTo make the `x-agent-trust` signing scheme easy to adopt in any language and any stack, with no commercial dependency. Fork it, port it, vendor it — that's the point. If the primitive is everywhere, the ecosystem converges on one way to prove an agent authored a request.\n\nIf you're building a production agent-payment flow you almost certainly want the commercial SDK — `signRequest()` is the easy bit; the hard bits are sanctions, trust, rails, audit, and compliance.\n\n## Licence\n\nApache License, Version 2.0. See [`LICENSE`](LICENSE).\n\n## Related work\n\n- OpenAPI Extensions Registry entry: https://spec.openapis.org/registry/extension/x-agent-trust.html\n- IETF Internet-Draft (payments): https://datatracker.ietf.org/doc/draft-sharif-agent-payment-trust/\n- IETF Internet-Draft (MCP transport): https://datatracker.ietf.org/doc/draft-sharif-mcps-secure-mcp/\n- OWASP MCP Security Cheat Sheet Section 7 (message integrity and replay protection): https://cheatsheetseries.owasp.org/cheatsheets/MCP_Security_Cheat_Sheet.html\n- OWASP MCP Top 10 (recommended controls): https://owasp.org/www-project-mcp-top-10/\n- AgentPass commercial SDK: https://agentpass.co.uk/rails\n\n## Maintainer\n\nRaza Sharif, FBCS, CISSP, CSSLP. Published author, *Breach 20/20*.\nCyberSecAI Ltd — contact@agentsign.dev\n","readmeFilename":"README.md","_rev":"1-f0654b2c83bce951ec3defd01998c30b"}