@peers-app/peers-sdk 0.25.6 → 0.25.7

package/dist/device/device.d.ts

@@ -1,10 +1,28 @@
-import { type IDeviceHandshake, type IDeviceInfo } from "../data";
+import { type IDeviceHandshake, type IDeviceInfo, type IHandshakeFrameCrypto } from "../data";
 import { type IDataBox, type ISignedObject } from "../keys";
+import { type DerivedFrameKeys } from "./frame-cipher";
 /** Optional presentation metadata advertised with signed device identity. */
 export interface IDeviceDisplayInfo {
     userName?: string;
     deviceName?: string;
 }
+/** Inputs for {@link Device.deriveFrameKeys}. */
+export interface DeviceFrameKeyParams {
+    /** Remote device's static X25519 public key (base64url), from its signed handshake. */
+    remotePublicBoxKey: string;
+    /** This connection's local ephemeral X25519 secret key (raw 32 bytes). Zeroized on return. */
+    ephemeralSecretKey: Uint8Array;
+    /** Remote ephemeral X25519 public key (base64url), from `frameCrypto.ephemeralBoxKey`. */
+    remoteEphemeralBoxKey: string;
+    /** Connection ID shared by both sockets. */
+    connectionId: string;
+    /** `deviceId` of the handshake initiator. */
+    clientDeviceId: string;
+    /** `deviceId` of the handshake responder. */
+    serverDeviceId: string;
+    /** `timestamp` from the client's signed handshake. */
+    timestamp: number;
+}
 /** Runtime cryptographic identity for a Peers device. */
 export declare class Device implements IDeviceInfo {
     readonly userId: string;
@@ -13,33 +31,55 @@ export declare class Device implements IDeviceInfo {
     private _userName?;
     private _deviceName?;
     constructor(userId?: string, deviceId?: string, keys?: import("../keys").IPublicPrivateKeys, displayInfo?: IDeviceDisplayInfo);
+    /** Bounded user display name advertised in signed identity messages. */
     get userName(): string | undefined;
+    /** Bounded device display name advertised in signed identity messages. */
     get deviceName(): string | undefined;
+    /** Ed25519 signing public key, base64url. */
     get publicKey(): string;
+    /** X25519 box public key derived from the signing key, base64url. */
     get publicBoxKey(): string;
+    /** Signs a UTF-8 message with this device's key (NaCl combined format, base64url). */
     signMessageWithSecretKey(msg: string): string;
+    /** Detached-signs `obj` over its canonical JSON with this device's key. */
     signObjectWithSecretKey<T>(obj: T): ISignedObject<T>;
+    /** Boxes `data` to `toPublicKey` (X25519, base64url) from this device's box key. */
     boxDataWithKeys(data: any, toPublicKey: string): IDataBox;
+    /** Boxes `data` to a device's advertised `publicBoxKey`. */
     boxDataForDevice(data: any, device: IDeviceInfo): IDataBox;
+    /** Opens a box addressed to this device. @throws on authentication failure */
     openBoxWithSecretKey(data: IDataBox): any;
+    /** Signs then boxes `data` for a device: the legacy per-message RPC envelope. */
     signAndBoxDataForDevice<T>(data: T, device: IDeviceInfo): IDataBox;
+    /** Signs then boxes `data` to a raw X25519 public key (base64url). */
     signAndBoxDataForKey<T>(data: T, toPublicBoxKey: string): IDataBox;
+    /**
+     * Derives this peer's frame-cipher keys for one connection without exposing
+     * the static secret key. Computes the ephemeral-ephemeral and static-static
+     * X25519 shared secrets, feeds them to `frame-cipher.deriveFrameKeys`, and
+     * zeroizes both secrets and the supplied ephemeral secret key.
+     */
+    deriveFrameKeys(params: DeviceFrameKeyParams): DerivedFrameKeys;
+    /**
+     * Unwraps a possibly boxed and/or signed RPC value down to its contents.
+     * Plain values pass through unchanged.
+     */
     unwrapResponse<T>(response: T | ISignedObject<T> | IDataBox): T;
+    /** Opens a box addressed to this device and verifies the signed object inside. */
     openBoxedAndSignedData<T>(data: IDataBox): T;
     /** Updates bounded presentation metadata included in future signed identity messages. */
     setDisplayInfo({ userName, deviceName }: IDeviceDisplayInfo): void;
-    getHandshake(connectionId: string, serverAddress: string): ISignedObject<IDeviceHandshake>;
-    handshakeResponse(remoteHandshake: ISignedObject<IDeviceHandshake>, connectionId: string, thisServerAddress: string): {
-        timestamp: number;
-        publicKey: string;
-        publicBoxKey: string;
-        userId: string;
-        deviceId: string;
-        connectionId: string;
-        serverAddress: string;
-        userName?: string | undefined;
-        deviceName?: string | undefined;
-    };
+    /**
+     * Builds and signs the client half of a connection handshake.
+     * @param frameCrypto Include to advertise frame-cipher support with this connection's ephemeral key.
+     */
+    getHandshake(connectionId: string, serverAddress: string, frameCrypto?: IHandshakeFrameCrypto): ISignedObject<IDeviceHandshake>;
+    /**
+     * Validates a client handshake (signature, claimed key, connection ID) and
+     * builds the unsigned server response. `Connection` signs and boxes it.
+     * @param frameCrypto Include to accept the client's frame-cipher offer with this side's ephemeral key.
+     */
+    handshakeResponse(remoteHandshake: ISignedObject<IDeviceHandshake>, connectionId: string, thisServerAddress: string, frameCrypto?: IHandshakeFrameCrypto): IDeviceHandshake;
     private deviceInfoSigned;
     /** Returns cached signed identity information, refreshing after display metadata changes. */
     getDeviceInfo(): ISignedObject<IDeviceInfo>;

package/dist/device/device.js

@@ -4,6 +4,7 @@ exports.Device = void 0;
 const data_1 = require("../data");
 const keys_1 = require("../keys");
 const utils_1 = require("../utils");
+const frame_cipher_1 = require("./frame-cipher");
 /** Runtime cryptographic identity for a Peers device. */
 class Device {
     userId;
@@ -17,41 +18,81 @@ class Device {
         this.keys = keys;
         this.setDisplayInfo(displayInfo);
     }
+    /** Bounded user display name advertised in signed identity messages. */
     get userName() {
         return this._userName;
     }
+    /** Bounded device display name advertised in signed identity messages. */
     get deviceName() {
         return this._deviceName;
     }
+    /** Ed25519 signing public key, base64url. */
     get publicKey() {
         return this.keys.publicKey;
     }
+    /** X25519 box public key derived from the signing key, base64url. */
     get publicBoxKey() {
         return this.keys.publicBoxKey;
     }
+    /** Signs a UTF-8 message with this device's key (NaCl combined format, base64url). */
     signMessageWithSecretKey(msg) {
         return (0, keys_1.signMessageWithSecretKey)(msg, this.keys.secretKey);
     }
+    /** Detached-signs `obj` over its canonical JSON with this device's key. */
     signObjectWithSecretKey(obj) {
         return (0, keys_1.signObjectWithSecretKey)(obj, this.keys.secretKey);
     }
+    /** Boxes `data` to `toPublicKey` (X25519, base64url) from this device's box key. */
     boxDataWithKeys(data, toPublicKey) {
         return (0, keys_1.boxDataWithKeys)(data, toPublicKey, this.keys.secretKey);
     }
+    /** Boxes `data` to a device's advertised `publicBoxKey`. */
     boxDataForDevice(data, device) {
         return this.boxDataWithKeys(data, device.publicBoxKey);
     }
+    /** Opens a box addressed to this device. @throws on authentication failure */
     openBoxWithSecretKey(data) {
         return (0, keys_1.openBoxWithSecretKey)(data, this.keys.secretKey);
     }
+    /** Signs then boxes `data` for a device: the legacy per-message RPC envelope. */
     signAndBoxDataForDevice(data, device) {
         const signedData = this.signObjectWithSecretKey(data);
         return this.boxDataForDevice(signedData, device);
     }
+    /** Signs then boxes `data` to a raw X25519 public key (base64url). */
     signAndBoxDataForKey(data, toPublicBoxKey) {
         const signedData = this.signObjectWithSecretKey(data);
         return this.boxDataWithKeys(signedData, toPublicBoxKey);
     }
+    /**
+     * Derives this peer's frame-cipher keys for one connection without exposing
+     * the static secret key. Computes the ephemeral-ephemeral and static-static
+     * X25519 shared secrets, feeds them to `frame-cipher.deriveFrameKeys`, and
+     * zeroizes both secrets and the supplied ephemeral secret key.
+     */
+    deriveFrameKeys(params) {
+        const ephemeralSharedSecret = (0, keys_1.computeEphemeralSharedSecret)(params.ephemeralSecretKey, params.remoteEphemeralBoxKey);
+        const staticSharedSecret = (0, keys_1.computeStaticSharedSecret)(this.keys.secretKey, params.remotePublicBoxKey);
+        try {
+            return (0, frame_cipher_1.deriveFrameKeys)({
+                ephemeralSharedSecret,
+                staticSharedSecret,
+                connectionId: params.connectionId,
+                clientDeviceId: params.clientDeviceId,
+                serverDeviceId: params.serverDeviceId,
+                timestamp: params.timestamp,
+            });
+        }
+        finally {
+            ephemeralSharedSecret.fill(0);
+            staticSharedSecret.fill(0);
+            params.ephemeralSecretKey.fill(0);
+        }
+    }
+    /**
+     * Unwraps a possibly boxed and/or signed RPC value down to its contents.
+     * Plain values pass through unchanged.
+     */
     unwrapResponse(response) {
         if (!response) {
             return response;
@@ -72,6 +113,7 @@ class Device {
         }
         return response;
     }
+    /** Opens a box addressed to this device and verifies the signed object inside. */
     openBoxedAndSignedData(data) {
         const signedData = this.openBoxWithSecretKey(data);
         return (0, keys_1.openSignedObject)(signedData);
@@ -89,7 +131,11 @@ class Device {
         this._deviceName = deviceName;
         this.deviceInfoSigned = undefined;
     }
-    getHandshake(connectionId, serverAddress) {
+    /**
+     * Builds and signs the client half of a connection handshake.
+     * @param frameCrypto Include to advertise frame-cipher support with this connection's ephemeral key.
+     */
+    getHandshake(connectionId, serverAddress, frameCrypto) {
         try {
             const localDeviceInfo = data_1.deviceHandshakeSchema.parse({
                 connectionId,
@@ -101,6 +147,7 @@ class Device {
                 deviceName: this.deviceName,
                 serverAddress,
                 timestamp: Date.now(),
+                frameCrypto,
             });
             const localDeviceInfoSigned = this.signObjectWithSecretKey(localDeviceInfo);
             return localDeviceInfoSigned;
@@ -109,7 +156,12 @@ class Device {
             throw new Error(`Failed to handshake: ${e.message}`, { cause: e });
         }
     }
-    handshakeResponse(remoteHandshake, connectionId, thisServerAddress) {
+    /**
+     * Validates a client handshake (signature, claimed key, connection ID) and
+     * builds the unsigned server response. `Connection` signs and boxes it.
+     * @param frameCrypto Include to accept the client's frame-cipher offer with this side's ephemeral key.
+     */
+    handshakeResponse(remoteHandshake, connectionId, thisServerAddress, frameCrypto) {
         try {
             const deviceInfo = data_1.deviceHandshakeSchema.parse((0, keys_1.openSignedObject)(remoteHandshake));
             if (remoteHandshake.publicKey !== deviceInfo.publicKey) {
@@ -128,6 +180,7 @@ class Device {
                 deviceName: this.deviceName,
                 serverAddress: thisServerAddress,
                 timestamp: Date.now(),
+                frameCrypto,
             });
             return handshakeResponse;
         }

package/dist/device/frame-cipher.d.ts

@@ -0,0 +1,133 @@
+/**
+ * frame-cipher.ts
+ *
+ * Per-connection AEAD layer for `binary-peer-connection-v2` frames.
+ *
+ * Every frame between two devices that both support `frameCrypto` v1 is sealed
+ * with ChaCha20-Poly1305 (RFC 8439) under a per-direction key derived from the
+ * handshake. This module is pure: it knows nothing about sockets, only bytes.
+ *
+ * Wire format of a sealed frame:
+ *
+ * ```
+ * [0x20 = FRAME_ENC][ciphertext of the entire inner frame][16-byte Poly1305 tag]
+ * ```
+ *
+ * The inner frame is a normal v2 frame including its own type byte, so the
+ * router opens the frame and then dispatches exactly as it would for a
+ * plaintext frame. Frame types are not visible on the wire.
+ *
+ * Nonces are implicit: a 12-byte big-endian counter per direction, starting at
+ * zero and never transmitted. Both transports are ordered and reliable, so a
+ * lost or reordered frame is a transport failure and surfaces as a tag
+ * mismatch. AAD is the UTF-8 `connectionId`, binding every frame to the
+ * connection it was sealed for.
+ *
+ * Design: `working/transport-security.md`.
+ */
+/** Frame type byte for a sealed frame. The only cleartext byte on the wire once armed. */
+export declare const FRAME_ENC = 32;
+/** Poly1305 authentication tag length in bytes. */
+export declare const FRAME_CIPHER_TAG_BYTES = 16;
+/** Bytes added to every frame by the cipher: 1 type byte plus the tag. */
+export declare const FRAME_CIPHER_OVERHEAD: number;
+/** ChaCha20-Poly1305 key length in bytes. */
+export declare const FRAME_CIPHER_KEY_BYTES = 32;
+/** Directional keys for one connection, from the point of view of one peer. */
+export interface FrameKeys {
+    /** Key this peer seals outbound frames with. */
+    sendKey: Uint8Array;
+    /** Key this peer opens inbound frames with. */
+    receiveKey: Uint8Array;
+}
+/** Both directional keys, named by direction rather than by role. */
+export interface DerivedFrameKeys {
+    /** Key for frames the handshake client sends to the handshake server. */
+    clientToServer: Uint8Array;
+    /** Key for frames the handshake server sends to the handshake client. */
+    serverToClient: Uint8Array;
+}
+/** Inputs to {@link deriveFrameKeys}. Both peers must supply identical values. */
+export interface FrameKeyDerivationParams {
+    /** `X25519(eph_local, eph_remote)`: provides forward secrecy. */
+    ephemeralSharedSecret: Uint8Array;
+    /** `X25519(static_local, static_remote)`: binds the keys to the signed identities. */
+    staticSharedSecret: Uint8Array;
+    /** Connection ID shared by both sockets; used as the HKDF salt and the frame AAD. */
+    connectionId: string;
+    /** `deviceId` of the peer that initiated the handshake. */
+    clientDeviceId: string;
+    /** `deviceId` of the peer that completed the handshake. */
+    serverDeviceId: string;
+    /** `timestamp` from the client's signed handshake. */
+    timestamp: number;
+}
+/**
+ * Derives the two directional frame keys for a connection.
+ *
+ * ```
+ * ikm  = ephemeralSharedSecret || staticSharedSecret
+ * salt = connectionId
+ * info = "peers-frame-v1" || len(clientDeviceId) || clientDeviceId
+ *      || len(serverDeviceId) || serverDeviceId || timestamp (8-byte BE)
+ * okm  = HKDF-SHA256(ikm, salt, info, 64)
+ * clientToServer = okm[0..32], serverToClient = okm[32..64]
+ * ```
+ *
+ * Symmetric: both peers compute the same pair, then pick their {@link FrameKeys}
+ * with {@link frameKeysForRole}. The caller owns the shared secrets and should
+ * zeroize them once this returns.
+ */
+export declare function deriveFrameKeys(params: FrameKeyDerivationParams): DerivedFrameKeys;
+/** Which side of the handshake a peer played. */
+export type FrameCipherRole = "client" | "server";
+/** Selects a peer's send/receive keys from the direction-named pair. */
+export declare function frameKeysForRole(derived: DerivedFrameKeys, role: FrameCipherRole): FrameKeys;
+/**
+ * One direction of the frame cipher: a key, the connection AAD, and a counter.
+ *
+ * Instantiate one {@link FrameSealer} for outbound frames and one
+ * {@link FrameOpener} for inbound frames; never share an instance between
+ * directions, because the nonce counter must track exactly one stream.
+ */
+declare abstract class FrameCipherDirection {
+    protected readonly key: Uint8Array;
+    protected readonly aad: Uint8Array;
+    private readonly nonce;
+    private used;
+    /**
+     * @param key 32-byte ChaCha20-Poly1305 key for this direction (owned by the instance)
+     * @param connectionId Connection ID used as AAD
+     */
+    constructor(key: Uint8Array, connectionId: string);
+    /** Number of frames processed so far in this direction. */
+    get count(): number;
+    /** Returns the nonce for the next frame and advances the counter. */
+    protected nextNonce(): Uint8Array;
+    /** Overwrites the key material. The instance is unusable afterwards. */
+    destroy(): void;
+}
+/** Seals outbound frames. One instance per connection direction. */
+export declare class FrameSealer extends FrameCipherDirection {
+    /**
+     * Seals a complete inner frame (type byte included) into a `FRAME_ENC` frame.
+     * Output length is `inner.length + FRAME_CIPHER_OVERHEAD`.
+     */
+    seal(inner: Uint8Array): Uint8Array;
+}
+/** Opens inbound frames. One instance per connection direction. */
+export declare class FrameOpener extends FrameCipherDirection {
+    /**
+     * Opens a `FRAME_ENC` frame and returns the inner frame, or `null` if the
+     * frame is malformed or fails authentication. The counter advances on every
+     * call, including failures, because a failed frame means the ordered stream
+     * is already broken and the caller must close the connection.
+     */
+    open(frame: Uint8Array): Uint8Array | null;
+}
+/** Convenience: builds both directions for one peer from its {@link FrameKeys}. */
+export declare function createFrameCiphers(keys: FrameKeys, connectionId: string): {
+    sealer: FrameSealer;
+    opener: FrameOpener;
+};
+export {};

package/dist/device/frame-cipher.js

@@ -0,0 +1,212 @@
+"use strict";
+/**
+ * frame-cipher.ts
+ *
+ * Per-connection AEAD layer for `binary-peer-connection-v2` frames.
+ *
+ * Every frame between two devices that both support `frameCrypto` v1 is sealed
+ * with ChaCha20-Poly1305 (RFC 8439) under a per-direction key derived from the
+ * handshake. This module is pure: it knows nothing about sockets, only bytes.
+ *
+ * Wire format of a sealed frame:
+ *
+ * ```
+ * [0x20 = FRAME_ENC][ciphertext of the entire inner frame][16-byte Poly1305 tag]
+ * ```
+ *
+ * The inner frame is a normal v2 frame including its own type byte, so the
+ * router opens the frame and then dispatches exactly as it would for a
+ * plaintext frame. Frame types are not visible on the wire.
+ *
+ * Nonces are implicit: a 12-byte big-endian counter per direction, starting at
+ * zero and never transmitted. Both transports are ordered and reliable, so a
+ * lost or reordered frame is a transport failure and surfaces as a tag
+ * mismatch. AAD is the UTF-8 `connectionId`, binding every frame to the
+ * connection it was sealed for.
+ *
+ * Design: `working/transport-security.md`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FrameOpener = exports.FrameSealer = exports.FRAME_CIPHER_KEY_BYTES = exports.FRAME_CIPHER_OVERHEAD = exports.FRAME_CIPHER_TAG_BYTES = exports.FRAME_ENC = void 0;
+exports.deriveFrameKeys = deriveFrameKeys;
+exports.frameKeysForRole = frameKeysForRole;
+exports.createFrameCiphers = createFrameCiphers;
+const chacha_1 = require("@noble/ciphers/chacha");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha2_1 = require("@noble/hashes/sha2");
+/** Frame type byte for a sealed frame. The only cleartext byte on the wire once armed. */
+exports.FRAME_ENC = 0x20;
+/** Poly1305 authentication tag length in bytes. */
+exports.FRAME_CIPHER_TAG_BYTES = 16;
+/** Bytes added to every frame by the cipher: 1 type byte plus the tag. */
+exports.FRAME_CIPHER_OVERHEAD = 1 + exports.FRAME_CIPHER_TAG_BYTES;
+/** ChaCha20-Poly1305 key length in bytes. */
+exports.FRAME_CIPHER_KEY_BYTES = 32;
+/** RFC 8439 nonce length in bytes. */
+const NONCE_BYTES = 12;
+/** HKDF `info` label; bump with the `frameCrypto.version` if the derivation ever changes. */
+const HKDF_LABEL = "peers-frame-v1";
+const utf8 = new TextEncoder();
+function concatBytes(...parts) {
+    let length = 0;
+    for (const part of parts)
+        length += part.length;
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+    }
+    return out;
+}
+function encodeTimestamp(timestamp) {
+    if (!Number.isSafeInteger(timestamp) || timestamp < 0) {
+        throw new Error(`Invalid handshake timestamp for key derivation: ${timestamp}`);
+    }
+    const bytes = new Uint8Array(8);
+    new DataView(bytes.buffer).setBigUint64(0, BigInt(timestamp), false);
+    return bytes;
+}
+function encodeLengthPrefixed(value) {
+    const bytes = utf8.encode(value);
+    if (bytes.length > 0xffff) {
+        throw new Error("Key derivation input too long");
+    }
+    const out = new Uint8Array(2 + bytes.length);
+    new DataView(out.buffer).setUint16(0, bytes.length, false);
+    out.set(bytes, 2);
+    return out;
+}
+/**
+ * Derives the two directional frame keys for a connection.
+ *
+ * ```
+ * ikm  = ephemeralSharedSecret || staticSharedSecret
+ * salt = connectionId
+ * info = "peers-frame-v1" || len(clientDeviceId) || clientDeviceId
+ *      || len(serverDeviceId) || serverDeviceId || timestamp (8-byte BE)
+ * okm  = HKDF-SHA256(ikm, salt, info, 64)
+ * clientToServer = okm[0..32], serverToClient = okm[32..64]
+ * ```
+ *
+ * Symmetric: both peers compute the same pair, then pick their {@link FrameKeys}
+ * with {@link frameKeysForRole}. The caller owns the shared secrets and should
+ * zeroize them once this returns.
+ */
+function deriveFrameKeys(params) {
+    const { ephemeralSharedSecret, staticSharedSecret, connectionId, clientDeviceId, serverDeviceId, timestamp, } = params;
+    if (ephemeralSharedSecret.length !== 32 || staticSharedSecret.length !== 32) {
+        throw new Error("Frame key derivation requires two 32-byte X25519 shared secrets");
+    }
+    if (!connectionId || !clientDeviceId || !serverDeviceId) {
+        throw new Error("Frame key derivation requires connectionId and both device IDs");
+    }
+    const ikm = concatBytes(ephemeralSharedSecret, staticSharedSecret);
+    const salt = utf8.encode(connectionId);
+    const info = concatBytes(utf8.encode(HKDF_LABEL), encodeLengthPrefixed(clientDeviceId), encodeLengthPrefixed(serverDeviceId), encodeTimestamp(timestamp));
+    const okm = (0, hkdf_1.hkdf)(sha2_1.sha256, ikm, salt, info, 2 * exports.FRAME_CIPHER_KEY_BYTES);
+    ikm.fill(0);
+    return {
+        clientToServer: okm.slice(0, exports.FRAME_CIPHER_KEY_BYTES),
+        serverToClient: okm.slice(exports.FRAME_CIPHER_KEY_BYTES, 2 * exports.FRAME_CIPHER_KEY_BYTES),
+    };
+}
+/** Selects a peer's send/receive keys from the direction-named pair. */
+function frameKeysForRole(derived, role) {
+    return role === "client"
+        ? { sendKey: derived.clientToServer, receiveKey: derived.serverToClient }
+        : { sendKey: derived.serverToClient, receiveKey: derived.clientToServer };
+}
+/**
+ * One direction of the frame cipher: a key, the connection AAD, and a counter.
+ *
+ * Instantiate one {@link FrameSealer} for outbound frames and one
+ * {@link FrameOpener} for inbound frames; never share an instance between
+ * directions, because the nonce counter must track exactly one stream.
+ */
+class FrameCipherDirection {
+    key;
+    aad;
+    nonce = new Uint8Array(NONCE_BYTES);
+    used = 0;
+    /**
+     * @param key 32-byte ChaCha20-Poly1305 key for this direction (owned by the instance)
+     * @param connectionId Connection ID used as AAD
+     */
+    constructor(key, connectionId) {
+        if (key.length !== exports.FRAME_CIPHER_KEY_BYTES) {
+            throw new Error(`Frame cipher key must be ${exports.FRAME_CIPHER_KEY_BYTES} bytes`);
+        }
+        this.key = key;
+        this.aad = utf8.encode(connectionId);
+    }
+    /** Number of frames processed so far in this direction. */
+    get count() {
+        return this.used;
+    }
+    /** Returns the nonce for the next frame and advances the counter. */
+    nextNonce() {
+        const current = this.nonce.slice();
+        let i = NONCE_BYTES - 1;
+        while (i >= 0) {
+            this.nonce[i] = (this.nonce[i] + 1) & 0xff;
+            if (this.nonce[i] !== 0)
+                break;
+            i--;
+        }
+        if (i < 0) {
+            throw new Error("Frame cipher nonce counter exhausted");
+        }
+        this.used++;
+        return current;
+    }
+    /** Overwrites the key material. The instance is unusable afterwards. */
+    destroy() {
+        this.key.fill(0);
+    }
+}
+/** Seals outbound frames. One instance per connection direction. */
+class FrameSealer extends FrameCipherDirection {
+    /**
+     * Seals a complete inner frame (type byte included) into a `FRAME_ENC` frame.
+     * Output length is `inner.length + FRAME_CIPHER_OVERHEAD`.
+     */
+    seal(inner) {
+        const nonce = this.nextNonce();
+        const sealed = (0, chacha_1.chacha20poly1305)(this.key, nonce, this.aad).encrypt(inner);
+        const frame = new Uint8Array(1 + sealed.length);
+        frame[0] = exports.FRAME_ENC;
+        frame.set(sealed, 1);
+        return frame;
+    }
+}
+exports.FrameSealer = FrameSealer;
+/** Opens inbound frames. One instance per connection direction. */
+class FrameOpener extends FrameCipherDirection {
+    /**
+     * Opens a `FRAME_ENC` frame and returns the inner frame, or `null` if the
+     * frame is malformed or fails authentication. The counter advances on every
+     * call, including failures, because a failed frame means the ordered stream
+     * is already broken and the caller must close the connection.
+     */
+    open(frame) {
+        if (frame.length < exports.FRAME_CIPHER_OVERHEAD || frame[0] !== exports.FRAME_ENC) {
+            return null;
+        }
+        const nonce = this.nextNonce();
+        try {
+            return (0, chacha_1.chacha20poly1305)(this.key, nonce, this.aad).decrypt(frame.subarray(1));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.FrameOpener = FrameOpener;
+/** Convenience: builds both directions for one peer from its {@link FrameKeys}. */
+function createFrameCiphers(keys, connectionId) {
+    return {
+        sealer: new FrameSealer(keys.sendKey, connectionId),
+        opener: new FrameOpener(keys.receiveKey, connectionId),
+    };
+}

package/dist/device/frame-cipher.test.d.ts

@@ -0,0 +1 @@
+export {};