@orangecheck/agent-core 2.5.0 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @orangecheck/agent-core
 
-> **Full reference:** [docs.ochk.io/sdk/agent-core](https://docs.ochk.io/sdk/agent-core) — auto-generated from the TypeScript source on every release.
+> **Full reference:** [ochk.io/docs/sdk/agent-core](https://ochk.io/docs/sdk/agent-core) — auto-generated from the TypeScript source on every release.
 > Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.
 
 
@@ -14,8 +14,8 @@ Canonical messages, envelope formats (delegation / action / revocation), scope g
 
 ```bash
 npm i @orangecheck/agent-core
-# peer dep:
-npm i @orangecheck/stamp-core
+# for the quickstart below: relay reads and a BIP-322 verifier
+npm i @orangecheck/nostr-core @orangecheck/bip322
 ```
 
 ## Quickstart
@@ -24,11 +24,16 @@ npm i @orangecheck/stamp-core
 import {
     canonicalizeScopes,
     computeDelegationId,
-    delegationCanonicalMessage,
     verifyDelegation,
+    type DelegationEnvelope,
+    type RevocationEnvelope,
 } from '@orangecheck/agent-core';
+import { verifySignature } from '@orangecheck/bip322';
+import { queryEvents } from '@orangecheck/nostr-core';
 
-// 1. Build a delegation canonical message.
+// 1. Build a delegation's canonical fields and id.
+const iso = (d: Date) => d.toISOString().replace(/\.\d+Z$/, 'Z');
+const issued = new Date();
 const scopes = canonicalizeScopes([
     'lock:seal(recipient=bc1qalice)',
     'stamp:sign(mime=text/markdown)',
@@ -38,19 +43,18 @@ const canon = {
     agent: 'bc1qagent…',
     scopes,
     bond_sats: 500_000,
-    bond_attestation: '22…22', // 64-hex OrangeCheck attestation id
-    issued_at: '2026-04-22T12:00:00Z',
-    expires_at: '2026-04-29T12:00:00Z',
-    nonce: '0123…cdef',
+    bond_attestation: '22…22', // 64-hex OrangeCheck attestation id, or 'none'
+    issued_at: iso(issued),
+    expires_at: iso(new Date(issued.getTime() + 7 * 86_400_000)), // one week
+    nonce: '0123…cdef', // 32-hex, random
 };
-const msg = delegationCanonicalMessage(canon);
 const id = computeDelegationId(canon);
 
-// 2. Have the wallet sign `id` (hex ASCII) via BIP-322.
+// 2. Have the principal's wallet sign `id` (hex ASCII) via BIP-322.
 const sigValue = await wallet.signMessage(id);
 
 // 3. Build the wire envelope.
-const envelope = {
+const envelope: DelegationEnvelope = {
     v: 1, kind: 'agent-delegation', id,
     principal: { address: canon.principal, alg: 'bip322' },
     agent: { address: canon.agent, alg: 'bip322' },
@@ -59,12 +63,28 @@ const envelope = {
     issued_at: canon.issued_at, expires_at: canon.expires_at, nonce: canon.nonce,
     revocation: { holders: ['principal'], ref: null },
     sig: { alg: 'bip322', pubkey: canon.principal, value: sigValue },
-} as const;
+};
+
+// 4. Fetch its revocations: kind 30085 by `#t` (SPEC §9.4). Relays do not
+//    index the multi-letter `delegation` tag. Only a relay that sent EOSE
+//    can show that none exists (SPEC §10.4).
+const feed = await queryEvents({ kinds: [30085], '#t': [id] });
+if (!feed.relayStatus.some((r) => r.eose)) throw new Error('no relay answered');
+const revocations = feed.events.flatMap((e): RevocationEnvelope[] => {
+    try {
+        const r = JSON.parse(e.content);
+        return r?.kind === 'agent-revocation' && r.delegation_id === id ? [r] : [];
+    } catch {
+        return [];
+    }
+});
 
-// 4. Verify.
+// 5. Verify. `revocations` is required: pass what you fetched, or state
+//    `skipRevocationCheck: true` if you are not checking.
 const result = await verifyDelegation({
     envelope,
-    verifyBip322: async (m, s, a) => bip322.verify(a, m, s),
+    revocations,
+    verifyBip322: async (msg, sig, addr) => verifySignature(addr, msg, sig),
 });
 if (!result.ok) throw new Error(result.code + ': ' + result.message);
 ```
@@ -93,12 +113,14 @@ if (!result.ok) throw new Error(result.code + ': ' + result.message);
 
 ### Verification (§SPEC 8)
 
-- `verifyDelegation({ envelope, verifyBip322, now?, skipTemporalCheck?, scopeMode? })`
-- `verifyAction({ action, delegation, revocations?, verifyBip322, verifyOtsAnchor?, content?, resolveAnchorBlockHeight?, scopeMode? })`
+- `verifyDelegation({ envelope, revocations | skipRevocationCheck, verifyBip322, now?, skipTemporalCheck?, scopeMode? })`
+- `verifyAction({ action, delegation, revocations | skipRevocationCheck, verifyBip322, verifyOtsAnchor?, content?, resolveAnchorBlockHeight?, scopeMode? })`
 - `verifyRevocation({ envelope, delegation, verifyBip322 })` — the principal may always revoke; `revocation.holders` can only add the agent
 - `verifyOtsAnchor(proofB64, blockHeight, blockHash, envelopeId)` — an anchor orders an action against a revocation only when this returns true
 - `verifyFederationRevocation({ envelope, delegation, verifyBip322 })`
 
+`verifyDelegation`, `verifyAction` and `verifyFederationDelegation` refuse with `E_MALFORMED` unless you pass `revocations` or `skipRevocationCheck: true`. Fetch revocations with `{ kinds: [30085], "#t": [<delegation id>] }`; for an action under a sub-delegation chain, list every link's id. Pass `[]` only when a relay answered with EOSE and nothing matched.
+
 Each returns a discriminated union:
 
 ```ts

package/dist/index.js

@@ -513,7 +513,7 @@ async function verifyDelegation(input) {
   if (!input.skipRevocationCheck && !input.revocations) {
     return err(
       "E_MALFORMED",
-      "verifyDelegation requires `revocations` (fetch kind-30085 by #delegation) or an explicit skipRevocationCheck:true to state that revocation is not being checked"
+      'verifyDelegation requires `revocations` (query kind 30085 with "#t": [delegation id], SPEC \xA79.4) or an explicit skipRevocationCheck:true to state that revocation is not being checked'
     );
   }
   if (input.revocations) {
@@ -533,7 +533,6 @@ async function verifyDelegation(input) {
     const now = input.now ?? /* @__PURE__ */ new Date();
     const issued = new Date(env.issued_at);
     const expires = new Date(env.expires_at);
-    if (expires <= issued) return err("E_MALFORMED", "expires_at <= issued_at");
     if (now < issued) return err("E_NOT_YET_VALID", `delegation not valid until ${env.issued_at}`);
     if (now >= expires) return err("E_EXPIRED", `delegation expired at ${env.expires_at}`);
   }
@@ -641,7 +640,7 @@ async function verifyAction(input) {
   if (!input.skipRevocationCheck && !input.revocations) {
     return err(
       "E_MALFORMED",
-      "verifyAction requires `revocations` (fetch kind-30085 by #delegation for every link in the chain) or an explicit skipRevocationCheck:true"
+      'verifyAction requires `revocations` (query kind 30085 with "#t": [id of every link in the chain], SPEC \xA79.4) or an explicit skipRevocationCheck:true'
     );
   }
   let actionAnchor;
@@ -798,11 +797,22 @@ function checkDelegationShape(env) {
   }
   if (!isIsoUtc(env.issued_at)) return err("E_MALFORMED", "issued_at must be ISO 8601 UTC");
   if (!isIsoUtc(env.expires_at)) return err("E_MALFORMED", "expires_at must be ISO 8601 UTC");
+  const windowError = delegationWindowError(env.issued_at, env.expires_at);
+  if (windowError) return err("E_MALFORMED", windowError);
   if (!/^[0-9a-f]{32}$/.test(env.nonce)) return err("E_MALFORMED", "nonce must be 32 lowercase hex chars");
   if (env.sig?.alg !== "bip322" || typeof env.sig.value !== "string") return err("E_MALFORMED", "sig invalid");
   if (env.sig.pubkey !== env.principal.address) return err("E_MALFORMED", "sig.pubkey must equal principal.address");
   return null;
 }
+var MAX_DELEGATION_MS = 365 * 864e5;
+function delegationWindowError(issuedAt, expiresAt) {
+  const issued = Date.parse(issuedAt);
+  const expires = Date.parse(expiresAt);
+  if (Number.isNaN(issued) || Number.isNaN(expires)) return "issued_at / expires_at must be real UTC times";
+  if (expires <= issued) return "expires_at must be after issued_at";
+  if (expires - issued > MAX_DELEGATION_MS) return "expires_at is more than 365 days after issued_at (SPEC \xA74.4)";
+  return null;
+}
 function checkActionShape(a) {
   if (a.kind !== "agent-action") return err("E_MALFORMED", 'kind must be "agent-action"');
   if (!isHex64(a.id)) return err("E_MALFORMED", "id must be 64 lowercase hex chars");
@@ -1074,6 +1084,8 @@ async function verifyFederationDelegation(input) {
   if (!ISO_UTC.test(env.issued_at) || !ISO_UTC.test(env.expires_at)) {
     return fail("E_MALFORMED", "issued_at / expires_at must be ISO 8601 UTC");
   }
+  const windowError = delegationWindowError(env.issued_at, env.expires_at);
+  if (windowError) return fail("E_MALFORMED", windowError);
   if (!/^[0-9a-f]{32}$/.test(env.nonce)) return fail("E_MALFORMED", "nonce must be 32 hex chars");
   let canonicalScopes;
   try {
@@ -1105,7 +1117,7 @@ async function verifyFederationDelegation(input) {
   if (!input.skipRevocationCheck && !input.revocations) {
     return fail(
       "E_MALFORMED",
-      "verifyFederationDelegation requires `revocations` (fetch kind-30085 by #delegation) or an explicit skipRevocationCheck:true to state that revocation is not being checked"
+      'verifyFederationDelegation requires `revocations` (query kind 30085 with "#t": [delegation id], SPEC \xA79.4) or an explicit skipRevocationCheck:true to state that revocation is not being checked'
     );
   }
   for (const rev of input.revocations ?? []) {
@@ -1118,7 +1130,6 @@ async function verifyFederationDelegation(input) {
     const now = input.now ?? /* @__PURE__ */ new Date();
     const issued = new Date(env.issued_at);
     const expires = new Date(env.expires_at);
-    if (expires <= issued) return fail("E_MALFORMED", "expires_at <= issued_at");
     if (now < issued) return fail("E_NOT_YET_VALID", `delegation not valid until ${env.issued_at}`);
     if (now >= expires) return fail("E_EXPIRED", `delegation expired at ${env.expires_at}`);
   }