@orangecheck/agent-core 1.0.1 → 1.1.0

package/dist/types.d.mts

@@ -153,7 +153,7 @@ interface RevocationCanonicalInput {
     reason: string;
     signed_at: string;
 }
-type AgentErrorCode = 'E_UNSUPPORTED_VERSION' | 'E_MALFORMED' | 'E_BAD_ID' | 'E_BAD_SIG' | 'E_BAD_SCOPE_GRAMMAR' | 'E_NOT_YET_VALID' | 'E_EXPIRED' | 'E_REVOKED' | 'E_DELEGATION_MISMATCH' | 'E_AGENT_MISMATCH' | 'E_OUT_OF_WINDOW' | 'E_SCOPE_DENIED' | 'E_BAD_ACTION_STAMP' | 'E_NO_BOND' | 'E_BOND_UNMET' | 'E_BOND_UNVERIFIED' | 'E_REVOKER_UNAUTHORIZED' | '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';
+type AgentErrorCode = 'E_UNSUPPORTED_VERSION' | 'E_MALFORMED' | 'E_BAD_ID' | 'E_BAD_SIG' | 'E_BAD_SCOPE_GRAMMAR' | 'E_NOT_YET_VALID' | 'E_EXPIRED' | 'E_REVOKED' | 'E_DELEGATION_MISMATCH' | 'E_AGENT_MISMATCH' | 'E_OUT_OF_WINDOW' | 'E_SCOPE_DENIED' | 'E_BAD_ACTION_STAMP' | 'E_NO_BOND' | 'E_BOND_UNMET' | 'E_BOND_UNVERIFIED' | 'E_REVOKER_UNAUTHORIZED' | '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' | 'E_BAD_FEDERATION_DESCRIPTOR' | 'E_THRESHOLD_MISMATCH' | 'E_THRESHOLD_NOT_MET' | 'E_UNKNOWN_GUARDIAN' | 'E_DUPLICATE_GUARDIAN';
 interface VerifyOk<T> {
     ok: true;
     envelope: T;

package/dist/types.d.ts

@@ -153,7 +153,7 @@ interface RevocationCanonicalInput {
     reason: string;
     signed_at: string;
 }
-type AgentErrorCode = 'E_UNSUPPORTED_VERSION' | 'E_MALFORMED' | 'E_BAD_ID' | 'E_BAD_SIG' | 'E_BAD_SCOPE_GRAMMAR' | 'E_NOT_YET_VALID' | 'E_EXPIRED' | 'E_REVOKED' | 'E_DELEGATION_MISMATCH' | 'E_AGENT_MISMATCH' | 'E_OUT_OF_WINDOW' | 'E_SCOPE_DENIED' | 'E_BAD_ACTION_STAMP' | 'E_NO_BOND' | 'E_BOND_UNMET' | 'E_BOND_UNVERIFIED' | 'E_REVOKER_UNAUTHORIZED' | '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';
+type AgentErrorCode = 'E_UNSUPPORTED_VERSION' | 'E_MALFORMED' | 'E_BAD_ID' | 'E_BAD_SIG' | 'E_BAD_SCOPE_GRAMMAR' | 'E_NOT_YET_VALID' | 'E_EXPIRED' | 'E_REVOKED' | 'E_DELEGATION_MISMATCH' | 'E_AGENT_MISMATCH' | 'E_OUT_OF_WINDOW' | 'E_SCOPE_DENIED' | 'E_BAD_ACTION_STAMP' | 'E_NO_BOND' | 'E_BOND_UNMET' | 'E_BOND_UNVERIFIED' | 'E_REVOKER_UNAUTHORIZED' | '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' | 'E_BAD_FEDERATION_DESCRIPTOR' | 'E_THRESHOLD_MISMATCH' | 'E_THRESHOLD_NOT_MET' | 'E_UNKNOWN_GUARDIAN' | 'E_DUPLICATE_GUARDIAN';
 interface VerifyOk<T> {
     ok: true;
     envelope: T;

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AAEO,IAAM,gBAAA,GAAmB","file":"types.js","sourcesContent":["// Wire types for OC Agent v1 envelopes. See SPEC.md §4, §5, §9.\n\nexport const ENVELOPE_VERSION = 1 as const;\n\nexport type EnvelopeKind =\n    | 'agent-delegation'\n    | 'agent-action'\n    | 'agent-revocation'\n    | 'agent-subdelegation';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Shared building blocks\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActorRef {\n    /** mainnet Bitcoin address (P2WPKH, P2TR, or P2PKH). */\n    address: string;\n    alg: 'bip322';\n}\n\nexport interface Signature {\n    alg: 'bip322';\n    pubkey: string; // equals the producing actor's address\n    value: string; // base64 BIP-322 signature over hex(id)\n}\n\nexport type RevocationHolder = 'principal' | 'agent';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Delegation (SPEC §4)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface DelegationBond {\n    /** Non-negative sats declared as bonded at issuance time. */\n    sats: number;\n    /** SHA-256 hex of the OrangeCheck canonical message signed by principal.address. */\n    attestation_id: string;\n}\n\nexport interface DelegationRevocationRef {\n    /** Who MAY publish a revocation. Default [\"principal\"]. */\n    holders: RevocationHolder[];\n    /** Optional Nostr-addressable pointer to a published revocation. Non-cryptographic. */\n    ref: string | null;\n}\n\n/**\n * v1.2 private-scope mode: a wholesale OC Lock v2 LockEnvelope wrapping the\n * canonical scope list as its payload. We re-import the LockEnvelope type\n * structurally rather than depending on the @orangecheck/lock-core type — agent-\n * core's type surface stays loose so verifiers can be authored in either an\n * agent-only or full-family setup.\n */\nexport interface ScopesEncryptedEnvelope {\n    v: 2;\n    kind: 'identity';\n    id: string;\n    alg: { kem: 'x25519'; aead: 'aes-256-gcm'; kdf: 'hkdf-sha256' };\n    from: { address: string; attestation_id?: string };\n    recipients: Array<{\n        address: string;\n        device_id: string;\n        device_pk: string;\n        eph_pk: string;\n        wrapped_key: string;\n        nonce_kek: string;\n    }>;\n    ciphertext: string;\n    nonce_ct: string;\n    hint?: string;\n    created_at: string;\n    expires_at: string | null;\n    payment: unknown | null;\n    sig: { alg: 'bip322'; pubkey: string; value: string };\n}\n\nexport interface DelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-delegation';\n    id: string; // 64-hex sha256(canonical_message)\n    principal: ActorRef;\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: sorted lexicographically in the canonical\n     * message; stored in sorted order on the envelope too.\n     *\n     * v1.2 private mode: this field is OMITTED from the envelope JSON;\n     * `scopes_encrypted` is set instead. After decryption, the recovered\n     * scope list takes this field's place in the in-memory envelope object\n     * for the remainder of verification.\n     */\n    scopes?: string[];\n    /**\n     * v1.2 private mode (PRIVATE-SCOPE.md §1.1): an OC Lock v2 envelope\n     * wrapping the canonical scope-list bytes as its payload, sealed to one\n     * or more recipients (typically the agent ± named verifiers). MUTUALLY\n     * EXCLUSIVE with `scopes`.\n     */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    bond: DelegationBond | null;\n    issued_at: string; // ISO 8601 UTC\n    expires_at: string; // ISO 8601 UTC\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface DelegationCanonicalInput {\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    bond_sats: number;\n    /** 64-hex attestation id or the literal string \"none\". */\n    bond_attestation: string;\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Agent-action (SPEC §5) — strict extension of OC Stamp\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActionContent {\n    hash: string; // \"sha256:<64-hex>\"\n    length: number;\n    mime: string;\n    ref: string | null;\n}\n\nexport interface ActionOts {\n    status: 'pending' | 'confirmed';\n    proof: string;\n    calendars: string[];\n    block_height: number | null;\n    block_hash: string | null;\n    upgraded_at: string | null;\n}\n\nexport interface ActionEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-action';\n    id: string;\n    content: ActionContent;\n    signer: ActorRef; // agent\n    signed_at: string;\n    delegation_id: string; // 64-hex\n    scope_exercised: string; // a sub-scope of some granted scope\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface ActionCanonicalInput {\n    address: string; // agent address\n    content_hash: string;\n    content_length: number;\n    content_mime: string;\n    signed_at: string;\n    delegation_id: string;\n    scope_exercised: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Sub-delegation (SUB-DELEGATION.md, v1.1)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface SubdelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-subdelegation';\n    id: string; // 64-hex sha256(canonical_message)\n    parent_id: string; // 64-hex; the immediate parent envelope's id\n    /** The sub-principal — equal to parent.agent.address. */\n    principal: ActorRef;\n    /** The recipient sub-agent. */\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: each scope MUST be a sub-scope of some scope\n     * on the parent. v1.2 private mode: omitted; `scopes_encrypted` set.\n     */\n    scopes?: string[];\n    /** v1.2 private mode — same shape as the root delegation field. */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    issued_at: string; // ISO 8601 UTC; >= parent.issued_at\n    expires_at: string; // ISO 8601 UTC; <= parent.expires_at\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface SubdelegationCanonicalInput {\n    parent_id: string;\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n/** Either a root or a sub envelope; chain links walk up to a root delegation. */\nexport type ChainLink = DelegationEnvelope | SubdelegationEnvelope;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Revocation (SPEC §9)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface RevocationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-revocation';\n    id: string;\n    delegation_id: string;\n    signer: ActorRef;\n    /** Short ASCII rationale, <= 128 bytes. Empty string if omitted. */\n    reason: string;\n    signed_at: string;\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface RevocationCanonicalInput {\n    address: string;\n    delegation_id: string;\n    reason: string;\n    signed_at: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Error codes (SPEC §11)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type AgentErrorCode =\n    | 'E_UNSUPPORTED_VERSION'\n    | 'E_MALFORMED'\n    | 'E_BAD_ID'\n    | 'E_BAD_SIG'\n    | 'E_BAD_SCOPE_GRAMMAR'\n    | 'E_NOT_YET_VALID'\n    | 'E_EXPIRED'\n    | 'E_REVOKED'\n    | 'E_DELEGATION_MISMATCH'\n    | 'E_AGENT_MISMATCH'\n    | 'E_OUT_OF_WINDOW'\n    | 'E_SCOPE_DENIED'\n    | 'E_BAD_ACTION_STAMP'\n    | 'E_NO_BOND'\n    | 'E_BOND_UNMET'\n    | 'E_BOND_UNVERIFIED'\n    | 'E_REVOKER_UNAUTHORIZED'\n    | 'E_CALENDAR_UNREACHABLE'\n    | 'E_SUBDELEGATION_DEPTH_EXCEEDED'\n    | 'E_SUBDELEGATION_PRINCIPAL_MISMATCH'\n    | 'E_SUBDELEGATION_EXPIRES_EXTENDED'\n    | 'E_SUBDELEGATION_SCOPE_ESCALATED'\n    | 'E_SCOPES_BOTH_PROVIDED'\n    | 'E_SCOPES_NEITHER_PROVIDED'\n    | 'E_SCOPES_UNREADABLE'\n    | 'E_BAD_LOCK_ENVELOPE';\n\nexport interface VerifyOk<T> {\n    ok: true;\n    envelope: T;\n    canonicalMessage: string;\n    id: string;\n}\n\nexport interface VerifyErr {\n    ok: false;\n    code: AgentErrorCode;\n    message: string;\n}\n\nexport type VerifyDelegationResult = VerifyOk<DelegationEnvelope> | VerifyErr;\nexport type VerifyRevocationResult = VerifyOk<RevocationEnvelope> | VerifyErr;\nexport type VerifySubdelegationResult = VerifyOk<SubdelegationEnvelope> | VerifyErr;\n\nexport interface VerifyActionOkExtra {\n    /** The ROOT delegation rooting the authority chain. */\n    delegation: DelegationEnvelope;\n    /**\n     * The sub-delegation chain `[S_1, …, S_leaf]`. Empty when the action cites\n     * the root directly. The action's authority leaf is\n     * `chain[chain.length - 1] ?? delegation`.\n     */\n    chain: SubdelegationEnvelope[];\n    scopeExercised: string;\n    anchor:\n        | { status: 'none' }\n        | { status: 'pending' }\n        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: boolean };\n}\n\nexport type VerifyActionResult =\n    | (VerifyOk<ActionEnvelope> & VerifyActionOkExtra)\n    | VerifyErr;\n"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AAEO,IAAM,gBAAA,GAAmB","file":"types.js","sourcesContent":["// Wire types for OC Agent v1 envelopes. See SPEC.md §4, §5, §9.\n\nexport const ENVELOPE_VERSION = 1 as const;\n\nexport type EnvelopeKind =\n    | 'agent-delegation'\n    | 'agent-action'\n    | 'agent-revocation'\n    | 'agent-subdelegation';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Shared building blocks\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActorRef {\n    /** mainnet Bitcoin address (P2WPKH, P2TR, or P2PKH). */\n    address: string;\n    alg: 'bip322';\n}\n\nexport interface Signature {\n    alg: 'bip322';\n    pubkey: string; // equals the producing actor's address\n    value: string; // base64 BIP-322 signature over hex(id)\n}\n\nexport type RevocationHolder = 'principal' | 'agent';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Delegation (SPEC §4)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface DelegationBond {\n    /** Non-negative sats declared as bonded at issuance time. */\n    sats: number;\n    /** SHA-256 hex of the OrangeCheck canonical message signed by principal.address. */\n    attestation_id: string;\n}\n\nexport interface DelegationRevocationRef {\n    /** Who MAY publish a revocation. Default [\"principal\"]. */\n    holders: RevocationHolder[];\n    /** Optional Nostr-addressable pointer to a published revocation. Non-cryptographic. */\n    ref: string | null;\n}\n\n/**\n * v1.2 private-scope mode: a wholesale OC Lock v2 LockEnvelope wrapping the\n * canonical scope list as its payload. We re-import the LockEnvelope type\n * structurally rather than depending on the @orangecheck/lock-core type — agent-\n * core's type surface stays loose so verifiers can be authored in either an\n * agent-only or full-family setup.\n */\nexport interface ScopesEncryptedEnvelope {\n    v: 2;\n    kind: 'identity';\n    id: string;\n    alg: { kem: 'x25519'; aead: 'aes-256-gcm'; kdf: 'hkdf-sha256' };\n    from: { address: string; attestation_id?: string };\n    recipients: Array<{\n        address: string;\n        device_id: string;\n        device_pk: string;\n        eph_pk: string;\n        wrapped_key: string;\n        nonce_kek: string;\n    }>;\n    ciphertext: string;\n    nonce_ct: string;\n    hint?: string;\n    created_at: string;\n    expires_at: string | null;\n    payment: unknown | null;\n    sig: { alg: 'bip322'; pubkey: string; value: string };\n}\n\nexport interface DelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-delegation';\n    id: string; // 64-hex sha256(canonical_message)\n    principal: ActorRef;\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: sorted lexicographically in the canonical\n     * message; stored in sorted order on the envelope too.\n     *\n     * v1.2 private mode: this field is OMITTED from the envelope JSON;\n     * `scopes_encrypted` is set instead. After decryption, the recovered\n     * scope list takes this field's place in the in-memory envelope object\n     * for the remainder of verification.\n     */\n    scopes?: string[];\n    /**\n     * v1.2 private mode (PRIVATE-SCOPE.md §1.1): an OC Lock v2 envelope\n     * wrapping the canonical scope-list bytes as its payload, sealed to one\n     * or more recipients (typically the agent ± named verifiers). MUTUALLY\n     * EXCLUSIVE with `scopes`.\n     */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    bond: DelegationBond | null;\n    issued_at: string; // ISO 8601 UTC\n    expires_at: string; // ISO 8601 UTC\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface DelegationCanonicalInput {\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    bond_sats: number;\n    /** 64-hex attestation id or the literal string \"none\". */\n    bond_attestation: string;\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Agent-action (SPEC §5) — strict extension of OC Stamp\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActionContent {\n    hash: string; // \"sha256:<64-hex>\"\n    length: number;\n    mime: string;\n    ref: string | null;\n}\n\nexport interface ActionOts {\n    status: 'pending' | 'confirmed';\n    proof: string;\n    calendars: string[];\n    block_height: number | null;\n    block_hash: string | null;\n    upgraded_at: string | null;\n}\n\nexport interface ActionEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-action';\n    id: string;\n    content: ActionContent;\n    signer: ActorRef; // agent\n    signed_at: string;\n    delegation_id: string; // 64-hex\n    scope_exercised: string; // a sub-scope of some granted scope\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface ActionCanonicalInput {\n    address: string; // agent address\n    content_hash: string;\n    content_length: number;\n    content_mime: string;\n    signed_at: string;\n    delegation_id: string;\n    scope_exercised: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Sub-delegation (SUB-DELEGATION.md, v1.1)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface SubdelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-subdelegation';\n    id: string; // 64-hex sha256(canonical_message)\n    parent_id: string; // 64-hex; the immediate parent envelope's id\n    /** The sub-principal — equal to parent.agent.address. */\n    principal: ActorRef;\n    /** The recipient sub-agent. */\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: each scope MUST be a sub-scope of some scope\n     * on the parent. v1.2 private mode: omitted; `scopes_encrypted` set.\n     */\n    scopes?: string[];\n    /** v1.2 private mode — same shape as the root delegation field. */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    issued_at: string; // ISO 8601 UTC; >= parent.issued_at\n    expires_at: string; // ISO 8601 UTC; <= parent.expires_at\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface SubdelegationCanonicalInput {\n    parent_id: string;\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n/** Either a root or a sub envelope; chain links walk up to a root delegation. */\nexport type ChainLink = DelegationEnvelope | SubdelegationEnvelope;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Revocation (SPEC §9)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface RevocationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-revocation';\n    id: string;\n    delegation_id: string;\n    signer: ActorRef;\n    /** Short ASCII rationale, <= 128 bytes. Empty string if omitted. */\n    reason: string;\n    signed_at: string;\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface RevocationCanonicalInput {\n    address: string;\n    delegation_id: string;\n    reason: string;\n    signed_at: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Error codes (SPEC §11)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type AgentErrorCode =\n    | 'E_UNSUPPORTED_VERSION'\n    | 'E_MALFORMED'\n    | 'E_BAD_ID'\n    | 'E_BAD_SIG'\n    | 'E_BAD_SCOPE_GRAMMAR'\n    | 'E_NOT_YET_VALID'\n    | 'E_EXPIRED'\n    | 'E_REVOKED'\n    | 'E_DELEGATION_MISMATCH'\n    | 'E_AGENT_MISMATCH'\n    | 'E_OUT_OF_WINDOW'\n    | 'E_SCOPE_DENIED'\n    | 'E_BAD_ACTION_STAMP'\n    | 'E_NO_BOND'\n    | 'E_BOND_UNMET'\n    | 'E_BOND_UNVERIFIED'\n    | 'E_REVOKER_UNAUTHORIZED'\n    | 'E_CALENDAR_UNREACHABLE'\n    | 'E_SUBDELEGATION_DEPTH_EXCEEDED'\n    | 'E_SUBDELEGATION_PRINCIPAL_MISMATCH'\n    | 'E_SUBDELEGATION_EXPIRES_EXTENDED'\n    | 'E_SUBDELEGATION_SCOPE_ESCALATED'\n    | 'E_SCOPES_BOTH_PROVIDED'\n    | 'E_SCOPES_NEITHER_PROVIDED'\n    | 'E_SCOPES_UNREADABLE'\n    | 'E_BAD_LOCK_ENVELOPE'\n    // v1.2 federation principal (FEDERATION.md §3.3)\n    | 'E_BAD_FEDERATION_DESCRIPTOR'\n    | 'E_THRESHOLD_MISMATCH'\n    | 'E_THRESHOLD_NOT_MET'\n    | 'E_UNKNOWN_GUARDIAN'\n    | 'E_DUPLICATE_GUARDIAN';\n\nexport interface VerifyOk<T> {\n    ok: true;\n    envelope: T;\n    canonicalMessage: string;\n    id: string;\n}\n\nexport interface VerifyErr {\n    ok: false;\n    code: AgentErrorCode;\n    message: string;\n}\n\nexport type VerifyDelegationResult = VerifyOk<DelegationEnvelope> | VerifyErr;\nexport type VerifyRevocationResult = VerifyOk<RevocationEnvelope> | VerifyErr;\nexport type VerifySubdelegationResult = VerifyOk<SubdelegationEnvelope> | VerifyErr;\n\nexport interface VerifyActionOkExtra {\n    /** The ROOT delegation rooting the authority chain. */\n    delegation: DelegationEnvelope;\n    /**\n     * The sub-delegation chain `[S_1, …, S_leaf]`. Empty when the action cites\n     * the root directly. The action's authority leaf is\n     * `chain[chain.length - 1] ?? delegation`.\n     */\n    chain: SubdelegationEnvelope[];\n    scopeExercised: string;\n    anchor:\n        | { status: 'none' }\n        | { status: 'pending' }\n        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: boolean };\n}\n\nexport type VerifyActionResult =\n    | (VerifyOk<ActionEnvelope> & VerifyActionOkExtra)\n    | VerifyErr;\n"]}

package/dist/types.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAEO,IAAM,gBAAA,GAAmB","file":"types.mjs","sourcesContent":["// Wire types for OC Agent v1 envelopes. See SPEC.md §4, §5, §9.\n\nexport const ENVELOPE_VERSION = 1 as const;\n\nexport type EnvelopeKind =\n    | 'agent-delegation'\n    | 'agent-action'\n    | 'agent-revocation'\n    | 'agent-subdelegation';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Shared building blocks\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActorRef {\n    /** mainnet Bitcoin address (P2WPKH, P2TR, or P2PKH). */\n    address: string;\n    alg: 'bip322';\n}\n\nexport interface Signature {\n    alg: 'bip322';\n    pubkey: string; // equals the producing actor's address\n    value: string; // base64 BIP-322 signature over hex(id)\n}\n\nexport type RevocationHolder = 'principal' | 'agent';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Delegation (SPEC §4)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface DelegationBond {\n    /** Non-negative sats declared as bonded at issuance time. */\n    sats: number;\n    /** SHA-256 hex of the OrangeCheck canonical message signed by principal.address. */\n    attestation_id: string;\n}\n\nexport interface DelegationRevocationRef {\n    /** Who MAY publish a revocation. Default [\"principal\"]. */\n    holders: RevocationHolder[];\n    /** Optional Nostr-addressable pointer to a published revocation. Non-cryptographic. */\n    ref: string | null;\n}\n\n/**\n * v1.2 private-scope mode: a wholesale OC Lock v2 LockEnvelope wrapping the\n * canonical scope list as its payload. We re-import the LockEnvelope type\n * structurally rather than depending on the @orangecheck/lock-core type — agent-\n * core's type surface stays loose so verifiers can be authored in either an\n * agent-only or full-family setup.\n */\nexport interface ScopesEncryptedEnvelope {\n    v: 2;\n    kind: 'identity';\n    id: string;\n    alg: { kem: 'x25519'; aead: 'aes-256-gcm'; kdf: 'hkdf-sha256' };\n    from: { address: string; attestation_id?: string };\n    recipients: Array<{\n        address: string;\n        device_id: string;\n        device_pk: string;\n        eph_pk: string;\n        wrapped_key: string;\n        nonce_kek: string;\n    }>;\n    ciphertext: string;\n    nonce_ct: string;\n    hint?: string;\n    created_at: string;\n    expires_at: string | null;\n    payment: unknown | null;\n    sig: { alg: 'bip322'; pubkey: string; value: string };\n}\n\nexport interface DelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-delegation';\n    id: string; // 64-hex sha256(canonical_message)\n    principal: ActorRef;\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: sorted lexicographically in the canonical\n     * message; stored in sorted order on the envelope too.\n     *\n     * v1.2 private mode: this field is OMITTED from the envelope JSON;\n     * `scopes_encrypted` is set instead. After decryption, the recovered\n     * scope list takes this field's place in the in-memory envelope object\n     * for the remainder of verification.\n     */\n    scopes?: string[];\n    /**\n     * v1.2 private mode (PRIVATE-SCOPE.md §1.1): an OC Lock v2 envelope\n     * wrapping the canonical scope-list bytes as its payload, sealed to one\n     * or more recipients (typically the agent ± named verifiers). MUTUALLY\n     * EXCLUSIVE with `scopes`.\n     */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    bond: DelegationBond | null;\n    issued_at: string; // ISO 8601 UTC\n    expires_at: string; // ISO 8601 UTC\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface DelegationCanonicalInput {\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    bond_sats: number;\n    /** 64-hex attestation id or the literal string \"none\". */\n    bond_attestation: string;\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Agent-action (SPEC §5) — strict extension of OC Stamp\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActionContent {\n    hash: string; // \"sha256:<64-hex>\"\n    length: number;\n    mime: string;\n    ref: string | null;\n}\n\nexport interface ActionOts {\n    status: 'pending' | 'confirmed';\n    proof: string;\n    calendars: string[];\n    block_height: number | null;\n    block_hash: string | null;\n    upgraded_at: string | null;\n}\n\nexport interface ActionEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-action';\n    id: string;\n    content: ActionContent;\n    signer: ActorRef; // agent\n    signed_at: string;\n    delegation_id: string; // 64-hex\n    scope_exercised: string; // a sub-scope of some granted scope\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface ActionCanonicalInput {\n    address: string; // agent address\n    content_hash: string;\n    content_length: number;\n    content_mime: string;\n    signed_at: string;\n    delegation_id: string;\n    scope_exercised: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Sub-delegation (SUB-DELEGATION.md, v1.1)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface SubdelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-subdelegation';\n    id: string; // 64-hex sha256(canonical_message)\n    parent_id: string; // 64-hex; the immediate parent envelope's id\n    /** The sub-principal — equal to parent.agent.address. */\n    principal: ActorRef;\n    /** The recipient sub-agent. */\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: each scope MUST be a sub-scope of some scope\n     * on the parent. v1.2 private mode: omitted; `scopes_encrypted` set.\n     */\n    scopes?: string[];\n    /** v1.2 private mode — same shape as the root delegation field. */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    issued_at: string; // ISO 8601 UTC; >= parent.issued_at\n    expires_at: string; // ISO 8601 UTC; <= parent.expires_at\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface SubdelegationCanonicalInput {\n    parent_id: string;\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n/** Either a root or a sub envelope; chain links walk up to a root delegation. */\nexport type ChainLink = DelegationEnvelope | SubdelegationEnvelope;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Revocation (SPEC §9)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface RevocationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-revocation';\n    id: string;\n    delegation_id: string;\n    signer: ActorRef;\n    /** Short ASCII rationale, <= 128 bytes. Empty string if omitted. */\n    reason: string;\n    signed_at: string;\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface RevocationCanonicalInput {\n    address: string;\n    delegation_id: string;\n    reason: string;\n    signed_at: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Error codes (SPEC §11)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type AgentErrorCode =\n    | 'E_UNSUPPORTED_VERSION'\n    | 'E_MALFORMED'\n    | 'E_BAD_ID'\n    | 'E_BAD_SIG'\n    | 'E_BAD_SCOPE_GRAMMAR'\n    | 'E_NOT_YET_VALID'\n    | 'E_EXPIRED'\n    | 'E_REVOKED'\n    | 'E_DELEGATION_MISMATCH'\n    | 'E_AGENT_MISMATCH'\n    | 'E_OUT_OF_WINDOW'\n    | 'E_SCOPE_DENIED'\n    | 'E_BAD_ACTION_STAMP'\n    | 'E_NO_BOND'\n    | 'E_BOND_UNMET'\n    | 'E_BOND_UNVERIFIED'\n    | 'E_REVOKER_UNAUTHORIZED'\n    | 'E_CALENDAR_UNREACHABLE'\n    | 'E_SUBDELEGATION_DEPTH_EXCEEDED'\n    | 'E_SUBDELEGATION_PRINCIPAL_MISMATCH'\n    | 'E_SUBDELEGATION_EXPIRES_EXTENDED'\n    | 'E_SUBDELEGATION_SCOPE_ESCALATED'\n    | 'E_SCOPES_BOTH_PROVIDED'\n    | 'E_SCOPES_NEITHER_PROVIDED'\n    | 'E_SCOPES_UNREADABLE'\n    | 'E_BAD_LOCK_ENVELOPE';\n\nexport interface VerifyOk<T> {\n    ok: true;\n    envelope: T;\n    canonicalMessage: string;\n    id: string;\n}\n\nexport interface VerifyErr {\n    ok: false;\n    code: AgentErrorCode;\n    message: string;\n}\n\nexport type VerifyDelegationResult = VerifyOk<DelegationEnvelope> | VerifyErr;\nexport type VerifyRevocationResult = VerifyOk<RevocationEnvelope> | VerifyErr;\nexport type VerifySubdelegationResult = VerifyOk<SubdelegationEnvelope> | VerifyErr;\n\nexport interface VerifyActionOkExtra {\n    /** The ROOT delegation rooting the authority chain. */\n    delegation: DelegationEnvelope;\n    /**\n     * The sub-delegation chain `[S_1, …, S_leaf]`. Empty when the action cites\n     * the root directly. The action's authority leaf is\n     * `chain[chain.length - 1] ?? delegation`.\n     */\n    chain: SubdelegationEnvelope[];\n    scopeExercised: string;\n    anchor:\n        | { status: 'none' }\n        | { status: 'pending' }\n        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: boolean };\n}\n\nexport type VerifyActionResult =\n    | (VerifyOk<ActionEnvelope> & VerifyActionOkExtra)\n    | VerifyErr;\n"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAEO,IAAM,gBAAA,GAAmB","file":"types.mjs","sourcesContent":["// Wire types for OC Agent v1 envelopes. See SPEC.md §4, §5, §9.\n\nexport const ENVELOPE_VERSION = 1 as const;\n\nexport type EnvelopeKind =\n    | 'agent-delegation'\n    | 'agent-action'\n    | 'agent-revocation'\n    | 'agent-subdelegation';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Shared building blocks\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActorRef {\n    /** mainnet Bitcoin address (P2WPKH, P2TR, or P2PKH). */\n    address: string;\n    alg: 'bip322';\n}\n\nexport interface Signature {\n    alg: 'bip322';\n    pubkey: string; // equals the producing actor's address\n    value: string; // base64 BIP-322 signature over hex(id)\n}\n\nexport type RevocationHolder = 'principal' | 'agent';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Delegation (SPEC §4)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface DelegationBond {\n    /** Non-negative sats declared as bonded at issuance time. */\n    sats: number;\n    /** SHA-256 hex of the OrangeCheck canonical message signed by principal.address. */\n    attestation_id: string;\n}\n\nexport interface DelegationRevocationRef {\n    /** Who MAY publish a revocation. Default [\"principal\"]. */\n    holders: RevocationHolder[];\n    /** Optional Nostr-addressable pointer to a published revocation. Non-cryptographic. */\n    ref: string | null;\n}\n\n/**\n * v1.2 private-scope mode: a wholesale OC Lock v2 LockEnvelope wrapping the\n * canonical scope list as its payload. We re-import the LockEnvelope type\n * structurally rather than depending on the @orangecheck/lock-core type — agent-\n * core's type surface stays loose so verifiers can be authored in either an\n * agent-only or full-family setup.\n */\nexport interface ScopesEncryptedEnvelope {\n    v: 2;\n    kind: 'identity';\n    id: string;\n    alg: { kem: 'x25519'; aead: 'aes-256-gcm'; kdf: 'hkdf-sha256' };\n    from: { address: string; attestation_id?: string };\n    recipients: Array<{\n        address: string;\n        device_id: string;\n        device_pk: string;\n        eph_pk: string;\n        wrapped_key: string;\n        nonce_kek: string;\n    }>;\n    ciphertext: string;\n    nonce_ct: string;\n    hint?: string;\n    created_at: string;\n    expires_at: string | null;\n    payment: unknown | null;\n    sig: { alg: 'bip322'; pubkey: string; value: string };\n}\n\nexport interface DelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-delegation';\n    id: string; // 64-hex sha256(canonical_message)\n    principal: ActorRef;\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: sorted lexicographically in the canonical\n     * message; stored in sorted order on the envelope too.\n     *\n     * v1.2 private mode: this field is OMITTED from the envelope JSON;\n     * `scopes_encrypted` is set instead. After decryption, the recovered\n     * scope list takes this field's place in the in-memory envelope object\n     * for the remainder of verification.\n     */\n    scopes?: string[];\n    /**\n     * v1.2 private mode (PRIVATE-SCOPE.md §1.1): an OC Lock v2 envelope\n     * wrapping the canonical scope-list bytes as its payload, sealed to one\n     * or more recipients (typically the agent ± named verifiers). MUTUALLY\n     * EXCLUSIVE with `scopes`.\n     */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    bond: DelegationBond | null;\n    issued_at: string; // ISO 8601 UTC\n    expires_at: string; // ISO 8601 UTC\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface DelegationCanonicalInput {\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    bond_sats: number;\n    /** 64-hex attestation id or the literal string \"none\". */\n    bond_attestation: string;\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Agent-action (SPEC §5) — strict extension of OC Stamp\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ActionContent {\n    hash: string; // \"sha256:<64-hex>\"\n    length: number;\n    mime: string;\n    ref: string | null;\n}\n\nexport interface ActionOts {\n    status: 'pending' | 'confirmed';\n    proof: string;\n    calendars: string[];\n    block_height: number | null;\n    block_hash: string | null;\n    upgraded_at: string | null;\n}\n\nexport interface ActionEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-action';\n    id: string;\n    content: ActionContent;\n    signer: ActorRef; // agent\n    signed_at: string;\n    delegation_id: string; // 64-hex\n    scope_exercised: string; // a sub-scope of some granted scope\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface ActionCanonicalInput {\n    address: string; // agent address\n    content_hash: string;\n    content_length: number;\n    content_mime: string;\n    signed_at: string;\n    delegation_id: string;\n    scope_exercised: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Sub-delegation (SUB-DELEGATION.md, v1.1)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface SubdelegationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-subdelegation';\n    id: string; // 64-hex sha256(canonical_message)\n    parent_id: string; // 64-hex; the immediate parent envelope's id\n    /** The sub-principal — equal to parent.agent.address. */\n    principal: ActorRef;\n    /** The recipient sub-agent. */\n    agent: ActorRef;\n    /**\n     * v1.0 / v1.1 public mode: each scope MUST be a sub-scope of some scope\n     * on the parent. v1.2 private mode: omitted; `scopes_encrypted` set.\n     */\n    scopes?: string[];\n    /** v1.2 private mode — same shape as the root delegation field. */\n    scopes_encrypted?: ScopesEncryptedEnvelope;\n    issued_at: string; // ISO 8601 UTC; >= parent.issued_at\n    expires_at: string; // ISO 8601 UTC; <= parent.expires_at\n    nonce: string; // 32-hex random\n    revocation: DelegationRevocationRef;\n    sig: Signature;\n}\n\nexport interface SubdelegationCanonicalInput {\n    parent_id: string;\n    principal: string;\n    agent: string;\n    scopes: string[]; // pre-canonicalized, pre-sorted\n    issued_at: string;\n    expires_at: string;\n    nonce: string;\n}\n\n/** Either a root or a sub envelope; chain links walk up to a root delegation. */\nexport type ChainLink = DelegationEnvelope | SubdelegationEnvelope;\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Revocation (SPEC §9)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface RevocationEnvelope {\n    v: typeof ENVELOPE_VERSION;\n    kind: 'agent-revocation';\n    id: string;\n    delegation_id: string;\n    signer: ActorRef;\n    /** Short ASCII rationale, <= 128 bytes. Empty string if omitted. */\n    reason: string;\n    signed_at: string;\n    ots: ActionOts | null;\n    sig: Signature;\n}\n\nexport interface RevocationCanonicalInput {\n    address: string;\n    delegation_id: string;\n    reason: string;\n    signed_at: string;\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Error codes (SPEC §11)\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport type AgentErrorCode =\n    | 'E_UNSUPPORTED_VERSION'\n    | 'E_MALFORMED'\n    | 'E_BAD_ID'\n    | 'E_BAD_SIG'\n    | 'E_BAD_SCOPE_GRAMMAR'\n    | 'E_NOT_YET_VALID'\n    | 'E_EXPIRED'\n    | 'E_REVOKED'\n    | 'E_DELEGATION_MISMATCH'\n    | 'E_AGENT_MISMATCH'\n    | 'E_OUT_OF_WINDOW'\n    | 'E_SCOPE_DENIED'\n    | 'E_BAD_ACTION_STAMP'\n    | 'E_NO_BOND'\n    | 'E_BOND_UNMET'\n    | 'E_BOND_UNVERIFIED'\n    | 'E_REVOKER_UNAUTHORIZED'\n    | 'E_CALENDAR_UNREACHABLE'\n    | 'E_SUBDELEGATION_DEPTH_EXCEEDED'\n    | 'E_SUBDELEGATION_PRINCIPAL_MISMATCH'\n    | 'E_SUBDELEGATION_EXPIRES_EXTENDED'\n    | 'E_SUBDELEGATION_SCOPE_ESCALATED'\n    | 'E_SCOPES_BOTH_PROVIDED'\n    | 'E_SCOPES_NEITHER_PROVIDED'\n    | 'E_SCOPES_UNREADABLE'\n    | 'E_BAD_LOCK_ENVELOPE'\n    // v1.2 federation principal (FEDERATION.md §3.3)\n    | 'E_BAD_FEDERATION_DESCRIPTOR'\n    | 'E_THRESHOLD_MISMATCH'\n    | 'E_THRESHOLD_NOT_MET'\n    | 'E_UNKNOWN_GUARDIAN'\n    | 'E_DUPLICATE_GUARDIAN';\n\nexport interface VerifyOk<T> {\n    ok: true;\n    envelope: T;\n    canonicalMessage: string;\n    id: string;\n}\n\nexport interface VerifyErr {\n    ok: false;\n    code: AgentErrorCode;\n    message: string;\n}\n\nexport type VerifyDelegationResult = VerifyOk<DelegationEnvelope> | VerifyErr;\nexport type VerifyRevocationResult = VerifyOk<RevocationEnvelope> | VerifyErr;\nexport type VerifySubdelegationResult = VerifyOk<SubdelegationEnvelope> | VerifyErr;\n\nexport interface VerifyActionOkExtra {\n    /** The ROOT delegation rooting the authority chain. */\n    delegation: DelegationEnvelope;\n    /**\n     * The sub-delegation chain `[S_1, …, S_leaf]`. Empty when the action cites\n     * the root directly. The action's authority leaf is\n     * `chain[chain.length - 1] ?? delegation`.\n     */\n    chain: SubdelegationEnvelope[];\n    scopeExercised: string;\n    anchor:\n        | { status: 'none' }\n        | { status: 'pending' }\n        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: boolean };\n}\n\nexport type VerifyActionResult =\n    | (VerifyOk<ActionEnvelope> & VerifyActionOkExtra)\n    | VerifyErr;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "OC Agent canonical messages, envelope formats (delegation/action/revocation), scope grammar, and verification. See https://github.com/orangecheck/oc-agent-protocol.",
   "keywords": [
     "bitcoin",

package/src/federation.test.ts

@@ -0,0 +1,139 @@
+// Conformance: OC Agent v1.2 federation-principal vectors (FEDERATION.md §9),
+// loaded from oc-agent-protocol/test-vectors/ v18–v26.
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import {
+    computeFederationDescriptorId,
+    federationDescriptorCanonicalMessage,
+    verifyFederationDelegation,
+    verifyFederationRevocation,
+    type FederationDelegationEnvelope,
+    type FederationRevocationEnvelope,
+} from './federation.js';
+import { verifyDelegation } from './verify.js';
+import type { DelegationEnvelope } from './types.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const VECTORS_DIR =
+    process.env.OC_AGENT_VECTORS_DIR ??
+    resolve(__dirname, '..', '..', '..', 'oc-agent-protocol', 'test-vectors');
+
+async function load(name: string): Promise<any> {
+    return JSON.parse(await readFile(resolve(VECTORS_DIR, name), 'utf8'));
+}
+
+const opts = { skipSignatureVerification: true, skipTemporalCheck: true } as const;
+
+// FEDERATION.md + its v18–v26 vectors live on the oc-agent-protocol
+// `spec/federation-v1.2` DRAFT branch (not yet merged to main). When the spec
+// checkout doesn't have them (e.g. CI clones spec main), skip these conformance
+// tests rather than failing — the implementation is still type-checked + built.
+const HAVE_FED_VECTORS = existsSync(resolve(VECTORS_DIR, 'v18-federation-descriptor-3of5.json'));
+const d = HAVE_FED_VECTORS ? describe : describe.skip;
+
+if (!HAVE_FED_VECTORS) {
+    describe('federation conformance', () => {
+        it.skip('skipped — federation vectors absent (draft spec branch not present)', () => {});
+    });
+}
+
+d('federation descriptor (v18)', () => {
+    it('canonical message + descriptor_id reconstruct byte-identical', async () => {
+        const v = await load('v18-federation-descriptor-3of5.json');
+        const descriptor = {
+            v: 1 as const,
+            kind: 'agent-federation' as const,
+            threshold: v.inputs.threshold,
+            guardians: v.inputs.guardians,
+        };
+        expect(federationDescriptorCanonicalMessage(descriptor)).toBe(
+            v.expected.canonical_message
+        );
+        expect(computeFederationDescriptorId(descriptor)).toBe(v.expected.descriptor_id);
+    });
+});
+
+d('federation delegation vectors (v19–v24, v26)', () => {
+    const cases: Array<[string, 'valid' | 'invalid']> = [
+        ['v19-federation-delegation-3of5-valid.json', 'valid'],
+        ['v20-federation-delegation-2of5-below-threshold.json', 'invalid'],
+        ['v21-federation-delegation-duplicate-guardian.json', 'invalid'],
+        ['v22-federation-delegation-unknown-guardian.json', 'invalid'],
+        ['v23-federation-delegation-descriptor-id-mismatch.json', 'invalid'],
+        ['v24-federation-delegation-threshold-mismatch.json', 'invalid'],
+        ['v26-federation-singleaddress-baseline-unchanged.json', 'valid'],
+    ];
+
+    for (const [file, verdict] of cases) {
+        it(`${file} → verifier returns ${verdict}`, async () => {
+            const v = await load(file);
+            const env = v.expected.envelope;
+            const result =
+                env.principal?.alg === 'federation'
+                    ? await verifyFederationDelegation({
+                          envelope: env as FederationDelegationEnvelope,
+                          ...opts,
+                      })
+                    : await verifyDelegation({
+                          envelope: env as DelegationEnvelope,
+                          skipSignatureVerification: true,
+                          skipTemporalCheck: true,
+                      });
+            expect(result.ok).toBe(verdict === 'valid');
+            if (verdict === 'valid' && result.ok) {
+                expect(result.id).toBe(env.id);
+            }
+        });
+    }
+});
+
+d('federation revocation (v25)', () => {
+    it('3-of-5 threshold met → valid', async () => {
+        const v = await load('v25-federation-revocation-3of5-valid.json');
+        const result = await verifyFederationRevocation({
+            envelope: v.expected.envelope as FederationRevocationEnvelope,
+            skipSignatureVerification: true,
+        });
+        expect(result.ok).toBe(true);
+        if (result.ok) expect(result.id).toBe(v.expected.envelope.id);
+    });
+});
+
+d('federation reject reasons (each invalid case fails for its named reason)', () => {
+    it('below threshold → E_THRESHOLD_NOT_MET', async () => {
+        const v = await load('v20-federation-delegation-2of5-below-threshold.json');
+        const r = await verifyFederationDelegation({ envelope: v.expected.envelope, ...opts });
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.code).toBe('E_THRESHOLD_NOT_MET');
+    });
+    it('duplicate guardian → E_DUPLICATE_GUARDIAN', async () => {
+        const v = await load('v21-federation-delegation-duplicate-guardian.json');
+        const r = await verifyFederationDelegation({ envelope: v.expected.envelope, ...opts });
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.code).toBe('E_DUPLICATE_GUARDIAN');
+    });
+    it('unknown guardian → E_UNKNOWN_GUARDIAN', async () => {
+        const v = await load('v22-federation-delegation-unknown-guardian.json');
+        const r = await verifyFederationDelegation({ envelope: v.expected.envelope, ...opts });
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.code).toBe('E_UNKNOWN_GUARDIAN');
+    });
+    it('descriptor_id mismatch → E_BAD_FEDERATION_DESCRIPTOR', async () => {
+        const v = await load('v23-federation-delegation-descriptor-id-mismatch.json');
+        const r = await verifyFederationDelegation({ envelope: v.expected.envelope, ...opts });
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.code).toBe('E_BAD_FEDERATION_DESCRIPTOR');
+    });
+    it('threshold mismatch → E_THRESHOLD_MISMATCH', async () => {
+        const v = await load('v24-federation-delegation-threshold-mismatch.json');
+        const r = await verifyFederationDelegation({ envelope: v.expected.envelope, ...opts });
+        expect(r.ok).toBe(false);
+        if (!r.ok) expect(r.code).toBe('E_THRESHOLD_MISMATCH');
+    });
+});

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,