@orangecheck/agent-core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,10 +1,12 @@
-import { AgentErrorCode, ActionEnvelope, DelegationEnvelope, RevocationEnvelope, VerifyActionResult, VerifyDelegationResult, VerifyRevocationResult } from './types.js';
-export { ActionCanonicalInput, ActionContent, ActionOts, ActorRef, DelegationBond, DelegationCanonicalInput, DelegationRevocationRef, ENVELOPE_VERSION, EnvelopeKind, RevocationCanonicalInput, RevocationHolder, Signature, VerifyActionOkExtra, VerifyErr, VerifyOk } from './types.js';
-export { actionCanonicalBytes, actionCanonicalMessage, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScopes, computeActionId, computeDelegationId, computeRevocationId, delegationCanonicalBytes, delegationCanonicalMessage, parseAndCanonicalizeScopes, revocationCanonicalBytes, revocationCanonicalMessage, sha256Hex } from './canonical.js';
+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';
+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';
+import { SealInput, DeviceRecord, UnsealInput } from '@orangecheck/lock-core';
 export { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
 
+declare const DEFAULT_MAX_CHAIN_DEPTH = 5;
 interface VerifyBase {
     verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
     skipSignatureVerification?: boolean;
@@ -18,21 +20,74 @@ interface VerifyDelegationInput extends VerifyBase {
     envelope: DelegationEnvelope;
     now?: Date;
     skipTemporalCheck?: boolean;
+    decryptScopesWith?: {
+        device_id: string;
+        secretKey: Uint8Array;
+    };
 }
 declare function verifyDelegation(input: VerifyDelegationInput): Promise<VerifyDelegationResult>;
 interface VerifyActionInput extends VerifyBase {
     action: ActionEnvelope;
     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;
+    decryptScopesWith?: {
+        device_id: string;
+        secretKey: Uint8Array;
+    };
 }
 declare function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult>;
 interface VerifyRevocationInput extends VerifyBase {
     envelope: RevocationEnvelope;
-    delegation: DelegationEnvelope;
+    delegation: ChainLink;
 }
 declare function verifyRevocation(input: VerifyRevocationInput): Promise<VerifyRevocationResult>;
+interface VerifySubdelegationInput extends VerifyBase {
+    envelope: SubdelegationEnvelope;
+    parent: ChainLink;
+    skipTemporalCheck?: boolean;
+    now?: Date;
+    decryptScopesWith?: {
+        device_id: string;
+        secretKey: Uint8Array;
+    };
+}
+declare function verifySubdelegation(input: VerifySubdelegationInput): Promise<VerifySubdelegationResult>;
+
+declare function encodeScopesPayload(scopes: string[]): Uint8Array;
+declare function decodeScopesPayload(bytes: Uint8Array): string[];
+interface SealScopesInput {
+    scopes: string[];
+    sender: SealInput['sender'];
+    recipients: DeviceRecord[];
+    hint?: string;
+    expiresAt?: Date | null;
+}
+declare function sealScopes(input: SealScopesInput): Promise<ScopesEncryptedEnvelope>;
+interface UnsealScopesInput {
+    envelope: ScopesEncryptedEnvelope;
+    device: UnsealInput['device'];
+    verifyBip322?: UnsealInput['verifyBip322'];
+    skipSenderVerification?: boolean;
+}
+interface UnsealedScopes {
+    scopes: string[];
+    sender: {
+        address: string;
+        attestation_id?: string;
+    };
+    matchedDeviceId: string;
+}
+declare function unsealScopes(input: UnsealScopesInput): Promise<UnsealedScopes>;
+declare function hasPrivateScopes<T extends {
+    scopes?: string[];
+    scopes_encrypted?: ScopesEncryptedEnvelope;
+}>(envelope: T): envelope is T & {
+    scopes_encrypted: ScopesEncryptedEnvelope;
+};
 
-export { ActionEnvelope, AgentError, AgentErrorCode, DelegationEnvelope, RevocationEnvelope, ValidationOptions, type VerifyActionInput, VerifyActionResult, type VerifyBase, type VerifyDelegationInput, VerifyDelegationResult, type VerifyRevocationInput, VerifyRevocationResult, verifyAction, verifyDelegation, verifyRevocation };
+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 };

package/dist/index.js

@@ -2,6 +2,7 @@
 
 var sha256 = require('@noble/hashes/sha256');
 var canonical = require('@orangecheck/stamp-core/canonical');
+var lockCore = require('@orangecheck/lock-core');
 
 // src/types.ts
 var ENVELOPE_VERSION = 1;
@@ -294,6 +295,19 @@ function revocationCanonicalMessage(input) {
     `signed_at: ${input.signed_at}`
   ].join("\n");
 }
+function subdelegationCanonicalMessage(input) {
+  const scopeField = input.scopes.join(",");
+  return [
+    "oc-agent:subdelegation:v1",
+    `parent_id: ${input.parent_id}`,
+    `principal: ${input.principal}`,
+    `agent: ${input.agent}`,
+    `scopes: ${scopeField}`,
+    `issued_at: ${input.issued_at}`,
+    `expires_at: ${input.expires_at}`,
+    `nonce: ${input.nonce}`
+  ].join("\n");
+}
 function delegationCanonicalBytes(input) {
   return new TextEncoder().encode(delegationCanonicalMessage(input));
 }
@@ -303,6 +317,9 @@ function actionCanonicalBytes(input) {
 function revocationCanonicalBytes(input) {
   return new TextEncoder().encode(revocationCanonicalMessage(input));
 }
+function subdelegationCanonicalBytes(input) {
+  return new TextEncoder().encode(subdelegationCanonicalMessage(input));
+}
 function computeDelegationId(input) {
   return canonical.hexEncode(sha256.sha256(delegationCanonicalBytes(input)));
 }
@@ -312,6 +329,9 @@ function computeActionId(input) {
 function computeRevocationId(input) {
   return canonical.hexEncode(sha256.sha256(revocationCanonicalBytes(input)));
 }
+function computeSubdelegationId(input) {
+  return canonical.hexEncode(sha256.sha256(subdelegationCanonicalBytes(input)));
+}
 function canonicalizeDelegation(env) {
   return canonical.canonicalize(env);
 }
@@ -333,6 +353,51 @@ function canonicalRevocationBytes(env) {
 function sha256Hex(bytes) {
   return canonical.hexEncode(sha256.sha256(bytes));
 }
+function encodeScopesPayload(scopes) {
+  const canonical = canonicalizeScopes(scopes);
+  const json = JSON.stringify(canonical);
+  return new TextEncoder().encode(json);
+}
+function decodeScopesPayload(bytes) {
+  const json = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const parsed = JSON.parse(json);
+  if (!Array.isArray(parsed) || !parsed.every((s) => typeof s === "string")) {
+    throw new Error("scopes payload must be a JSON array of strings");
+  }
+  return parsed;
+}
+async function sealScopes(input) {
+  const env = await lockCore.seal({
+    kind: "identity",
+    payload: encodeScopesPayload(input.scopes),
+    sender: input.sender,
+    recipients: input.recipients,
+    ...input.hint !== void 0 && { hint: input.hint },
+    ...input.expiresAt !== void 0 && { expiresAt: input.expiresAt }
+  });
+  return env;
+}
+async function unsealScopes(input) {
+  const r = await lockCore.unseal({
+    envelope: input.envelope,
+    device: input.device,
+    ...input.verifyBip322 ? { verifyBip322: input.verifyBip322 } : {},
+    ...input.skipSenderVerification !== void 0 && {
+      skipSenderVerification: input.skipSenderVerification
+    }
+  });
+  return {
+    scopes: decodeScopesPayload(r.payload),
+    sender: r.sender,
+    matchedDeviceId: r.matchedDeviceId
+  };
+}
+function hasPrivateScopes(envelope) {
+  return !!envelope.scopes_encrypted;
+}
+
+// src/verify.ts
+var DEFAULT_MAX_CHAIN_DEPTH = 5;
 var AgentError = class extends Error {
   constructor(code, message) {
     super(message);
@@ -347,19 +412,63 @@ async function verifyDelegation(input) {
   }
   const shape = checkDelegationShape(env);
   if (shape) return shape;
+  if (env.scopes !== void 0 && env.scopes_encrypted !== void 0) {
+    return err(
+      "E_SCOPES_BOTH_PROVIDED",
+      "envelope carries both scopes and scopes_encrypted; pick one"
+    );
+  }
+  if (env.scopes === void 0 && env.scopes_encrypted === void 0) {
+    return err(
+      "E_SCOPES_NEITHER_PROVIDED",
+      "envelope carries neither scopes nor scopes_encrypted"
+    );
+  }
+  let workingScopes;
+  if (env.scopes_encrypted !== void 0) {
+    if (env.scopes_encrypted.from?.address !== env.principal.address) {
+      return err(
+        "E_MALFORMED",
+        `scopes_encrypted.from.address (${env.scopes_encrypted.from?.address}) does not match principal.address (${env.principal.address})`
+      );
+    }
+    if (!input.decryptScopesWith) {
+      return err(
+        "E_SCOPES_UNREADABLE",
+        "envelope carries scopes_encrypted; no decryption key provided"
+      );
+    }
+    try {
+      const r = await unsealScopes({
+        envelope: env.scopes_encrypted,
+        device: input.decryptScopesWith,
+        ...input.verifyBip322 ? { verifyBip322: input.verifyBip322 } : {},
+        skipSenderVerification: !!input.skipSignatureVerification
+      });
+      workingScopes = r.scopes;
+    } catch (e) {
+      const msg = e.message ?? String(e);
+      if (/no matching recipient|no recipient|device_id/i.test(msg)) {
+        return err("E_SCOPES_UNREADABLE", msg);
+      }
+      return err("E_BAD_LOCK_ENVELOPE", msg);
+    }
+  } else {
+    workingScopes = env.scopes;
+  }
   let canonicalScopes;
   try {
-    for (const s of env.scopes) validateScope(parseScope(s), { mode: input.scopeMode ?? "strict" });
-    canonicalScopes = canonicalizeScopes(env.scopes);
+    for (const s of workingScopes) validateScope(parseScope(s), { mode: input.scopeMode ?? "strict" });
+    canonicalScopes = canonicalizeScopes(workingScopes);
   } catch (e) {
     const msg = e instanceof ScopeParseError ? e.message : e.message;
     return err("E_BAD_SCOPE_GRAMMAR", msg);
   }
   for (let i = 0; i < canonicalScopes.length; i++) {
-    if (env.scopes[i] !== canonicalScopes[i]) {
+    if (workingScopes[i] !== canonicalScopes[i]) {
       return err(
         "E_BAD_SCOPE_GRAMMAR",
-        `scope at index ${i} not in canonical form; expected ${canonicalScopes[i]} got ${env.scopes[i]}`
+        `scope at index ${i} not in canonical form; expected ${canonicalScopes[i]} got ${workingScopes[i]}`
       );
     }
   }
@@ -396,9 +505,10 @@ async function verifyDelegation(input) {
     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}`);
   }
+  const returnedEnvelope = env.scopes_encrypted !== void 0 ? { ...env, scopes: canonicalScopes } : env;
   return {
     ok: true,
-    envelope: env,
+    envelope: returnedEnvelope,
     canonicalMessage: reconstructedMessage,
     id: env.id
   };
@@ -406,15 +516,36 @@ async function verifyDelegation(input) {
 async function verifyAction(input) {
   const a = input.action;
   const d = input.delegation;
+  const chain = input.subdelegationChain ?? [];
+  const maxDepth = input.maxChainDepth ?? DEFAULT_MAX_CHAIN_DEPTH;
+  if (chain.length > maxDepth) {
+    return err(
+      "E_SUBDELEGATION_DEPTH_EXCEEDED",
+      `chain depth ${chain.length} exceeds maximum ${maxDepth}`
+    );
+  }
   const dr = await verifyDelegation({
     envelope: d,
     verifyBip322: input.verifyBip322,
     skipSignatureVerification: input.skipSignatureVerification,
     scopeMode: input.scopeMode,
-    skipTemporalCheck: true
+    skipTemporalCheck: true,
     // action window check dominates
+    ...input.decryptScopesWith ? { decryptScopesWith: input.decryptScopesWith } : {}
   });
   if (!dr.ok) return dr;
+  const rootHydrated = dr.envelope;
+  let parent = rootHydrated;
+  const hydratedChain = [];
+  for (const sub of chain) {
+    const hydrated = await hydrateSubdelegationScopes(sub, input);
+    if (!hydrated.ok) return hydrated;
+    const r = await verifyChainLink(hydrated.envelope, parent, input);
+    if (!r.ok) return r;
+    hydratedChain.push(hydrated.envelope);
+    parent = hydrated.envelope;
+  }
+  const leaf = hydratedChain.length > 0 ? hydratedChain[hydratedChain.length - 1] : rootHydrated;
   if (a.v !== ENVELOPE_VERSION) {
     return err("E_UNSUPPORTED_VERSION", `action version ${a.v} not supported`);
   }
@@ -439,25 +570,28 @@ async function verifyAction(input) {
     const ok = await input.verifyBip322(a.id, a.sig.value, a.signer.address);
     if (!ok) return err("E_BAD_ACTION_STAMP", "action BIP-322 signature did not verify");
   }
-  if (a.delegation_id !== d.id) {
-    return err("E_DELEGATION_MISMATCH", `action.delegation_id (${a.delegation_id}) != delegation.id (${d.id})`);
+  if (a.delegation_id !== leaf.id) {
+    return err("E_DELEGATION_MISMATCH", `action.delegation_id (${a.delegation_id}) != leaf.id (${leaf.id})`);
   }
-  if (a.signer.address !== d.agent.address) {
-    return err("E_AGENT_MISMATCH", `action signer (${a.signer.address}) != delegation.agent (${d.agent.address})`);
+  if (a.signer.address !== leaf.agent.address) {
+    return err("E_AGENT_MISMATCH", `action signer (${a.signer.address}) != leaf.agent (${leaf.agent.address})`);
   }
-  const issued = new Date(d.issued_at).getTime();
-  const expires = new Date(d.expires_at).getTime();
+  const issued = new Date(leaf.issued_at).getTime();
+  const expires = new Date(leaf.expires_at).getTime();
   const signed = new Date(a.signed_at).getTime();
   if (Number.isNaN(issued) || Number.isNaN(expires) || Number.isNaN(signed)) {
     return err("E_MALFORMED", "unparseable ISO 8601 timestamp");
   }
   if (signed < issued || signed >= expires) {
-    return err("E_OUT_OF_WINDOW", `action.signed_at ${a.signed_at} is outside delegation window [${d.issued_at}, ${d.expires_at})`);
+    return err("E_OUT_OF_WINDOW", `action.signed_at ${a.signed_at} is outside leaf window [${leaf.issued_at}, ${leaf.expires_at})`);
+  }
+  if (!leaf.scopes) {
+    return err("E_SCOPES_NEITHER_PROVIDED", "leaf has no plaintext scopes after hydration");
   }
   let exercised, accepted;
   try {
     exercised = canonicalizeScope(parseScope(a.scope_exercised));
-    const granted = d.scopes.map((s) => parseScope(s));
+    const granted = leaf.scopes.map((s) => parseScope(s));
     const exercisedParsed = parseScope(a.scope_exercised);
     validateScope(exercisedParsed, { mode: input.scopeMode ?? "strict" });
     accepted = granted.some((g) => isSubScope(exercisedParsed, g));
@@ -467,19 +601,22 @@ async function verifyAction(input) {
   }
   if (!accepted) return err("E_SCOPE_DENIED", `scope_exercised (${exercised}) not a sub-scope of any granted scope`);
   if (input.revocations && input.revocations.length > 0) {
-    for (const rev of input.revocations) {
-      if (rev.delegation_id !== d.id) continue;
-      const rr = await verifyRevocation({
-        envelope: rev,
-        delegation: d,
-        verifyBip322: input.verifyBip322,
-        skipSignatureVerification: input.skipSignatureVerification
-      });
-      if (!rr.ok) continue;
-      const effective = effectiveRevocationTime(rev, input.resolveAnchorBlockHeight);
-      const actionTime = actionEffectiveTime(a, input.resolveAnchorBlockHeight);
-      if (compareTimes(effective, actionTime) <= 0) {
-        return err("E_REVOKED", `delegation was revoked by ${rev.id} before action was signed`);
+    const allLinks = [rootHydrated, ...hydratedChain];
+    for (const link of allLinks) {
+      for (const rev of input.revocations) {
+        if (rev.delegation_id !== link.id) continue;
+        const rr = await verifyRevocation({
+          envelope: rev,
+          delegation: link,
+          verifyBip322: input.verifyBip322,
+          skipSignatureVerification: input.skipSignatureVerification
+        });
+        if (!rr.ok) continue;
+        const effective = effectiveRevocationTime(rev, input.resolveAnchorBlockHeight);
+        const actionTime = actionEffectiveTime(a, input.resolveAnchorBlockHeight);
+        if (compareTimes(effective, actionTime) <= 0) {
+          return err("E_REVOKED", `chain link ${link.id} was revoked by ${rev.id} before action was signed`);
+        }
       }
     }
   }
@@ -515,11 +652,56 @@ async function verifyAction(input) {
     envelope: a,
     canonicalMessage: reconstructedMessage,
     id: a.id,
-    delegation: d,
+    delegation: rootHydrated,
+    chain: hydratedChain,
     scopeExercised: exercised,
     anchor
   };
 }
+async function hydrateSubdelegationScopes(sub, input) {
+  if (sub.scopes !== void 0 && sub.scopes_encrypted !== void 0) {
+    return err(
+      "E_SCOPES_BOTH_PROVIDED",
+      "subdelegation carries both scopes and scopes_encrypted"
+    );
+  }
+  if (sub.scopes === void 0 && sub.scopes_encrypted === void 0) {
+    return err(
+      "E_SCOPES_NEITHER_PROVIDED",
+      "subdelegation carries neither scopes nor scopes_encrypted"
+    );
+  }
+  if (sub.scopes_encrypted === void 0) {
+    return { ok: true, envelope: sub };
+  }
+  if (sub.scopes_encrypted.from?.address !== sub.principal.address) {
+    return err(
+      "E_MALFORMED",
+      `subdelegation.scopes_encrypted.from.address (${sub.scopes_encrypted.from?.address}) does not match principal.address (${sub.principal.address})`
+    );
+  }
+  if (!input.decryptScopesWith) {
+    return err(
+      "E_SCOPES_UNREADABLE",
+      "subdelegation carries scopes_encrypted; no decryption key provided for the chain"
+    );
+  }
+  try {
+    const r = await unsealScopes({
+      envelope: sub.scopes_encrypted,
+      device: input.decryptScopesWith,
+      ...input.verifyBip322 ? { verifyBip322: input.verifyBip322 } : {},
+      skipSenderVerification: !!input.skipSignatureVerification
+    });
+    return { ok: true, envelope: { ...sub, scopes: r.scopes } };
+  } catch (e) {
+    const msg = e.message ?? String(e);
+    if (/no matching recipient|no recipient|device_id/i.test(msg)) {
+      return err("E_SCOPES_UNREADABLE", msg);
+    }
+    return err("E_BAD_LOCK_ENVELOPE", msg);
+  }
+}
 async function verifyRevocation(input) {
   const env = input.envelope;
   const d = input.delegation;
@@ -561,7 +743,10 @@ function checkDelegationShape(env) {
   if (!isHex64(env.id)) return err("E_MALFORMED", "id must be 64 lowercase hex chars");
   if (!env.principal?.address || env.principal.alg !== "bip322") return err("E_MALFORMED", "principal invalid");
   if (!env.agent?.address || env.agent.alg !== "bip322") return err("E_MALFORMED", "agent invalid");
-  if (!Array.isArray(env.scopes) || env.scopes.length === 0) return err("E_MALFORMED", "scopes must be non-empty array");
+  if (env.scopes !== void 0) {
+    if (!Array.isArray(env.scopes) || env.scopes.length === 0)
+      return err("E_MALFORMED", "scopes must be non-empty array");
+  }
   if (env.bond !== null) {
     if (!Number.isInteger(env.bond.sats) || env.bond.sats < 0) return err("E_MALFORMED", "bond.sats must be non-negative integer");
     if (!isHex64(env.bond.attestation_id)) return err("E_MALFORMED", "bond.attestation_id must be 64-hex");
@@ -599,6 +784,138 @@ function checkRevocationShape(env) {
   if (env.sig.pubkey !== env.signer.address) return err("E_MALFORMED", "sig.pubkey must equal signer.address");
   return null;
 }
+function checkSubdelegationShape(env) {
+  if (env.kind !== "agent-subdelegation") return err("E_MALFORMED", 'kind must be "agent-subdelegation"');
+  if (!isHex64(env.id)) return err("E_MALFORMED", "id must be 64 lowercase hex chars");
+  if (!isHex64(env.parent_id)) return err("E_MALFORMED", "parent_id must be 64-hex");
+  if (!env.principal?.address || env.principal.alg !== "bip322") return err("E_MALFORMED", "principal invalid");
+  if (!env.agent?.address || env.agent.alg !== "bip322") return err("E_MALFORMED", "agent invalid");
+  if (env.scopes !== void 0) {
+    if (!Array.isArray(env.scopes) || env.scopes.length === 0)
+      return err("E_MALFORMED", "scopes must be non-empty array");
+  }
+  if ("bond" in env && env.bond !== void 0) {
+    return err("E_MALFORMED", "sub-delegation envelopes MUST NOT carry a bond field");
+  }
+  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");
+  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;
+}
+async function verifyChainLink(s, parent, input) {
+  if (s.v !== ENVELOPE_VERSION) {
+    return err("E_UNSUPPORTED_VERSION", `subdelegation version ${s.v} not supported`);
+  }
+  const shape = checkSubdelegationShape(s);
+  if (shape) return shape;
+  if (!s.scopes) {
+    return err(
+      "E_SCOPES_NEITHER_PROVIDED",
+      "subdelegation has no plaintext scopes \u2014 caller must hydrate v1.2 envelopes before invoking verifyChainLink"
+    );
+  }
+  let canonicalScopesList;
+  try {
+    canonicalScopesList = canonicalizeScopes(s.scopes);
+  } catch (e) {
+    const msg = e instanceof ScopeParseError ? e.message : e.message;
+    return err("E_BAD_SCOPE_GRAMMAR", msg);
+  }
+  const canonInput = {
+    parent_id: s.parent_id,
+    principal: s.principal.address,
+    agent: s.agent.address,
+    scopes: canonicalScopesList,
+    issued_at: s.issued_at,
+    expires_at: s.expires_at,
+    nonce: s.nonce
+  };
+  const reconstructedId = computeSubdelegationId(canonInput);
+  if (reconstructedId !== s.id) {
+    return err("E_BAD_ID", `reconstructed subdelegation id (${reconstructedId}) does not match envelope id (${s.id})`);
+  }
+  let parsedScopes;
+  try {
+    parsedScopes = s.scopes.map((str) => parseScope(str));
+    for (const p of parsedScopes) validateScope(p, { mode: input.scopeMode ?? "strict" });
+  } catch (e) {
+    const msg = e instanceof ScopeParseError ? e.message : e.message;
+    return err("E_BAD_SCOPE_GRAMMAR", msg);
+  }
+  if (!input.skipSignatureVerification) {
+    if (!input.verifyBip322) return err("E_BAD_SIG", "no BIP-322 verifier supplied for subdelegation");
+    const ok = await input.verifyBip322(s.id, s.sig.value, s.principal.address);
+    if (!ok) return err("E_BAD_SIG", "subdelegation BIP-322 signature did not verify");
+  }
+  if (s.parent_id !== parent.id) {
+    return err(
+      "E_SUBDELEGATION_PRINCIPAL_MISMATCH",
+      `subdelegation.parent_id (${s.parent_id}) does not match parent envelope id (${parent.id})`
+    );
+  }
+  if (s.principal.address !== parent.agent.address) {
+    return err(
+      "E_SUBDELEGATION_PRINCIPAL_MISMATCH",
+      `subdelegation.principal (${s.principal.address}) does not match parent.agent (${parent.agent.address})`
+    );
+  }
+  const sIssued = new Date(s.issued_at).getTime();
+  const sExpires = new Date(s.expires_at).getTime();
+  const pIssued = new Date(parent.issued_at).getTime();
+  const pExpires = new Date(parent.expires_at).getTime();
+  if (Number.isNaN(sIssued) || Number.isNaN(sExpires) || Number.isNaN(pIssued) || Number.isNaN(pExpires)) {
+    return err("E_MALFORMED", "unparseable ISO 8601 timestamp in chain");
+  }
+  if (sExpires <= sIssued) {
+    return err("E_MALFORMED", "subdelegation expires_at must be > issued_at");
+  }
+  if (sIssued < pIssued || sExpires > pExpires) {
+    return err(
+      "E_SUBDELEGATION_EXPIRES_EXTENDED",
+      `subdelegation window [${s.issued_at}, ${s.expires_at}) is not contained in parent's [${parent.issued_at}, ${parent.expires_at})`
+    );
+  }
+  if (!parent.scopes) {
+    return err(
+      "E_SCOPES_NEITHER_PROVIDED",
+      "parent has no plaintext scopes \u2014 caller must hydrate v1.2 parents before invoking verifyChainLink"
+    );
+  }
+  const parentScopesParsed = parent.scopes.map((str) => parseScope(str));
+  for (let i = 0; i < parsedScopes.length; i++) {
+    const childScope = parsedScopes[i];
+    const containedBySomeParentScope = parentScopesParsed.some((p) => isSubScope(childScope, p));
+    if (!containedBySomeParentScope) {
+      return err(
+        "E_SUBDELEGATION_SCOPE_ESCALATED",
+        `subdelegation scope ${canonicalizeScope(childScope)} is not a sub-scope of any granted scope on the parent`
+      );
+    }
+  }
+  return {
+    ok: true,
+    envelope: s,
+    canonicalMessage: "",
+    // not populated for chain links; computeSubdelegationId is the binding form
+    id: s.id
+  };
+}
+async function verifySubdelegation(input) {
+  const hydrated = await hydrateSubdelegationScopes(input.envelope, input);
+  if (!hydrated.ok) return hydrated;
+  const r = await verifyChainLink(hydrated.envelope, input.parent, input);
+  if (!r.ok) return r;
+  if (!input.skipTemporalCheck) {
+    const now = (input.now ?? /* @__PURE__ */ new Date()).getTime();
+    const issued = new Date(input.envelope.issued_at).getTime();
+    const expires = new Date(input.envelope.expires_at).getTime();
+    if (now < issued) return err("E_NOT_YET_VALID", `subdelegation issued_at ${input.envelope.issued_at} is in the future`);
+    if (now >= expires) return err("E_EXPIRED", `subdelegation expires_at ${input.envelope.expires_at} is past`);
+  }
+  return r;
+}
 function actionEffectiveTime(a, resolve) {
   if (a.ots?.status === "confirmed") {
     const h = resolve ? resolve(a) : a.ots.block_height;
@@ -638,6 +955,7 @@ Object.defineProperty(exports, "hexEncode", {
   get: function () { return canonical.hexEncode; }
 });
 exports.AgentError = AgentError;
+exports.DEFAULT_MAX_CHAIN_DEPTH = DEFAULT_MAX_CHAIN_DEPTH;
 exports.ENVELOPE_VERSION = ENVELOPE_VERSION;
 exports.REGISTERED_SCOPES = REGISTERED_SCOPES;
 exports.ScopeParseError = ScopeParseError;
@@ -655,17 +973,26 @@ exports.canonicalizeScopes = canonicalizeScopes;
 exports.computeActionId = computeActionId;
 exports.computeDelegationId = computeDelegationId;
 exports.computeRevocationId = computeRevocationId;
+exports.computeSubdelegationId = computeSubdelegationId;
+exports.decodeScopesPayload = decodeScopesPayload;
 exports.delegationCanonicalBytes = delegationCanonicalBytes;
 exports.delegationCanonicalMessage = delegationCanonicalMessage;
+exports.encodeScopesPayload = encodeScopesPayload;
+exports.hasPrivateScopes = hasPrivateScopes;
 exports.isSubScope = isSubScope;
 exports.parseAndCanonicalizeScopes = parseAndCanonicalizeScopes;
 exports.parseScope = parseScope;
 exports.revocationCanonicalBytes = revocationCanonicalBytes;
 exports.revocationCanonicalMessage = revocationCanonicalMessage;
+exports.sealScopes = sealScopes;
 exports.sha256Hex = sha256Hex;
+exports.subdelegationCanonicalBytes = subdelegationCanonicalBytes;
+exports.subdelegationCanonicalMessage = subdelegationCanonicalMessage;
+exports.unsealScopes = unsealScopes;
 exports.validateScope = validateScope;
 exports.verifyAction = verifyAction;
 exports.verifyDelegation = verifyDelegation;
 exports.verifyRevocation = verifyRevocation;
+exports.verifySubdelegation = verifySubdelegation;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map