@vorim/sdk 3.22.0 → 3.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +60 -6
  3. package/dist/httpSignatures.cjs +726 -0
  4. package/dist/httpSignatures.cjs.map +1 -0
  5. package/dist/httpSignatures.d.cts +131 -0
  6. package/dist/httpSignatures.d.ts +131 -0
  7. package/dist/httpSignatures.js +686 -0
  8. package/dist/httpSignatures.js.map +1 -0
  9. package/dist/index.cjs +764 -13
  10. package/dist/index.cjs.map +1 -1
  11. package/dist/index.d.cts +61 -1
  12. package/dist/index.d.ts +61 -1
  13. package/dist/index.js +757 -12
  14. package/dist/index.js.map +1 -1
  15. package/dist/integrations/anthropic.d.cts +1 -0
  16. package/dist/integrations/anthropic.d.ts +1 -0
  17. package/dist/integrations/ap2.d.cts +1 -0
  18. package/dist/integrations/ap2.d.ts +1 -0
  19. package/dist/integrations/aws-iam.d.cts +1 -0
  20. package/dist/integrations/aws-iam.d.ts +1 -0
  21. package/dist/integrations/bank-rails.d.cts +1 -0
  22. package/dist/integrations/bank-rails.d.ts +1 -0
  23. package/dist/integrations/circle.d.cts +1 -0
  24. package/dist/integrations/circle.d.ts +1 -0
  25. package/dist/integrations/cloudflare.d.cts +1 -0
  26. package/dist/integrations/cloudflare.d.ts +1 -0
  27. package/dist/integrations/coinbase-cdp.d.cts +1 -0
  28. package/dist/integrations/coinbase-cdp.d.ts +1 -0
  29. package/dist/integrations/commerce-agents.d.cts +1 -0
  30. package/dist/integrations/commerce-agents.d.ts +1 -0
  31. package/dist/integrations/crewai.d.cts +1 -0
  32. package/dist/integrations/crewai.d.ts +1 -0
  33. package/dist/integrations/entra.d.cts +1 -0
  34. package/dist/integrations/entra.d.ts +1 -0
  35. package/dist/integrations/fhir.d.cts +1 -0
  36. package/dist/integrations/fhir.d.ts +1 -0
  37. package/dist/integrations/grok.d.cts +1 -0
  38. package/dist/integrations/grok.d.ts +1 -0
  39. package/dist/integrations/guidewire.d.cts +1 -0
  40. package/dist/integrations/guidewire.d.ts +1 -0
  41. package/dist/integrations/hermes.d.cts +1 -0
  42. package/dist/integrations/hermes.d.ts +1 -0
  43. package/dist/integrations/jira.d.cts +1 -0
  44. package/dist/integrations/jira.d.ts +1 -0
  45. package/dist/integrations/langchain.d.cts +1 -0
  46. package/dist/integrations/langchain.d.ts +1 -0
  47. package/dist/integrations/langgraph.d.cts +1 -0
  48. package/dist/integrations/langgraph.d.ts +1 -0
  49. package/dist/integrations/legal.d.cts +1 -0
  50. package/dist/integrations/legal.d.ts +1 -0
  51. package/dist/integrations/life-sciences.d.cts +1 -0
  52. package/dist/integrations/life-sciences.d.ts +1 -0
  53. package/dist/integrations/linear.d.cts +1 -0
  54. package/dist/integrations/linear.d.ts +1 -0
  55. package/dist/integrations/lithic.d.cts +1 -0
  56. package/dist/integrations/lithic.d.ts +1 -0
  57. package/dist/integrations/llamaindex.d.cts +1 -0
  58. package/dist/integrations/llamaindex.d.ts +1 -0
  59. package/dist/integrations/marqeta.d.cts +1 -0
  60. package/dist/integrations/marqeta.d.ts +1 -0
  61. package/dist/integrations/modern-treasury.d.cts +1 -0
  62. package/dist/integrations/modern-treasury.d.ts +1 -0
  63. package/dist/integrations/muse.d.cts +1 -0
  64. package/dist/integrations/muse.d.ts +1 -0
  65. package/dist/integrations/nekuda.d.cts +1 -0
  66. package/dist/integrations/nekuda.d.ts +1 -0
  67. package/dist/integrations/okta.d.cts +1 -0
  68. package/dist/integrations/okta.d.ts +1 -0
  69. package/dist/integrations/openai.d.cts +1 -0
  70. package/dist/integrations/openai.d.ts +1 -0
  71. package/dist/integrations/openrouter.d.cts +1 -0
  72. package/dist/integrations/openrouter.d.ts +1 -0
  73. package/dist/integrations/paypal-agent.d.cts +1 -0
  74. package/dist/integrations/paypal-agent.d.ts +1 -0
  75. package/dist/integrations/perplexity.d.cts +1 -0
  76. package/dist/integrations/perplexity.d.ts +1 -0
  77. package/dist/integrations/plaid.d.cts +1 -0
  78. package/dist/integrations/plaid.d.ts +1 -0
  79. package/dist/integrations/ramp.d.cts +1 -0
  80. package/dist/integrations/ramp.d.ts +1 -0
  81. package/dist/integrations/shopify.d.cts +1 -0
  82. package/dist/integrations/shopify.d.ts +1 -0
  83. package/dist/integrations/skyfire.d.cts +1 -0
  84. package/dist/integrations/skyfire.d.ts +1 -0
  85. package/dist/integrations/stripe-acp.d.cts +1 -0
  86. package/dist/integrations/stripe-acp.d.ts +1 -0
  87. package/dist/integrations/stripe-issuing.d.cts +1 -0
  88. package/dist/integrations/stripe-issuing.d.ts +1 -0
  89. package/dist/integrations/truanon.d.cts +1 -0
  90. package/dist/integrations/truanon.d.ts +1 -0
  91. package/dist/integrations/typesafe.d.cts +1 -0
  92. package/dist/integrations/typesafe.d.ts +1 -0
  93. package/dist/integrations/ucp.d.cts +1 -0
  94. package/dist/integrations/ucp.d.ts +1 -0
  95. package/dist/integrations/vercel-ai.d.cts +1 -0
  96. package/dist/integrations/vercel-ai.d.ts +1 -0
  97. package/dist/integrations/x402.d.cts +1 -0
  98. package/dist/integrations/x402.d.ts +1 -0
  99. package/package.json +11 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog — @vorim/sdk
2
2
 
3
+ ## 3.23.0
4
+
5
+ ### Added
6
+
7
+ - **HTTP Message Signatures (RFC 9421) with Content-Digest (RFC 9530)**, as `@vorim/sdk/http-signatures` and from the package root. `signHttpRequest`, `verifyHttpRequest`, `createSignatureBase` and `contentDigest` sign and verify any request over the components you choose. Algorithms are `ed25519` and `ecdsa-p256-sha256` (raw r||s). The algorithm comes from the key, and a conflicting `alg` parameter fails verification. Verification checks `expires`, an optional max age, required components, and recomputes Content-Digest when the body is supplied. Passes the RFC 9421 Appendix B.2.6 Ed25519 vector. Uses Web Crypto and falls back to `node:crypto`.
8
+ - `vorim.signHttpRequest(agentId, request, options?)` signs with the agent's cached key (`keyid` = agent_id, `alg` = ed25519, `tag` = vorim) and throws `AGENT_KEY_NOT_LOADED` when no key is cached. `vorim.verifyHttpRequest(request, { label?, maxAgeSeconds? })` calls `POST /v1/http-signatures/verify` and returns the agent, org, status and trust score behind the signature. Parity with `sign_http_request` / `verify_http_request` in the Python SDK.
9
+
10
+ ## 3.22.1
11
+
12
+ ### Fixed
13
+
14
+ - `emit()` and `emitBatch()` return types now include the `events` array the API already returns (`{ ingested, events?: { event_id, digest? }[], rejected_invalid_signature?, replayed? }`), so `const { events } = await vorim.emit(...)` type-checks.
15
+ - README: quick start states the key scopes it needs (agents:read, agents:write, permissions:read, audit:read, audit:write), how to run it as an ES module, that public `verify()` returns no `active_scopes`, and that `register()` needs at least one scope.
16
+
3
17
  ## 3.20.0
4
18
 
5
19
  ### Added
package/README.md CHANGED
@@ -10,7 +10,7 @@ Register agents with cryptographic Ed25519 identities, enforce scoped permission
10
10
  [![Node](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)
11
11
  [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)]()
12
12
 
13
- > **[vorim.ai](https://vorim.ai)** — Create a free account and get your API key in 30 seconds.
13
+ > **API key**: create one in the Vorim dashboard under Settings, API keys. No account yet? Request access at [vorim.ai](https://vorim.ai).
14
14
  > **[Documentation](https://vorim.ai/docs)** — Full API reference, framework integrations, and examples.
15
15
  > **[Quick Start](https://vorim.ai/quickstart)** — Set up in under 5 minutes.
16
16
 
@@ -48,6 +48,10 @@ pnpm add @vorim/sdk
48
48
 
49
49
  ## Quick Start
50
50
 
51
+ The key for this quick start needs the `agents:read`, `agents:write`, `permissions:read`, `audit:read` and `audit:write` scopes. Scopes are independent, so `agents:write` does not include `agents:read`.
52
+
53
+ The example uses top-level `await`, so run it as ES module code. Save it as a `.mjs` file, set `"type": "module"` in your `package.json`, or run the `.ts` file with `npx tsx`.
54
+
51
55
  ```typescript
52
56
  import createVorim from "@vorim/sdk";
53
57
 
@@ -83,7 +87,9 @@ if (allowed) {
83
87
  // 4. Verify any agent's trust (public endpoint, no auth required)
84
88
  const trust = await vorim.verify(agent.agent_id);
85
89
  console.log(trust.trust_score); // 0–100
86
- console.log(trust.active_scopes); // ['agent:read', 'agent:execute']
90
+ // The public endpoint does not reveal scopes (active_scopes is always []).
91
+ // As the agent's owner, list them with your API key:
92
+ const permissions = await vorim.listPermissions(agent.agent_id);
87
93
  ```
88
94
 
89
95
  ---
@@ -334,8 +340,8 @@ trust.verified; // true
334
340
  trust.trust_score; // 82
335
341
  trust.status; // 'active'
336
342
  trust.owner.org_name; // 'Acme Corp'
337
- trust.active_scopes; // ['agent:read', 'agent:execute']
338
- trust.key_fingerprint; // 'a1b2c3d4...'
343
+ trust.active_scopes; // [] (not revealed publicly; owners use vorim.listPermissions(agentId))
344
+ trust.key_fingerprint; // '' (not revealed publicly)
339
345
  trust.revocation_status; // false
340
346
  ```
341
347
 
@@ -351,7 +357,7 @@ trust.revocation_status; // false
351
357
  From v3.1.0, the SDK signs every audit event at source with the agent's Ed25519 private key. No code change required — `register()` caches the key in memory and `emit()` adds the signature transparently.
352
358
 
353
359
  ```typescript
354
- const { agent } = await vorim.register({ name: "agent", capabilities: [], scopes: [] });
360
+ const { agent } = await vorim.register({ name: "agent", capabilities: [], scopes: ["agent:execute"] });
355
361
 
356
362
  // Auto-signed. The signature is attached before the request leaves the process.
357
363
  await vorim.emit({
@@ -383,6 +389,54 @@ const vorim = createVorim({ apiKey, autoSign: false });
383
389
 
384
390
  **Manual signing.** For payloads you sign yourself, `vorim.sign(payload, privateKeyPem)` returns an `ed25519:` prefixed signature. Any event with a pre-existing `signature` field is passed through unchanged.
385
391
 
392
+ ### HTTP Message Signatures (RFC 9421)
393
+
394
+ An agent can sign the HTTP requests it sends, so the service on the other end can check which agent made the call and that nobody changed it on the way. The signature follows RFC 9421 and goes in the `Signature-Input` and `Signature` headers. When the request has a body, the SDK adds an RFC 9530 `Content-Digest` header and puts it under the signature, which ties the body to it too.
395
+
396
+ Signing uses the key that `register()` or `useAgentKey()` cached for that agent. `keyid` is the agent_id, the algorithm is `ed25519`, and `tag` is `vorim`.
397
+
398
+ ```typescript
399
+ const body = JSON.stringify({ task: "summarise", doc_id: "d_91" });
400
+ const request = {
401
+ method: "POST",
402
+ url: "https://agent-b.example.com/tasks",
403
+ headers: { "content-type": "application/json" },
404
+ body,
405
+ };
406
+
407
+ const { headers } = await vorim.signHttpRequest(agent.agent_id, request);
408
+ await fetch(request.url, {
409
+ method: "POST",
410
+ headers: { ...request.headers, ...headers }, // Signature-Input, Signature, Content-Digest
411
+ body,
412
+ });
413
+ ```
414
+
415
+ On the receiving side, `verifyHttpRequest` sends the request to Vorim. Vorim looks up the signing agent's registered public key and refuses agents that are suspended or revoked. The result also carries the agent's org name, status and trust score. Pass the raw body if you want the digest checked; `content_digest_checked` tells you whether it was.
416
+
417
+ ```typescript
418
+ const result = await vorim.verifyHttpRequest(
419
+ { method: req.method, url: fullUrl, headers: req.headers, body: rawBody },
420
+ { maxAgeSeconds: 300 },
421
+ );
422
+ if (!result.valid) throw new Error(result.reason);
423
+ console.log(result.agent_id, result.trust_score);
424
+ ```
425
+
426
+ You can also verify locally with a public key you already hold, with no call to Vorim. The standalone module works in Node, browsers and Workers, and it also signs with ECDSA P-256 keys (`ecdsa-p256-sha256`), which is the curve iOS Secure Enclave and Android StrongBox keys use.
427
+
428
+ ```typescript
429
+ import { verifyHttpRequest, signHttpRequest } from "@vorim/sdk/http-signatures";
430
+
431
+ const result = await verifyHttpRequest(request, {
432
+ publicKey: agentPublicKeyPem, // SPKI PEM, Ed25519 or P-256
433
+ maxAgeSeconds: 300,
434
+ requiredComponents: ["@method", "@target-uri", "content-digest"],
435
+ });
436
+ ```
437
+
438
+ The module passes the Ed25519 test vector in RFC 9421 Appendix B.2.6. It supports every derived component in the RFC, and the `req`, `name` and `bs` component parameters. `sf`, `key` and `tr` raise an error because they aren't supported yet.
439
+
386
440
  ### Embeddable Trust Badge
387
441
 
388
442
  Every registered agent gets a public SVG trust badge you can embed anywhere:
@@ -481,7 +535,7 @@ const { events } = await vorim.emit({ /* ... */ });
481
535
  // events: [{ event_id: "evt_...", digest: "sha256:..." }]
482
536
 
483
537
  import { eventDigest } from "@vorim/sdk";
484
- await eventDigest(sentEvent) === events[0].digest; // true
538
+ await eventDigest(sentEvent) === events?.[0].digest; // true
485
539
  ```
486
540
 
487
541
  Byte-identical in `@vorim/verify` and the Python SDK. A content digest, not an