@orangecheck/agent-core 1.1.0 → 2.0.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, RevocationEnvelope, ChainLink, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult, VerifySubdelegationResult, ActorRef, DelegationBond, DelegationRevocationRef, ScopesEncryptedEnvelope } from './types.mjs';
+import { AgentErrorCode, RevocationEnvelope, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, ChainLink, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult, VerifySubdelegationResult, ActorRef, DelegationBond, DelegationRevocationRef, ScopesEncryptedEnvelope } from './types.mjs';
 export { ActionCanonicalInput, ActionContent, ActionOts, DelegationCanonicalInput, ENVELOPE_VERSION, EnvelopeKind, RevocationCanonicalInput, RevocationHolder, Signature, SubdelegationCanonicalInput, VerifyActionOkExtra, VerifyErr, VerifyOk } from './types.mjs';
 export { actionCanonicalBytes, actionCanonicalMessage, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScopes, computeActionId, computeDelegationId, computeRevocationId, computeSubdelegationId, delegationCanonicalBytes, delegationCanonicalMessage, parseAndCanonicalizeScopes, revocationCanonicalBytes, revocationCanonicalMessage, sha256Hex, subdelegationCanonicalBytes, subdelegationCanonicalMessage } from './canonical.mjs';
 import { ValidationOptions } from './scope.mjs';
@@ -11,6 +11,8 @@ interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
     scopeMode?: ValidationOptions['mode'];
+    skipRevocationCheck?: boolean;
+    revocations?: RevocationEnvelope[];
 }
 declare class AgentError extends Error {
     code: AgentErrorCode;
@@ -31,7 +33,6 @@ interface VerifyActionInput extends VerifyBase {
     delegation: DelegationEnvelope;
     subdelegationChain?: SubdelegationEnvelope[];
     maxChainDepth?: number;
-    revocations?: RevocationEnvelope[];
     content?: Uint8Array;
     verifyOtsAnchor?: (proofB64: string, blockHeight: number, blockHash: string) => Promise<boolean>;
     resolveAnchorBlockHeight?: (env: ActionEnvelope | RevocationEnvelope) => number | null;
@@ -165,4 +166,14 @@ declare function hasPrivateScopes<T extends {
     scopes_encrypted: ScopesEncryptedEnvelope;
 };
 
-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, 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, computeFederationDescriptorId, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
+interface ScopeBearingDelegation {
+    scopes?: string[];
+    scopes_encrypted?: ScopesEncryptedEnvelope;
+}
+declare class ScopeNotGrantedError extends Error {
+    readonly reason: 'not_subscope' | 'scopes_encrypted' | 'no_scopes';
+    constructor(reason: ScopeNotGrantedError['reason'], message: string);
+}
+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 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, RevocationEnvelope, ChainLink, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult, VerifySubdelegationResult, ActorRef, DelegationBond, DelegationRevocationRef, ScopesEncryptedEnvelope } from './types.js';
+import { AgentErrorCode, RevocationEnvelope, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, ChainLink, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult, VerifySubdelegationResult, ActorRef, DelegationBond, DelegationRevocationRef, ScopesEncryptedEnvelope } from './types.js';
 export { ActionCanonicalInput, ActionContent, ActionOts, DelegationCanonicalInput, ENVELOPE_VERSION, EnvelopeKind, RevocationCanonicalInput, RevocationHolder, Signature, SubdelegationCanonicalInput, VerifyActionOkExtra, VerifyErr, VerifyOk } from './types.js';
 export { actionCanonicalBytes, actionCanonicalMessage, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScopes, computeActionId, computeDelegationId, computeRevocationId, computeSubdelegationId, delegationCanonicalBytes, delegationCanonicalMessage, parseAndCanonicalizeScopes, revocationCanonicalBytes, revocationCanonicalMessage, sha256Hex, subdelegationCanonicalBytes, subdelegationCanonicalMessage } from './canonical.js';
 import { ValidationOptions } from './scope.js';
@@ -11,6 +11,8 @@ interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
     scopeMode?: ValidationOptions['mode'];
+    skipRevocationCheck?: boolean;
+    revocations?: RevocationEnvelope[];
 }
 declare class AgentError extends Error {
     code: AgentErrorCode;
@@ -31,7 +33,6 @@ interface VerifyActionInput extends VerifyBase {
     delegation: DelegationEnvelope;
     subdelegationChain?: SubdelegationEnvelope[];
     maxChainDepth?: number;
-    revocations?: RevocationEnvelope[];
     content?: Uint8Array;
     verifyOtsAnchor?: (proofB64: string, blockHeight: number, blockHash: string) => Promise<boolean>;
     resolveAnchorBlockHeight?: (env: ActionEnvelope | RevocationEnvelope) => number | null;
@@ -165,4 +166,14 @@ declare function hasPrivateScopes<T extends {
     scopes_encrypted: ScopesEncryptedEnvelope;
 };
 
-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, 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, computeFederationDescriptorId, decodeScopesPayload, encodeScopesPayload, federationDescriptorCanonicalMessage, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, verifyFederationDelegation, verifyFederationRevocation, verifyRevocation, verifySubdelegation };
+interface ScopeBearingDelegation {
+    scopes?: string[];
+    scopes_encrypted?: ScopesEncryptedEnvelope;
+}
+declare class ScopeNotGrantedError extends Error {
+    readonly reason: 'not_subscope' | 'scopes_encrypted' | 'no_scopes';
+    constructor(reason: ScopeNotGrantedError['reason'], message: string);
+}
+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 };

package/dist/index.js

@@ -497,6 +497,25 @@ async function verifyDelegation(input) {
     const ok = await input.verifyBip322(env.id, env.sig.value, env.principal.address);
     if (!ok) return err("E_BAD_SIG", "BIP-322 signature did not verify");
   }
+  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"
+    );
+  }
+  if (input.revocations) {
+    for (const rev of input.revocations) {
+      if (rev.delegation_id !== env.id) continue;
+      const rr = await verifyRevocation({
+        envelope: rev,
+        delegation: env,
+        verifyBip322: input.verifyBip322,
+        skipSignatureVerification: input.skipSignatureVerification
+      });
+      if (!rr.ok) continue;
+      return err("E_REVOKED", `delegation ${env.id} was revoked by ${rev.id}`);
+    }
+  }
   if (!input.skipTemporalCheck) {
     const now = input.now ?? /* @__PURE__ */ new Date();
     const issued = new Date(env.issued_at);
@@ -531,6 +550,12 @@ async function verifyAction(input) {
     scopeMode: input.scopeMode,
     skipTemporalCheck: true,
     // action window check dominates
+    // Revocation is evaluated ONCE, below, across every link in the chain
+    // (root + subdelegations) against the action's effective time — a
+    // per-link check here would use the wrong clock and would also
+    // double-report. Forward the caller's decision so this inner call does
+    // not trip the fail-closed guard.
+    skipRevocationCheck: true,
     ...input.decryptScopesWith ? { decryptScopesWith: input.decryptScopesWith } : {}
   });
   if (!dr.ok) return dr;
@@ -600,6 +625,12 @@ async function verifyAction(input) {
     return err("E_BAD_SCOPE_GRAMMAR", msg);
   }
   if (!accepted) return err("E_SCOPE_DENIED", `scope_exercised (${exercised}) not a sub-scope of any granted scope`);
+  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"
+    );
+  }
   if (input.revocations && input.revocations.length > 0) {
     const allLinks = [rootHydrated, ...hydratedChain];
     for (const link of allLinks) {
@@ -1102,6 +1133,37 @@ function fail(code, message) {
   return { ok: false, code, message };
 }
 
+// src/assert-scope.ts
+var ScopeNotGrantedError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.name = "ScopeNotGrantedError";
+    this.reason = reason;
+  }
+};
+function assertScopeGranted(delegation, scopeExercised, fnName) {
+  if (hasPrivateScopes(delegation)) {
+    throw new ScopeNotGrantedError(
+      "scopes_encrypted",
+      `${fnName}: this delegation uses v1.2 private scopes \u2014 \`scopes_encrypted\` is set and \`scopes\` is absent, so the granted set cannot be read here. Decrypt it with decryptPrivateScopes() using a matching device key and pass the recovered scopes as \`delegation.scopes\`. Refusing to stamp \`${scopeExercised}\` against an unreadable grant.`
+    );
+  }
+  const scopes = delegation.scopes;
+  if (scopes === void 0 || scopes.length === 0) {
+    throw new ScopeNotGrantedError(
+      "no_scopes",
+      `${fnName}: delegation grants no scopes, so \`${scopeExercised}\` cannot be exercised. An absent or empty \`scopes\` means nothing is granted, never everything.`
+    );
+  }
+  const exercised = parseScope(scopeExercised);
+  if (!scopes.map(parseScope).some((g) => isSubScope(exercised, g))) {
+    throw new ScopeNotGrantedError(
+      "not_subscope",
+      `${fnName}: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope (${scopes.join(", ")})`
+    );
+  }
+}
+
 Object.defineProperty(exports, "canonicalize", {
   enumerable: true,
   get: function () { return canonical.canonicalize; }
@@ -1114,9 +1176,11 @@ exports.AgentError = AgentError;
 exports.DEFAULT_MAX_CHAIN_DEPTH = DEFAULT_MAX_CHAIN_DEPTH;
 exports.ENVELOPE_VERSION = ENVELOPE_VERSION;
 exports.REGISTERED_SCOPES = REGISTERED_SCOPES;
+exports.ScopeNotGrantedError = ScopeNotGrantedError;
 exports.ScopeParseError = ScopeParseError;
 exports.actionCanonicalBytes = actionCanonicalBytes;
 exports.actionCanonicalMessage = actionCanonicalMessage;
+exports.assertScopeGranted = assertScopeGranted;
 exports.canonicalActionBytes = canonicalActionBytes;
 exports.canonicalDelegationBytes = canonicalDelegationBytes;
 exports.canonicalRevocationBytes = canonicalRevocationBytes;