@orangecheck/agent-core 0.1.0 → 0.3.0

package/src/test-vectors.test.ts

@@ -12,27 +12,38 @@ import {
     computeActionId,
     computeDelegationId,
     computeRevocationId,
+    computeSubdelegationId,
     delegationCanonicalMessage,
     revocationCanonicalMessage,
+    subdelegationCanonicalMessage,
 } from './canonical.js';
-import { verifyAction, verifyDelegation, verifyRevocation } from './verify.js';
+import { parseScope, ScopeParseError } from './scope.js';
+import { verifyAction, verifyDelegation, verifyRevocation, verifySubdelegation } from './verify.js';
 import type {
     ActionEnvelope,
+    AgentErrorCode,
     DelegationEnvelope,
     RevocationEnvelope,
+    SubdelegationEnvelope,
 } from './types.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const VECTORS_DIR = resolve(__dirname, '..', '..', '..', 'oc-agent-protocol', 'test-vectors');
+const VECTORS_DIR =
+    process.env.OC_AGENT_VECTORS_DIR ??
+    resolve(__dirname, '..', '..', '..', 'oc-agent-protocol', 'test-vectors');
 
 interface BaseVector {
     description: string;
-    kind: 'delegation' | 'action' | 'revocation';
+    kind: 'delegation' | 'action' | 'revocation' | 'subdelegation';
     expected: {
         canonical_message: string;
         canonical_message_bytes_len: number;
         id: string;
-        envelope: DelegationEnvelope | ActionEnvelope | RevocationEnvelope;
+        envelope:
+            | DelegationEnvelope
+            | ActionEnvelope
+            | RevocationEnvelope
+            | SubdelegationEnvelope;
     };
 }
 
@@ -75,7 +86,106 @@ interface RevocationVector extends BaseVector {
     expected: BaseVector['expected'] & { envelope: RevocationEnvelope };
 }
 
-type Vector = DelegationVector | ActionVector | RevocationVector;
+interface SubdelegationVector extends BaseVector {
+    kind: 'subdelegation';
+    inputs: {
+        parent_id: string;
+        principal: string;
+        agent: string;
+        scopes: string[];
+        issued_at: string;
+        expires_at: string;
+        nonce: string;
+    };
+    expected: BaseVector['expected'] & { envelope: SubdelegationEnvelope };
+}
+
+// Negative vectors carry "negative": true at the top level and document an
+// expected verifier rejection (SPEC §11 error code) instead of a canonical-
+// message round-trip.
+interface NegativeVectorBase {
+    description: string;
+    kind: 'delegation' | 'action' | 'revocation';
+    negative: true;
+    expected: {
+        verification_outcome: 'REJECT';
+        error_code: AgentErrorCode;
+        spec_reference: string;
+        rejection_reason: string;
+    };
+}
+
+interface NegativeActionVector extends NegativeVectorBase {
+    kind: 'action';
+    inputs: {
+        address: string;
+        content_hash: string;
+        content_length: number;
+        content_mime: string;
+        signed_at: string;
+        delegation_id: string;
+        scope_exercised: string;
+        content_ref?: string | null;
+        ots?: unknown;
+    };
+}
+
+interface NegativeRevocationVector extends NegativeVectorBase {
+    kind: 'revocation';
+    inputs: {
+        address: string;
+        delegation_id: string;
+        reason: string;
+        signed_at: string;
+    };
+}
+
+interface NegativeDelegationVector extends NegativeVectorBase {
+    kind: 'delegation';
+    inputs: {
+        principal: string;
+        agent: string;
+        scopes: string[];
+        bond: { sats: number; attestation_id: string } | null;
+        issued_at: string;
+        expires_at: string;
+        nonce: string;
+    };
+    additional_malformed_examples_for_implementer_smoke_tests?: {
+        scope: string;
+        why: string;
+    }[];
+}
+
+interface NegativeSubdelegationVector extends NegativeVectorBase {
+    kind: 'subdelegation';
+    inputs: {
+        parent_id: string;
+        principal: string;
+        agent: string;
+        scopes: string[];
+        issued_at: string;
+        expires_at: string;
+        nonce: string;
+    };
+}
+
+type NegativeVector =
+    | NegativeActionVector
+    | NegativeRevocationVector
+    | NegativeDelegationVector
+    | NegativeSubdelegationVector;
+
+type Vector =
+    | DelegationVector
+    | ActionVector
+    | RevocationVector
+    | SubdelegationVector
+    | NegativeVector;
+
+function isNegative(v: Vector): v is NegativeVector {
+    return 'negative' in v && v.negative === true;
+}
 
 async function loadVectors(): Promise<{ name: string; data: Vector }[]> {
     try {
@@ -100,16 +210,22 @@ describe('oc-agent-protocol test vectors', () => {
         return;
     }
 
-    // First pass: the vectors can cross-reference each other (action cites delegation id).
-    // We'll need the envelopes keyed for the verifyAction tests.
+    // First pass: the vectors can cross-reference each other (action cites delegation id;
+    // subdelegation cites parent id which may be a root or another sub).
+    // Key both kinds so chain walking works.
     const delegationEnvelopes = new Map<string, DelegationEnvelope>();
+    const subdelegationEnvelopes = new Map<string, SubdelegationEnvelope>();
     for (const { data } of vectors) {
+        if (isNegative(data)) continue;
         if (data.kind === 'delegation') {
             delegationEnvelopes.set(data.expected.id, data.expected.envelope);
+        } else if (data.kind === 'subdelegation') {
+            subdelegationEnvelopes.set(data.expected.id, data.expected.envelope);
         }
     }
 
     for (const { name, data } of vectors) {
+        if (isNegative(data)) continue;
         it(`${name} — canonical message reconstructs byte-identical`, () => {
             const msg = reconstructCanonical(data);
             expect(msg).toBe(data.expected.canonical_message);
@@ -143,7 +259,7 @@ describe('oc-agent-protocol test vectors', () => {
                     skipSignatureVerification: true,
                 });
                 expect(r.ok).toBe(true);
-            } else {
+            } else if (data.kind === 'revocation') {
                 const delegation = delegationEnvelopes.get(data.inputs.delegation_id);
                 if (!delegation) {
                     throw new Error(`revocation vector ${name} references missing delegation ${data.inputs.delegation_id}`);
@@ -154,12 +270,36 @@ describe('oc-agent-protocol test vectors', () => {
                     skipSignatureVerification: true,
                 });
                 expect(r.ok).toBe(true);
+            } else {
+                // subdelegation — parent may be a root delegation or another subdelegation.
+                const parentId = data.inputs.parent_id;
+                const parent =
+                    delegationEnvelopes.get(parentId) ??
+                    subdelegationEnvelopes.get(parentId);
+                if (!parent) {
+                    throw new Error(
+                        `subdelegation vector ${name} references missing parent ${parentId}`
+                    );
+                }
+                const r = await verifySubdelegation({
+                    envelope: data.expected.envelope,
+                    parent,
+                    skipSignatureVerification: true,
+                    skipTemporalCheck: true,
+                });
+                expect(r.ok).toBe(true);
             }
         });
     }
 });
 
-function reconstructCanonical(v: Vector): string {
+type PositiveVector =
+    | DelegationVector
+    | ActionVector
+    | RevocationVector
+    | SubdelegationVector;
+
+function reconstructCanonical(v: PositiveVector): string {
     if (v.kind === 'delegation') {
         // Canonicalize each scope (constraints sorted by key) then sort the list.
         const canonical = canonicalizeScopes(v.inputs.scopes);
@@ -177,10 +317,23 @@ function reconstructCanonical(v: Vector): string {
     if (v.kind === 'action') {
         return actionCanonicalMessage(v.inputs);
     }
-    return revocationCanonicalMessage(v.inputs);
+    if (v.kind === 'revocation') {
+        return revocationCanonicalMessage(v.inputs);
+    }
+    // subdelegation
+    const canonical = canonicalizeScopes(v.inputs.scopes);
+    return subdelegationCanonicalMessage({
+        parent_id: v.inputs.parent_id,
+        principal: v.inputs.principal,
+        agent: v.inputs.agent,
+        scopes: canonical,
+        issued_at: v.inputs.issued_at,
+        expires_at: v.inputs.expires_at,
+        nonce: v.inputs.nonce,
+    });
 }
 
-function reconstructId(v: Vector): string {
+function reconstructId(v: PositiveVector): string {
     if (v.kind === 'delegation') {
         const canonical = canonicalizeScopes(v.inputs.scopes);
         return computeDelegationId({
@@ -195,5 +348,198 @@ function reconstructId(v: Vector): string {
         });
     }
     if (v.kind === 'action') return computeActionId(v.inputs);
-    return computeRevocationId(v.inputs);
+    if (v.kind === 'revocation') return computeRevocationId(v.inputs);
+    // subdelegation
+    const canonical = canonicalizeScopes(v.inputs.scopes);
+    return computeSubdelegationId({
+        parent_id: v.inputs.parent_id,
+        principal: v.inputs.principal,
+        agent: v.inputs.agent,
+        scopes: canonical,
+        issued_at: v.inputs.issued_at,
+        expires_at: v.inputs.expires_at,
+        nonce: v.inputs.nonce,
+    });
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Negative vectors — verifier MUST reject with the declared error code.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('oc-agent-protocol negative test vectors', () => {
+    const negatives = vectors.filter(({ data }) => isNegative(data)) as {
+        name: string;
+        data: NegativeVector;
+    }[];
+
+    if (negatives.length === 0) {
+        it.skip('(no negative vectors found)', () => {});
+        return;
+    }
+
+    // Need positive delegation envelopes to feed verifyAction / verifyRevocation
+    // for the cross-referenced negative vectors.
+    const delegationEnvelopes = new Map<string, DelegationEnvelope>();
+    for (const { data } of vectors) {
+        if (!isNegative(data) && data.kind === 'delegation') {
+            delegationEnvelopes.set(data.expected.id, data.expected.envelope);
+        }
+    }
+
+    for (const { name, data } of negatives) {
+        it(`${name} — verifier rejects with ${data.expected.error_code}`, async () => {
+            if (data.kind === 'action') {
+                const v = data as NegativeActionVector;
+                const delegation = delegationEnvelopes.get(v.inputs.delegation_id);
+                if (!delegation) {
+                    throw new Error(
+                        `negative action vector ${name} cites missing delegation ${v.inputs.delegation_id}`
+                    );
+                }
+                // Build a syntactically well-formed action envelope from the
+                // inputs (the rejection here is semantic — scope / window —
+                // not structural). The id MUST be the real sha256(canonical)
+                // or the verifier will short-circuit with E_BAD_ID before
+                // reaching the rule we're actually testing.
+                const realId = computeActionId({
+                    address: v.inputs.address,
+                    content_hash: v.inputs.content_hash,
+                    content_length: v.inputs.content_length,
+                    content_mime: v.inputs.content_mime,
+                    signed_at: v.inputs.signed_at,
+                    delegation_id: v.inputs.delegation_id,
+                    scope_exercised: v.inputs.scope_exercised,
+                });
+                const action: ActionEnvelope = {
+                    v: 1,
+                    kind: 'agent-action',
+                    id: realId,
+                    content: {
+                        hash: v.inputs.content_hash,
+                        length: v.inputs.content_length,
+                        mime: v.inputs.content_mime,
+                        ref: v.inputs.content_ref ?? null,
+                    },
+                    signer: { address: v.inputs.address, alg: 'bip322' },
+                    signed_at: v.inputs.signed_at,
+                    delegation_id: v.inputs.delegation_id,
+                    scope_exercised: v.inputs.scope_exercised,
+                    ots: null,
+                    sig: { alg: 'bip322', pubkey: v.inputs.address, value: 'AAAA' },
+                };
+                const r = await verifyAction({
+                    action,
+                    delegation,
+                    skipSignatureVerification: true,
+                });
+                expect(r.ok).toBe(false);
+                if (!r.ok) {
+                    // v07 specifically allows either E_OUT_OF_WINDOW or E_EXPIRED
+                    // since both fire for an action signed past the delegation's
+                    // expires_at; harness_assertion documents this.
+                    if (
+                        v.expected.error_code === 'E_OUT_OF_WINDOW' &&
+                        r.code === 'E_EXPIRED'
+                    ) {
+                        // accept the alternate code
+                    } else {
+                        expect(r.code).toBe(v.expected.error_code);
+                    }
+                }
+            } else if (data.kind === 'revocation') {
+                const v = data as NegativeRevocationVector;
+                const delegation = delegationEnvelopes.get(v.inputs.delegation_id);
+                if (!delegation) {
+                    throw new Error(
+                        `negative revocation vector ${name} cites missing delegation ${v.inputs.delegation_id}`
+                    );
+                }
+                const realRevId = computeRevocationId({
+                    address: v.inputs.address,
+                    delegation_id: v.inputs.delegation_id,
+                    reason: v.inputs.reason,
+                    signed_at: v.inputs.signed_at,
+                });
+                const revocation: RevocationEnvelope = {
+                    v: 1,
+                    kind: 'agent-revocation',
+                    id: realRevId,
+                    delegation_id: v.inputs.delegation_id,
+                    signer: { address: v.inputs.address, alg: 'bip322' },
+                    reason: v.inputs.reason,
+                    signed_at: v.inputs.signed_at,
+                    ots: null,
+                    sig: { alg: 'bip322', pubkey: v.inputs.address, value: 'AAAA' },
+                };
+                const r = await verifyRevocation({
+                    envelope: revocation,
+                    delegation,
+                    skipSignatureVerification: true,
+                });
+                expect(r.ok).toBe(false);
+                if (!r.ok) expect(r.code).toBe(v.expected.error_code);
+            } else if (data.kind === 'delegation') {
+                // Delegation negative vectors target the §7.1 grammar parser
+                // directly — that's where E_BAD_SCOPE_GRAMMAR fires per
+                // SPEC §8.1 step 4. Asserting parseScope throws is the
+                // right level of rigor.
+                const v = data as NegativeDelegationVector;
+                expect(v.expected.error_code).toBe('E_BAD_SCOPE_GRAMMAR');
+                for (const s of v.inputs.scopes) {
+                    expect(() => parseScope(s)).toThrow(ScopeParseError);
+                }
+                for (const ex of v.additional_malformed_examples_for_implementer_smoke_tests ??
+                    []) {
+                    expect(
+                        () => parseScope(ex.scope),
+                        `additional malformed example: ${ex.why}`
+                    ).toThrow(ScopeParseError);
+                }
+            } else if (data.kind === 'subdelegation') {
+                // v12, v13, v14 — chain-link checks via verifySubdelegation.
+                // Build a structurally valid subdelegation envelope from inputs
+                // (the rejection here is semantic — scope / window / linkage —
+                // not structural) and feed it to verifySubdelegation against the
+                // root delegation vector.
+                const v = data as NegativeSubdelegationVector;
+                const parent = delegationEnvelopes.get(v.inputs.parent_id);
+                if (!parent) {
+                    throw new Error(
+                        `negative subdelegation vector ${name} references missing parent ${v.inputs.parent_id}`
+                    );
+                }
+                const realId = computeSubdelegationId({
+                    parent_id: v.inputs.parent_id,
+                    principal: v.inputs.principal,
+                    agent: v.inputs.agent,
+                    scopes: canonicalizeScopes(v.inputs.scopes),
+                    issued_at: v.inputs.issued_at,
+                    expires_at: v.inputs.expires_at,
+                    nonce: v.inputs.nonce,
+                });
+                const sub: SubdelegationEnvelope = {
+                    v: 1,
+                    kind: 'agent-subdelegation',
+                    id: realId,
+                    parent_id: v.inputs.parent_id,
+                    principal: { address: v.inputs.principal, alg: 'bip322' },
+                    agent: { address: v.inputs.agent, alg: 'bip322' },
+                    scopes: v.inputs.scopes,
+                    issued_at: v.inputs.issued_at,
+                    expires_at: v.inputs.expires_at,
+                    nonce: v.inputs.nonce,
+                    revocation: { holders: ['principal'], ref: null },
+                    sig: { alg: 'bip322', pubkey: v.inputs.principal, value: 'AAAA' },
+                };
+                const r = await verifySubdelegation({
+                    envelope: sub,
+                    parent,
+                    skipSignatureVerification: true,
+                    skipTemporalCheck: true,
+                });
+                expect(r.ok).toBe(false);
+                if (!r.ok) expect(r.code).toBe(v.expected.error_code);
+            }
+        });
+    }
+});

package/src/types.ts

@@ -2,7 +2,11 @@
 
 export const ENVELOPE_VERSION = 1 as const;
 
-export type EnvelopeKind = 'agent-delegation' | 'agent-action' | 'agent-revocation';
+export type EnvelopeKind =
+    | 'agent-delegation'
+    | 'agent-action'
+    | 'agent-revocation'
+    | 'agent-subdelegation';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Shared building blocks
@@ -40,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
@@ -111,6 +160,46 @@ export interface ActionCanonicalInput {
     scope_exercised: string;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Sub-delegation (SUB-DELEGATION.md, v1.1)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SubdelegationEnvelope {
+    v: typeof ENVELOPE_VERSION;
+    kind: 'agent-subdelegation';
+    id: string; // 64-hex sha256(canonical_message)
+    parent_id: string; // 64-hex; the immediate parent envelope's id
+    /** The sub-principal — equal to parent.agent.address. */
+    principal: ActorRef;
+    /** The recipient sub-agent. */
+    agent: ActorRef;
+    /**
+     * 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
+    revocation: DelegationRevocationRef;
+    sig: Signature;
+}
+
+export interface SubdelegationCanonicalInput {
+    parent_id: string;
+    principal: string;
+    agent: string;
+    scopes: string[]; // pre-canonicalized, pre-sorted
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+}
+
+/** Either a root or a sub envelope; chain links walk up to a root delegation. */
+export type ChainLink = DelegationEnvelope | SubdelegationEnvelope;
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Revocation (SPEC §9)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -157,7 +246,15 @@ export type AgentErrorCode =
     | 'E_BOND_UNMET'
     | 'E_BOND_UNVERIFIED'
     | 'E_REVOKER_UNAUTHORIZED'
-    | 'E_CALENDAR_UNREACHABLE';
+    | 'E_CALENDAR_UNREACHABLE'
+    | 'E_SUBDELEGATION_DEPTH_EXCEEDED'
+    | 'E_SUBDELEGATION_PRINCIPAL_MISMATCH'
+    | 'E_SUBDELEGATION_EXPIRES_EXTENDED'
+    | '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;
@@ -174,9 +271,17 @@ export interface VerifyErr {
 
 export type VerifyDelegationResult = VerifyOk<DelegationEnvelope> | VerifyErr;
 export type VerifyRevocationResult = VerifyOk<RevocationEnvelope> | VerifyErr;
+export type VerifySubdelegationResult = VerifyOk<SubdelegationEnvelope> | VerifyErr;
 
 export interface VerifyActionOkExtra {
+    /** The ROOT delegation rooting the authority chain. */
     delegation: DelegationEnvelope;
+    /**
+     * The sub-delegation chain `[S_1, …, S_leaf]`. Empty when the action cites
+     * the root directly. The action's authority leaf is
+     * `chain[chain.length - 1] ?? delegation`.
+     */
+    chain: SubdelegationEnvelope[];
     scopeExercised: string;
     anchor:
         | { status: 'none' }