@orangecheck/agent-core 0.2.0 → 1.0.0

package/dist/index.mjs

@@ -1,6 +1,7 @@
 import { sha256 } from '@noble/hashes/sha256';
 import { hexEncode, canonicalize } from '@orangecheck/stamp-core/canonical';
 export { canonicalize, hexEncode } from '@orangecheck/stamp-core/canonical';
+import { seal, unseal } from '@orangecheck/lock-core';
 
 // src/types.ts
 var ENVELOPE_VERSION = 1;
@@ -351,6 +352,50 @@ function canonicalRevocationBytes(env) {
 function sha256Hex(bytes) {
   return hexEncode(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 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 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) {
@@ -366,19 +411,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]}`
       );
     }
   }
@@ -415,9 +504,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
   };
@@ -438,17 +528,23 @@ async function verifyAction(input) {
     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;
-  let parent = d;
+  const rootHydrated = dr.envelope;
+  let parent = rootHydrated;
+  const hydratedChain = [];
   for (const sub of chain) {
-    const r = await verifyChainLink(sub, parent, input);
+    const hydrated = await hydrateSubdelegationScopes(sub, input);
+    if (!hydrated.ok) return hydrated;
+    const r = await verifyChainLink(hydrated.envelope, parent, input);
     if (!r.ok) return r;
-    parent = sub;
+    hydratedChain.push(hydrated.envelope);
+    parent = hydrated.envelope;
   }
-  const leaf = chain.length > 0 ? chain[chain.length - 1] : d;
+  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`);
   }
@@ -488,6 +584,9 @@ 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 (!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));
@@ -501,7 +600,7 @@ 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) {
-    const allLinks = [d, ...chain];
+    const allLinks = [rootHydrated, ...hydratedChain];
     for (const link of allLinks) {
       for (const rev of input.revocations) {
         if (rev.delegation_id !== link.id) continue;
@@ -552,12 +651,56 @@ async function verifyAction(input) {
     envelope: a,
     canonicalMessage: reconstructedMessage,
     id: a.id,
-    delegation: d,
-    chain,
+    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;
@@ -599,7 +742,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");
@@ -643,7 +789,10 @@ function checkSubdelegationShape(env) {
   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 (!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 ("bond" in env && env.bond !== void 0) {
     return err("E_MALFORMED", "sub-delegation envelopes MUST NOT carry a bond field");
   }
@@ -660,6 +809,12 @@ async function verifyChainLink(s, parent, input) {
   }
   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);
@@ -721,6 +876,12 @@ async function verifyChainLink(s, parent, input) {
       `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];
@@ -741,7 +902,9 @@ async function verifyChainLink(s, parent, input) {
   };
 }
 async function verifySubdelegation(input) {
-  const r = await verifyChainLink(input.envelope, input.parent, 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();
@@ -782,6 +945,6 @@ function isIsoUtc(s) {
   return typeof s === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(s);
 }
 
-export { AgentError, DEFAULT_MAX_CHAIN_DEPTH, ENVELOPE_VERSION, REGISTERED_SCOPES, ScopeParseError, actionCanonicalBytes, actionCanonicalMessage, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScope, canonicalizeScopeString, canonicalizeScopes, computeActionId, computeDelegationId, computeRevocationId, computeSubdelegationId, delegationCanonicalBytes, delegationCanonicalMessage, isSubScope, parseAndCanonicalizeScopes, parseScope, revocationCanonicalBytes, revocationCanonicalMessage, sha256Hex, subdelegationCanonicalBytes, subdelegationCanonicalMessage, validateScope, verifyAction, verifyDelegation, verifyRevocation, verifySubdelegation };
+export { AgentError, DEFAULT_MAX_CHAIN_DEPTH, ENVELOPE_VERSION, REGISTERED_SCOPES, ScopeParseError, actionCanonicalBytes, actionCanonicalMessage, canonicalActionBytes, canonicalDelegationBytes, canonicalRevocationBytes, canonicalizeAction, canonicalizeDelegation, canonicalizeRevocation, canonicalizeScope, canonicalizeScopeString, canonicalizeScopes, computeActionId, computeDelegationId, computeRevocationId, computeSubdelegationId, decodeScopesPayload, delegationCanonicalBytes, delegationCanonicalMessage, encodeScopesPayload, hasPrivateScopes, isSubScope, parseAndCanonicalizeScopes, parseScope, revocationCanonicalBytes, revocationCanonicalMessage, sealScopes, sha256Hex, subdelegationCanonicalBytes, subdelegationCanonicalMessage, unsealScopes, validateScope, verifyAction, verifyDelegation, verifyRevocation, verifySubdelegation };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map