@floegence/flowersec-core 0.1.1

package/dist/e2ee/handshake.js

@@ -0,0 +1,322 @@
+import { x25519 } from "@noble/curves/ed25519";
+import { p256 } from "@noble/curves/p256";
+import { sha256 } from "@noble/hashes/sha256";
+import { base64urlDecode, base64urlEncode } from "../utils/base64url.js";
+import { HANDSHAKE_TYPE_ACK, HANDSHAKE_TYPE_INIT, HANDSHAKE_TYPE_RESP, PROTOCOL_VERSION, RECORD_FLAG_PING } from "./constants.js";
+import { encodeHandshakeFrame, decodeHandshakeFrame } from "./framing.js";
+import { computeAuthTag, deriveSessionKeys } from "./kdf.js";
+import { transcriptHash } from "./transcript.js";
+import { decryptRecord, encryptRecord } from "./record.js";
+import { SecureChannel } from "./secureChannel.js";
+import { E2EEHandshakeError } from "./errors.js";
+import { TimeoutError, throwIfAborted } from "../utils/errors.js";
+const te = new TextEncoder();
+const td = new TextDecoder();
+function handshakeDeadlineMs(timeoutMs) {
+    const ms = Math.max(0, timeoutMs ?? 10_000);
+    if (ms <= 0)
+        return null;
+    return Date.now() + ms;
+}
+function ioReadOpts(signal, deadlineMs) {
+    throwIfAborted(signal, "handshake aborted");
+    if (deadlineMs == null)
+        return signal != null ? { signal } : {};
+    const remaining = deadlineMs - Date.now();
+    if (remaining <= 0)
+        throw new TimeoutError("handshake timeout");
+    return signal != null ? { signal, timeoutMs: remaining } : { timeoutMs: remaining };
+}
+function ioWriteOpts(signal) {
+    throwIfAborted(signal, "handshake aborted");
+    return signal != null ? { signal } : {};
+}
+function randomBytes(n) {
+    const out = new Uint8Array(n);
+    crypto.getRandomValues(out);
+    return out;
+}
+// suiteKeypair generates a per-handshake ECDH keypair.
+function suiteKeypair(suite) {
+    if (suite === 1) {
+        const priv = x25519.utils.randomPrivateKey();
+        const pub = x25519.getPublicKey(priv);
+        return { priv, pub };
+    }
+    if (suite === 2) {
+        const priv = p256.utils.randomPrivateKey();
+        const pub = p256.getPublicKey(priv, false);
+        return { priv, pub };
+    }
+    throw new Error(`unsupported suite ${suite}`);
+}
+// suiteSharedSecret computes the ECDH shared secret for the suite.
+function suiteSharedSecret(suite, priv, peerPub) {
+    if (suite === 1)
+        return x25519.getSharedSecret(priv, peerPub);
+    if (suite === 2) {
+        // P-256 uses the x-coordinate (32 bytes) to align with Go's crypto/ecdh output.
+        const shared = p256.getSharedSecret(priv, peerPub, false);
+        if (shared.length !== 65 || shared[0] !== 4)
+            throw new Error("invalid P-256 shared secret encoding");
+        return shared.slice(1, 33);
+    }
+    throw new Error(`unsupported suite ${suite}`);
+}
+function fingerprintInit(init) {
+    // Canonicalize to avoid JSON key-order affecting the cache key.
+    const canonical = {
+        channel_id: init.channel_id,
+        role: init.role,
+        version: init.version,
+        suite: init.suite,
+        client_eph_pub_b64u: init.client_eph_pub_b64u,
+        nonce_c_b64u: init.nonce_c_b64u,
+        client_features: init.client_features
+    };
+    const b = te.encode(JSON.stringify(canonical));
+    const sum = sha256(b);
+    // Full 32-byte fingerprint (aligns with Go's sha256-based fingerprinting).
+    return base64urlEncode(sum);
+}
+// clientHandshake performs the client side of the E2EE handshake.
+export async function clientHandshake(transport, opts) {
+    if (opts.psk.length !== 32)
+        throw new Error("psk must be 32 bytes");
+    if (opts.channelId === "")
+        throw new Error("missing channel_id");
+    const deadlineMs = handshakeDeadlineMs(opts.timeoutMs);
+    const kp = suiteKeypair(opts.suite);
+    const nonceC = randomBytes(32);
+    const init = {
+        channel_id: opts.channelId,
+        role: 1,
+        version: PROTOCOL_VERSION,
+        suite: opts.suite,
+        client_eph_pub_b64u: base64urlEncode(kp.pub),
+        nonce_c_b64u: base64urlEncode(nonceC),
+        client_features: opts.clientFeatures >>> 0
+    };
+    const initJson = te.encode(JSON.stringify(init));
+    await transport.writeBinary(encodeHandshakeFrame(HANDSHAKE_TYPE_INIT, initJson), ioWriteOpts(opts.signal));
+    // Read server response with ephemeral key and nonce.
+    const respFrame = await transport.readBinary(ioReadOpts(opts.signal, deadlineMs));
+    const decoded = decodeHandshakeFrame(respFrame, opts.maxHandshakePayload);
+    if (decoded.handshakeType !== HANDSHAKE_TYPE_RESP)
+        throw new Error("unexpected handshake type");
+    const resp = JSON.parse(td.decode(decoded.payloadJsonUtf8));
+    if (resp.handshake_id == null || resp.handshake_id === "")
+        throw new Error("missing handshake_id");
+    if (resp.server_eph_pub_b64u == null || resp.server_eph_pub_b64u === "")
+        throw new Error("missing server_eph_pub_b64u");
+    if (resp.nonce_s_b64u == null || resp.nonce_s_b64u === "")
+        throw new Error("missing nonce_s_b64u");
+    const serverPub = base64urlDecode(resp.server_eph_pub_b64u);
+    const nonceS = base64urlDecode(resp.nonce_s_b64u);
+    if (nonceS.length !== 32)
+        throw new Error("bad nonce_s length");
+    if (opts.suite === 1 && serverPub.length !== 32)
+        throw new Error("bad server eph pub length");
+    if (opts.suite === 2 && serverPub.length !== 65)
+        throw new Error("bad server eph pub length");
+    const th = transcriptHash({
+        version: PROTOCOL_VERSION,
+        suite: opts.suite,
+        role: 1,
+        clientFeatures: init.client_features,
+        serverFeatures: resp.server_features >>> 0,
+        channelId: opts.channelId,
+        nonceC,
+        nonceS,
+        clientEphPub: kp.pub,
+        serverEphPub: serverPub
+    });
+    const shared = suiteSharedSecret(opts.suite, kp.priv, serverPub);
+    const keys = deriveSessionKeys(opts.psk, shared, th);
+    const ts = BigInt(Math.floor(Date.now() / 1000));
+    const tag = computeAuthTag(opts.psk, th, ts);
+    const ack = {
+        handshake_id: resp.handshake_id,
+        timestamp_unix_s: Number(ts),
+        auth_tag_b64u: base64urlEncode(tag)
+    };
+    await transport.writeBinary(encodeHandshakeFrame(HANDSHAKE_TYPE_ACK, te.encode(JSON.stringify(ack))), ioWriteOpts(opts.signal));
+    // Server-finished confirmation: require an encrypted ping record (seq=1) before returning.
+    const finishedFrame = await transport.readBinary(ioReadOpts(opts.signal, deadlineMs));
+    const finished = decryptRecord(keys.s2cKey, keys.s2cNoncePrefix, finishedFrame, 1n, opts.maxRecordBytes);
+    if (finished.flags !== RECORD_FLAG_PING || finished.plaintext.length !== 0) {
+        throw new Error("expected server-finished ping");
+    }
+    // Client sends application data with the C2S keys.
+    return new SecureChannel({
+        transport,
+        maxRecordBytes: opts.maxRecordBytes,
+        ...(opts.maxBufferedBytes !== undefined ? { maxBufferedBytes: opts.maxBufferedBytes } : {}),
+        sendKey: keys.c2sKey,
+        recvKey: keys.s2cKey,
+        sendNoncePrefix: keys.c2sNoncePrefix,
+        recvNoncePrefix: keys.s2cNoncePrefix,
+        rekeyBase: keys.rekeyBase,
+        transcriptHash: th,
+        sendDir: 1,
+        recvDir: 2,
+        recvSeq: 2n
+    });
+}
+// ServerHandshakeCache stores server-side handshake state for retries.
+export class ServerHandshakeCache {
+    // Cache keyed by init fingerprint.
+    m = new Map();
+    // Time-to-live for cache entries in milliseconds.
+    ttlMs;
+    // Maximum number of cached entries.
+    maxEntries;
+    constructor(opts = {}) {
+        this.ttlMs = Math.max(0, opts.ttlMs ?? 60_000);
+        this.maxEntries = Math.max(0, opts.maxEntries ?? 4096);
+    }
+    cleanup(nowMs) {
+        if (this.ttlMs <= 0)
+            return;
+        for (const [k, v] of this.m) {
+            if (nowMs - v.createdAtMs > this.ttlMs)
+                this.m.delete(k);
+        }
+    }
+    // getOrCreate returns a cached entry or creates a new handshake response.
+    getOrCreate(init, suite, serverFeatures) {
+        const nowMs = Date.now();
+        const initKey = fingerprintInit(init);
+        this.cleanup(nowMs);
+        const existing = this.m.get(initKey);
+        if (existing != null)
+            return existing;
+        if (this.maxEntries > 0 && this.m.size >= this.maxEntries) {
+            throw new Error("too many pending handshakes");
+        }
+        const kp = suiteKeypair(suite);
+        const nonceS = randomBytes(32);
+        const entry = {
+            initKey,
+            suite,
+            serverPriv: kp.priv,
+            serverPub: kp.pub,
+            nonceS,
+            handshakeId: base64urlEncode(randomBytes(24)),
+            serverFeatures: serverFeatures >>> 0,
+            createdAtMs: nowMs
+        };
+        this.m.set(initKey, entry);
+        return entry;
+    }
+    // delete removes a cached handshake entry.
+    delete(init) {
+        const initKey = fingerprintInit(init);
+        this.m.delete(initKey);
+    }
+}
+// serverHandshake performs the server side of the E2EE handshake.
+export async function serverHandshake(transport, cache, opts) {
+    if (opts.initExpireAtUnixS <= 0)
+        throw new Error("missing init_exp");
+    const deadlineMs = handshakeDeadlineMs(opts.timeoutMs);
+    const initFrame = await transport.readBinary(ioReadOpts(opts.signal, deadlineMs));
+    const decodedInit = decodeHandshakeFrame(initFrame, opts.maxHandshakePayload);
+    if (decodedInit.handshakeType !== HANDSHAKE_TYPE_INIT)
+        throw new Error("unexpected handshake type");
+    const init = JSON.parse(td.decode(decodedInit.payloadJsonUtf8));
+    if (init.version !== PROTOCOL_VERSION)
+        throw new E2EEHandshakeError("invalid_version", "bad version");
+    if (init.role !== 1)
+        throw new Error("bad role");
+    if (init.channel_id !== opts.channelId)
+        throw new Error("bad channel_id");
+    const suite = init.suite;
+    if (suite !== opts.suite)
+        throw new Error("bad suite");
+    const clientPub = base64urlDecode(init.client_eph_pub_b64u);
+    const nonceC = base64urlDecode(init.nonce_c_b64u);
+    if (nonceC.length !== 32)
+        throw new Error("bad nonce_c length");
+    if (suite === 1 && clientPub.length !== 32)
+        throw new Error("bad client eph pub length");
+    if (suite === 2 && clientPub.length !== 65)
+        throw new Error("bad client eph pub length");
+    const entry = cache.getOrCreate(init, suite, opts.serverFeatures);
+    const resp = {
+        handshake_id: entry.handshakeId,
+        server_eph_pub_b64u: base64urlEncode(entry.serverPub),
+        nonce_s_b64u: base64urlEncode(entry.nonceS),
+        server_features: entry.serverFeatures
+    };
+    await transport.writeBinary(encodeHandshakeFrame(HANDSHAKE_TYPE_RESP, te.encode(JSON.stringify(resp))), ioWriteOpts(opts.signal));
+    let ack;
+    while (true) {
+        const frame = await transport.readBinary(ioReadOpts(opts.signal, deadlineMs));
+        const decoded = decodeHandshakeFrame(frame, opts.maxHandshakePayload);
+        if (decoded.handshakeType === HANDSHAKE_TYPE_INIT) {
+            // Client retry: re-send the cached response if parameters match.
+            const retry = JSON.parse(td.decode(decoded.payloadJsonUtf8));
+            if (fingerprintInit(retry) !== entry.initKey)
+                throw new Error("unexpected init retry parameters");
+            await transport.writeBinary(encodeHandshakeFrame(HANDSHAKE_TYPE_RESP, te.encode(JSON.stringify(resp))), ioWriteOpts(opts.signal));
+            continue;
+        }
+        if (decoded.handshakeType !== HANDSHAKE_TYPE_ACK)
+            throw new Error("unexpected handshake type");
+        ack = JSON.parse(td.decode(decoded.payloadJsonUtf8));
+        break;
+    }
+    if (ack.handshake_id !== entry.handshakeId)
+        throw new Error("handshake_id mismatch");
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - ack.timestamp_unix_s) > opts.clockSkewSeconds)
+        throw new E2EEHandshakeError("timestamp_out_of_skew", "timestamp skew");
+    if (ack.timestamp_unix_s > opts.initExpireAtUnixS + opts.clockSkewSeconds)
+        throw new E2EEHandshakeError("timestamp_after_init_exp", "timestamp after init_exp");
+    const th = transcriptHash({
+        version: PROTOCOL_VERSION,
+        suite: suite,
+        role: 1,
+        clientFeatures: init.client_features >>> 0,
+        serverFeatures: entry.serverFeatures,
+        channelId: init.channel_id,
+        nonceC,
+        nonceS: entry.nonceS,
+        clientEphPub: clientPub,
+        serverEphPub: entry.serverPub
+    });
+    const expected = computeAuthTag(opts.psk, th, BigInt(ack.timestamp_unix_s));
+    const got = base64urlDecode(ack.auth_tag_b64u);
+    if (got.length !== expected.length || !equalBytes(got, expected))
+        throw new E2EEHandshakeError("auth_tag_mismatch", "auth tag mismatch");
+    const shared = suiteSharedSecret(suite, entry.serverPriv, clientPub);
+    const keys = deriveSessionKeys(opts.psk, shared, th);
+    cache.delete(init);
+    // Server-finished confirmation: send an encrypted ping record (seq=1) immediately after the handshake.
+    const pingFrame = encryptRecord(keys.s2cKey, keys.s2cNoncePrefix, RECORD_FLAG_PING, 1n, new Uint8Array(), opts.maxRecordBytes);
+    await transport.writeBinary(pingFrame, ioWriteOpts(opts.signal));
+    // Server sends application data with the S2C keys.
+    return new SecureChannel({
+        transport,
+        maxRecordBytes: opts.maxRecordBytes,
+        ...(opts.maxBufferedBytes !== undefined ? { maxBufferedBytes: opts.maxBufferedBytes } : {}),
+        sendKey: keys.s2cKey,
+        recvKey: keys.c2sKey,
+        sendNoncePrefix: keys.s2cNoncePrefix,
+        recvNoncePrefix: keys.c2sNoncePrefix,
+        rekeyBase: keys.rekeyBase,
+        transcriptHash: th,
+        sendDir: 2,
+        recvDir: 1,
+        sendSeq: 2n
+    });
+}
+function equalBytes(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let ok = 0;
+    for (let i = 0; i < a.length; i++)
+        ok |= a[i] ^ b[i];
+    return ok === 0;
+}

package/dist/e2ee/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./framing.js";
+export * from "./kdf.js";
+export * from "./record.js";
+export * from "./secureChannel.js";
+export * from "./handshake.js";
+export * from "./transcript.js";

package/dist/e2ee/index.js

@@ -0,0 +1,7 @@
+export * from "./constants.js";
+export * from "./framing.js";
+export * from "./kdf.js";
+export * from "./record.js";
+export * from "./secureChannel.js";
+export * from "./handshake.js";
+export * from "./transcript.js";

package/dist/e2ee/kdf.d.ts

@@ -0,0 +1,15 @@
+export type SessionKeys = Readonly<{
+    /** Client-to-server AEAD key (32 bytes). */
+    c2sKey: Uint8Array;
+    /** Server-to-client AEAD key (32 bytes). */
+    s2cKey: Uint8Array;
+    /** Client-to-server nonce prefix (4 bytes). */
+    c2sNoncePrefix: Uint8Array;
+    /** Server-to-client nonce prefix (4 bytes). */
+    s2cNoncePrefix: Uint8Array;
+    /** Base secret for deriving per-sequence rekeyed keys. */
+    rekeyBase: Uint8Array;
+}>;
+export declare function deriveSessionKeys(psk: Uint8Array, sharedSecret: Uint8Array, transcriptHash: Uint8Array): SessionKeys;
+export declare function computeAuthTag(psk: Uint8Array, transcriptHash: Uint8Array, timestampUnixS: bigint): Uint8Array;
+export declare function deriveRekeyKey(rekeyBase: Uint8Array, transcriptHash: Uint8Array, seq: bigint, dir: number): Uint8Array;

package/dist/e2ee/kdf.js

@@ -0,0 +1,39 @@
+import { hkdf } from "@noble/hashes/hkdf";
+import { hmac } from "@noble/hashes/hmac";
+import { sha256 } from "@noble/hashes/sha256";
+import { concatBytes, u64be } from "../utils/bin.js";
+const te = new TextEncoder();
+// deriveSessionKeys expands the shared secret and transcript into session keys.
+export function deriveSessionKeys(psk, sharedSecret, transcriptHash) {
+    if (psk.length !== 32)
+        throw new Error("psk must be 32 bytes");
+    if (transcriptHash.length !== 32)
+        throw new Error("transcript hash must be 32 bytes");
+    const ikm = concatBytes([sharedSecret, transcriptHash]);
+    const c2sKey = hkdf(sha256, ikm, psk, te.encode("flowersec-e2ee-v1:c2s:key"), 32);
+    const s2cKey = hkdf(sha256, ikm, psk, te.encode("flowersec-e2ee-v1:s2c:key"), 32);
+    const rekeyBase = hkdf(sha256, ikm, psk, te.encode("flowersec-e2ee-v1:rekey_base"), 32);
+    const c2sNoncePrefix = hkdf(sha256, ikm, psk, te.encode("flowersec-e2ee-v1:c2s:nonce_prefix"), 4);
+    const s2cNoncePrefix = hkdf(sha256, ikm, psk, te.encode("flowersec-e2ee-v1:s2c:nonce_prefix"), 4);
+    return { c2sKey, s2cKey, c2sNoncePrefix, s2cNoncePrefix, rekeyBase };
+}
+// computeAuthTag authenticates the transcript hash and timestamp.
+export function computeAuthTag(psk, transcriptHash, timestampUnixS) {
+    if (psk.length !== 32)
+        throw new Error("psk must be 32 bytes");
+    if (transcriptHash.length !== 32)
+        throw new Error("transcript hash must be 32 bytes");
+    const msg = concatBytes([transcriptHash, u64be(timestampUnixS)]);
+    return hmac(sha256, psk, msg);
+}
+// deriveRekeyKey derives a new record key bound to sequence and direction.
+export function deriveRekeyKey(rekeyBase, transcriptHash, seq, dir) {
+    if (rekeyBase.length !== 32)
+        throw new Error("rekeyBase must be 32 bytes");
+    if (transcriptHash.length !== 32)
+        throw new Error("transcript hash must be 32 bytes");
+    const msg = concatBytes([transcriptHash, u64be(seq), new Uint8Array([dir & 0xff])]);
+    const salt = hmac(sha256, rekeyBase, msg);
+    const prkIkm = te.encode("flowersec-e2ee-v1:rekey");
+    return hkdf(sha256, prkIkm, salt, te.encode("flowersec-e2ee-v1:rekey:key"), 32);
+}

package/dist/e2ee/record.d.ts

@@ -0,0 +1,11 @@
+import { RECORD_FLAG_APP, RECORD_FLAG_PING, RECORD_FLAG_REKEY } from "./constants.js";
+export type RecordFlag = typeof RECORD_FLAG_APP | typeof RECORD_FLAG_PING | typeof RECORD_FLAG_REKEY;
+export declare class RecordError extends Error {
+}
+export declare function maxPlaintextBytes(maxRecordBytes: number): number;
+export declare function encryptRecord(key: Uint8Array, noncePrefix: Uint8Array, flags: RecordFlag, seq: bigint, plaintext: Uint8Array, maxRecordBytes: number): Uint8Array;
+export declare function decryptRecord(key: Uint8Array, noncePrefix: Uint8Array, frame: Uint8Array, expectSeq: bigint | null, maxRecordBytes: number): {
+    flags: number;
+    seq: bigint;
+    plaintext: Uint8Array;
+};

package/dist/e2ee/record.js

@@ -0,0 +1,69 @@
+import { gcm } from "@noble/ciphers/aes";
+import { concatBytes, readU32be, readU64be, u32be, u64be } from "../utils/bin.js";
+import { PROTOCOL_VERSION, RECORD_MAGIC, RECORD_FLAG_APP, RECORD_FLAG_PING, RECORD_FLAG_REKEY } from "./constants.js";
+const te = new TextEncoder();
+// RecordError marks record parsing or cryptographic failures.
+export class RecordError extends Error {
+}
+// maxPlaintextBytes returns the payload cap derived from a record size limit.
+export function maxPlaintextBytes(maxRecordBytes) {
+    if (maxRecordBytes <= 0)
+        return 0;
+    return maxRecordBytes - (4 + 1 + 1 + 8 + 4) - 16;
+}
+// encryptRecord builds an AEAD-protected record frame.
+export function encryptRecord(key, noncePrefix, flags, seq, plaintext, maxRecordBytes) {
+    if (key.length !== 32)
+        throw new RecordError("key must be 32 bytes");
+    if (noncePrefix.length !== 4)
+        throw new RecordError("noncePrefix must be 4 bytes");
+    const cipherLen = plaintext.length + 16;
+    if (cipherLen > 0xffffffff)
+        throw new RecordError("record too large");
+    const header = new Uint8Array(4 + 1 + 1 + 8 + 4);
+    header.set(te.encode(RECORD_MAGIC), 0);
+    header[4] = PROTOCOL_VERSION;
+    header[5] = flags & 0xff;
+    header.set(u64be(seq), 6);
+    header.set(u32be(cipherLen), 14);
+    const nonce = concatBytes([noncePrefix, u64be(seq)]);
+    const cipher = gcm(key, nonce, header).encrypt(plaintext);
+    const out = concatBytes([header, cipher]);
+    if (maxRecordBytes > 0 && out.length > maxRecordBytes)
+        throw new RecordError("record too large");
+    return out;
+}
+// decryptRecord validates and decrypts a record frame.
+export function decryptRecord(key, noncePrefix, frame, expectSeq, maxRecordBytes) {
+    if (key.length !== 32)
+        throw new RecordError("key must be 32 bytes");
+    if (noncePrefix.length !== 4)
+        throw new RecordError("noncePrefix must be 4 bytes");
+    const headerLen = 4 + 1 + 1 + 8 + 4;
+    if (maxRecordBytes > 0 && frame.length > maxRecordBytes)
+        throw new RecordError("record too large");
+    if (frame.length < headerLen)
+        throw new RecordError("record too short");
+    if (new TextDecoder().decode(frame.slice(0, 4)) !== RECORD_MAGIC)
+        throw new RecordError("bad record magic");
+    if (frame[4] !== PROTOCOL_VERSION)
+        throw new RecordError("bad record version");
+    const flags = frame[5];
+    if (flags !== RECORD_FLAG_APP && flags !== RECORD_FLAG_PING && flags !== RECORD_FLAG_REKEY) {
+        throw new RecordError("bad record flag");
+    }
+    const seq = readU64be(frame, 6);
+    if (expectSeq != null && seq !== expectSeq)
+        throw new RecordError(`bad seq: got=${seq} want=${expectSeq}`);
+    const n = readU32be(frame, 14);
+    if (headerLen + n !== frame.length)
+        throw new RecordError("length mismatch");
+    const nonce = concatBytes([noncePrefix, u64be(seq)]);
+    try {
+        const plaintext = gcm(key, nonce, frame.slice(0, headerLen)).decrypt(frame.slice(headerLen));
+        return { flags, seq, plaintext };
+    }
+    catch (e) {
+        throw new RecordError(`decrypt failed: ${String(e)} len=${frame.length}`);
+    }
+}

package/dist/e2ee/secureChannel.d.ts

@@ -0,0 +1,82 @@
+export type ReadBinaryOptions = Readonly<{
+    /** Optional AbortSignal to cancel the pending operation. */
+    signal?: AbortSignal;
+    /** Optional timeout (milliseconds) for the pending operation. */
+    timeoutMs?: number;
+}>;
+export type WriteBinaryOptions = Readonly<{
+    /** Optional AbortSignal to cancel the pending operation. */
+    signal?: AbortSignal;
+}>;
+export type BinaryTransport = {
+    /** Reads the next binary frame from the underlying transport. */
+    readBinary(opts?: ReadBinaryOptions): Promise<Uint8Array>;
+    /** Writes a binary frame to the underlying transport. */
+    writeBinary(frame: Uint8Array, opts?: WriteBinaryOptions): Promise<void>;
+    /** Closes the transport and unblocks pending readers/writers. */
+    close(): void;
+};
+export type SecureChannelOptions = Readonly<{
+    /** Maximum encoded record size (header + ciphertext). */
+    maxRecordBytes: number;
+    /** Maximum queued plaintext bytes before backpressure/errors. */
+    maxBufferedBytes?: number;
+}>;
+type Direction = 1 | 2;
+export declare class SecureChannel {
+    private readonly transport;
+    private readonly maxRecordBytes;
+    private readonly maxBufferedBytes;
+    private sendKey;
+    private recvKey;
+    private sendNoncePrefix;
+    private recvNoncePrefix;
+    private readonly rekeyBase;
+    private readonly transcriptHash;
+    private readonly sendDir;
+    private readonly recvDir;
+    private sendSeq;
+    private recvSeq;
+    private sendQueue;
+    private sendQueueHead;
+    private sendWaiters;
+    private sendWaitersHead;
+    private sendClosed;
+    private sendErr;
+    private readonly recvQueue;
+    private recvQueueHead;
+    private recvQueueBytes;
+    private recvWaiters;
+    private readErr;
+    private closed;
+    constructor(args: {
+        transport: BinaryTransport;
+        maxRecordBytes: number;
+        maxBufferedBytes?: number;
+        sendKey: Uint8Array;
+        recvKey: Uint8Array;
+        sendNoncePrefix: Uint8Array;
+        recvNoncePrefix: Uint8Array;
+        rekeyBase: Uint8Array;
+        transcriptHash: Uint8Array;
+        sendDir: Direction;
+        recvDir: Direction;
+        sendSeq?: bigint;
+        recvSeq?: bigint;
+    });
+    write(plaintext: Uint8Array): Promise<void>;
+    read(): Promise<Uint8Array>;
+    close(): void;
+    sendPing(): Promise<void>;
+    rekeyNow(): Promise<void>;
+    private enqueueSend;
+    private nextSend;
+    private dequeueSend;
+    private shiftSendWaiter;
+    private wakeSendWaiters;
+    private rejectQueuedSenders;
+    private failSend;
+    private sendLoop;
+    private readLoop;
+}
+export {};