@orangecheck/agent-core 1.0.1 → 1.2.0

package/src/federation.ts

@@ -0,0 +1,329 @@
+// OC Agent v1.2 — Federation Principal (FEDERATION.md).
+//
+// ADDITIVE module. Implements the federation-principal extension WITHOUT
+// touching the v1 single-address path (types.ts DelegationEnvelope, verify.ts
+// verifyDelegation are unchanged + byte-identical against their vectors). A
+// dispatcher routes by `principal.alg` / `signer.alg`:
+//
+//   principal.alg === 'bip322'      → verifyDelegation   (v1, unchanged)
+//   principal.alg === 'federation'  → verifyFederationDelegation (this module)
+//
+// A federation principal is a content-addressed M-of-N guardian set. A
+// delegation / revocation under it is authentic iff M of N declared guardians
+// have BIP-322-signed the canonical message. The canonical-message + id rules
+// are unchanged — only the principal line (`federation:<descriptor_id>`) and the
+// signature block (`federation-bip322` with M-of-N) generalize. FEDERATION.md
+// §2 / §3 / §4.
+
+import { sha256 } from '@noble/hashes/sha256';
+
+import {
+    canonicalizeScopes,
+    computeDelegationId,
+    computeRevocationId,
+    delegationCanonicalMessage,
+    hexEncode,
+    revocationCanonicalMessage,
+} from './canonical.js';
+import type { ActorRef, AgentErrorCode, DelegationBond, DelegationRevocationRef } from './types.js';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types (FEDERATION.md §2 / §3.2)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface FederationGuardian {
+    /** mainnet Bitcoin address (P2WPKH, P2TR, or P2PKH). */
+    address: string;
+    alg: 'bip322';
+    /** Optional human label. NOT part of the cryptographic identity. */
+    name?: string;
+}
+
+export interface FederationDescriptor {
+    v: 1;
+    kind: 'agent-federation';
+    /** "M-of-N", 1 ≤ M ≤ N, N === guardians.length. */
+    threshold: string;
+    guardians: FederationGuardian[];
+}
+
+export interface FederationPrincipal {
+    alg: 'federation';
+    descriptor_id: string;
+    descriptor: FederationDescriptor;
+}
+
+export interface FederationSignature {
+    alg: 'federation-bip322';
+    threshold: string;
+    signatures: Array<{ guardian_address: string; value: string }>;
+}
+
+export interface FederationDelegationEnvelope {
+    v: 1;
+    kind: 'agent-delegation';
+    id: string;
+    principal: FederationPrincipal;
+    agent: ActorRef;
+    scopes: string[];
+    bond: DelegationBond | null;
+    issued_at: string;
+    expires_at: string;
+    nonce: string;
+    revocation: DelegationRevocationRef;
+    sig: FederationSignature;
+}
+
+export interface FederationRevocationEnvelope {
+    v: 1;
+    kind: 'agent-revocation';
+    id: string;
+    delegation_id: string;
+    /** Federation principal that authorizes the revocation (the guardian set). */
+    signer: FederationPrincipal;
+    reason: string;
+    signed_at: string;
+    ots?: unknown | null;
+    sig: FederationSignature;
+}
+
+export type FederationVerifyResult =
+    | { ok: true; id: string; canonicalMessage: string }
+    | { ok: false; code: AgentErrorCode; message: string };
+
+export interface VerifyFederationBase {
+    /** Injected BIP-322 verifier. Required unless `skipSignatureVerification`. */
+    verifyBip322?: (msg: string, signatureB64: string, address: string) => Promise<boolean>;
+    skipSignatureVerification?: boolean;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Descriptor canonicalization (FEDERATION.md §2.1 / §2.2)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The canonical, line-oriented descriptor message. Guardians are emitted in
+ * lexicographic byte order of their address (NOT the JSON array order); the
+ * `name` label is excluded — it is JSON-only metadata. No trailing LF.
+ */
+export function federationDescriptorCanonicalMessage(descriptor: FederationDescriptor): string {
+    const addresses = descriptor.guardians
+        .map((g) => g.address)
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return [
+        'oc-agent:federation:v1',
+        `threshold: ${descriptor.threshold}`,
+        ...addresses.map((a) => `guardian: ${a}`),
+    ].join('\n');
+}
+
+/** descriptor_id := H(canonical_descriptor_bytes). 64 lowercase hex. */
+export function computeFederationDescriptorId(descriptor: FederationDescriptor): string {
+    return hexEncode(sha256(new TextEncoder().encode(federationDescriptorCanonicalMessage(descriptor))));
+}
+
+function parseThreshold(t: unknown): { m: number; n: number } | null {
+    if (typeof t !== 'string') return null;
+    const m = /^(\d+)-of-(\d+)$/.exec(t);
+    if (!m) return null;
+    const mm = Number(m[1]);
+    const nn = Number(m[2]);
+    if (!Number.isInteger(mm) || !Number.isInteger(nn) || mm < 1 || mm > nn) return null;
+    return { m: mm, n: nn };
+}
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+/**
+ * Shared descriptor + quorum validation (FEDERATION.md §3.3 checks 3–8 minus the
+ * id check, plus BIP-322). `reconstructedId` is the already-computed envelope id.
+ */
+async function checkFederationQuorum(
+    principal: FederationPrincipal,
+    sig: FederationSignature,
+    reconstructedId: string,
+    input: VerifyFederationBase
+): Promise<{ ok: true } | { ok: false; code: AgentErrorCode; message: string }> {
+    // §3.3.2 — principal alg.
+    if (principal?.alg !== 'federation') {
+        return fail('E_MALFORMED', 'principal.alg must be "federation"');
+    }
+    const descriptor = principal.descriptor;
+    if (!descriptor || descriptor.kind !== 'agent-federation') {
+        return fail('E_MALFORMED', 'principal.descriptor missing or wrong kind');
+    }
+    const parsed = parseThreshold(descriptor.threshold);
+    if (!parsed) return fail('E_MALFORMED', `malformed threshold "${descriptor.threshold}"`);
+    if (!Array.isArray(descriptor.guardians) || descriptor.guardians.length !== parsed.n) {
+        return fail('E_MALFORMED', 'guardians length must equal N in M-of-N');
+    }
+
+    // §3.3.3 — descriptor_id matches the canonical hash of the inlined descriptor.
+    const computedDescId = computeFederationDescriptorId(descriptor);
+    if (principal.descriptor_id !== computedDescId) {
+        return fail(
+            'E_BAD_FEDERATION_DESCRIPTOR',
+            `declared descriptor_id (${principal.descriptor_id}) != canonical hash (${computedDescId})`
+        );
+    }
+
+    // §3.3.4 — sig.threshold equals descriptor.threshold.
+    if (sig?.alg !== 'federation-bip322') {
+        return fail('E_MALFORMED', 'sig.alg must be "federation-bip322"');
+    }
+    if (sig.threshold !== descriptor.threshold) {
+        return fail(
+            'E_THRESHOLD_MISMATCH',
+            `sig.threshold (${sig.threshold}) != descriptor.threshold (${descriptor.threshold})`
+        );
+    }
+
+    // §3.3.5 — at least M signatures.
+    const sigs = sig.signatures;
+    if (!Array.isArray(sigs)) return fail('E_MALFORMED', 'sig.signatures must be an array');
+    if (sigs.length < parsed.m) {
+        return fail(
+            'E_THRESHOLD_NOT_MET',
+            `${sigs.length} signature(s) below threshold M=${parsed.m}`
+        );
+    }
+
+    // §3.3.6 / §3.3.7 — every signer is a declared guardian; no duplicates.
+    const guardianSet = new Set(descriptor.guardians.map((g) => g.address));
+    const seen = new Set<string>();
+    for (const s of sigs) {
+        if (!guardianSet.has(s.guardian_address)) {
+            return fail('E_UNKNOWN_GUARDIAN', `${s.guardian_address} is not a declared guardian`);
+        }
+        if (seen.has(s.guardian_address)) {
+            return fail('E_DUPLICATE_GUARDIAN', `${s.guardian_address} signed more than once`);
+        }
+        seen.add(s.guardian_address);
+    }
+
+    // §3.3.8 — each signature verifies under BIP-322 over the hex-encoded id.
+    if (!input.skipSignatureVerification) {
+        if (!input.verifyBip322) return fail('E_BAD_SIG', 'no BIP-322 verifier supplied');
+        for (const s of sigs) {
+            const ok = await input.verifyBip322(reconstructedId, s.value, s.guardian_address);
+            if (!ok) {
+                return fail('E_BAD_SIG', `guardian ${s.guardian_address} signature did not verify`);
+            }
+        }
+    }
+    return { ok: true };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Delegation under a federation principal (FEDERATION.md §3)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface VerifyFederationDelegationInput extends VerifyFederationBase {
+    envelope: FederationDelegationEnvelope;
+    now?: Date;
+    skipTemporalCheck?: boolean;
+}
+
+export async function verifyFederationDelegation(
+    input: VerifyFederationDelegationInput
+): Promise<FederationVerifyResult> {
+    const env = input.envelope;
+    if (env?.kind !== 'agent-delegation') return fail('E_MALFORMED', 'kind must be "agent-delegation"');
+    if (!HEX64.test(env.id ?? '')) return fail('E_MALFORMED', 'id must be 64 lowercase hex chars');
+    if (!env.agent?.address || env.agent.alg !== 'bip322') return fail('E_MALFORMED', 'agent invalid');
+    if (!Array.isArray(env.scopes) || env.scopes.length === 0) {
+        return fail('E_MALFORMED', 'scopes must be a non-empty array');
+    }
+    if (!ISO_UTC.test(env.issued_at) || !ISO_UTC.test(env.expires_at)) {
+        return fail('E_MALFORMED', 'issued_at / expires_at must be ISO 8601 UTC');
+    }
+    if (!/^[0-9a-f]{32}$/.test(env.nonce)) return fail('E_MALFORMED', 'nonce must be 32 hex chars');
+
+    // Canonical scopes (identical rules to v1) must be sorted on the envelope.
+    let canonicalScopes: string[];
+    try {
+        canonicalScopes = canonicalizeScopes(env.scopes);
+    } catch (e) {
+        return fail('E_BAD_SCOPE_GRAMMAR', (e as Error).message);
+    }
+    for (let i = 0; i < canonicalScopes.length; i++) {
+        if (env.scopes[i] !== canonicalScopes[i]) {
+            return fail('E_BAD_SCOPE_GRAMMAR', `scope index ${i} not in canonical order`);
+        }
+    }
+
+    // §3.3.1 / §3.1 — reconstruct the id with the `federation:<descriptor_id>`
+    // principal substitution. Everything else is the v1 canonical message.
+    const canonInput = {
+        principal: `federation:${env.principal?.descriptor_id ?? ''}`,
+        agent: env.agent.address,
+        scopes: canonicalScopes,
+        bond_sats: env.bond?.sats ?? 0,
+        bond_attestation: env.bond?.attestation_id ?? 'none',
+        issued_at: env.issued_at,
+        expires_at: env.expires_at,
+        nonce: env.nonce,
+    };
+    const reconstructedId = computeDelegationId(canonInput);
+    if (reconstructedId !== env.id) {
+        return fail('E_BAD_ID', `reconstructed id (${reconstructedId}) != envelope.id (${env.id})`);
+    }
+
+    const quorum = await checkFederationQuorum(env.principal, env.sig, env.id, input);
+    if (!quorum.ok) return quorum;
+
+    if (!input.skipTemporalCheck) {
+        const now = input.now ?? new Date();
+        const issued = new Date(env.issued_at);
+        const expires = new Date(env.expires_at);
+        if (expires <= issued) return fail('E_MALFORMED', 'expires_at <= issued_at');
+        if (now < issued) return fail('E_NOT_YET_VALID', `delegation not valid until ${env.issued_at}`);
+        if (now >= expires) return fail('E_EXPIRED', `delegation expired at ${env.expires_at}`);
+    }
+
+    return { ok: true, id: env.id, canonicalMessage: delegationCanonicalMessage(canonInput) };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Revocation under a federation principal (FEDERATION.md §4)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface VerifyFederationRevocationInput extends VerifyFederationBase {
+    envelope: FederationRevocationEnvelope;
+}
+
+export async function verifyFederationRevocation(
+    input: VerifyFederationRevocationInput
+): Promise<FederationVerifyResult> {
+    const env = input.envelope;
+    if (env?.kind !== 'agent-revocation') return fail('E_MALFORMED', 'kind must be "agent-revocation"');
+    if (!HEX64.test(env.id ?? '')) return fail('E_MALFORMED', 'id must be 64 lowercase hex chars');
+    if (!HEX64.test(env.delegation_id ?? '')) return fail('E_MALFORMED', 'delegation_id must be 64-hex');
+    if (typeof env.reason !== 'string' || env.reason.length > 128) {
+        return fail('E_MALFORMED', 'reason must be a string ≤128 bytes');
+    }
+    if (!ISO_UTC.test(env.signed_at)) return fail('E_MALFORMED', 'signed_at must be ISO 8601 UTC');
+
+    // §4 — the `address:` line carries the `federation:<descriptor_id>`
+    // substitution; everything else is the v1 revocation canonical message.
+    const canonInput = {
+        address: `federation:${env.signer?.descriptor_id ?? ''}`,
+        delegation_id: env.delegation_id,
+        reason: env.reason,
+        signed_at: env.signed_at,
+    };
+    const reconstructedId = computeRevocationId(canonInput);
+    if (reconstructedId !== env.id) {
+        return fail('E_BAD_ID', `reconstructed id (${reconstructedId}) != envelope.id (${env.id})`);
+    }
+
+    const quorum = await checkFederationQuorum(env.signer, env.sig, env.id, input);
+    if (!quorum.ok) return quorum;
+
+    return { ok: true, id: env.id, canonicalMessage: revocationCanonicalMessage(canonInput) };
+}
+
+function fail(code: AgentErrorCode, message: string): { ok: false; code: AgentErrorCode; message: string } {
+    return { ok: false, code, message };
+}

package/src/index.ts

@@ -49,6 +49,24 @@ export type {
     VerifyRevocationInput,
     VerifySubdelegationInput,
 } from './verify.js';
+export {
+    federationDescriptorCanonicalMessage,
+    computeFederationDescriptorId,
+    verifyFederationDelegation,
+    verifyFederationRevocation,
+} from './federation.js';
+export type {
+    FederationGuardian,
+    FederationDescriptor,
+    FederationPrincipal,
+    FederationSignature,
+    FederationDelegationEnvelope,
+    FederationRevocationEnvelope,
+    FederationVerifyResult,
+    VerifyFederationBase,
+    VerifyFederationDelegationInput,
+    VerifyFederationRevocationInput,
+} from './federation.js';
 export {
     sealScopes,
     unsealScopes,
@@ -61,3 +79,6 @@ export type {
     UnsealScopesInput,
     UnsealedScopes,
 } from './private-scope.js';
+
+export { assertScopeGranted, ScopeNotGrantedError } from './assert-scope.js';
+export type { ScopeBearingDelegation } from './assert-scope.js';

package/src/test-vectors.test.ts

@@ -187,6 +187,21 @@ function isNegative(v: Vector): v is NegativeVector {
     return 'negative' in v && v.negative === true;
 }
 
+// v1.2 federation-principal vectors (v18–v26) are exercised by federation.test.ts
+// against verifyFederationDelegation / verifyFederationRevocation. They use a
+// `federation:<descriptor_id>` principal that the v1 single-address path here
+// intentionally rejects, so skip them in the generic v1 loops. (v26 — the
+// single-address baseline — stays: its principal.alg is "bip322".)
+function isFederation(v: Vector): boolean {
+    const d = v as unknown as {
+        kind?: string;
+        expected?: { envelope?: { principal?: { alg?: string }; signer?: { alg?: string } } };
+    };
+    if (d.kind === 'federation-descriptor') return true;
+    const env = d.expected?.envelope;
+    return env?.principal?.alg === 'federation' || env?.signer?.alg === 'federation';
+}
+
 async function loadVectors(): Promise<{ name: string; data: Vector }[]> {
     try {
         const files = await readdir(VECTORS_DIR);
@@ -217,6 +232,7 @@ describe('oc-agent-protocol test vectors', () => {
     const subdelegationEnvelopes = new Map<string, SubdelegationEnvelope>();
     for (const { data } of vectors) {
         if (isNegative(data)) continue;
+        if (isFederation(data)) continue;
         if ((data as { private_scope?: unknown }).private_scope) continue;
         if (data.kind === 'delegation') {
             delegationEnvelopes.set(data.expected.id, data.expected.envelope);
@@ -227,6 +243,7 @@ describe('oc-agent-protocol test vectors', () => {
 
     for (const { name, data } of vectors) {
         if (isNegative(data)) continue;
+        if (isFederation(data)) continue;
         if ((data as { private_scope?: unknown }).private_scope) continue;
         it(`${name} — canonical message reconstructs byte-identical`, () => {
             const msg = reconstructCanonical(data);

package/src/types.ts

@@ -254,7 +254,13 @@ export type AgentErrorCode =
     | 'E_SCOPES_BOTH_PROVIDED'
     | 'E_SCOPES_NEITHER_PROVIDED'
     | 'E_SCOPES_UNREADABLE'
-    | 'E_BAD_LOCK_ENVELOPE';
+    | 'E_BAD_LOCK_ENVELOPE'
+    // v1.2 federation principal (FEDERATION.md §3.3)
+    | 'E_BAD_FEDERATION_DESCRIPTOR'
+    | 'E_THRESHOLD_MISMATCH'
+    | 'E_THRESHOLD_NOT_MET'
+    | 'E_UNKNOWN_GUARDIAN'
+    | 'E_DUPLICATE_GUARDIAN';
 
 export interface VerifyOk<T> {
     ok: true;