@orangecheck/agent-core 1.0.1 → 1.2.0

package/README.md

@@ -1,5 +1,9 @@
 # @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.
+> Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.
+
+
 Canonical messages, envelope formats (delegation / action / revocation), scope grammar, and verification for [OC Agent](https://github.com/orangecheck/oc-agent-protocol) — the OrangeCheck authority primitive.
 
 - **Pure TypeScript.** No Node built-ins outside `@noble/hashes`. Runs in Node, browsers, Deno, Cloudflare Workers.

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, RevocationEnvelope, ChainLink, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult, VerifySubdelegationResult, ScopesEncryptedEnvelope } from './types.mjs';
-export { ActionCanonicalInput, ActionContent, ActionOts, ActorRef, DelegationBond, DelegationCanonicalInput, DelegationRevocationRef, ENVELOPE_VERSION, EnvelopeKind, RevocationCanonicalInput, RevocationHolder, Signature, SubdelegationCanonicalInput, VerifyActionOkExtra, VerifyErr, VerifyOk } from './types.mjs';
+import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, RevocationEnvelope, 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';
 export { REGISTERED_SCOPES, Scope, ScopeConstraint, ScopeOp, ScopeParseError, canonicalizeScope, canonicalizeScopeString, isSubScope, parseScope, validateScope } from './scope.mjs';
@@ -58,6 +58,81 @@ interface VerifySubdelegationInput extends VerifyBase {
 }
 declare function verifySubdelegation(input: VerifySubdelegationInput): Promise<VerifySubdelegationResult>;
 
+interface FederationGuardian {
+    address: string;
+    alg: 'bip322';
+    name?: string;
+}
+interface FederationDescriptor {
+    v: 1;
+    kind: 'agent-federation';
+    threshold: string;
+    guardians: FederationGuardian[];
+}
+interface FederationPrincipal {
+    alg: 'federation';
+    descriptor_id: string;
+    descriptor: FederationDescriptor;
+}
+interface FederationSignature {
+    alg: 'federation-bip322';
+    threshold: string;
+    signatures: Array<{
+        guardian_address: string;
+        value: string;
+    }>;
+}
+interface FederationDelegationEnvelope {
+    v: 1;
+    kind: 'agent-delegation';
+    id: string;
+    principal: FederationPrincipal;
+    agent: ActorRef;
+    scopes: string[];
+    bond: DelegationBond | null;
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+    revocation: DelegationRevocationRef;
+    sig: FederationSignature;
+}
+interface FederationRevocationEnvelope {
+    v: 1;
+    kind: 'agent-revocation';
+    id: string;
+    delegation_id: string;
+    signer: FederationPrincipal;
+    reason: string;
+    signed_at: string;
+    ots?: unknown | null;
+    sig: FederationSignature;
+}
+type FederationVerifyResult = {
+    ok: true;
+    id: string;
+    canonicalMessage: string;
+} | {
+    ok: false;
+    code: AgentErrorCode;
+    message: string;
+};
+interface VerifyFederationBase {
+    verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
+    skipSignatureVerification?: boolean;
+}
+declare function federationDescriptorCanonicalMessage(descriptor: FederationDescriptor): string;
+declare function computeFederationDescriptorId(descriptor: FederationDescriptor): string;
+interface VerifyFederationDelegationInput extends VerifyFederationBase {
+    envelope: FederationDelegationEnvelope;
+    now?: Date;
+    skipTemporalCheck?: boolean;
+}
+declare function verifyFederationDelegation(input: VerifyFederationDelegationInput): Promise<FederationVerifyResult>;
+interface VerifyFederationRevocationInput extends VerifyFederationBase {
+    envelope: FederationRevocationEnvelope;
+}
+declare function verifyFederationRevocation(input: VerifyFederationRevocationInput): Promise<FederationVerifyResult>;
+
 declare function encodeScopesPayload(scopes: string[]): Uint8Array;
 declare function decodeScopesPayload(bytes: Uint8Array): string[];
 interface SealScopesInput {
@@ -90,4 +165,14 @@ declare function hasPrivateScopes<T extends {
     scopes_encrypted: ScopesEncryptedEnvelope;
 };
 
-export { ActionEnvelope, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DelegationEnvelope, RevocationEnvelope, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, decodeScopesPayload, encodeScopesPayload, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, 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,5 +1,5 @@
-import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, RevocationEnvelope, ChainLink, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult, VerifySubdelegationResult, ScopesEncryptedEnvelope } from './types.js';
-export { ActionCanonicalInput, ActionContent, ActionOts, ActorRef, DelegationBond, DelegationCanonicalInput, DelegationRevocationRef, ENVELOPE_VERSION, EnvelopeKind, RevocationCanonicalInput, RevocationHolder, Signature, SubdelegationCanonicalInput, VerifyActionOkExtra, VerifyErr, VerifyOk } from './types.js';
+import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, SubdelegationEnvelope, RevocationEnvelope, 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';
 export { REGISTERED_SCOPES, Scope, ScopeConstraint, ScopeOp, ScopeParseError, canonicalizeScope, canonicalizeScopeString, isSubScope, parseScope, validateScope } from './scope.js';
@@ -58,6 +58,81 @@ interface VerifySubdelegationInput extends VerifyBase {
 }
 declare function verifySubdelegation(input: VerifySubdelegationInput): Promise<VerifySubdelegationResult>;
 
+interface FederationGuardian {
+    address: string;
+    alg: 'bip322';
+    name?: string;
+}
+interface FederationDescriptor {
+    v: 1;
+    kind: 'agent-federation';
+    threshold: string;
+    guardians: FederationGuardian[];
+}
+interface FederationPrincipal {
+    alg: 'federation';
+    descriptor_id: string;
+    descriptor: FederationDescriptor;
+}
+interface FederationSignature {
+    alg: 'federation-bip322';
+    threshold: string;
+    signatures: Array<{
+        guardian_address: string;
+        value: string;
+    }>;
+}
+interface FederationDelegationEnvelope {
+    v: 1;
+    kind: 'agent-delegation';
+    id: string;
+    principal: FederationPrincipal;
+    agent: ActorRef;
+    scopes: string[];
+    bond: DelegationBond | null;
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+    revocation: DelegationRevocationRef;
+    sig: FederationSignature;
+}
+interface FederationRevocationEnvelope {
+    v: 1;
+    kind: 'agent-revocation';
+    id: string;
+    delegation_id: string;
+    signer: FederationPrincipal;
+    reason: string;
+    signed_at: string;
+    ots?: unknown | null;
+    sig: FederationSignature;
+}
+type FederationVerifyResult = {
+    ok: true;
+    id: string;
+    canonicalMessage: string;
+} | {
+    ok: false;
+    code: AgentErrorCode;
+    message: string;
+};
+interface VerifyFederationBase {
+    verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
+    skipSignatureVerification?: boolean;
+}
+declare function federationDescriptorCanonicalMessage(descriptor: FederationDescriptor): string;
+declare function computeFederationDescriptorId(descriptor: FederationDescriptor): string;
+interface VerifyFederationDelegationInput extends VerifyFederationBase {
+    envelope: FederationDelegationEnvelope;
+    now?: Date;
+    skipTemporalCheck?: boolean;
+}
+declare function verifyFederationDelegation(input: VerifyFederationDelegationInput): Promise<FederationVerifyResult>;
+interface VerifyFederationRevocationInput extends VerifyFederationBase {
+    envelope: FederationRevocationEnvelope;
+}
+declare function verifyFederationRevocation(input: VerifyFederationRevocationInput): Promise<FederationVerifyResult>;
+
 declare function encodeScopesPayload(scopes: string[]): Uint8Array;
 declare function decodeScopesPayload(bytes: Uint8Array): string[];
 interface SealScopesInput {
@@ -90,4 +165,14 @@ declare function hasPrivateScopes<T extends {
     scopes_encrypted: ScopesEncryptedEnvelope;
 };
 
-export { ActionEnvelope, AgentError, AgentErrorCode, ChainLink, DEFAULT_MAX_CHAIN_DEPTH, DelegationEnvelope, RevocationEnvelope, ScopesEncryptedEnvelope, type SealScopesInput, SubdelegationEnvelope, type UnsealScopesInput, type UnsealedScopes, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyRevocationInput, VerifyRevocationResult, type VerifySubdelegationInput, VerifySubdelegationResult, decodeScopesPayload, encodeScopesPayload, hasPrivateScopes, sealScopes, unsealScopes, verifyAction, verifyDelegation, 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

@@ -945,6 +945,193 @@ function isHex64(s) {
 function isIsoUtc(s) {
   return typeof s === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(s);
 }
+function federationDescriptorCanonicalMessage(descriptor) {
+  const addresses = descriptor.guardians.map((g) => g.address).sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  return [
+    "oc-agent:federation:v1",
+    `threshold: ${descriptor.threshold}`,
+    ...addresses.map((a) => `guardian: ${a}`)
+  ].join("\n");
+}
+function computeFederationDescriptorId(descriptor) {
+  return canonical.hexEncode(sha256.sha256(new TextEncoder().encode(federationDescriptorCanonicalMessage(descriptor))));
+}
+function parseThreshold(t) {
+  if (typeof t !== "string") return null;
+  const m = /^(\d+)-of-(\d+)$/.exec(t);
+  if (!m) return null;
+  const mm = Number(m[1]);
+  const nn = Number(m[2]);
+  if (!Number.isInteger(mm) || !Number.isInteger(nn) || mm < 1 || mm > nn) return null;
+  return { m: mm, n: nn };
+}
+var HEX64 = /^[0-9a-f]{64}$/;
+var ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+async function checkFederationQuorum(principal, sig, reconstructedId, input) {
+  if (principal?.alg !== "federation") {
+    return fail("E_MALFORMED", 'principal.alg must be "federation"');
+  }
+  const descriptor = principal.descriptor;
+  if (!descriptor || descriptor.kind !== "agent-federation") {
+    return fail("E_MALFORMED", "principal.descriptor missing or wrong kind");
+  }
+  const parsed = parseThreshold(descriptor.threshold);
+  if (!parsed) return fail("E_MALFORMED", `malformed threshold "${descriptor.threshold}"`);
+  if (!Array.isArray(descriptor.guardians) || descriptor.guardians.length !== parsed.n) {
+    return fail("E_MALFORMED", "guardians length must equal N in M-of-N");
+  }
+  const computedDescId = computeFederationDescriptorId(descriptor);
+  if (principal.descriptor_id !== computedDescId) {
+    return fail(
+      "E_BAD_FEDERATION_DESCRIPTOR",
+      `declared descriptor_id (${principal.descriptor_id}) != canonical hash (${computedDescId})`
+    );
+  }
+  if (sig?.alg !== "federation-bip322") {
+    return fail("E_MALFORMED", 'sig.alg must be "federation-bip322"');
+  }
+  if (sig.threshold !== descriptor.threshold) {
+    return fail(
+      "E_THRESHOLD_MISMATCH",
+      `sig.threshold (${sig.threshold}) != descriptor.threshold (${descriptor.threshold})`
+    );
+  }
+  const sigs = sig.signatures;
+  if (!Array.isArray(sigs)) return fail("E_MALFORMED", "sig.signatures must be an array");
+  if (sigs.length < parsed.m) {
+    return fail(
+      "E_THRESHOLD_NOT_MET",
+      `${sigs.length} signature(s) below threshold M=${parsed.m}`
+    );
+  }
+  const guardianSet = new Set(descriptor.guardians.map((g) => g.address));
+  const seen = /* @__PURE__ */ new Set();
+  for (const s of sigs) {
+    if (!guardianSet.has(s.guardian_address)) {
+      return fail("E_UNKNOWN_GUARDIAN", `${s.guardian_address} is not a declared guardian`);
+    }
+    if (seen.has(s.guardian_address)) {
+      return fail("E_DUPLICATE_GUARDIAN", `${s.guardian_address} signed more than once`);
+    }
+    seen.add(s.guardian_address);
+  }
+  if (!input.skipSignatureVerification) {
+    if (!input.verifyBip322) return fail("E_BAD_SIG", "no BIP-322 verifier supplied");
+    for (const s of sigs) {
+      const ok = await input.verifyBip322(reconstructedId, s.value, s.guardian_address);
+      if (!ok) {
+        return fail("E_BAD_SIG", `guardian ${s.guardian_address} signature did not verify`);
+      }
+    }
+  }
+  return { ok: true };
+}
+async function verifyFederationDelegation(input) {
+  const env = input.envelope;
+  if (env?.kind !== "agent-delegation") return fail("E_MALFORMED", 'kind must be "agent-delegation"');
+  if (!HEX64.test(env.id ?? "")) return fail("E_MALFORMED", "id must be 64 lowercase hex chars");
+  if (!env.agent?.address || env.agent.alg !== "bip322") return fail("E_MALFORMED", "agent invalid");
+  if (!Array.isArray(env.scopes) || env.scopes.length === 0) {
+    return fail("E_MALFORMED", "scopes must be a non-empty array");
+  }
+  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");
+  }
+  if (!/^[0-9a-f]{32}$/.test(env.nonce)) return fail("E_MALFORMED", "nonce must be 32 hex chars");
+  let canonicalScopes;
+  try {
+    canonicalScopes = canonicalizeScopes(env.scopes);
+  } catch (e) {
+    return fail("E_BAD_SCOPE_GRAMMAR", e.message);
+  }
+  for (let i = 0; i < canonicalScopes.length; i++) {
+    if (env.scopes[i] !== canonicalScopes[i]) {
+      return fail("E_BAD_SCOPE_GRAMMAR", `scope index ${i} not in canonical order`);
+    }
+  }
+  const canonInput = {
+    principal: `federation:${env.principal?.descriptor_id ?? ""}`,
+    agent: env.agent.address,
+    scopes: canonicalScopes,
+    bond_sats: env.bond?.sats ?? 0,
+    bond_attestation: env.bond?.attestation_id ?? "none",
+    issued_at: env.issued_at,
+    expires_at: env.expires_at,
+    nonce: env.nonce
+  };
+  const reconstructedId = computeDelegationId(canonInput);
+  if (reconstructedId !== env.id) {
+    return fail("E_BAD_ID", `reconstructed id (${reconstructedId}) != envelope.id (${env.id})`);
+  }
+  const quorum = await checkFederationQuorum(env.principal, env.sig, env.id, input);
+  if (!quorum.ok) return quorum;
+  if (!input.skipTemporalCheck) {
+    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}`);
+  }
+  return { ok: true, id: env.id, canonicalMessage: delegationCanonicalMessage(canonInput) };
+}
+async function verifyFederationRevocation(input) {
+  const env = input.envelope;
+  if (env?.kind !== "agent-revocation") return fail("E_MALFORMED", 'kind must be "agent-revocation"');
+  if (!HEX64.test(env.id ?? "")) return fail("E_MALFORMED", "id must be 64 lowercase hex chars");
+  if (!HEX64.test(env.delegation_id ?? "")) return fail("E_MALFORMED", "delegation_id must be 64-hex");
+  if (typeof env.reason !== "string" || env.reason.length > 128) {
+    return fail("E_MALFORMED", "reason must be a string \u2264128 bytes");
+  }
+  if (!ISO_UTC.test(env.signed_at)) return fail("E_MALFORMED", "signed_at must be ISO 8601 UTC");
+  const canonInput = {
+    address: `federation:${env.signer?.descriptor_id ?? ""}`,
+    delegation_id: env.delegation_id,
+    reason: env.reason,
+    signed_at: env.signed_at
+  };
+  const reconstructedId = computeRevocationId(canonInput);
+  if (reconstructedId !== env.id) {
+    return fail("E_BAD_ID", `reconstructed id (${reconstructedId}) != envelope.id (${env.id})`);
+  }
+  const quorum = await checkFederationQuorum(env.signer, env.sig, env.id, input);
+  if (!quorum.ok) return quorum;
+  return { ok: true, id: env.id, canonicalMessage: revocationCanonicalMessage(canonInput) };
+}
+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,
@@ -958,9 +1145,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;
@@ -972,12 +1161,14 @@ exports.canonicalizeScopeString = canonicalizeScopeString;
 exports.canonicalizeScopes = canonicalizeScopes;
 exports.computeActionId = computeActionId;
 exports.computeDelegationId = computeDelegationId;
+exports.computeFederationDescriptorId = computeFederationDescriptorId;
 exports.computeRevocationId = computeRevocationId;
 exports.computeSubdelegationId = computeSubdelegationId;
 exports.decodeScopesPayload = decodeScopesPayload;
 exports.delegationCanonicalBytes = delegationCanonicalBytes;
 exports.delegationCanonicalMessage = delegationCanonicalMessage;
 exports.encodeScopesPayload = encodeScopesPayload;
+exports.federationDescriptorCanonicalMessage = federationDescriptorCanonicalMessage;
 exports.hasPrivateScopes = hasPrivateScopes;
 exports.isSubScope = isSubScope;
 exports.parseAndCanonicalizeScopes = parseAndCanonicalizeScopes;
@@ -992,6 +1183,8 @@ exports.unsealScopes = unsealScopes;
 exports.validateScope = validateScope;
 exports.verifyAction = verifyAction;
 exports.verifyDelegation = verifyDelegation;
+exports.verifyFederationDelegation = verifyFederationDelegation;
+exports.verifyFederationRevocation = verifyFederationRevocation;
 exports.verifyRevocation = verifyRevocation;
 exports.verifySubdelegation = verifySubdelegation;
 //# sourceMappingURL=index.js.map