@sideband/secure-relay 0.0.1

package/dist/session.js

@@ -0,0 +1,123 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Session management for Sideband Relay Protocol (SBRP).
+ *
+ * Handles encrypted message sending/receiving with proper key selection,
+ * sequence number tracking, and replay protection.
+ */
+import { decrypt, encrypt, extractSequence, zeroize } from "./crypto.js";
+import { checkAndUpdateReplay, createReplayWindow, } from "./replay.js";
+import { Direction, SbrpError, SbrpErrorCode } from "./types.js";
+/**
+ * Create a client session (daemon side).
+ *
+ * Used by daemon to manage state for each connected client.
+ */
+export function createClientSession(clientId, trafficKeys) {
+    return {
+        clientId,
+        clientToDaemon: {
+            trafficKey: trafficKeys.clientToDaemon,
+            sendSeq: 0n,
+            recvWindow: createReplayWindow(),
+        },
+        daemonToClient: {
+            trafficKey: trafficKeys.daemonToClient,
+            sendSeq: 0n,
+            recvWindow: createReplayWindow(),
+        },
+    };
+}
+/**
+ * Create a daemon connection (client side).
+ *
+ * Used by client to communicate with daemon.
+ */
+export function createDaemonConnection(trafficKeys) {
+    return {
+        clientToDaemon: {
+            trafficKey: trafficKeys.clientToDaemon,
+            sendSeq: 0n,
+            recvWindow: createReplayWindow(),
+        },
+        daemonToClient: {
+            trafficKey: trafficKeys.daemonToClient,
+            sendSeq: 0n,
+            recvWindow: createReplayWindow(),
+        },
+    };
+}
+/**
+ * Encrypt a message from client to daemon.
+ */
+export function encryptClientToDaemon(conn, plaintext) {
+    const seq = conn.clientToDaemon.sendSeq++;
+    const data = encrypt(conn.clientToDaemon.trafficKey, Direction.ClientToDaemon, seq, plaintext);
+    return { type: "encrypted", seq, data };
+}
+/**
+ * Encrypt a message from daemon to client.
+ */
+export function encryptDaemonToClient(session, plaintext) {
+    const seq = session.daemonToClient.sendSeq++;
+    const data = encrypt(session.daemonToClient.trafficKey, Direction.DaemonToClient, seq, plaintext);
+    return { type: "encrypted", seq, data };
+}
+/**
+ * Decrypt a message received by daemon from client.
+ *
+ * @throws {SbrpError} with code SequenceError if replay detected
+ * @throws {SbrpError} with code DecryptFailed if decryption fails
+ */
+export function decryptClientToDaemon(session, message) {
+    // Check replay protection
+    const seq = extractSequence(message.data);
+    if (!checkAndUpdateReplay(seq, session.clientToDaemon.recvWindow)) {
+        throw new SbrpError(SbrpErrorCode.SequenceError, "Sequence number outside valid window or replay detected");
+    }
+    try {
+        return decrypt(session.clientToDaemon.trafficKey, message.data);
+    }
+    catch {
+        throw new SbrpError(SbrpErrorCode.DecryptFailed, "Message decryption failed");
+    }
+}
+/**
+ * Decrypt a message received by client from daemon.
+ *
+ * @throws {SbrpError} with code SequenceError if replay detected
+ * @throws {SbrpError} with code DecryptFailed if decryption fails
+ */
+export function decryptDaemonToClient(conn, message) {
+    // Check replay protection
+    const seq = extractSequence(message.data);
+    if (!checkAndUpdateReplay(seq, conn.daemonToClient.recvWindow)) {
+        throw new SbrpError(SbrpErrorCode.SequenceError, "Sequence number outside valid window or replay detected");
+    }
+    try {
+        return decrypt(conn.daemonToClient.trafficKey, message.data);
+    }
+    catch {
+        throw new SbrpError(SbrpErrorCode.DecryptFailed, "Message decryption failed");
+    }
+}
+/**
+ * Clear all key material from a client session.
+ *
+ * Best-effort zeroization (JS/GC limitations apply).
+ */
+export function clearClientSession(session) {
+    zeroize(session.clientToDaemon.trafficKey);
+    zeroize(session.daemonToClient.trafficKey);
+}
+/**
+ * Clear all key material from a daemon connection.
+ *
+ * Best-effort zeroization (JS/GC limitations apply).
+ */
+export function clearDaemonConnection(conn) {
+    zeroize(conn.clientToDaemon.trafficKey);
+    zeroize(conn.daemonToClient.trafficKey);
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,6CAA6C;AAE7C;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EACL,oBAAoB,EACpB,kBAAkB,GAEnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAsBjE;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAkB,EAClB,WAAwB;IAExB,OAAO;QACL,QAAQ;QACR,cAAc,EAAE;YACd,UAAU,EAAE,WAAW,CAAC,cAAc;YACtC,OAAO,EAAE,EAAE;YACX,UAAU,EAAE,kBAAkB,EAAE;SACjC;QACD,cAAc,EAAE;YACd,UAAU,EAAE,WAAW,CAAC,cAAc;YACtC,OAAO,EAAE,EAAE;YACX,UAAU,EAAE,kBAAkB,EAAE;SACjC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAwB;IAExB,OAAO;QACL,cAAc,EAAE;YACd,UAAU,EAAE,WAAW,CAAC,cAAc;YACtC,OAAO,EAAE,EAAE;YACX,UAAU,EAAE,kBAAkB,EAAE;SACjC;QACD,cAAc,EAAE;YACd,UAAU,EAAE,WAAW,CAAC,cAAc;YACtC,OAAO,EAAE,EAAE;YACX,UAAU,EAAE,kBAAkB,EAAE;SACjC;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAsB,EACtB,SAAqB;IAErB,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,OAAO,CAClB,IAAI,CAAC,cAAc,CAAC,UAAU,EAC9B,SAAS,CAAC,cAAc,EACxB,GAAG,EACH,SAAS,CACV,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,SAAqB;IAErB,MAAM,GAAG,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,OAAO,CAClB,OAAO,CAAC,cAAc,CAAC,UAAU,EACjC,SAAS,CAAC,cAAc,EACxB,GAAG,EACH,SAAS,CACV,CAAC;IAEF,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAsB,EACtB,OAAyB;IAEzB,0BAA0B;IAC1B,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,aAAa,EAC3B,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,aAAa,CAAC,aAAa,EAAE,2BAA2B,CAAC,CAAC;IAChF,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAsB,EACtB,OAAyB;IAEzB,0BAA0B;IAC1B,MAAM,GAAG,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,oBAAoB,CAAC,GAAG,EAAE,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,SAAS,CACjB,aAAa,CAAC,aAAa,EAC3B,yDAAyD,CAC1D,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,SAAS,CAAC,aAAa,CAAC,aAAa,EAAE,2BAA2B,CAAC,CAAC;IAChF,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAsB;IACvD,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAC3C,OAAO,CAAC,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAsB;IAC1D,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IACxC,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;AAC1C,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Type definitions for Sideband Relay Protocol (SBRP).
+ */
+/** Branded type for daemon identifiers */
+export type DaemonId = string & {
+    readonly __brand: "DaemonId";
+};
+/** Branded type for client session identifiers (relay-assigned) */
+export type ClientId = string & {
+    readonly __brand: "ClientId";
+};
+/** Ed25519 identity keypair for daemon authentication */
+export interface IdentityKeyPair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+/** X25519 ephemeral keypair for key exchange */
+export interface EphemeralKeyPair {
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+}
+/** Pinned identity for TOFU verification (browser-side storage) */
+export interface PinnedIdentity {
+    daemonId: DaemonId;
+    identityPublicKey: Uint8Array;
+    firstSeen: Date;
+    lastSeen: Date;
+}
+/** Traffic keys derived from handshake (directional symmetric keys) */
+export interface TrafficKeys {
+    /** Key for encrypting client→daemon messages */
+    clientToDaemon: Uint8Array;
+    /** Key for encrypting daemon→client messages */
+    daemonToClient: Uint8Array;
+}
+/** Handshake init message (browser → daemon) */
+export interface HandshakeInit {
+    type: "handshake.init";
+    browserPublicKey: Uint8Array;
+}
+/** Handshake accept message (daemon → browser) */
+export interface HandshakeAccept {
+    type: "handshake.accept";
+    daemonPublicKey: Uint8Array;
+    signature: Uint8Array;
+}
+/** Encrypted message envelope */
+export interface EncryptedMessage {
+    type: "encrypted";
+    seq: bigint;
+    data: Uint8Array;
+}
+/** Direction of message flow (used in nonce construction) */
+export declare const enum Direction {
+    ClientToDaemon = 1,
+    DaemonToClient = 2
+}
+/** SBRP error codes */
+export declare const enum SbrpErrorCode {
+    Unauthorized = "unauthorized",
+    DaemonNotFound = "daemon_not_found",
+    DaemonOffline = "daemon_offline",
+    DaemonNotOwned = "daemon_not_owned",
+    IdentityKeyChanged = "identity_key_changed",
+    HandshakeFailed = "handshake_failed",
+    DecryptFailed = "decrypt_failed",
+    SequenceError = "sequence_error",
+    RateLimited = "rate_limited"
+}
+/** SBRP-specific error */
+export declare class SbrpError extends Error {
+    readonly code: SbrpErrorCode;
+    constructor(code: SbrpErrorCode, message: string);
+}
+/** Type guard for DaemonId */
+export declare function asDaemonId(value: string): DaemonId;
+/** Type guard for ClientId */
+export declare function asClientId(value: string): ClientId;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAGA;;GAEG;AAEH,0CAA0C;AAC1C,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAEjE,mEAAmE;AACnE,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAA;CAAE,CAAC;AAEjE,yDAAyD;AACzD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,gDAAgD;AAChD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,UAAU,CAAC;IACtB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,QAAQ,CAAC;IACnB,iBAAiB,EAAE,UAAU,CAAC;IAC9B,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,IAAI,CAAC;CAChB;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,cAAc,EAAE,UAAU,CAAC;IAC3B,gDAAgD;IAChD,cAAc,EAAE,UAAU,CAAC;CAC5B;AAED,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,gBAAgB,CAAC;IACvB,gBAAgB,EAAE,UAAU,CAAC;CAC9B;AAED,kDAAkD;AAClD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,kBAAkB,CAAC;IACzB,eAAe,EAAE,UAAU,CAAC;IAC5B,SAAS,EAAE,UAAU,CAAC;CACvB;AAED,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,6DAA6D;AAC7D,0BAAkB,SAAS;IACzB,cAAc,IAAI;IAClB,cAAc,IAAI;CACnB;AAED,uBAAuB;AACvB,0BAAkB,aAAa;IAC7B,YAAY,iBAAiB;IAC7B,cAAc,qBAAqB;IACnC,aAAa,mBAAmB;IAChC,cAAc,qBAAqB;IACnC,kBAAkB,yBAAyB;IAC3C,eAAe,qBAAqB;IACpC,aAAa,mBAAmB;IAChC,aAAa,mBAAmB;IAChC,WAAW,iBAAiB;CAC7B;AAED,0BAA0B;AAC1B,qBAAa,SAAU,SAAQ,KAAK;aAEhB,IAAI,EAAE,aAAa;gBAAnB,IAAI,EAAE,aAAa,EACnC,OAAO,EAAE,MAAM;CAKlB;AAED,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAElD;AAED,8BAA8B;AAC9B,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAElD"}

package/dist/types.js

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** Direction of message flow (used in nonce construction) */
+export var Direction;
+(function (Direction) {
+    Direction[Direction["ClientToDaemon"] = 1] = "ClientToDaemon";
+    Direction[Direction["DaemonToClient"] = 2] = "DaemonToClient";
+})(Direction || (Direction = {}));
+/** SBRP error codes */
+export var SbrpErrorCode;
+(function (SbrpErrorCode) {
+    SbrpErrorCode["Unauthorized"] = "unauthorized";
+    SbrpErrorCode["DaemonNotFound"] = "daemon_not_found";
+    SbrpErrorCode["DaemonOffline"] = "daemon_offline";
+    SbrpErrorCode["DaemonNotOwned"] = "daemon_not_owned";
+    SbrpErrorCode["IdentityKeyChanged"] = "identity_key_changed";
+    SbrpErrorCode["HandshakeFailed"] = "handshake_failed";
+    SbrpErrorCode["DecryptFailed"] = "decrypt_failed";
+    SbrpErrorCode["SequenceError"] = "sequence_error";
+    SbrpErrorCode["RateLimited"] = "rate_limited";
+})(SbrpErrorCode || (SbrpErrorCode = {}));
+/** SBRP-specific error */
+export class SbrpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SbrpError";
+    }
+}
+/** Type guard for DaemonId */
+export function asDaemonId(value) {
+    return value;
+}
+/** Type guard for ClientId */
+export function asClientId(value) {
+    return value;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,6CAA6C;AA4D7C,6DAA6D;AAC7D,MAAM,CAAN,IAAkB,SAGjB;AAHD,WAAkB,SAAS;IACzB,6DAAkB,CAAA;IAClB,6DAAkB,CAAA;AACpB,CAAC,EAHiB,SAAS,KAAT,SAAS,QAG1B;AAED,uBAAuB;AACvB,MAAM,CAAN,IAAkB,aAUjB;AAVD,WAAkB,aAAa;IAC7B,8CAA6B,CAAA;IAC7B,oDAAmC,CAAA;IACnC,iDAAgC,CAAA;IAChC,oDAAmC,CAAA;IACnC,4DAA2C,CAAA;IAC3C,qDAAoC,CAAA;IACpC,iDAAgC,CAAA;IAChC,iDAAgC,CAAA;IAChC,6CAA4B,CAAA;AAC9B,CAAC,EAViB,aAAa,KAAb,aAAa,QAU9B;AAED,0BAA0B;AAC1B,MAAM,OAAO,SAAU,SAAQ,KAAK;IAEhB;IADlB,YACkB,IAAmB,EACnC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAe;QAInC,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC;IAC1B,CAAC;CACF;AAED,8BAA8B;AAC9B,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAiB,CAAC;AAC3B,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,KAAiB,CAAC;AAC3B,CAAC"}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@sideband/secure-relay",
+  "version": "0.0.1",
+  "description": "Secure Relay Protocol (SBRP): E2EE handshake, session encryption, and TOFU identity pinning for relay-mediated communication.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sidebandtech/sideband.git",
+    "directory": "packages/secure-relay"
+  },
+  "bugs": {
+    "url": "https://github.com/sidebandtech/sideband/issues"
+  },
+  "homepage": "https://sideband.tech",
+  "author": "Sideband <hello@sideband.tech>",
+  "contributors": [
+    "Konstantin Tarkus <koistya@kriasoft.com>"
+  ],
+  "keywords": [
+    "sideband",
+    "secure-relay",
+    "relay-protocol",
+    "e2ee",
+    "end-to-end-encryption",
+    "authenticated-encryption",
+    "identity-pinning",
+    "tofu",
+    "zero-trust",
+    "secure-websocket",
+    "agent-communication",
+    "browser-to-daemon",
+    "remote-daemon",
+    "encryption",
+    "x25519",
+    "ed25519",
+    "chacha20-poly1305"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^1.2.1",
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.7.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.3"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Protocol constants for Sideband Relay Protocol (SBRP).
+ */
+
+/** Domain separation context for handshake signature payload */
+export const SBRP_HANDSHAKE_CONTEXT = "sbrp-v1-handshake";
+
+/** Domain separation context for transcript hash (HKDF salt) */
+export const SBRP_TRANSCRIPT_CONTEXT = "sbrp-v1-transcript";
+
+/** HKDF info string for session key derivation */
+export const SBRP_SESSION_KEYS_INFO = "sbrp-session-keys";
+
+/** Length of session keys in bytes (browserToDaemon + daemonToBrowser) */
+export const SESSION_KEYS_LENGTH = 64;
+
+/** Length of a single symmetric key in bytes */
+export const SYMMETRIC_KEY_LENGTH = 32;
+
+/** Length of Ed25519 public key in bytes */
+export const ED25519_PUBLIC_KEY_LENGTH = 32;
+
+/** Length of Ed25519 private key seed in bytes */
+export const ED25519_PRIVATE_KEY_LENGTH = 32;
+
+/** Length of Ed25519 signature in bytes */
+export const ED25519_SIGNATURE_LENGTH = 64;
+
+/** Length of X25519 public key in bytes */
+export const X25519_PUBLIC_KEY_LENGTH = 32;
+
+/** Length of X25519 private key in bytes */
+export const X25519_PRIVATE_KEY_LENGTH = 32;
+
+/** Length of ChaCha20-Poly1305 nonce in bytes */
+export const NONCE_LENGTH = 12;
+
+/** Length of Poly1305 auth tag in bytes */
+export const AUTH_TAG_LENGTH = 16;
+
+/** Default replay window size (bits) */
+export const DEFAULT_REPLAY_WINDOW_SIZE = 64n;
+
+/** Direction bytes in nonce (4 bytes, big-endian) */
+export const DIRECTION_CLIENT_TO_DAEMON = new Uint8Array([0, 0, 0, 1]);
+export const DIRECTION_DAEMON_TO_CLIENT = new Uint8Array([0, 0, 0, 2]);

package/src/crypto.ts

@@ -0,0 +1,234 @@
+// SPDX-FileCopyrightText: 2025-present Sideband
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Cryptographic primitives for Sideband Relay Protocol (SBRP).
+ *
+ * Uses @noble/curves for Ed25519/X25519, @noble/ciphers for ChaCha20-Poly1305,
+ * and @noble/hashes for SHA-256/HKDF.
+ */
+
+import { chacha20poly1305 } from "@noble/ciphers/chacha";
+import { ed25519 } from "@noble/curves/ed25519";
+import { x25519 } from "@noble/curves/ed25519";
+import { hkdf } from "@noble/hashes/hkdf";
+import { sha256 } from "@noble/hashes/sha256";
+import { concatBytes, randomBytes } from "@noble/hashes/utils";
+import {
+  AUTH_TAG_LENGTH,
+  DIRECTION_CLIENT_TO_DAEMON,
+  DIRECTION_DAEMON_TO_CLIENT,
+  NONCE_LENGTH,
+  SBRP_HANDSHAKE_CONTEXT,
+  SBRP_SESSION_KEYS_INFO,
+  SBRP_TRANSCRIPT_CONTEXT,
+  SESSION_KEYS_LENGTH,
+  SYMMETRIC_KEY_LENGTH,
+} from "./constants.js";
+import type {
+  DaemonId,
+  EphemeralKeyPair,
+  IdentityKeyPair,
+  SessionKeys,
+} from "./types.js";
+import { Direction } from "./types.js";
+
+const textEncoder = new TextEncoder();
+
+/** Generate a new Ed25519 identity keypair */
+export function generateIdentityKeyPair(): IdentityKeyPair {
+  const privateKey = ed25519.utils.randomPrivateKey();
+  const publicKey = ed25519.getPublicKey(privateKey);
+  return { publicKey, privateKey };
+}
+
+/** Generate a new X25519 ephemeral keypair */
+export function generateEphemeralKeyPair(): EphemeralKeyPair {
+  const privateKey = x25519.utils.randomPrivateKey();
+  const publicKey = x25519.getPublicKey(privateKey);
+  return { publicKey, privateKey };
+}
+
+/** Compute SHA-256 fingerprint of an identity public key */
+export function computeFingerprint(identityPublicKey: Uint8Array): string {
+  const hash = sha256(identityPublicKey);
+  const hex = Array.from(hash)
+    .map((b) => b.toString(16).padStart(2, "0").toUpperCase())
+    .join(":");
+  return `SHA256:${hex}`;
+}
+
+/**
+ * Create the signature payload for handshake authentication.
+ *
+ * payload = SHA256("sbrp-v1-handshake" || daemonId || clientPublicKey || daemonEphemeralPublicKey)
+ */
+export function createSignaturePayload(
+  daemonId: DaemonId,
+  clientPublicKey: Uint8Array,
+  daemonEphemeralPublicKey: Uint8Array,
+): Uint8Array {
+  return sha256(
+    concatBytes(
+      textEncoder.encode(SBRP_HANDSHAKE_CONTEXT),
+      textEncoder.encode(daemonId),
+      clientPublicKey,
+      daemonEphemeralPublicKey,
+    ),
+  );
+}
+
+/** Sign a payload with an Ed25519 identity private key */
+export function signPayload(
+  payload: Uint8Array,
+  identityPrivateKey: Uint8Array,
+): Uint8Array {
+  return ed25519.sign(payload, identityPrivateKey);
+}
+
+/** Verify an Ed25519 signature */
+export function verifySignature(
+  payload: Uint8Array,
+  signature: Uint8Array,
+  identityPublicKey: Uint8Array,
+): boolean {
+  return ed25519.verify(signature, payload, identityPublicKey);
+}
+
+/** Compute X25519 shared secret */
+export function computeSharedSecret(
+  myPrivateKey: Uint8Array,
+  peerPublicKey: Uint8Array,
+): Uint8Array {
+  return x25519.getSharedSecret(myPrivateKey, peerPublicKey);
+}
+
+/**
+ * Create the transcript hash for key derivation.
+ *
+ * transcript = SHA256("sbrp-v1-transcript" || daemonId || clientPublicKey || daemonPublicKey || signature)
+ */
+export function createTranscriptHash(
+  daemonId: DaemonId,
+  clientPublicKey: Uint8Array,
+  daemonPublicKey: Uint8Array,
+  signature: Uint8Array,
+): Uint8Array {
+  return sha256(
+    concatBytes(
+      textEncoder.encode(SBRP_TRANSCRIPT_CONTEXT),
+      textEncoder.encode(daemonId),
+      clientPublicKey,
+      daemonPublicKey,
+      signature,
+    ),
+  );
+}
+
+/**
+ * Derive session keys using HKDF-SHA256.
+ *
+ * Keys are derived with transcript hash as salt to bind to the authenticated session.
+ */
+export function deriveSessionKeys(
+  sharedSecret: Uint8Array,
+  transcriptHash: Uint8Array,
+): SessionKeys {
+  const keys = hkdf(
+    sha256,
+    sharedSecret,
+    transcriptHash,
+    SBRP_SESSION_KEYS_INFO,
+    SESSION_KEYS_LENGTH,
+  );
+
+  return {
+    clientToDaemon: keys.slice(0, SYMMETRIC_KEY_LENGTH),
+    daemonToClient: keys.slice(SYMMETRIC_KEY_LENGTH, SESSION_KEYS_LENGTH),
+  };
+}
+
+/**
+ * Construct a nonce for ChaCha20-Poly1305.
+ *
+ * Nonce format (12 bytes):
+ * - Bytes 0-3: Direction (0x00000001 = client→daemon, 0x00000002 = daemon→client)
+ * - Bytes 4-11: Sequence number (big-endian uint64)
+ */
+export function constructNonce(direction: Direction, seq: bigint): Uint8Array {
+  const nonce = new Uint8Array(NONCE_LENGTH);
+  const directionBytes =
+    direction === Direction.ClientToDaemon
+      ? DIRECTION_CLIENT_TO_DAEMON
+      : DIRECTION_DAEMON_TO_CLIENT;
+
+  nonce.set(directionBytes, 0);
+
+  // Write sequence number as big-endian uint64 (bytes 4-11)
+  const view = new DataView(nonce.buffer);
+  view.setBigUint64(4, seq, false); // false = big-endian
+
+  return nonce;
+}
+
+/**
+ * Encrypt a message using ChaCha20-Poly1305.
+ *
+ * Returns: nonce (12 bytes) || ciphertext || authTag (16 bytes)
+ */
+export function encrypt(
+  key: Uint8Array,
+  direction: Direction,
+  seq: bigint,
+  plaintext: Uint8Array,
+): Uint8Array {
+  const nonce = constructNonce(direction, seq);
+  const cipher = chacha20poly1305(key, nonce);
+  const ciphertext = cipher.encrypt(plaintext);
+
+  return concatBytes(nonce, ciphertext);
+}
+
+/**
+ * Decrypt a message using ChaCha20-Poly1305.
+ *
+ * Input format: nonce (12 bytes) || ciphertext || authTag (16 bytes)
+ * Returns the plaintext, or throws on decryption failure.
+ */
+export function decrypt(key: Uint8Array, data: Uint8Array): Uint8Array {
+  if (data.length < NONCE_LENGTH + AUTH_TAG_LENGTH) {
+    throw new Error("Invalid encrypted message: too short");
+  }
+
+  const nonce = data.slice(0, NONCE_LENGTH);
+  const ciphertext = data.slice(NONCE_LENGTH);
+
+  const cipher = chacha20poly1305(key, nonce);
+  return cipher.decrypt(ciphertext);
+}
+
+/**
+ * Extract sequence number from encrypted message data.
+ *
+ * Reads bytes 4-11 of the nonce as big-endian uint64.
+ */
+export function extractSequence(data: Uint8Array): bigint {
+  if (data.length < NONCE_LENGTH) {
+    throw new Error("Invalid encrypted message: too short");
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  return view.getBigUint64(4, false); // false = big-endian
+}
+
+/**
+ * Best-effort zeroization of sensitive key material.
+ *
+ * Note: JavaScript/GC limitations mean this is not guaranteed to prevent
+ * key material from remaining in memory.
+ */
+export function zeroize(data: Uint8Array): void {
+  data.fill(0);
+}
+
+/** Generate random bytes */
+export { randomBytes };