@orangecheck/agent-core 2.5.1 → 2.7.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.
 
 
@@ -114,7 +114,9 @@ if (!result.ok) throw new Error(result.code + ': ' + result.message);
 ### Verification (§SPEC 8)
 
 - `verifyDelegation({ envelope, revocations | skipRevocationCheck, verifyBip322, now?, skipTemporalCheck?, scopeMode? })`
-- `verifyAction({ action, delegation, revocations | skipRevocationCheck, verifyBip322, verifyOtsAnchor?, content?, resolveAnchorBlockHeight?, scopeMode? })`
+- `verifyAction({ action, delegation, revocations | skipRevocationCheck, verifyBip322, now?, maxSkewMs?, verifyOtsAnchor?, content?, resolveAnchorBlockHeight?, scopeMode? })` — the live check, as of `now` (default: the current time). Every link of the chain must be in force at `now`, a revocation in effect at or before `now` refuses the action (`E_REVOKED`), and `signed_at` must lie within `maxSkewMs` of `now` (default 120 s; else `E_STALE`). The result's `asOf` is `{ basis: 'now', now }`.
+- `verifyActionAsOfSignedAt({ … })` — an audit of a past action, as of its own `signed_at`. The agent chooses that time, so `asOf.anchored` says whether a verified OTS anchor fixes it. Never use it to decide whether to act now.
+- `createReplayGuard(maxSkewMs?)` — `firstUse(action, now?)` is true once per action id. It keeps each id until `signed_at + maxSkewMs`, as long as the action could pass `verifyAction`. One process only; across instances keep the same record in a shared store. Replay is the caller's to stop: `verifyAction` keeps no state.
 - `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 })`

package/dist/index.d.mts

@@ -7,6 +7,7 @@ import { SealInput, DeviceRecord, UnsealInput } from '@orangecheck/lock-core';
 export { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
 
 declare const DEFAULT_MAX_CHAIN_DEPTH = 5;
+declare const DEFAULT_MAX_SKEW_MS = 120000;
 interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
@@ -40,8 +41,15 @@ interface VerifyActionInput extends VerifyBase {
         device_id: string;
         secretKey: Uint8Array;
     };
+    now?: Date;
+    maxSkewMs?: number;
 }
+type VerifyActionAsOfSignedAtInput = Omit<VerifyActionInput, 'now' | 'maxSkewMs'>;
 declare function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult>;
+declare function verifyActionAsOfSignedAt(input: VerifyActionAsOfSignedAtInput): Promise<VerifyActionResult>;
+declare function createReplayGuard(maxSkewMs?: number): {
+    firstUse(action: Pick<ActionEnvelope, 'id' | 'signed_at'>, now?: Date): boolean;
+};
 interface VerifyRevocationInput extends VerifyBase {
     envelope: RevocationEnvelope;
     delegation: ChainLink;
@@ -179,4 +187,4 @@ declare class ScopeNotGrantedError extends Error {
 }
 declare function assertScopeGranted(delegation: ScopeBearingDelegation, scopeExercised: string, fnName: string): void;
 
-export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
+export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DEFAULT_MAX_SKEW_MS, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionAsOfSignedAtInput, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, createReplayGuard, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyActionAsOfSignedAt, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import { SealInput, DeviceRecord, UnsealInput } from '@orangecheck/lock-core';
 export { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
 
 declare const DEFAULT_MAX_CHAIN_DEPTH = 5;
+declare const DEFAULT_MAX_SKEW_MS = 120000;
 interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
@@ -40,8 +41,15 @@ interface VerifyActionInput extends VerifyBase {
         device_id: string;
         secretKey: Uint8Array;
     };
+    now?: Date;
+    maxSkewMs?: number;
 }
+type VerifyActionAsOfSignedAtInput = Omit<VerifyActionInput, 'now' | 'maxSkewMs'>;
 declare function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult>;
+declare function verifyActionAsOfSignedAt(input: VerifyActionAsOfSignedAtInput): Promise<VerifyActionResult>;
+declare function createReplayGuard(maxSkewMs?: number): {
+    firstUse(action: Pick<ActionEnvelope, 'id' | 'signed_at'>, now?: Date): boolean;
+};
 interface VerifyRevocationInput extends VerifyBase {
     envelope: RevocationEnvelope;
     delegation: ChainLink;
@@ -179,4 +187,4 @@ declare class ScopeNotGrantedError extends Error {
 }
 declare function assertScopeGranted(delegation: ScopeBearingDelegation, scopeExercised: string, fnName: string): void;
 
-export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
+export { ActionEnvelope, ActorRef, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DEFAULT_MAX_SKEW_MS, DelegationBond, DelegationEnvelope, DelegationRevocationRef, type FederationDelegationEnvelope, type FederationDescriptor, type FederationGuardian, type FederationPrincipal, type FederationRevocationEnvelope, type FederationSignature, type FederationVerifyResult, RevocationEnvelope, type ScopeBearingDelegation, ScopeNotGrantedError, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionAsOfSignedAtInput, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyFederationBase, type VerifyFederationDelegationInput, type VerifyFederationRevocationInput, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, assertScopeGranted, computeFederationDescriptorId, createReplayGuard, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyActionAsOfSignedAt, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };

package/dist/index.js

@@ -411,6 +411,7 @@ function hasPrivateScopes(envelope) {
 
 // src/verify.ts
 var DEFAULT_MAX_CHAIN_DEPTH = 5;
+var DEFAULT_MAX_SKEW_MS = 12e4;
 var AgentError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -533,7 +534,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}`);
   }
@@ -546,6 +546,12 @@ async function verifyDelegation(input) {
   };
 }
 async function verifyAction(input) {
+  return verifyActionAt(input, input.now ?? /* @__PURE__ */ new Date());
+}
+async function verifyActionAsOfSignedAt(input) {
+  return verifyActionAt(input, null);
+}
+async function verifyActionAt(input, now) {
   const a = input.action;
   const d = input.delegation;
   const chain = input.subdelegationChain ?? [];
@@ -623,6 +629,17 @@ async function verifyAction(input) {
   if (signed < issued || signed >= expires) {
     return err("E_OUT_OF_WINDOW", `action.signed_at ${a.signed_at} is outside leaf window [${leaf.issued_at}, ${leaf.expires_at})`);
   }
+  if (now) {
+    const t = now.getTime();
+    for (const link of [rootHydrated, ...hydratedChain]) {
+      if (t < new Date(link.issued_at).getTime()) {
+        return err("E_NOT_YET_VALID", `${link.id} is not valid until ${link.issued_at}`);
+      }
+      if (t >= new Date(link.expires_at).getTime()) {
+        return err("E_EXPIRED", `${link.id} expired at ${link.expires_at}`);
+      }
+    }
+  }
   if (!leaf.scopes) {
     return err("E_SCOPES_NEITHER_PROVIDED", "leaf has no plaintext scopes after hydration");
   }
@@ -671,9 +688,21 @@ async function verifyAction(input) {
         if (revocationPrecedes(rev, revAnchor, a, actionAnchor)) {
           return err("E_REVOKED", `chain link ${link.id} was revoked by ${rev.id} before action was signed`);
         }
+        if (now && (revAnchor !== null || new Date(rev.signed_at).getTime() <= now.getTime())) {
+          return err("E_REVOKED", `chain link ${link.id} was revoked by ${rev.id}`);
+        }
       }
     }
   }
+  if (now) {
+    const maxSkew = input.maxSkewMs ?? DEFAULT_MAX_SKEW_MS;
+    if (Math.abs(now.getTime() - signed) > maxSkew) {
+      return err(
+        "E_STALE",
+        `action.signed_at ${a.signed_at} is more than ${maxSkew} ms from the time of verification ${now.toISOString()}`
+      );
+    }
+  }
   if (input.content) {
     const actualHash = "sha256:" + canonical.hexEncode(sha256.sha256(input.content));
     if (actualHash !== a.content.hash) {
@@ -701,7 +730,20 @@ async function verifyAction(input) {
     delegation: rootHydrated,
     chain: hydratedChain,
     scopeExercised: exercised,
-    anchor
+    anchor,
+    asOf: now ? { basis: "now", now: now.toISOString() } : { basis: "signed_at", signedAt: a.signed_at, anchored: actionAnchor !== null }
+  };
+}
+function createReplayGuard(maxSkewMs = DEFAULT_MAX_SKEW_MS) {
+  const keepUntil = /* @__PURE__ */ new Map();
+  return {
+    firstUse(action, now = /* @__PURE__ */ new Date()) {
+      const t = now.getTime();
+      for (const [id, until] of keepUntil) if (until <= t) keepUntil.delete(id);
+      if (keepUntil.has(action.id)) return false;
+      keepUntil.set(action.id, new Date(action.signed_at).getTime() + maxSkewMs);
+      return true;
+    }
   };
 }
 async function hydrateSubdelegationScopes(sub, input) {
@@ -798,11 +840,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 +1127,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 {
@@ -1118,7 +1173,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}`);
   }
@@ -1239,6 +1293,7 @@ Object.defineProperty(exports, "hexEncode", {
 });
 exports.AgentError = AgentError;
 exports.DEFAULT_MAX_CHAIN_DEPTH = DEFAULT_MAX_CHAIN_DEPTH;
+exports.DEFAULT_MAX_SKEW_MS = DEFAULT_MAX_SKEW_MS;
 exports.ENVELOPE_VERSION = ENVELOPE_VERSION;
 exports.REGISTERED_SCOPES = REGISTERED_SCOPES;
 exports.ScopeNotGrantedError = ScopeNotGrantedError;
@@ -1260,6 +1315,7 @@ exports.computeDelegationId = computeDelegationId;
 exports.computeFederationDescriptorId = computeFederationDescriptorId;
 exports.computeRevocationId = computeRevocationId;
 exports.computeSubdelegationId = computeSubdelegationId;
+exports.createReplayGuard = createReplayGuard;
 exports.decodeScopesPayload = decodeScopesPayload;
 exports.delegationCanonicalBytes = delegationCanonicalBytes;
 exports.delegationCanonicalMessage = delegationCanonicalMessage;
@@ -1278,6 +1334,7 @@ exports.subdelegationCanonicalMessage = subdelegationCanonicalMessage;
 exports.unsealScopes = unsealScopes;
 exports.validateScope = validateScope;
 exports.verifyAction = verifyAction;
+exports.verifyActionAsOfSignedAt = verifyActionAsOfSignedAt;
 exports.verifyDelegation = verifyDelegation;
 exports.verifyFederationDelegation = verifyFederationDelegation;
 exports.verifyFederationRevocation = verifyFederationRevocation;