@orangecheck/agent-core 0.2.0 → 1.0.0

package/src/verify.ts

@@ -14,6 +14,7 @@ import {
     revocationCanonicalBytes,
     revocationCanonicalMessage,
 } from './canonical.js';
+import { unsealScopes } from './private-scope.js';
 import {
     canonicalizeScope,
     isSubScope,
@@ -68,6 +69,16 @@ export interface VerifyDelegationInput extends VerifyBase {
     now?: Date;
     /** Skip temporal checks entirely (useful for inspecting historical envelopes). */
     skipTemporalCheck?: boolean;
+    /**
+     * v1.2 private-scope decryption key. When the envelope carries
+     * `scopes_encrypted`, the verifier MUST supply a device key matching one
+     * of the recipient entries to recover the plaintext scope list. Without
+     * this, verification returns `E_SCOPES_UNREADABLE`.
+     */
+    decryptScopesWith?: {
+        device_id: string;
+        secretKey: Uint8Array;
+    };
 }
 
 export async function verifyDelegation(input: VerifyDelegationInput): Promise<VerifyDelegationResult> {
@@ -80,22 +91,86 @@ export async function verifyDelegation(input: VerifyDelegationInput): Promise<Ve
     const shape = checkDelegationShape(env);
     if (shape) return shape;
 
+    // ─── v1.2 PRE-VERIFICATION (PRIVATE-SCOPE.md §2 steps P1–P6) ───────────
+    // Steps P1 / P2: mutual exclusion + presence.
+    if (env.scopes !== undefined && env.scopes_encrypted !== undefined) {
+        return err(
+            'E_SCOPES_BOTH_PROVIDED',
+            'envelope carries both scopes and scopes_encrypted; pick one'
+        );
+    }
+    if (env.scopes === undefined && env.scopes_encrypted === undefined) {
+        return err(
+            'E_SCOPES_NEITHER_PROVIDED',
+            'envelope carries neither scopes nor scopes_encrypted'
+        );
+    }
+
+    // The plaintext scope list. Either copied from env.scopes (public mode)
+    // or recovered by decrypting env.scopes_encrypted (private mode).
+    let workingScopes: string[];
+
+    if (env.scopes_encrypted !== undefined) {
+        // Step P3: issuer binding — the inner Lock envelope's `from.address`
+        // must match the OC Agent envelope's principal.
+        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})`
+            );
+        }
+        // Step P5: decryption capability.
+        if (!input.decryptScopesWith) {
+            return err(
+                'E_SCOPES_UNREADABLE',
+                'envelope carries scopes_encrypted; no decryption key provided'
+            );
+        }
+        // Step P6: decrypt. Step P4 (inner-sig verify) is handled inside
+        // unsealScopes via the same BIP-322 verifier — but only when
+        // skipSignatureVerification is false.
+        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 as Error).message ?? String(e);
+            // Distinguish "I had a key but the cryptographic operation failed
+            // (bad envelope)" from "I had no matching recipient" — the latter
+            // is the more common case and gets E_SCOPES_UNREADABLE; the
+            // former gets E_BAD_LOCK_ENVELOPE.
+            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!;
+    }
+
+    // ─── Standard verification (SPEC.md §8.1) ──────────────────────────────
     // Scope grammar.
     let canonicalScopes: string[];
     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 as Error).message;
         return err('E_BAD_SCOPE_GRAMMAR', msg);
     }
 
-    // The envelope's `scopes` array must already be in canonical sorted order.
+    // In public mode the envelope's `scopes` array must already be in
+    // canonical sorted order. (Private mode: the decrypted plaintext is
+    // canonicalized at seal time, so this loop is a no-op for it.)
     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]}`
             );
         }
     }
@@ -139,9 +214,17 @@ export async function verifyDelegation(input: VerifyDelegationInput): Promise<Ve
         if (now >= expires) return err('E_EXPIRED', `delegation expired at ${env.expires_at}`);
     }
 
+    // In private mode, return a hydrated envelope that includes the recovered
+    // plaintext scopes so callers (verifyAction's chain walker, web-app
+    // consumers) don't have to repeat the decryption.
+    const returnedEnvelope: DelegationEnvelope =
+        env.scopes_encrypted !== undefined
+            ? { ...env, scopes: canonicalScopes }
+            : env;
+
     return {
         ok: true,
-        envelope: env,
+        envelope: returnedEnvelope,
         canonicalMessage: reconstructedMessage,
         id: env.id,
     };
@@ -181,6 +264,17 @@ export interface VerifyActionInput extends VerifyBase {
     verifyOtsAnchor?: (proofB64: string, blockHeight: number, blockHash: string) => Promise<boolean>;
     /** If action and revocation are both OTS-anchored, pass a function that returns the comparable block height of each via proof parsing. Defaults: use envelope.ots.block_height. */
     resolveAnchorBlockHeight?: (env: ActionEnvelope | RevocationEnvelope) => number | null;
+    /**
+     * v1.2 private-scope decryption key. Applied to the root delegation AND
+     * every subdelegation in the chain that carries `scopes_encrypted`. If a
+     * link is private-mode and no key matches its recipients, verification
+     * fails E_SCOPES_UNREADABLE — the chain's transitive narrowing cannot be
+     * checked without the plaintext.
+     */
+    decryptScopesWith?: {
+        device_id: string;
+        secretKey: Uint8Array;
+    };
 }
 
 export async function verifyAction(input: VerifyActionInput): Promise<VerifyActionResult> {
@@ -197,25 +291,38 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         );
     }
 
-    // 1. First verify the root delegation.
+    // 1. First verify the root delegation. verifyDelegation handles v1.2
+    //    private-scope hydration internally — when the root is private-mode,
+    //    the returned envelope already has `scopes` populated from the
+    //    decrypted plaintext.
     const dr = await verifyDelegation({
         envelope: d,
         verifyBip322: input.verifyBip322,
         skipSignatureVerification: input.skipSignatureVerification,
         scopeMode: input.scopeMode,
         skipTemporalCheck: true, // action window check dominates
+        ...(input.decryptScopesWith ? { decryptScopesWith: input.decryptScopesWith } : {}),
     });
     if (!dr.ok) return dr;
+    const rootHydrated: DelegationEnvelope = dr.envelope;
 
     // 1b. Walk the sub-delegation chain (SUB-DELEGATION.md §2.2 step 3).
-    let parent: ChainLink = d;
+    //     Each link may independently be private-mode; we hydrate it before
+    //     handing it to verifyChainLink so the chain walker sees plaintext
+    //     scopes uniformly.
+    let parent: ChainLink = rootHydrated;
+    const hydratedChain: SubdelegationEnvelope[] = [];
     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;
     }
     /** The envelope `action.delegation_id` should cite (root if no chain, leaf otherwise). */
-    const leaf: ChainLink = chain.length > 0 ? chain[chain.length - 1]! : d;
+    const leaf: ChainLink =
+        hydratedChain.length > 0 ? hydratedChain[hydratedChain.length - 1]! : rootHydrated;
 
     // 2. Core action checks.
     if (a.v !== ENVELOPE_VERSION) {
@@ -266,6 +373,12 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
     }
 
     // 5. Scope containment — against the leaf's granted set.
+    //    Leaf is post-hydration, so `scopes` is guaranteed populated. The
+    //    runtime guard satisfies the type checker and would only fire if a
+    //    caller bypassed the hydration path.
+    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));
@@ -283,7 +396,7 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
     //    (root + every subdelegation). Per SUB-DELEGATION.md §2.2 step 5, a
     //    revocation against ANY link invalidates the action.
     if (input.revocations && input.revocations.length > 0) {
-        const allLinks: ChainLink[] = [d, ...chain];
+        const allLinks: ChainLink[] = [rootHydrated, ...hydratedChain];
         for (const link of allLinks) {
             for (const rev of input.revocations) {
                 if (rev.delegation_id !== link.id) continue;
@@ -342,13 +455,69 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         envelope: a,
         canonicalMessage: reconstructedMessage,
         id: a.id,
-        delegation: d,
-        chain,
+        delegation: rootHydrated,
+        chain: hydratedChain,
         scopeExercised: exercised,
         anchor,
     };
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// v1.2 chain-link hydration — decrypt scopes_encrypted on subdelegations
+// before passing them to the chain walker so all containment checks operate
+// on plaintext.
+// ─────────────────────────────────────────────────────────────────────────────
+
+async function hydrateSubdelegationScopes(
+    sub: SubdelegationEnvelope,
+    input: VerifyBase & {
+        decryptScopesWith?: { device_id: string; secretKey: Uint8Array };
+    }
+): Promise<{ ok: true; envelope: SubdelegationEnvelope } | VerifyErrResult> {
+    if (sub.scopes !== undefined && sub.scopes_encrypted !== undefined) {
+        return err(
+            'E_SCOPES_BOTH_PROVIDED',
+            'subdelegation carries both scopes and scopes_encrypted'
+        );
+    }
+    if (sub.scopes === undefined && sub.scopes_encrypted === undefined) {
+        return err(
+            'E_SCOPES_NEITHER_PROVIDED',
+            'subdelegation carries neither scopes nor scopes_encrypted'
+        );
+    }
+    if (sub.scopes_encrypted === undefined) {
+        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 as Error).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);
+    }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Revocation (SPEC §9, §8 transitive)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -417,7 +586,15 @@ function checkDelegationShape(env: DelegationEnvelope): VerifyDelegationResult |
     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');
+    // v1.2: scopes OR scopes_encrypted (exactly one). Mutual exclusion +
+    // presence checks are performed by the verify-time PRE-VERIFICATION block
+    // (PRIVATE-SCOPE.md §2 steps P1–P2) so they can return their own error
+    // codes (E_SCOPES_BOTH_PROVIDED / E_SCOPES_NEITHER_PROVIDED) rather than
+    // collapsing into E_MALFORMED.
+    if (env.scopes !== undefined) {
+        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');
@@ -464,7 +641,13 @@ function checkSubdelegationShape(env: SubdelegationEnvelope): VerifySubdelegatio
     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');
+    // v1.2: scopes OR scopes_encrypted (post-hydration the chain walker
+    // always sees `scopes` populated). Mutual exclusion + presence checked
+    // by hydrateSubdelegationScopes.
+    if (env.scopes !== undefined) {
+        if (!Array.isArray(env.scopes) || env.scopes.length === 0)
+            return err('E_MALFORMED', 'scopes must be non-empty array');
+    }
     // Sub-delegations MUST NOT carry a bond field (SUB-DELEGATION.md §1.3).
     if ('bond' in env && (env as { bond?: unknown }).bond !== undefined) {
         return err('E_MALFORMED', 'sub-delegation envelopes MUST NOT carry a bond field');
@@ -502,6 +685,16 @@ async function verifyChainLink(
     const shape = checkSubdelegationShape(s);
     if (shape) return shape;
 
+    // verifyChainLink expects post-hydration scopes (callers run
+    // hydrateSubdelegationScopes upfront). The runtime guard makes the
+    // type-checker happy and protects against bypass.
+    if (!s.scopes) {
+        return err(
+            'E_SCOPES_NEITHER_PROVIDED',
+            'subdelegation has no plaintext scopes — caller must hydrate v1.2 envelopes before invoking verifyChainLink'
+        );
+    }
+
     // Step 3a: canonical id.
     let canonicalScopesList: string[];
     try {
@@ -574,6 +767,12 @@ async function verifyChainLink(
     }
 
     // Step 3g: scope containment (transitive narrowing).
+    if (!parent.scopes) {
+        return err(
+            'E_SCOPES_NEITHER_PROVIDED',
+            'parent has no plaintext scopes — 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]!;
@@ -600,12 +799,25 @@ async function verifyChainLink(
 
 export interface VerifySubdelegationInput extends VerifyBase {
     envelope: SubdelegationEnvelope;
-    /** The immediate parent envelope. Required for linkage / containment checks. */
+    /**
+     * The immediate parent envelope. Required for linkage / containment checks.
+     * If the parent is itself v1.2 private-mode (`scopes_encrypted`) the caller
+     * MUST pre-hydrate it (e.g., via verifyDelegation's returned envelope) —
+     * the chain walker reads `parent.scopes` directly.
+     */
     parent: ChainLink;
     /** Skip the "now ∈ [issued, expires)" check. Useful for inspection. */
     skipTemporalCheck?: boolean;
     /** Defaults to new Date(). */
     now?: Date;
+    /**
+     * v1.2 private-scope decryption key for the subdelegation envelope itself.
+     * Not used for the parent — the caller hydrates the parent.
+     */
+    decryptScopesWith?: {
+        device_id: string;
+        secretKey: Uint8Array;
+    };
 }
 
 /**
@@ -617,7 +829,11 @@ export interface VerifySubdelegationInput extends VerifyBase {
 export async function verifySubdelegation(
     input: VerifySubdelegationInput
 ): Promise<VerifySubdelegationResult> {
-    const r = await verifyChainLink(input.envelope, input.parent, input);
+    // v1.2: hydrate private-mode envelopes before chain-link checks so
+    // the walker uniformly reads plaintext scopes.
+    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) {