@orangecheck/agent-core 2.6.0 → 2.7.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' | 'E_BAD_FEDERATION_DESCRIPTOR' | 'E_THRESHOLD_MISMATCH' | 'E_THRESHOLD_NOT_MET' | 'E_UNKNOWN_GUARDIAN' | 'E_DUPLICATE_GUARDIAN';
+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_STALE' | '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;
@@ -187,6 +187,14 @@ interface VerifyActionOkExtra {
         blockHash: string;
         verified: true;
     };
+    asOf: {
+        basis: 'now';
+        now: string;
+    } | {
+        basis: 'signed_at';
+        signedAt: string;
+        anchored: boolean;
+    };
 }
 type VerifyActionResult = (VerifyOk<ActionEnvelope> & VerifyActionOkExtra) | VerifyErr;
 

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' | 'E_BAD_FEDERATION_DESCRIPTOR' | 'E_THRESHOLD_MISMATCH' | 'E_THRESHOLD_NOT_MET' | 'E_UNKNOWN_GUARDIAN' | 'E_DUPLICATE_GUARDIAN';
+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_STALE' | '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;
@@ -187,6 +187,14 @@ interface VerifyActionOkExtra {
         blockHash: string;
         verified: true;
     };
+    asOf: {
+        basis: 'now';
+        now: string;
+    } | {
+        basis: 'signed_at';
+        signedAt: string;
+        anchored: boolean;
+    };
 }
 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    /**\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"]}
+{"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_STALE'\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     * The time the verdict holds for. `now`: verifyAction, checked live.\n     * `signed_at`: verifyActionAsOfSignedAt, checked as of the time the agent\n     * claims; `anchored` is false when only the agent says so.\n     */\n    asOf:\n        | { basis: 'now'; now: string }\n        | { basis: 'signed_at'; signedAt: string; anchored: 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    // 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"]}
+{"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_STALE'\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     * The time the verdict holds for. `now`: verifyAction, checked live.\n     * `signed_at`: verifyActionAsOfSignedAt, checked as of the time the agent\n     * claims; `anchored` is false when only the agent says so.\n     */\n    asOf:\n        | { basis: 'now'; now: string }\n        | { basis: 'signed_at'; signedAt: string; anchored: 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": "2.6.0",
+  "version": "2.7.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/index.ts

@@ -37,15 +37,19 @@ export type { Scope, ScopeConstraint, ScopeOp, ValidationOptions } from './scope
 export {
     verifyDelegation,
     verifyAction,
+    verifyActionAsOfSignedAt,
+    createReplayGuard,
     verifyRevocation,
     verifySubdelegation,
     AgentError,
     DEFAULT_MAX_CHAIN_DEPTH,
+    DEFAULT_MAX_SKEW_MS,
 } from './verify.js';
 export type {
     VerifyBase,
     VerifyDelegationInput,
     VerifyActionInput,
+    VerifyActionAsOfSignedAtInput,
     VerifyRevocationInput,
     VerifySubdelegationInput,
 } from './verify.js';

package/src/live-time.test.ts

@@ -0,0 +1,151 @@
+// SPEC §8.1 step 6 checks the delegation at the time of verification, not at
+// the action's signed_at. The agent picks signed_at, so an action that only
+// had to fit the delegation's window could be backdated past its expiry or past
+// a revocation and still verify. A live verifier checks at `now`; an audit of a
+// past action says outright that it relied on the agent's claimed time.
+import { describe, expect, it } from 'vitest';
+
+import { computeActionId, computeRevocationId } from './canonical.js';
+import { createReplayGuard, verifyAction, verifyActionAsOfSignedAt } from './verify.js';
+import type { ActionEnvelope, DelegationEnvelope, RevocationEnvelope } from './types.js';
+
+const delegation: DelegationEnvelope = {
+    v: 1,
+    kind: 'agent-delegation',
+    id: '36d79600191db871baa3fc9aa3b5e77750a5c423b1f620ec26cf16bd122e19a7',
+    principal: { address: 'bc1qprincipal000000000000000000000000000000', alg: 'bip322' },
+    agent: { address: 'bc1qagent0000000000000000000000000000000000', alg: 'bip322' },
+    scopes: ['lock:seal(recipient=bc1qalice000000000000000000000000000000000)'],
+    bond: null,
+    issued_at: '2026-04-22T12:00:00Z',
+    expires_at: '2026-04-29T12:00:00Z',
+    nonce: '0123456789abcdef0123456789abcdef',
+    revocation: { holders: ['principal'], ref: null },
+    sig: { alg: 'bip322', pubkey: 'bc1qprincipal000000000000000000000000000000', value: 'AAAA' },
+} as DelegationEnvelope;
+
+function action(signed_at: string): ActionEnvelope {
+    const canon = {
+        address: delegation.agent.address,
+        content_hash: 'sha256:' + '00'.repeat(32),
+        content_length: 0,
+        content_mime: 'text/plain',
+        signed_at,
+        delegation_id: delegation.id,
+        scope_exercised: delegation.scopes![0]!,
+    };
+    return {
+        v: 1,
+        kind: 'agent-action',
+        id: computeActionId(canon),
+        content: { hash: canon.content_hash, length: 0, mime: 'text/plain', ref: null },
+        signer: { address: canon.address, alg: 'bip322' },
+        signed_at,
+        delegation_id: delegation.id,
+        scope_exercised: canon.scope_exercised,
+        ots: null,
+        sig: { alg: 'bip322', pubkey: canon.address, value: 'AAAA' },
+    } as ActionEnvelope;
+}
+
+function revocation(signed_at: string): RevocationEnvelope {
+    const canon = { address: delegation.principal.address, delegation_id: delegation.id, reason: '', signed_at };
+    return {
+        v: 1,
+        kind: 'agent-revocation',
+        id: computeRevocationId(canon),
+        delegation_id: delegation.id,
+        signer: { address: canon.address, alg: 'bip322' },
+        reason: '',
+        signed_at,
+        ots: null,
+        sig: { alg: 'bip322', pubkey: canon.address, value: 'AAAA' },
+    } as RevocationEnvelope;
+}
+
+const base = { delegation, skipSignatureVerification: true };
+
+describe('live verification checks at now', () => {
+    it('refuses an action backdated into the window of a delegation that has expired', async () => {
+        const r = await verifyAction({
+            ...base,
+            action: action('2026-04-28T00:00:00Z'),
+            revocations: [],
+            now: new Date('2026-05-01T00:00:00Z'),
+        });
+        expect(r.ok === false && r.code).toBe('E_EXPIRED');
+    });
+
+    it('refuses an action backdated to before a revocation that is already in effect', async () => {
+        const r = await verifyAction({
+            ...base,
+            action: action('2026-04-24T11:59:00Z'),
+            revocations: [revocation('2026-04-24T11:59:30Z')],
+            now: new Date('2026-04-24T12:00:00Z'),
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+    });
+
+    it('refuses an action signed further from now than the freshness bound', async () => {
+        const now = new Date('2026-04-24T12:00:00Z');
+        const old = await verifyAction({ ...base, action: action('2026-04-24T11:50:00Z'), revocations: [], now });
+        expect(old.ok === false && old.code).toBe('E_STALE');
+        const ahead = await verifyAction({ ...base, action: action('2026-04-24T12:05:00Z'), revocations: [], now });
+        expect(ahead.ok === false && ahead.code).toBe('E_STALE');
+    });
+
+    it('accepts a fresh action under a clear feed, and says it was checked at now', async () => {
+        const now = new Date('2026-04-24T12:00:00Z');
+        const r = await verifyAction({ ...base, action: action('2026-04-24T11:59:30Z'), revocations: [], now });
+        expect(r.ok).toBe(true);
+        expect(r.ok && r.asOf).toEqual({ basis: 'now', now: '2026-04-24T12:00:00.000Z' });
+    });
+
+    it('takes a wider freshness bound when the caller sets one', async () => {
+        const r = await verifyAction({
+            ...base,
+            action: action('2026-04-24T11:50:00Z'),
+            revocations: [],
+            now: new Date('2026-04-24T12:00:00Z'),
+            maxSkewMs: 15 * 60_000,
+        });
+        expect(r.ok).toBe(true);
+    });
+
+    it('does not let a revocation dated in the future refuse an action today', async () => {
+        const r = await verifyAction({
+            ...base,
+            action: action('2026-04-24T11:59:30Z'),
+            revocations: [revocation('2026-04-25T00:00:00Z')],
+            now: new Date('2026-04-24T12:00:00Z'),
+        });
+        expect(r.ok).toBe(true);
+    });
+});
+
+describe('an audit checks as of signed_at, and says that time is a claim', () => {
+    it('accepts a past action inside its window, with an unanchored signed_at', async () => {
+        const r = await verifyActionAsOfSignedAt({ ...base, action: action('2026-04-28T00:00:00Z'), revocations: [] });
+        expect(r.ok).toBe(true);
+        expect(r.ok && r.asOf).toEqual({ basis: 'signed_at', signedAt: '2026-04-28T00:00:00Z', anchored: false });
+    });
+
+    it('still refuses an action that claims a time after the revocation', async () => {
+        const r = await verifyActionAsOfSignedAt({
+            ...base,
+            action: action('2026-04-24T12:00:00Z'),
+            revocations: [revocation('2026-04-24T11:59:30Z')],
+        });
+        expect(r.ok === false && r.code).toBe('E_REVOKED');
+    });
+});
+
+describe('createReplayGuard', () => {
+    it('admits an action once, and forgets it when it could no longer pass as fresh', () => {
+        const guard = createReplayGuard(120_000);
+        const a = action('2026-04-24T12:00:00Z');
+        expect(guard.firstUse(a, new Date('2026-04-24T12:00:05Z'))).toBe(true);
+        expect(guard.firstUse(a, new Date('2026-04-24T12:01:00Z'))).toBe(false);
+        expect(guard.firstUse(a, new Date('2026-04-24T12:02:01Z'))).toBe(true);
+    });
+});

package/src/revocation-authority.test.ts

@@ -5,7 +5,7 @@
 import { describe, expect, it } from 'vitest';
 
 import { computeActionId, computeDelegationId, computeRevocationId } from './canonical.js';
-import { verifyAction, verifyDelegation, verifyRevocation } from './verify.js';
+import { verifyActionAsOfSignedAt, verifyDelegation, verifyRevocation } from './verify.js';
 import type { ActionEnvelope, ActionOts, DelegationEnvelope, RevocationEnvelope } from './types.js';
 
 const PRINCIPAL = 'bc1qprincipal000000000000000000000000000000';
@@ -91,6 +91,8 @@ function confirmed(height: number): ActionOts {
 
 const AT = new Date('2026-04-23T12:00:00Z');
 
+// Priority between an action and a revocation (SPEC §9.3) is a question about
+// the action's own time, so these run as audits, as of signed_at.
 describe('revocation authority always includes the principal', () => {
     for (const holders of [['agent'], [], ['principal'], undefined, 'agent']) {
         it(`principal revocation is honoured with holders=${JSON.stringify(holders)}`, async () => {
@@ -105,7 +107,7 @@ describe('revocation authority always includes the principal', () => {
                 now: AT,
             });
             expect(dr.ok === false && dr.code).toBe('E_REVOKED');
-            const ar = await verifyAction({
+            const ar = await verifyActionAsOfSignedAt({
                 action: action(d, '2026-04-23T06:00:00Z'),
                 delegation: d,
                 revocations: [rev],
@@ -150,7 +152,7 @@ describe('revocation priority uses only verified anchors', () => {
     const later = '2026-04-23T06:00:00Z';
 
     it('an action anchor with no anchor verifier does not outrank a revocation', async () => {
-        const r = await verifyAction({
+        const r = await verifyActionAsOfSignedAt({
             action: action(d, later, confirmed(1)),
             delegation: d,
             revocations: [rev],
@@ -160,7 +162,7 @@ describe('revocation priority uses only verified anchors', () => {
     });
 
     it('an action anchor the verifier rejects does not outrank a revocation', async () => {
-        const r = await verifyAction({
+        const r = await verifyActionAsOfSignedAt({
             action: action(d, later, confirmed(1)),
             delegation: d,
             revocations: [rev],
@@ -168,7 +170,7 @@ describe('revocation priority uses only verified anchors', () => {
             verifyOtsAnchor: async () => false,
         });
         expect(r.ok === false && r.code).toBe('E_REVOKED');
-        const clean = await verifyAction({
+        const clean = await verifyActionAsOfSignedAt({
             action: action(d, later, confirmed(1)),
             delegation: d,
             revocations: [],
@@ -185,14 +187,14 @@ describe('revocation priority uses only verified anchors', () => {
 
     // 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({
+        const unwalked = await verifyActionAsOfSignedAt({
             action: action(d, later, confirmed(1)),
             delegation: d,
             revocations: [],
             skipSignatureVerification: true,
         });
         expect(unwalked.ok && unwalked.anchor.status).toBe('claimed');
-        const walked = await verifyAction({
+        const walked = await verifyActionAsOfSignedAt({
             action: action(d, later, confirmed(1)),
             delegation: d,
             revocations: [],
@@ -211,7 +213,7 @@ describe('revocation priority uses only verified anchors', () => {
         const a = action(d, later, confirmed(100));
         const revAnchored = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(200));
         const seen: string[] = [];
-        const r = await verifyAction({
+        const r = await verifyActionAsOfSignedAt({
             action: a,
             delegation: d,
             revocations: [revAnchored],
@@ -227,7 +229,7 @@ describe('revocation priority uses only verified anchors', () => {
     });
 
     it('a verified action anchor against an unanchored revocation falls back to signed times', async () => {
-        const r = await verifyAction({
+        const r = await verifyActionAsOfSignedAt({
             action: action(d, later, confirmed(1)),
             delegation: d,
             revocations: [rev],
@@ -235,7 +237,7 @@ describe('revocation priority uses only verified anchors', () => {
             verifyOtsAnchor: async () => true,
         });
         expect(r.ok === false && r.code).toBe('E_REVOKED');
-        const before = await verifyAction({
+        const before = await verifyActionAsOfSignedAt({
             action: action(d, '2026-04-22T18:00:00Z', confirmed(1)),
             delegation: d,
             revocations: [rev],
@@ -248,7 +250,7 @@ describe('revocation priority uses only verified anchors', () => {
     it('a revocation anchor that does not verify cannot move the revocation later', async () => {
         const revFarFuture = revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(10_000_000));
         const a = action(d, later, confirmed(100));
-        const r = await verifyAction({
+        const r = await verifyActionAsOfSignedAt({
             action: a,
             delegation: d,
             revocations: [revFarFuture],
@@ -262,7 +264,7 @@ describe('revocation priority uses only verified anchors', () => {
         const a = action(d, later, confirmed(300));
         const revAt = (h: number) => revocation(d, PRINCIPAL, '2026-04-23T00:00:00Z', confirmed(h));
         const verifyOtsAnchor = async () => true;
-        const earlierRev = await verifyAction({
+        const earlierRev = await verifyActionAsOfSignedAt({
             action: a,
             delegation: d,
             revocations: [revAt(300)],
@@ -270,7 +272,7 @@ describe('revocation priority uses only verified anchors', () => {
             verifyOtsAnchor,
         });
         expect(earlierRev.ok === false && earlierRev.code).toBe('E_REVOKED');
-        const laterRev = await verifyAction({
+        const laterRev = await verifyActionAsOfSignedAt({
             action: a,
             delegation: d,
             revocations: [revAt(301)],

package/src/revocation-failclosed.test.ts

@@ -106,7 +106,7 @@ describe('the refusal names a query relays answer', () => {
     });
 
     it('verifyAction', async () => {
-        const r = await verifyAction({ action, delegation, skipSignatureVerification: true });
+        const r = await verifyAction({ action, delegation, skipSignatureVerification: true, now: AT });
         expect(r.ok === false && r.code).toBe('E_MALFORMED');
         expect(r.ok === false && r.message).toMatch(/"#t": \[id of every link in the chain\]/);
         expect(r.ok === false && r.message).not.toMatch(/#delegation/);

package/src/test-vectors.test.ts

@@ -18,7 +18,13 @@ import {
     subdelegationCanonicalMessage,
 } from './canonical.js';
 import { parseScope, ScopeParseError } from './scope.js';
-import { verifyAction, verifyDelegation, verifyRevocation, verifySubdelegation } from './verify.js';
+import {
+    verifyAction,
+    verifyActionAsOfSignedAt,
+    verifyDelegation,
+    verifyRevocation,
+    verifySubdelegation,
+} from './verify.js';
 import type {
     ActionEnvelope,
     AgentErrorCode,
@@ -127,6 +133,12 @@ interface NegativeActionVector extends NegativeVectorBase {
         scope_exercised: string;
         content_ref?: string | null;
         ots?: unknown;
+        /** Present on a live vector (§8.1 steps 6–7, §8.3 step 11a): the time of verification. */
+        verified_at?: string;
+        /** The freshness bound a live vector assumes, in seconds. */
+        max_skew_seconds?: number;
+        /** Revocations of the cited delegation, as the inputs of each envelope. */
+        revocations?: { address: string; reason: string; signed_at: string }[];
     };
 }
 
@@ -279,7 +291,8 @@ describe('oc-agent-protocol test vectors', () => {
                 if (!delegation) {
                     throw new Error(`action vector ${name} references missing delegation ${data.inputs.delegation_id}`);
                 }
-                const r = await verifyAction({
+                // A positive vector is the envelope as of its own signed_at.
+                const r = await verifyActionAsOfSignedAt({
                     skipRevocationCheck: true,
                     action: data.expected.envelope,
                     delegation,
@@ -461,12 +474,34 @@ describe('oc-agent-protocol negative test vectors', () => {
                     ots: null,
                     sig: { alg: 'bip322', pubkey: v.inputs.address, value: 'AAAA' },
                 };
-                const r = await verifyAction({
-                    skipRevocationCheck: true,
-                    action,
-                    delegation,
-                    skipSignatureVerification: true,
-                });
+                const revocations: RevocationEnvelope[] = (v.inputs.revocations ?? []).map((rv) => ({
+                    v: 1,
+                    kind: 'agent-revocation',
+                    id: computeRevocationId({ ...rv, delegation_id: v.inputs.delegation_id }),
+                    delegation_id: v.inputs.delegation_id,
+                    signer: { address: rv.address, alg: 'bip322' },
+                    reason: rv.reason,
+                    signed_at: rv.signed_at,
+                    ots: null,
+                    sig: { alg: 'bip322', pubkey: rv.address, value: 'AAAA' },
+                }));
+                // A vector with verified_at is checked live at that time; one
+                // without is an audit of the envelope as of its signed_at.
+                const r = v.inputs.verified_at
+                    ? await verifyAction({
+                          action,
+                          delegation,
+                          skipSignatureVerification: true,
+                          revocations,
+                          now: new Date(v.inputs.verified_at),
+                          maxSkewMs: (v.inputs.max_skew_seconds ?? 120) * 1000,
+                      })
+                    : await verifyActionAsOfSignedAt({
+                          skipRevocationCheck: true,
+                          action,
+                          delegation,
+                          skipSignatureVerification: true,
+                      });
                 expect(r.ok).toBe(false);
                 if (!r.ok) {
                     // v07 specifically allows either E_OUT_OF_WINDOW or E_EXPIRED

package/src/types.ts

@@ -237,6 +237,7 @@ export type AgentErrorCode =
     | 'E_NOT_YET_VALID'
     | 'E_EXPIRED'
     | 'E_REVOKED'
+    | 'E_STALE'
     | 'E_DELEGATION_MISMATCH'
     | 'E_AGENT_MISMATCH'
     | 'E_OUT_OF_WINDOW'
@@ -298,6 +299,14 @@ export interface VerifyActionOkExtra {
         | { status: 'pending' }
         | { status: 'claimed'; blockHeight: number; blockHash: string; verified: false }
         | { status: 'confirmed'; blockHeight: number; blockHash: string; verified: true };
+    /**
+     * The time the verdict holds for. `now`: verifyAction, checked live.
+     * `signed_at`: verifyActionAsOfSignedAt, checked as of the time the agent
+     * claims; `anchored` is false when only the agent says so.
+     */
+    asOf:
+        | { basis: 'now'; now: string }
+        | { basis: 'signed_at'; signedAt: string; anchored: boolean };
 }
 
 export type VerifyActionResult =