@the9ines/bolt-core 0.5.1 → 0.6.0

package/dist/btr/constants.d.ts

@@ -0,0 +1,20 @@
+/**
+ * BTR-specific constants — HKDF info strings and key lengths (§14).
+ *
+ * All values locked from PROTOCOL.md §14. No divergence permitted.
+ * Must match Rust bolt-btr/src/constants.rs exactly.
+ */
+/** HKDF info string for session root derivation (§16.3). */
+export declare const BTR_SESSION_ROOT_INFO = "bolt-btr-session-root-v1";
+/** HKDF info string for transfer root derivation (§16.3). */
+export declare const BTR_TRANSFER_ROOT_INFO = "bolt-btr-transfer-root-v1";
+/** HKDF info string for message key derivation (§16.3). */
+export declare const BTR_MESSAGE_KEY_INFO = "bolt-btr-message-key-v1";
+/** HKDF info string for chain key advancement (§16.3). */
+export declare const BTR_CHAIN_ADVANCE_INFO = "bolt-btr-chain-advance-v1";
+/** HKDF info string for DH ratchet step (§16.3). */
+export declare const BTR_DH_RATCHET_INFO = "bolt-btr-dh-ratchet-v1";
+/** BTR key length in bytes (all derived keys). */
+export declare const BTR_KEY_LENGTH = 32;
+/** BTR wire error codes (§16.7, extends PROTOCOL.md §10 registry). */
+export declare const BTR_WIRE_ERROR_CODES: readonly ["RATCHET_STATE_ERROR", "RATCHET_CHAIN_ERROR", "RATCHET_DECRYPT_FAIL", "RATCHET_DOWNGRADE_REJECTED"];

package/dist/btr/constants.js

@@ -0,0 +1,25 @@
+/**
+ * BTR-specific constants — HKDF info strings and key lengths (§14).
+ *
+ * All values locked from PROTOCOL.md §14. No divergence permitted.
+ * Must match Rust bolt-btr/src/constants.rs exactly.
+ */
+/** HKDF info string for session root derivation (§16.3). */
+export const BTR_SESSION_ROOT_INFO = 'bolt-btr-session-root-v1';
+/** HKDF info string for transfer root derivation (§16.3). */
+export const BTR_TRANSFER_ROOT_INFO = 'bolt-btr-transfer-root-v1';
+/** HKDF info string for message key derivation (§16.3). */
+export const BTR_MESSAGE_KEY_INFO = 'bolt-btr-message-key-v1';
+/** HKDF info string for chain key advancement (§16.3). */
+export const BTR_CHAIN_ADVANCE_INFO = 'bolt-btr-chain-advance-v1';
+/** HKDF info string for DH ratchet step (§16.3). */
+export const BTR_DH_RATCHET_INFO = 'bolt-btr-dh-ratchet-v1';
+/** BTR key length in bytes (all derived keys). */
+export const BTR_KEY_LENGTH = 32;
+/** BTR wire error codes (§16.7, extends PROTOCOL.md §10 registry). */
+export const BTR_WIRE_ERROR_CODES = [
+    'RATCHET_STATE_ERROR',
+    'RATCHET_CHAIN_ERROR',
+    'RATCHET_DECRYPT_FAIL',
+    'RATCHET_DOWNGRADE_REJECTED',
+];

package/dist/btr/encrypt.d.ts

@@ -0,0 +1,26 @@
+/**
+ * BTR encryption — NaCl secretbox keyed by BTR message_key (§16.4).
+ *
+ * Uses symmetric NaCl secretbox (XSalsa20-Poly1305), NOT asymmetric box.
+ * Both peers derive identical message_key deterministically via HKDF.
+ * Fresh 24-byte CSPRNG nonce per envelope (production) or fixed nonce (test vectors).
+ */
+/**
+ * Encrypt a chunk using NaCl secretbox with a BTR-derived message_key.
+ *
+ * Returns nonce || ciphertext (24 + plaintext.length + 16 bytes).
+ * Fresh 24-byte CSPRNG nonce generated internally.
+ */
+export declare function btrSeal(messageKey: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/**
+ * Encrypt with a caller-provided nonce (deterministic vectors only).
+ * NOT for production — nonce reuse with the same key is catastrophic.
+ */
+export declare function btrSealDeterministic(messageKey: Uint8Array, plaintext: Uint8Array, nonce: Uint8Array): Uint8Array;
+/**
+ * Decrypt a chunk using NaCl secretbox with a BTR-derived message_key.
+ *
+ * Expects nonce || ciphertext format (first 24 bytes are nonce).
+ * Throws BtrError with RATCHET_DECRYPT_FAIL on MAC failure or truncation.
+ */
+export declare function btrOpen(messageKey: Uint8Array, sealed: Uint8Array): Uint8Array;

package/dist/btr/encrypt.js

@@ -0,0 +1,56 @@
+/**
+ * BTR encryption — NaCl secretbox keyed by BTR message_key (§16.4).
+ *
+ * Uses symmetric NaCl secretbox (XSalsa20-Poly1305), NOT asymmetric box.
+ * Both peers derive identical message_key deterministically via HKDF.
+ * Fresh 24-byte CSPRNG nonce per envelope (production) or fixed nonce (test vectors).
+ */
+import tweetnacl from 'tweetnacl';
+import { ratchetDecryptFail } from './errors.js';
+/** NaCl secretbox nonce length (24 bytes). */
+const SECRETBOX_NONCE_LENGTH = 24;
+/** NaCl secretbox MAC overhead (Poly1305, 16 bytes). */
+const SECRETBOX_OVERHEAD = 16;
+/**
+ * Encrypt a chunk using NaCl secretbox with a BTR-derived message_key.
+ *
+ * Returns nonce || ciphertext (24 + plaintext.length + 16 bytes).
+ * Fresh 24-byte CSPRNG nonce generated internally.
+ */
+export function btrSeal(messageKey, plaintext) {
+    const nonce = tweetnacl.randomBytes(SECRETBOX_NONCE_LENGTH);
+    const ciphertext = tweetnacl.secretbox(plaintext, nonce, messageKey);
+    const combined = new Uint8Array(SECRETBOX_NONCE_LENGTH + ciphertext.length);
+    combined.set(nonce);
+    combined.set(ciphertext, SECRETBOX_NONCE_LENGTH);
+    return combined;
+}
+/**
+ * Encrypt with a caller-provided nonce (deterministic vectors only).
+ * NOT for production — nonce reuse with the same key is catastrophic.
+ */
+export function btrSealDeterministic(messageKey, plaintext, nonce) {
+    const ciphertext = tweetnacl.secretbox(plaintext, nonce, messageKey);
+    const combined = new Uint8Array(SECRETBOX_NONCE_LENGTH + ciphertext.length);
+    combined.set(nonce);
+    combined.set(ciphertext, SECRETBOX_NONCE_LENGTH);
+    return combined;
+}
+/**
+ * Decrypt a chunk using NaCl secretbox with a BTR-derived message_key.
+ *
+ * Expects nonce || ciphertext format (first 24 bytes are nonce).
+ * Throws BtrError with RATCHET_DECRYPT_FAIL on MAC failure or truncation.
+ */
+export function btrOpen(messageKey, sealed) {
+    if (sealed.length < SECRETBOX_NONCE_LENGTH + SECRETBOX_OVERHEAD) {
+        throw ratchetDecryptFail('sealed payload too short');
+    }
+    const nonce = sealed.slice(0, SECRETBOX_NONCE_LENGTH);
+    const ciphertext = sealed.slice(SECRETBOX_NONCE_LENGTH);
+    const plaintext = tweetnacl.secretbox.open(ciphertext, nonce, messageKey);
+    if (plaintext === null) {
+        throw ratchetDecryptFail('secretbox open failed');
+    }
+    return plaintext;
+}

package/dist/btr/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * BTR error types — §16.7 error behavior.
+ *
+ * Four error codes with deterministic behavior mapping.
+ * Must match Rust bolt-btr/src/errors.rs semantics exactly.
+ */
+import { BTR_WIRE_ERROR_CODES } from './constants.js';
+type BtrWireErrorCode = (typeof BTR_WIRE_ERROR_CODES)[number];
+/** BTR-specific error — carries a wire error code and disconnect semantics. */
+export declare class BtrError extends Error {
+    /** Canonical wire error code from §16.7. */
+    readonly wireCode: BtrWireErrorCode;
+    constructor(wireCode: BtrWireErrorCode, message: string);
+    /**
+     * Returns true if the required action is disconnect (vs cancel transfer).
+     * Matches Rust BtrError::requires_disconnect().
+     */
+    requiresDisconnect(): boolean;
+}
+/** Ratchet generation mismatch, unexpected DH key, or missing BTR fields. Action: disconnect. */
+export declare function ratchetStateError(detail: string): BtrError;
+/** chain_index != expected next, chain index gap, or replay. Action: cancel transfer. */
+export declare function ratchetChainError(detail: string): BtrError;
+/** NaCl secretbox open fails with BTR message key. Action: cancel transfer. */
+export declare function ratchetDecryptFail(detail: string): BtrError;
+/** Peer advertised BTR but sends invalid envelopes. Action: disconnect. */
+export declare function ratchetDowngradeRejected(detail: string): BtrError;
+export {};

package/dist/btr/errors.js

@@ -0,0 +1,38 @@
+/**
+ * BTR error types — §16.7 error behavior.
+ *
+ * Four error codes with deterministic behavior mapping.
+ * Must match Rust bolt-btr/src/errors.rs semantics exactly.
+ */
+/** BTR-specific error — carries a wire error code and disconnect semantics. */
+export class BtrError extends Error {
+    constructor(wireCode, message) {
+        super(`${wireCode}: ${message}`);
+        this.name = 'BtrError';
+        this.wireCode = wireCode;
+    }
+    /**
+     * Returns true if the required action is disconnect (vs cancel transfer).
+     * Matches Rust BtrError::requires_disconnect().
+     */
+    requiresDisconnect() {
+        return (this.wireCode === 'RATCHET_STATE_ERROR' ||
+            this.wireCode === 'RATCHET_DOWNGRADE_REJECTED');
+    }
+}
+/** Ratchet generation mismatch, unexpected DH key, or missing BTR fields. Action: disconnect. */
+export function ratchetStateError(detail) {
+    return new BtrError('RATCHET_STATE_ERROR', detail);
+}
+/** chain_index != expected next, chain index gap, or replay. Action: cancel transfer. */
+export function ratchetChainError(detail) {
+    return new BtrError('RATCHET_CHAIN_ERROR', detail);
+}
+/** NaCl secretbox open fails with BTR message key. Action: cancel transfer. */
+export function ratchetDecryptFail(detail) {
+    return new BtrError('RATCHET_DECRYPT_FAIL', detail);
+}
+/** Peer advertised BTR but sends invalid envelopes. Action: disconnect. */
+export function ratchetDowngradeRejected(detail) {
+    return new BtrError('RATCHET_DOWNGRADE_REJECTED', detail);
+}

package/dist/btr/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bolt Transfer Ratchet (BTR) — TypeScript parity implementation.
+ *
+ * Barrel re-export for all BTR modules.
+ */
+export { BTR_SESSION_ROOT_INFO, BTR_TRANSFER_ROOT_INFO, BTR_MESSAGE_KEY_INFO, BTR_CHAIN_ADVANCE_INFO, BTR_DH_RATCHET_INFO, BTR_KEY_LENGTH, BTR_WIRE_ERROR_CODES, } from './constants.js';
+export { BtrError, ratchetStateError, ratchetChainError, ratchetDecryptFail, ratchetDowngradeRejected, } from './errors.js';
+export { deriveSessionRoot, deriveTransferRoot, chainAdvance, } from './key-schedule.js';
+export type { ChainAdvanceOutput } from './key-schedule.js';
+export { generateRatchetKeypair, scalarMult, deriveRatchetedSessionRoot, } from './ratchet.js';
+export { btrSeal, btrSealDeterministic, btrOpen } from './encrypt.js';
+export { ReplayGuard } from './replay.js';
+export { BtrMode, negotiateBtr, btrLogToken } from './negotiate.js';
+export type { BtrModeValue } from './negotiate.js';
+export { BtrEngine, BtrTransferContext } from './state.js';

package/dist/btr/index.js

@@ -0,0 +1,21 @@
+/**
+ * Bolt Transfer Ratchet (BTR) — TypeScript parity implementation.
+ *
+ * Barrel re-export for all BTR modules.
+ */
+// Constants
+export { BTR_SESSION_ROOT_INFO, BTR_TRANSFER_ROOT_INFO, BTR_MESSAGE_KEY_INFO, BTR_CHAIN_ADVANCE_INFO, BTR_DH_RATCHET_INFO, BTR_KEY_LENGTH, BTR_WIRE_ERROR_CODES, } from './constants.js';
+// Errors
+export { BtrError, ratchetStateError, ratchetChainError, ratchetDecryptFail, ratchetDowngradeRejected, } from './errors.js';
+// Key schedule
+export { deriveSessionRoot, deriveTransferRoot, chainAdvance, } from './key-schedule.js';
+// DH ratchet
+export { generateRatchetKeypair, scalarMult, deriveRatchetedSessionRoot, } from './ratchet.js';
+// Encrypt/decrypt
+export { btrSeal, btrSealDeterministic, btrOpen } from './encrypt.js';
+// Replay guard
+export { ReplayGuard } from './replay.js';
+// Negotiate
+export { BtrMode, negotiateBtr, btrLogToken } from './negotiate.js';
+// State engine
+export { BtrEngine, BtrTransferContext } from './state.js';

package/dist/btr/key-schedule.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Key schedule — HKDF-SHA256 derivation chain (§16.3).
+ *
+ * All derivations use HKDF-SHA256 with info strings from §14.
+ * Output length is always 32 bytes (BTR_KEY_LENGTH).
+ * Must match Rust bolt-btr/src/key_schedule.rs exactly.
+ */
+/**
+ * Derive session root key from ephemeral shared secret (§16.3).
+ *
+ * session_root_key = HKDF-SHA256(salt=empty, ikm=shared_secret, info="bolt-btr-session-root-v1", len=32)
+ */
+export declare function deriveSessionRoot(ephemeralSharedSecret: Uint8Array): Uint8Array;
+/**
+ * Derive transfer root key from session root key and transfer_id (§16.3).
+ *
+ * transfer_root_key = HKDF-SHA256(salt=transfer_id, ikm=session_root_key, info="bolt-btr-transfer-root-v1", len=32)
+ */
+export declare function deriveTransferRoot(sessionRootKey: Uint8Array, transferId: Uint8Array): Uint8Array;
+/** Output of a single chain advance step. */
+export interface ChainAdvanceOutput {
+    /** Key for encrypting/decrypting one chunk. Single-use. */
+    messageKey: Uint8Array;
+    /** Replacement chain key for the next advance step. */
+    nextChainKey: Uint8Array;
+}
+/**
+ * Advance the symmetric chain: derive message_key and next_chain_key (§16.3).
+ *
+ * message_key = HKDF-SHA256(salt=empty, ikm=chain_key, info="bolt-btr-message-key-v1", len=32)
+ * next_chain_key = HKDF-SHA256(salt=empty, ikm=chain_key, info="bolt-btr-chain-advance-v1", len=32)
+ */
+export declare function chainAdvance(chainKey: Uint8Array): ChainAdvanceOutput;

package/dist/btr/key-schedule.js

@@ -0,0 +1,38 @@
+/**
+ * Key schedule — HKDF-SHA256 derivation chain (§16.3).
+ *
+ * All derivations use HKDF-SHA256 with info strings from §14.
+ * Output length is always 32 bytes (BTR_KEY_LENGTH).
+ * Must match Rust bolt-btr/src/key_schedule.rs exactly.
+ */
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { BTR_KEY_LENGTH, BTR_SESSION_ROOT_INFO, BTR_TRANSFER_ROOT_INFO, BTR_MESSAGE_KEY_INFO, BTR_CHAIN_ADVANCE_INFO, } from './constants.js';
+const encoder = new TextEncoder();
+/**
+ * Derive session root key from ephemeral shared secret (§16.3).
+ *
+ * session_root_key = HKDF-SHA256(salt=empty, ikm=shared_secret, info="bolt-btr-session-root-v1", len=32)
+ */
+export function deriveSessionRoot(ephemeralSharedSecret) {
+    return hkdf(sha256, ephemeralSharedSecret, undefined, encoder.encode(BTR_SESSION_ROOT_INFO), BTR_KEY_LENGTH);
+}
+/**
+ * Derive transfer root key from session root key and transfer_id (§16.3).
+ *
+ * transfer_root_key = HKDF-SHA256(salt=transfer_id, ikm=session_root_key, info="bolt-btr-transfer-root-v1", len=32)
+ */
+export function deriveTransferRoot(sessionRootKey, transferId) {
+    return hkdf(sha256, sessionRootKey, transferId, encoder.encode(BTR_TRANSFER_ROOT_INFO), BTR_KEY_LENGTH);
+}
+/**
+ * Advance the symmetric chain: derive message_key and next_chain_key (§16.3).
+ *
+ * message_key = HKDF-SHA256(salt=empty, ikm=chain_key, info="bolt-btr-message-key-v1", len=32)
+ * next_chain_key = HKDF-SHA256(salt=empty, ikm=chain_key, info="bolt-btr-chain-advance-v1", len=32)
+ */
+export function chainAdvance(chainKey) {
+    const messageKey = hkdf(sha256, chainKey, undefined, encoder.encode(BTR_MESSAGE_KEY_INFO), BTR_KEY_LENGTH);
+    const nextChainKey = hkdf(sha256, chainKey, undefined, encoder.encode(BTR_CHAIN_ADVANCE_INFO), BTR_KEY_LENGTH);
+    return { messageKey, nextChainKey };
+}

package/dist/btr/negotiate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Capability negotiation — BTR mode decision matrix (§4).
+ *
+ * Maps the 6-cell negotiation matrix from the BTR-0 spec.
+ * Must match Rust bolt-btr/src/negotiate.rs exactly.
+ */
+/** BTR negotiation result. */
+export declare const BtrMode: {
+    /** Both peers support BTR. Full per-transfer DH ratchet + per-chunk chain. */
+    readonly FullBtr: "FULL_BTR";
+    /** One peer supports BTR, the other does not. Fall back to static ephemeral. */
+    readonly Downgrade: "DOWNGRADE";
+    /** Neither peer supports BTR. Current v1 static ephemeral. */
+    readonly StaticEphemeral: "STATIC_EPHEMERAL";
+    /** Malformed BTR metadata detected. RATCHET_DOWNGRADE_REJECTED + disconnect. */
+    readonly Reject: "REJECT";
+};
+export type BtrModeValue = (typeof BtrMode)[keyof typeof BtrMode];
+/**
+ * Negotiate BTR mode from capability advertisement.
+ *
+ * Implements the 6-cell matrix from §4:
+ *
+ * | Local | Remote | Well-formed | Result          |
+ * |-------|--------|-------------|-----------------|
+ * | YES   | YES    | YES         | FullBtr         |
+ * | YES   | NO     | -           | Downgrade       |
+ * | NO    | YES    | -           | Downgrade       |
+ * | NO    | NO     | -           | StaticEphemeral |
+ * | YES   | YES    | NO          | Reject          |
+ */
+export declare function negotiateBtr(localSupports: boolean, remoteSupports: boolean, remoteWellFormed: boolean): BtrModeValue;
+/** Returns the log token for a given BTR mode, or null if none. */
+export declare function btrLogToken(mode: BtrModeValue): string | null;

package/dist/btr/negotiate.js

@@ -0,0 +1,50 @@
+/**
+ * Capability negotiation — BTR mode decision matrix (§4).
+ *
+ * Maps the 6-cell negotiation matrix from the BTR-0 spec.
+ * Must match Rust bolt-btr/src/negotiate.rs exactly.
+ */
+/** BTR negotiation result. */
+export const BtrMode = {
+    /** Both peers support BTR. Full per-transfer DH ratchet + per-chunk chain. */
+    FullBtr: 'FULL_BTR',
+    /** One peer supports BTR, the other does not. Fall back to static ephemeral. */
+    Downgrade: 'DOWNGRADE',
+    /** Neither peer supports BTR. Current v1 static ephemeral. */
+    StaticEphemeral: 'STATIC_EPHEMERAL',
+    /** Malformed BTR metadata detected. RATCHET_DOWNGRADE_REJECTED + disconnect. */
+    Reject: 'REJECT',
+};
+/**
+ * Negotiate BTR mode from capability advertisement.
+ *
+ * Implements the 6-cell matrix from §4:
+ *
+ * | Local | Remote | Well-formed | Result          |
+ * |-------|--------|-------------|-----------------|
+ * | YES   | YES    | YES         | FullBtr         |
+ * | YES   | NO     | -           | Downgrade       |
+ * | NO    | YES    | -           | Downgrade       |
+ * | NO    | NO     | -           | StaticEphemeral |
+ * | YES   | YES    | NO          | Reject          |
+ */
+export function negotiateBtr(localSupports, remoteSupports, remoteWellFormed) {
+    if (localSupports && remoteSupports) {
+        return remoteWellFormed ? BtrMode.FullBtr : BtrMode.Reject;
+    }
+    if (localSupports || remoteSupports) {
+        return BtrMode.Downgrade;
+    }
+    return BtrMode.StaticEphemeral;
+}
+/** Returns the log token for a given BTR mode, or null if none. */
+export function btrLogToken(mode) {
+    switch (mode) {
+        case BtrMode.Downgrade:
+            return '[BTR_DOWNGRADE]';
+        case BtrMode.Reject:
+            return '[BTR_DOWNGRADE_REJECTED]';
+        default:
+            return null;
+    }
+}

package/dist/btr/ratchet.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Inter-transfer DH ratchet — §16.3 DH ratchet step.
+ *
+ * Uses tweetnacl.scalarMult for X25519 DH (parity with Rust x25519-dalek).
+ * Uses HKDF-SHA256 for session root key derivation after DH.
+ */
+/**
+ * Generate a fresh X25519 keypair for the DH ratchet step.
+ *
+ * Returns { publicKey, secretKey } both 32 bytes.
+ * The secretKey should be consumed once for DH then discarded.
+ */
+export declare function generateRatchetKeypair(): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/**
+ * Perform X25519 DH with a remote peer's ratchet public key.
+ *
+ * Returns the raw 32-byte DH output.
+ * Matches Rust: x25519-dalek EphemeralSecret::diffie_hellman().
+ */
+export declare function scalarMult(localSecretKey: Uint8Array, remotePublicKey: Uint8Array): Uint8Array;
+/**
+ * Derive new session root key from DH ratchet step output (§16.3).
+ *
+ * new_session_root_key = HKDF-SHA256(
+ *   salt  = current_session_root_key,
+ *   ikm   = dh_output,
+ *   info  = "bolt-btr-dh-ratchet-v1",
+ *   len   = 32
+ * )
+ */
+export declare function deriveRatchetedSessionRoot(currentSessionRootKey: Uint8Array, dhOutput: Uint8Array): Uint8Array;

package/dist/btr/ratchet.js

@@ -0,0 +1,44 @@
+/**
+ * Inter-transfer DH ratchet — §16.3 DH ratchet step.
+ *
+ * Uses tweetnacl.scalarMult for X25519 DH (parity with Rust x25519-dalek).
+ * Uses HKDF-SHA256 for session root key derivation after DH.
+ */
+import tweetnacl from 'tweetnacl';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { BTR_DH_RATCHET_INFO, BTR_KEY_LENGTH } from './constants.js';
+const encoder = new TextEncoder();
+/**
+ * Generate a fresh X25519 keypair for the DH ratchet step.
+ *
+ * Returns { publicKey, secretKey } both 32 bytes.
+ * The secretKey should be consumed once for DH then discarded.
+ */
+export function generateRatchetKeypair() {
+    // tweetnacl.box.keyPair() generates X25519 keypairs
+    const kp = tweetnacl.box.keyPair();
+    return { publicKey: kp.publicKey, secretKey: kp.secretKey };
+}
+/**
+ * Perform X25519 DH with a remote peer's ratchet public key.
+ *
+ * Returns the raw 32-byte DH output.
+ * Matches Rust: x25519-dalek EphemeralSecret::diffie_hellman().
+ */
+export function scalarMult(localSecretKey, remotePublicKey) {
+    return tweetnacl.scalarMult(localSecretKey, remotePublicKey);
+}
+/**
+ * Derive new session root key from DH ratchet step output (§16.3).
+ *
+ * new_session_root_key = HKDF-SHA256(
+ *   salt  = current_session_root_key,
+ *   ikm   = dh_output,
+ *   info  = "bolt-btr-dh-ratchet-v1",
+ *   len   = 32
+ * )
+ */
+export function deriveRatchetedSessionRoot(currentSessionRootKey, dhOutput) {
+    return hkdf(sha256, dhOutput, currentSessionRootKey, encoder.encode(BTR_DH_RATCHET_INFO), BTR_KEY_LENGTH);
+}

package/dist/btr/replay.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Replay rejection — (transfer_id, generation, chain_index) guard (§11).
+ *
+ * ORDER-BTR: chain_index must equal expected_next_index (no gaps).
+ * REPLAY-BTR: (transfer_id, ratchet_generation, chain_index) triple
+ *   prevents cross-generation replay.
+ *
+ * Must match Rust bolt-btr/src/replay.rs semantics exactly.
+ */
+/**
+ * Replay guard tracking seen (transfer_id, generation, chain_index) triples.
+ *
+ * Enforces ORDER-BTR: chain_index must be strictly monotonic per transfer
+ * (no skipped-key buffer). Also rejects cross-generation replay.
+ */
+export declare class ReplayGuard {
+    private seen;
+    private expected;
+    /** Begin tracking a new transfer at the given generation. Resets expected chain_index to 0. */
+    beginTransfer(transferId: Uint8Array, generation: number): void;
+    /**
+     * Check and record a (transfer_id, generation, chain_index) triple.
+     * Throws BtrError on violation.
+     */
+    check(transferId: Uint8Array, generation: number, chainIndex: number): void;
+    /** End tracking for the current transfer. Retains seen set for cross-transfer replay detection. */
+    endTransfer(): void;
+    /** Full reset — clears all state. Used on disconnect. */
+    reset(): void;
+}

package/dist/btr/replay.js

@@ -0,0 +1,81 @@
+/**
+ * Replay rejection — (transfer_id, generation, chain_index) guard (§11).
+ *
+ * ORDER-BTR: chain_index must equal expected_next_index (no gaps).
+ * REPLAY-BTR: (transfer_id, ratchet_generation, chain_index) triple
+ *   prevents cross-generation replay.
+ *
+ * Must match Rust bolt-btr/src/replay.rs semantics exactly.
+ */
+import { ratchetStateError, ratchetChainError } from './errors.js';
+function tripleKey(tid, generation, chainIndex) {
+    // Encode triple as a string key for Set lookup
+    const hexTid = Array.from(tid, (b) => b.toString(16).padStart(2, '0')).join('');
+    return `${hexTid}:${generation}:${chainIndex}`;
+}
+/**
+ * Replay guard tracking seen (transfer_id, generation, chain_index) triples.
+ *
+ * Enforces ORDER-BTR: chain_index must be strictly monotonic per transfer
+ * (no skipped-key buffer). Also rejects cross-generation replay.
+ */
+export class ReplayGuard {
+    constructor() {
+        this.seen = new Set();
+        this.expected = null;
+    }
+    /** Begin tracking a new transfer at the given generation. Resets expected chain_index to 0. */
+    beginTransfer(transferId, generation) {
+        this.expected = {
+            transferId: new Uint8Array(transferId),
+            generation,
+            nextIndex: 0,
+        };
+    }
+    /**
+     * Check and record a (transfer_id, generation, chain_index) triple.
+     * Throws BtrError on violation.
+     */
+    check(transferId, generation, chainIndex) {
+        if (this.expected === null) {
+            throw ratchetStateError('no active transfer in replay guard');
+        }
+        // Check transfer_id matches
+        if (!uint8ArrayEqual(transferId, this.expected.transferId)) {
+            throw ratchetStateError('transfer_id mismatch');
+        }
+        // Check generation matches
+        if (generation !== this.expected.generation) {
+            throw ratchetStateError(`generation mismatch: expected ${this.expected.generation}, got ${generation}`);
+        }
+        // ORDER-BTR: chain_index must equal expected next (no gaps)
+        if (chainIndex !== this.expected.nextIndex) {
+            throw ratchetChainError(`chain_index out of order: expected ${this.expected.nextIndex}, got ${chainIndex}`);
+        }
+        // REPLAY-BTR: check for duplicate triple
+        const key = tripleKey(transferId, generation, chainIndex);
+        if (this.seen.has(key)) {
+            throw ratchetChainError(`replay detected: generation=${generation}, chain_index=${chainIndex}`);
+        }
+        this.seen.add(key);
+        this.expected.nextIndex = chainIndex + 1;
+    }
+    /** End tracking for the current transfer. Retains seen set for cross-transfer replay detection. */
+    endTransfer() {
+        this.expected = null;
+    }
+    /** Full reset — clears all state. Used on disconnect. */
+    reset() {
+        this.seen.clear();
+        this.expected = null;
+    }
+}
+function uint8ArrayEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}