@orangecheck/agent-core 2.3.0 → 2.4.0

package/dist/types.d.mts

@@ -176,11 +176,16 @@ interface VerifyActionOkExtra {
         status: 'none';
     } | {
         status: 'pending';
+    } | {
+        status: 'claimed';
+        blockHeight: number;
+        blockHash: string;
+        verified: false;
     } | {
         status: 'confirmed';
         blockHeight: number;
         blockHash: string;
-        verified: boolean;
+        verified: true;
     };
 }
 type VerifyActionResult = (VerifyOk<ActionEnvelope> & VerifyActionOkExtra) | VerifyErr;

package/dist/types.d.ts

@@ -176,11 +176,16 @@ interface VerifyActionOkExtra {
         status: 'none';
     } | {
         status: 'pending';
+    } | {
+        status: 'claimed';
+        blockHeight: number;
+        blockHash: string;
+        verified: false;
     } | {
         status: 'confirmed';
         blockHeight: number;
         blockHash: string;
-        verified: boolean;
+        verified: true;
     };
 }
 type VerifyActionResult = (VerifyOk<ActionEnvelope> & VerifyActionOkExtra) | VerifyErr;

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    // 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"]}
+{"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    /**\n     * `claimed` is a confirmed `ots` block no verifier walked: the block is the\n     * envelope's say-so. Only a passing `verifyOtsAnchor` yields `confirmed`.\n     */\n    anchor:\n        | { status: 'none' }\n        | { status: 'pending' }\n        | { status: 'claimed'; blockHeight: number; blockHash: string; verified: false }\n        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: true };\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    // 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"]}
+{"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    /**\n     * `claimed` is a confirmed `ots` block no verifier walked: the block is the\n     * envelope's say-so. Only a passing `verifyOtsAnchor` yields `confirmed`.\n     */\n    anchor:\n        | { status: 'none' }\n        | { status: 'pending' }\n        | { status: 'claimed'; blockHeight: number; blockHash: string; verified: false }\n        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: true };\n}\n\nexport type VerifyActionResult =\n    | (VerifyOk<ActionEnvelope> & VerifyActionOkExtra)\n    | VerifyErr;\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-core",
-  "version": "2.3.0",
+  "version": "2.4.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

@@ -16,6 +16,7 @@ import {
     type FederationDelegationEnvelope,
     type FederationRevocationEnvelope,
 } from './federation.js';
+import { computeRevocationId } from './canonical.js';
 import { verifyDelegation } from './verify.js';
 import type { DelegationEnvelope } from './types.js';
 
@@ -28,7 +29,11 @@ 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;
+const opts = {
+    skipSignatureVerification: true,
+    skipTemporalCheck: true,
+    skipRevocationCheck: 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
@@ -164,3 +169,94 @@ d('federation reject reasons (each invalid case fails for its named reason)', ()
         if (!r.ok) expect(r.code).toBe('E_THRESHOLD_MISMATCH');
     });
 });
+
+// FEDERATION.md §4 / SECURITY §7 item 7: a revoked federation delegation must
+// not verify, and skipping the revocation check has to be stated.
+d('federation delegation revocation check', () => {
+    const base = { skipSignatureVerification: true, skipTemporalCheck: true } as const;
+
+    it('fails closed when given neither revocations nor an explicit skip', async () => {
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
+        const r = await verifyFederationDelegation({ envelope: dv.expected.envelope, ...base });
+        expect(r.ok).toBe(false);
+        expect(r.ok === false && r.message).toMatch(/requires `revocations`/);
+    });
+
+    it('verifies with an empty revocation list', async () => {
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
+        const r = await verifyFederationDelegation({
+            envelope: dv.expected.envelope,
+            revocations: [],
+            ...base,
+        });
+        expect(r.ok).toBe(true);
+    });
+
+    it('refuses a delegation its federation revoked (v25)', async () => {
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
+        const rv = await load('v25-federation-revocation-3of5-valid.json');
+        const r = await verifyFederationDelegation({
+            envelope: dv.expected.envelope,
+            revocations: [rv.expected.envelope],
+            ...base,
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+    });
+
+    function agentRevocation(del: FederationDelegationEnvelope) {
+        const canon = {
+            address: del.agent.address,
+            delegation_id: del.id,
+            reason: 'agent retired',
+            signed_at: '2026-06-01T00:00:00Z',
+        };
+        return {
+            v: 1 as const,
+            kind: 'agent-revocation' as const,
+            id: computeRevocationId(canon),
+            delegation_id: del.id,
+            signer: { address: del.agent.address, alg: 'bip322' as const },
+            reason: canon.reason,
+            signed_at: canon.signed_at,
+            ots: null,
+            sig: { alg: 'bip322' as const, pubkey: del.agent.address, value: 'AAAA' },
+        };
+    }
+
+    it('honours an agent self-revocation only when holders include the agent', async () => {
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
+        const del = dv.expected.envelope as FederationDelegationEnvelope;
+        const principalOnly = { ...del, revocation: { holders: ['principal' as const], ref: null } };
+        const withAgent = {
+            ...del,
+            revocation: { holders: ['principal' as const, 'agent' as const], ref: null },
+        };
+        const ignored = await verifyFederationDelegation({
+            envelope: principalOnly,
+            revocations: [agentRevocation(principalOnly)],
+            ...base,
+        });
+        expect(ignored.ok).toBe(true);
+        const revoked = await verifyFederationDelegation({
+            envelope: withAgent,
+            revocations: [agentRevocation(withAgent)],
+            ...base,
+        });
+        expect(revoked.ok === false && revoked.code).toBe('E_REVOKED');
+    });
+
+    it('ignores a revocation from another federation', async () => {
+        const dv = await load('v19-federation-delegation-3of5-valid.json');
+        const rv = await load('v25-federation-revocation-3of5-valid.json');
+        const forged = {
+            ...rv.expected.envelope,
+            signer: { ...rv.expected.envelope.signer, descriptor_id: 'e'.repeat(64) },
+        };
+        const r = await verifyFederationDelegation({
+            envelope: dv.expected.envelope,
+            revocations: [forged],
+            ...base,
+        });
+        expect(r.ok).toBe(true);
+    });
+});

package/src/federation.ts

@@ -25,7 +25,13 @@ import {
     hexEncode,
     revocationCanonicalMessage,
 } from './canonical.js';
-import type { ActorRef, AgentErrorCode, DelegationBond, DelegationRevocationRef } from './types.js';
+import type {
+    ActorRef,
+    AgentErrorCode,
+    DelegationBond,
+    DelegationRevocationRef,
+    RevocationEnvelope,
+} from './types.js';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Types (FEDERATION.md §2 / §3.2)
@@ -221,6 +227,13 @@ async function checkFederationQuorum(
 
 export interface VerifyFederationDelegationInput extends VerifyFederationBase {
     envelope: FederationDelegationEnvelope;
+    /**
+     * Revocations to check (kind-30085 by `#delegation`): federation revocations,
+     * and agent self-revocations when `revocation.holders` includes "agent".
+     * Required unless `skipRevocationCheck` states that revocation is not checked.
+     */
+    revocations?: Array<FederationRevocationEnvelope | RevocationEnvelope>;
+    skipRevocationCheck?: boolean;
     now?: Date;
     skipTemporalCheck?: boolean;
 }
@@ -273,6 +286,21 @@ export async function verifyFederationDelegation(
     const quorum = await checkFederationQuorum(env.principal, env.sig, env.id, input);
     if (!quorum.ok) return quorum;
 
+    // Revocation — the same rule as verifyDelegation: check unless told not to.
+    if (!input.skipRevocationCheck && !input.revocations) {
+        return fail(
+            'E_MALFORMED',
+            'verifyFederationDelegation requires `revocations` (fetch kind-30085 by #delegation) ' +
+                'or an explicit skipRevocationCheck:true to state that revocation is not being checked'
+        );
+    }
+    for (const rev of input.revocations ?? []) {
+        if (rev?.delegation_id !== env.id) continue;
+        const rr = await verifyRevocationOf(env, rev, input);
+        if (!rr.ok) continue; // a malformed or unauthorized revocation revokes nothing
+        return fail('E_REVOKED', `delegation ${env.id} was revoked by ${rev.id}`);
+    }
+
     if (!input.skipTemporalCheck) {
         const now = input.now ?? new Date();
         const issued = new Date(env.issued_at);
@@ -285,6 +313,52 @@ export async function verifyFederationDelegation(
     return { ok: true, id: env.id, canonicalMessage: delegationCanonicalMessage(canonInput) };
 }
 
+/**
+ * FEDERATION.md §4: the federation (M-of-N) may always revoke; the agent may
+ * self-revoke with its own BIP-322 signature when `revocation.holders`
+ * includes "agent".
+ */
+async function verifyRevocationOf(
+    d: FederationDelegationEnvelope,
+    rev: FederationRevocationEnvelope | RevocationEnvelope,
+    input: VerifyFederationBase
+): Promise<FederationVerifyResult> {
+    if ((rev.signer as FederationPrincipal | undefined)?.alg === 'federation') {
+        return verifyFederationRevocation({
+            envelope: rev as FederationRevocationEnvelope,
+            delegation: d,
+            verifyBip322: input.verifyBip322,
+            skipSignatureVerification: input.skipSignatureVerification,
+        });
+    }
+    const v1 = rev as RevocationEnvelope;
+    const holders = d.revocation?.holders ?? ['principal'];
+    if (!Array.isArray(holders) || !holders.includes('agent')) {
+        return fail('E_REVOKER_UNAUTHORIZED', 'only the federation may revoke this delegation');
+    }
+    if (v1.kind !== 'agent-revocation' || v1.signer?.address !== d.agent.address) {
+        return fail('E_REVOKER_UNAUTHORIZED', 'a single-address revocation must be signed by the agent');
+    }
+    if (typeof v1.reason !== 'string' || !ISO_UTC.test(v1.signed_at ?? '')) {
+        return fail('E_MALFORMED', 'revocation reason / signed_at invalid');
+    }
+    const canonInput = {
+        address: v1.signer.address,
+        delegation_id: v1.delegation_id,
+        reason: v1.reason,
+        signed_at: v1.signed_at,
+    };
+    const id = computeRevocationId(canonInput);
+    if (id !== v1.id) return fail('E_BAD_ID', `reconstructed id (${id}) != revocation.id (${v1.id})`);
+    if (!input.skipSignatureVerification) {
+        if (!input.verifyBip322) return fail('E_BAD_SIG', 'no BIP-322 verifier supplied');
+        if (typeof v1.sig?.value !== 'string' || !(await input.verifyBip322(v1.id, v1.sig.value, v1.signer.address))) {
+            return fail('E_BAD_SIG', 'revocation BIP-322 signature did not verify');
+        }
+    }
+    return { ok: true, id: v1.id, canonicalMessage: revocationCanonicalMessage(canonInput) };
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Revocation under a federation principal (FEDERATION.md §4)
 // ─────────────────────────────────────────────────────────────────────────────

package/src/revocation-authority.test.ts

@@ -176,13 +176,37 @@ describe('revocation priority uses only verified anchors', () => {
             verifyOtsAnchor: async () => false,
         });
         expect(clean.ok && clean.anchor).toEqual({
-            status: 'confirmed',
+            status: 'claimed',
             blockHeight: 1,
             blockHash: 'ab'.repeat(32),
             verified: false,
         });
     });
 
+    // The ots block is outside the signature: its block is a claim until walked.
+    it('reports an unwalked anchor as claimed, and a walked one as confirmed', async () => {
+        const unwalked = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [],
+            skipSignatureVerification: true,
+        });
+        expect(unwalked.ok && unwalked.anchor.status).toBe('claimed');
+        const walked = await verifyAction({
+            action: action(d, later, confirmed(1)),
+            delegation: d,
+            revocations: [],
+            skipSignatureVerification: true,
+            verifyOtsAnchor: async () => true,
+        });
+        expect(walked.ok && walked.anchor).toEqual({
+            status: 'confirmed',
+            blockHeight: 1,
+            blockHash: 'ab'.repeat(32),
+            verified: true,
+        });
+    });
+
     it('the anchor verifier is asked about the envelope it belongs to', async () => {
         const a = action(d, later, confirmed(100));
         const revAnchored = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(200));

package/src/types.ts

@@ -289,10 +289,15 @@ export interface VerifyActionOkExtra {
      */
     chain: SubdelegationEnvelope[];
     scopeExercised: string;
+    /**
+     * `claimed` is a confirmed `ots` block no verifier walked: the block is the
+     * envelope's say-so. Only a passing `verifyOtsAnchor` yields `confirmed`.
+     */
     anchor:
         | { status: 'none' }
         | { status: 'pending' }
-        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: boolean };
+        | { status: 'claimed'; blockHeight: number; blockHash: string; verified: false }
+        | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: true };
 }
 
 export type VerifyActionResult =

package/src/verify.ts

@@ -512,8 +512,11 @@ export async function verifyAction(input: VerifyActionInput): Promise<VerifyActi
         if (h === null || hash === null) {
             return err('E_MALFORMED', 'confirmed OTS proof missing block_height or block_hash');
         }
-        const verified = actionAnchor !== null;
-        anchor = { status: 'confirmed', blockHeight: h, blockHash: hash, verified } as typeof anchor;
+        anchor = (
+            actionAnchor !== null
+                ? { status: 'confirmed', blockHeight: h, blockHash: hash, verified: true }
+                : { status: 'claimed', blockHeight: h, blockHash: hash, verified: false }
+        ) as typeof anchor;
     }
 
     return {