@orangecheck/agent-core 0.2.0 → 1.0.0

package/src/test-vectors.test.ts

@@ -217,6 +217,7 @@ describe('oc-agent-protocol test vectors', () => {
     const subdelegationEnvelopes = new Map<string, SubdelegationEnvelope>();
     for (const { data } of vectors) {
         if (isNegative(data)) continue;
+        if ((data as { private_scope?: unknown }).private_scope) continue;
         if (data.kind === 'delegation') {
             delegationEnvelopes.set(data.expected.id, data.expected.envelope);
         } else if (data.kind === 'subdelegation') {
@@ -226,6 +227,7 @@ describe('oc-agent-protocol test vectors', () => {
 
     for (const { name, data } of vectors) {
         if (isNegative(data)) continue;
+        if ((data as { private_scope?: unknown }).private_scope) continue;
         it(`${name} — canonical message reconstructs byte-identical`, () => {
             const msg = reconstructCanonical(data);
             expect(msg).toBe(data.expected.canonical_message);
@@ -367,7 +369,14 @@ function reconstructId(v: PositiveVector): string {
 // ─────────────────────────────────────────────────────────────────────────────
 
 describe('oc-agent-protocol negative test vectors', () => {
-    const negatives = vectors.filter(({ data }) => isNegative(data)) as {
+    // Filter out private-scope vectors — they have their own describe block
+    // because the round-trip path requires sealing first, not just verifying
+    // a pre-built envelope.
+    const negatives = vectors.filter(
+        ({ data }) =>
+            isNegative(data) &&
+            !(data as { private_scope?: unknown }).private_scope
+    ) as {
         name: string;
         data: NegativeVector;
     }[];
@@ -543,3 +552,178 @@ describe('oc-agent-protocol negative test vectors', () => {
         });
     }
 });
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Private-scope (v1.2) vectors — round-trip via sealScopes/verifyDelegation.
+// The OC Lock envelope uses random nonces, so byte-identical reproducibility
+// of the ciphertext is not asserted; what's pinned is the round-trip outcome.
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface PrivateScopeRecipientFixture {
+    address: string;
+    device_id: string;
+    device_pk: string;
+    device_secret: string;
+}
+
+interface PrivateScopeBaseInputs {
+    principal: string;
+    agent: string;
+    scopes_plaintext: string[];
+    recipients: PrivateScopeRecipientFixture[];
+    bond: { sats: number; attestation_id: string } | null;
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+}
+
+interface PrivateScopePositiveVector {
+    description: string;
+    kind: 'delegation';
+    private_scope: true;
+    inputs: PrivateScopeBaseInputs;
+    expected: {
+        verification_outcome: 'ACCEPT';
+        decrypted_scopes: string[];
+        verifier_uses_device_id: string;
+    };
+}
+
+interface PrivateScopeNegativeVector {
+    description: string;
+    kind: 'delegation';
+    private_scope: true;
+    negative: true;
+    inputs: PrivateScopeBaseInputs & {
+        verifier_holds_unrelated_key: {
+            device_id: string;
+            device_pk: string;
+            device_secret: string;
+        };
+    };
+    expected: {
+        verification_outcome: 'REJECT';
+        error_code: AgentErrorCode;
+    };
+}
+
+type PrivateScopeVector = PrivateScopePositiveVector | PrivateScopeNegativeVector;
+
+function isPrivateScopeVector(v: unknown): v is PrivateScopeVector {
+    return (
+        typeof v === 'object' &&
+        v !== null &&
+        (v as { private_scope?: unknown }).private_scope === true
+    );
+}
+
+describe('oc-agent-protocol private-scope vectors (v1.2)', () => {
+    const psVectors = vectors.filter(({ data }) =>
+        isPrivateScopeVector(data)
+    ) as { name: string; data: PrivateScopeVector }[];
+
+    if (psVectors.length === 0) {
+        it.skip('(no private-scope vectors found)', () => {});
+        return;
+    }
+
+    for (const { name, data } of psVectors) {
+        it(`${name} — ${data.expected.verification_outcome}`, async () => {
+            // Lazy-load to avoid pulling lock-core at module init time when no
+            // private-scope vectors are present.
+            const ps = await import('./private-scope.js');
+            const { hexDecode } = await import('@orangecheck/lock-crypto');
+
+            const sealed = await ps.sealScopes({
+                scopes: data.inputs.scopes_plaintext,
+                sender: {
+                    address: data.inputs.principal,
+                    signMessage: async () => 'AAAA',
+                },
+                recipients: data.inputs.recipients.map((r) => ({
+                    address: r.address,
+                    device_id: r.device_id,
+                    device_pk: r.device_pk,
+                })),
+            });
+
+            // Build the OC Agent envelope. Use the canonical (sorted) scopes
+            // so the id reconstructs cleanly.
+            const canonScopes = canonicalizeScopes(data.inputs.scopes_plaintext);
+            const canonInput = {
+                principal: data.inputs.principal,
+                agent: data.inputs.agent,
+                scopes: canonScopes,
+                bond_sats: data.inputs.bond?.sats ?? 0,
+                bond_attestation: data.inputs.bond?.attestation_id ?? 'none',
+                issued_at: data.inputs.issued_at,
+                expires_at: data.inputs.expires_at,
+                nonce: data.inputs.nonce,
+            };
+            const id = computeDelegationId(canonInput);
+            const env: DelegationEnvelope = {
+                v: 1,
+                kind: 'agent-delegation',
+                id,
+                principal: { address: data.inputs.principal, alg: 'bip322' },
+                agent: { address: data.inputs.agent, alg: 'bip322' },
+                scopes_encrypted: sealed,
+                bond: data.inputs.bond,
+                issued_at: data.inputs.issued_at,
+                expires_at: data.inputs.expires_at,
+                nonce: data.inputs.nonce,
+                revocation: { holders: ['principal'], ref: null },
+                sig: { alg: 'bip322', pubkey: data.inputs.principal, value: 'AAAA' },
+            };
+
+            if (data.expected.verification_outcome === 'ACCEPT') {
+                const positive = data as PrivateScopePositiveVector;
+                const recip = data.inputs.recipients.find(
+                    (r) => r.device_id === positive.expected.verifier_uses_device_id
+                );
+                if (!recip) {
+                    throw new Error(
+                        `vector ${name} names verifier_uses_device_id ${positive.expected.verifier_uses_device_id}, not in recipients`
+                    );
+                }
+                const r = await verifyDelegation({
+                    envelope: env,
+                    skipSignatureVerification: true,
+                    skipTemporalCheck: true,
+                    decryptScopesWith: {
+                        device_id: recip.device_id,
+                        secretKey: hexDecode(recip.device_secret),
+                    },
+                });
+                expect(r.ok).toBe(true);
+                if (r.ok) {
+                    expect(r.envelope.scopes).toEqual(
+                        canonicalizeScopes(positive.expected.decrypted_scopes)
+                    );
+                }
+            } else {
+                const negative = data as PrivateScopeNegativeVector;
+                const r = await verifyDelegation({
+                    envelope: env,
+                    skipSignatureVerification: true,
+                    skipTemporalCheck: true,
+                    decryptScopesWith: {
+                        device_id: negative.inputs.verifier_holds_unrelated_key.device_id,
+                        secretKey: hexDecode(
+                            negative.inputs.verifier_holds_unrelated_key.device_secret
+                        ),
+                    },
+                });
+                expect(r.ok).toBe(false);
+                if (!r.ok) {
+                    // Accept either E_SCOPES_UNREADABLE (preferred) or
+                    // E_BAD_LOCK_ENVELOPE (acceptable per harness_assertion).
+                    expect([
+                        'E_SCOPES_UNREADABLE',
+                        'E_BAD_LOCK_ENVELOPE',
+                    ]).toContain(r.code);
+                }
+            }
+        });
+    }
+});

package/src/types.ts

@@ -44,14 +44,59 @@ export interface DelegationRevocationRef {
     ref: string | null;
 }
 
+/**
+ * v1.2 private-scope mode: a wholesale OC Lock v2 LockEnvelope wrapping the
+ * canonical scope list as its payload. We re-import the LockEnvelope type
+ * structurally rather than depending on the @orangecheck/lock-core type — agent-
+ * core's type surface stays loose so verifiers can be authored in either an
+ * agent-only or full-family setup.
+ */
+export interface ScopesEncryptedEnvelope {
+    v: 2;
+    kind: 'identity';
+    id: string;
+    alg: { kem: 'x25519'; aead: 'aes-256-gcm'; kdf: 'hkdf-sha256' };
+    from: { address: string; attestation_id?: string };
+    recipients: Array<{
+        address: string;
+        device_id: string;
+        device_pk: string;
+        eph_pk: string;
+        wrapped_key: string;
+        nonce_kek: string;
+    }>;
+    ciphertext: string;
+    nonce_ct: string;
+    hint?: string;
+    created_at: string;
+    expires_at: string | null;
+    payment: unknown | null;
+    sig: { alg: 'bip322'; pubkey: string; value: string };
+}
+
 export interface DelegationEnvelope {
     v: typeof ENVELOPE_VERSION;
     kind: 'agent-delegation';
     id: string; // 64-hex sha256(canonical_message)
     principal: ActorRef;
     agent: ActorRef;
-    /** Sorted lexicographically in the canonical message; stored in sorted order on the envelope too. */
-    scopes: string[];
+    /**
+     * v1.0 / v1.1 public mode: sorted lexicographically in the canonical
+     * message; stored in sorted order on the envelope too.
+     *
+     * v1.2 private mode: this field is OMITTED from the envelope JSON;
+     * `scopes_encrypted` is set instead. After decryption, the recovered
+     * scope list takes this field's place in the in-memory envelope object
+     * for the remainder of verification.
+     */
+    scopes?: string[];
+    /**
+     * v1.2 private mode (PRIVATE-SCOPE.md §1.1): an OC Lock v2 envelope
+     * wrapping the canonical scope-list bytes as its payload, sealed to one
+     * or more recipients (typically the agent ± named verifiers). MUTUALLY
+     * EXCLUSIVE with `scopes`.
+     */
+    scopes_encrypted?: ScopesEncryptedEnvelope;
     bond: DelegationBond | null;
     issued_at: string; // ISO 8601 UTC
     expires_at: string; // ISO 8601 UTC
@@ -128,8 +173,13 @@ export interface SubdelegationEnvelope {
     principal: ActorRef;
     /** The recipient sub-agent. */
     agent: ActorRef;
-    /** Each scope MUST be a sub-scope of some scope on the parent. */
-    scopes: string[];
+    /**
+     * v1.0 / v1.1 public mode: each scope MUST be a sub-scope of some scope
+     * on the parent. v1.2 private mode: omitted; `scopes_encrypted` set.
+     */
+    scopes?: string[];
+    /** v1.2 private mode — same shape as the root delegation field. */
+    scopes_encrypted?: ScopesEncryptedEnvelope;
     issued_at: string; // ISO 8601 UTC; >= parent.issued_at
     expires_at: string; // ISO 8601 UTC; <= parent.expires_at
     nonce: string; // 32-hex random
@@ -200,7 +250,11 @@ export type AgentErrorCode =
     | 'E_SUBDELEGATION_DEPTH_EXCEEDED'
     | 'E_SUBDELEGATION_PRINCIPAL_MISMATCH'
     | 'E_SUBDELEGATION_EXPIRES_EXTENDED'
-    | 'E_SUBDELEGATION_SCOPE_ESCALATED';
+    | 'E_SUBDELEGATION_SCOPE_ESCALATED'
+    | 'E_SCOPES_BOTH_PROVIDED'
+    | 'E_SCOPES_NEITHER_PROVIDED'
+    | 'E_SCOPES_UNREADABLE'
+    | 'E_BAD_LOCK_ENVELOPE';
 
 export interface VerifyOk<T> {
     ok: true;