@pellux/goodvibes-transport-core 1.6.1 → 1.7.0

package/dist/relay/crypto.d.ts

@@ -0,0 +1,49 @@
+/** Named curve used for all relay key agreement. */
+export declare const RELAY_CURVE: "P-256";
+/** Raw (uncompressed) P-256 public key length in bytes. */
+export declare const RELAY_PUBLIC_KEY_BYTES = 65;
+/** AEAD nonce length in bytes (AES-GCM standard 96-bit nonce). */
+export declare const RELAY_NONCE_BYTES = 12;
+/** Symmetric key length in bytes (AES-256). */
+export declare const RELAY_KEY_BYTES = 32;
+/** Fill `n` bytes from the platform CSPRNG. */
+export declare function randomBytes(n: number): Uint8Array<ArrayBuffer>;
+/** Encode bytes to unpadded base64url. */
+export declare function toBase64Url(bytes: Uint8Array<ArrayBuffer>): string;
+/** Decode unpadded (or padded) base64url to bytes. Throws on invalid input. */
+export declare function fromBase64Url(text: string): Uint8Array<ArrayBuffer>;
+/** Constant-time equality for two byte arrays (length is not secret). */
+export declare function bytesEqual(a: Uint8Array<ArrayBuffer>, b: Uint8Array<ArrayBuffer>): boolean;
+/** Concatenate byte arrays into one. */
+export declare function concatBytes(...parts: readonly Uint8Array<ArrayBuffer>[]): Uint8Array<ArrayBuffer>;
+/** A relay identity/ephemeral key pair. Private key is non-extractable. */
+export interface RelayKeyPair {
+    readonly publicKey: CryptoKey;
+    readonly privateKey: CryptoKey;
+}
+/** Generate a fresh ECDH P-256 key pair for key agreement. */
+export declare function generateEcdhKeyPair(): Promise<RelayKeyPair>;
+/** Export a public key to its 65-byte raw uncompressed form. */
+export declare function exportRawPublicKey(key: CryptoKey): Promise<Uint8Array<ArrayBuffer>>;
+/** Import a 65-byte raw uncompressed P-256 public key. */
+export declare function importRawPublicKey(bytes: Uint8Array<ArrayBuffer>): Promise<CryptoKey>;
+/** Compute the raw ECDH shared secret (32-byte x-coordinate) between our private key and their public key. */
+export declare function deriveSharedSecret(privateKey: CryptoKey, publicKey: CryptoKey): Promise<Uint8Array<ArrayBuffer>>;
+/** SHA-256 digest. */
+export declare function sha256(data: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * HKDF-SHA-256 (extract + expand) producing `length` bytes of output key
+ * material. `salt` and `info` bind the derivation to the handshake transcript.
+ */
+export declare function hkdf(ikm: Uint8Array<ArrayBuffer>, salt: Uint8Array<ArrayBuffer>, info: Uint8Array<ArrayBuffer>, length: number): Promise<Uint8Array<ArrayBuffer>>;
+/** Import a 32-byte raw key as an AES-256-GCM key. */
+export declare function importAeadKey(rawKey: Uint8Array<ArrayBuffer>): Promise<CryptoKey>;
+/** AES-256-GCM seal. Returns ciphertext with the GCM tag appended. */
+export declare function aeadSeal(key: CryptoKey, nonce: Uint8Array<ArrayBuffer>, plaintext: Uint8Array<ArrayBuffer>, aad: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
+/** AES-256-GCM open. Throws (auth failure) if the ciphertext/tag/AAD do not verify. */
+export declare function aeadOpen(key: CryptoKey, nonce: Uint8Array<ArrayBuffer>, ciphertext: Uint8Array<ArrayBuffer>, aad: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
+/** UTF-8 encode a string to bytes. */
+export declare function encodeUtf8(text: string): Uint8Array<ArrayBuffer>;
+/** UTF-8 decode bytes to a string. */
+export declare function decodeUtf8(bytes: Uint8Array<ArrayBuffer>): string;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/relay/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../../src/relay/crypto.ts"],"names":[],"mappings":"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"}

package/dist/relay/crypto.js

@@ -0,0 +1,215 @@
+// relay/crypto.ts
+//
+// Runtime-neutral cryptographic primitives for the zero-knowledge relay
+// end-to-end (E2E) channel. Every primitive here is a thin, honest wrapper over
+// the Web Crypto API (`globalThis.crypto.subtle`) — the same interface exposed
+// by browsers, Bun, and Node 22+. Nothing is hand-rolled: key agreement is
+// ECDH over the NIST P-256 curve, key derivation is HKDF-SHA-256, and the AEAD
+// is AES-256-GCM. P-256 is chosen over X25519 because it is universally
+// available in Web Crypto across every surface that must terminate this channel
+// (browser PWA, Bun daemon, Node), and it matches the curve the codebase
+// already relies on for push-message encryption.
+//
+// This module intentionally holds ZERO relay-protocol knowledge — it only knows
+// bytes and keys. Higher layers (handshake.ts, secure-channel.ts) compose these.
+import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
+/** Named curve used for all relay key agreement. */
+export const RELAY_CURVE = 'P-256';
+/** Raw (uncompressed) P-256 public key length in bytes. */
+export const RELAY_PUBLIC_KEY_BYTES = 65;
+/** AEAD nonce length in bytes (AES-GCM standard 96-bit nonce). */
+export const RELAY_NONCE_BYTES = 12;
+/** Symmetric key length in bytes (AES-256). */
+export const RELAY_KEY_BYTES = 32;
+function subtle() {
+    const c = globalThis.crypto;
+    if (!c || typeof c.subtle === 'undefined') {
+        throw new GoodVibesSdkError('Web Crypto (crypto.subtle) is unavailable in this runtime.', {
+            category: 'config',
+            source: 'transport',
+            recoverable: false,
+            hint: 'Run the relay in a runtime that provides the Web Crypto API (browser, Bun, or Node 22+).',
+        });
+    }
+    return c.subtle;
+}
+/** Fill `n` bytes from the platform CSPRNG. */
+export function randomBytes(n) {
+    const out = new Uint8Array(n);
+    const c = globalThis.crypto;
+    if (!c || typeof c.getRandomValues !== 'function') {
+        throw new GoodVibesSdkError('Secure random generation is unavailable in this runtime.', {
+            category: 'config',
+            source: 'transport',
+            recoverable: false,
+            hint: 'Run the relay in a runtime that provides crypto.getRandomValues().',
+        });
+    }
+    c.getRandomValues(out);
+    return out;
+}
+// ─── base64url (no padding), binary-safe, no Buffer/atob dependency ───────────
+const B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const B64URL_LOOKUP = (() => {
+    const table = new Array(128).fill(-1);
+    for (let i = 0; i < B64URL_ALPHABET.length; i += 1)
+        table[B64URL_ALPHABET.charCodeAt(i)] = i;
+    return table;
+})();
+/** Encode bytes to unpadded base64url. */
+export function toBase64Url(bytes) {
+    let out = '';
+    let i = 0;
+    for (; i + 2 < bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out += B64URL_ALPHABET[(n >> 18) & 63] + B64URL_ALPHABET[(n >> 12) & 63] + B64URL_ALPHABET[(n >> 6) & 63] + B64URL_ALPHABET[n & 63];
+    }
+    const rem = bytes.length - i;
+    if (rem === 1) {
+        const n = bytes[i] << 16;
+        out += B64URL_ALPHABET[(n >> 18) & 63] + B64URL_ALPHABET[(n >> 12) & 63];
+    }
+    else if (rem === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out += B64URL_ALPHABET[(n >> 18) & 63] + B64URL_ALPHABET[(n >> 12) & 63] + B64URL_ALPHABET[(n >> 6) & 63];
+    }
+    return out;
+}
+/** Decode unpadded (or padded) base64url to bytes. Throws on invalid input. */
+export function fromBase64Url(text) {
+    const clean = text.replace(/=+$/, '');
+    const len = clean.length;
+    const fullGroups = Math.floor(len / 4);
+    const remainder = len - fullGroups * 4;
+    if (remainder === 1) {
+        throw new GoodVibesSdkError('Invalid base64url string length.', { category: 'bad_request', source: 'transport', recoverable: false });
+    }
+    const outLen = fullGroups * 3 + (remainder === 2 ? 1 : remainder === 3 ? 2 : 0);
+    const out = new Uint8Array(outLen);
+    let o = 0;
+    let i = 0;
+    const at = (index) => {
+        const code = clean.charCodeAt(index);
+        const v = code < 128 ? B64URL_LOOKUP[code] : -1;
+        if (v < 0)
+            throw new GoodVibesSdkError('Invalid base64url character.', { category: 'bad_request', source: 'transport', recoverable: false });
+        return v;
+    };
+    for (let g = 0; g < fullGroups; g += 1, i += 4) {
+        const n = (at(i) << 18) | (at(i + 1) << 12) | (at(i + 2) << 6) | at(i + 3);
+        out[o++] = (n >> 16) & 0xff;
+        out[o++] = (n >> 8) & 0xff;
+        out[o++] = n & 0xff;
+    }
+    if (remainder === 2) {
+        const n = (at(i) << 18) | (at(i + 1) << 12);
+        out[o++] = (n >> 16) & 0xff;
+    }
+    else if (remainder === 3) {
+        const n = (at(i) << 18) | (at(i + 1) << 12) | (at(i + 2) << 6);
+        out[o++] = (n >> 16) & 0xff;
+        out[o++] = (n >> 8) & 0xff;
+    }
+    return out;
+}
+/** Constant-time equality for two byte arrays (length is not secret). */
+export function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i += 1)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/** Concatenate byte arrays into one. */
+export function concatBytes(...parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const p of parts) {
+        out.set(p, offset);
+        offset += p.length;
+    }
+    return out;
+}
+/** Generate a fresh ECDH P-256 key pair for key agreement. */
+export async function generateEcdhKeyPair() {
+    const pair = (await subtle().generateKey({ name: 'ECDH', namedCurve: RELAY_CURVE }, true, ['deriveBits']));
+    return { publicKey: pair.publicKey, privateKey: pair.privateKey };
+}
+/** Export a public key to its 65-byte raw uncompressed form. */
+export async function exportRawPublicKey(key) {
+    const raw = await subtle().exportKey('raw', key);
+    return new Uint8Array(raw);
+}
+/** Import a 65-byte raw uncompressed P-256 public key. */
+export async function importRawPublicKey(bytes) {
+    if (bytes.length !== RELAY_PUBLIC_KEY_BYTES || bytes[0] !== 0x04) {
+        throw new GoodVibesSdkError('Malformed P-256 public key (expected 65-byte uncompressed point).', {
+            category: 'bad_request',
+            source: 'transport',
+            recoverable: false,
+        });
+    }
+    return subtle().importKey('raw', bytes, { name: 'ECDH', namedCurve: RELAY_CURVE }, true, []);
+}
+/** Compute the raw ECDH shared secret (32-byte x-coordinate) between our private key and their public key. */
+export async function deriveSharedSecret(privateKey, publicKey) {
+    const bits = await subtle().deriveBits({ name: 'ECDH', public: publicKey }, privateKey, 256);
+    return new Uint8Array(bits);
+}
+// ─── hashing + KDF ────────────────────────────────────────────────────────────
+/** SHA-256 digest. */
+export async function sha256(data) {
+    const digest = await subtle().digest('SHA-256', data);
+    return new Uint8Array(digest);
+}
+/**
+ * HKDF-SHA-256 (extract + expand) producing `length` bytes of output key
+ * material. `salt` and `info` bind the derivation to the handshake transcript.
+ */
+export async function hkdf(ikm, salt, info, length) {
+    const key = await subtle().importKey('raw', ikm, 'HKDF', false, ['deriveBits']);
+    const bits = await subtle().deriveBits({ name: 'HKDF', hash: 'SHA-256', salt, info }, key, length * 8);
+    return new Uint8Array(bits);
+}
+// ─── AEAD (AES-256-GCM) ────────────────────────────────────────────────────────
+/** Import a 32-byte raw key as an AES-256-GCM key. */
+export async function importAeadKey(rawKey) {
+    if (rawKey.length !== RELAY_KEY_BYTES) {
+        throw new GoodVibesSdkError('AEAD key must be 32 bytes.', { category: 'bad_request', source: 'transport', recoverable: false });
+    }
+    return subtle().importKey('raw', rawKey, { name: 'AES-GCM' }, false, ['encrypt', 'decrypt']);
+}
+/** AES-256-GCM seal. Returns ciphertext with the GCM tag appended. */
+export async function aeadSeal(key, nonce, plaintext, aad) {
+    const ct = await subtle().encrypt({ name: 'AES-GCM', iv: nonce, additionalData: aad }, key, plaintext);
+    return new Uint8Array(ct);
+}
+/** AES-256-GCM open. Throws (auth failure) if the ciphertext/tag/AAD do not verify. */
+export async function aeadOpen(key, nonce, ciphertext, aad) {
+    try {
+        const pt = await subtle().decrypt({ name: 'AES-GCM', iv: nonce, additionalData: aad }, key, ciphertext);
+        return new Uint8Array(pt);
+    }
+    catch {
+        throw new GoodVibesSdkError('Relay AEAD authentication failed (tampered or out-of-order frame).', {
+            category: 'bad_request',
+            source: 'transport',
+            recoverable: false,
+            hint: 'The end-to-end channel integrity check failed. The connection must be torn down.',
+        });
+    }
+}
+const TEXT_ENCODER = /* @__PURE__ */ new TextEncoder();
+const TEXT_DECODER = /* @__PURE__ */ new TextDecoder();
+/** UTF-8 encode a string to bytes. */
+export function encodeUtf8(text) {
+    return TEXT_ENCODER.encode(text);
+}
+/** UTF-8 decode bytes to a string. */
+export function decodeUtf8(bytes) {
+    return TEXT_DECODER.decode(bytes);
+}

package/dist/relay/handshake.d.ts

@@ -0,0 +1,43 @@
+import { type RelayKeyPair } from './crypto.js';
+/** Derived per-direction session keys plus the transcript binding. */
+export interface RelayHandshakeKeys {
+    /** AES-256-GCM key for client → daemon frames. */
+    readonly clientToDaemonKey: CryptoKey;
+    /** AES-256-GCM key for daemon → client frames. */
+    readonly daemonToClientKey: CryptoKey;
+    /** SHA-256 of the full handshake transcript (used as channel AAD prefix). */
+    readonly transcriptHash: Uint8Array<ArrayBuffer>;
+}
+/** Initiator (client) state carried between the two handshake messages. */
+export interface RelayInitiatorState {
+    readonly ephemeral: RelayKeyPair;
+    readonly ephemeralPublicRaw: Uint8Array<ArrayBuffer>;
+    readonly daemonStaticPublicRaw: Uint8Array<ArrayBuffer>;
+    readonly ridBytes: Uint8Array<ArrayBuffer>;
+}
+/**
+ * Begin the handshake. `daemonStaticPublicRaw` is the 65-byte pinned daemon key
+ * from the pairing payload; `ridBytes` are the UTF-8 bytes of the rendezvous id.
+ * Returns the state to keep and `message1` to send through the pipe.
+ */
+export declare function startInitiatorHandshake(daemonStaticPublicRaw: Uint8Array<ArrayBuffer>, ridBytes: Uint8Array<ArrayBuffer>): Promise<{
+    state: RelayInitiatorState;
+    message1: Uint8Array<ArrayBuffer>;
+}>;
+/**
+ * Complete the handshake on the initiator side. `message2` is the daemon's
+ * reply: its 65-byte ephemeral public key followed by an AEAD confirmation tag.
+ * Throws if the confirmation fails to verify (daemon impersonation / MITM).
+ */
+export declare function finishInitiatorHandshake(state: RelayInitiatorState, message2: Uint8Array<ArrayBuffer>): Promise<RelayHandshakeKeys>;
+/**
+ * Complete the handshake on the responder (daemon) side. `staticKeyPair` is the
+ * daemon's persistent identity key; `message1` is the initiator's ephemeral
+ * public key. Returns the derived channel keys and `message2` to send back
+ * (daemon ephemeral public key + AEAD confirmation tag).
+ */
+export declare function respondToHandshake(staticKeyPair: RelayKeyPair, ridBytes: Uint8Array<ArrayBuffer>, message1: Uint8Array<ArrayBuffer>): Promise<{
+    keys: RelayHandshakeKeys;
+    message2: Uint8Array<ArrayBuffer>;
+}>;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/relay/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/relay/handshake.ts"],"names":[],"mappings":"AAuBA,OAAO,EAcL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAQrB,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAC;IACtC,kDAAkD;IAClD,QAAQ,CAAC,iBAAiB,EAAE,SAAS,CAAC;IACtC,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAClD;AAED,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,kBAAkB,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACrD,QAAQ,CAAC,qBAAqB,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;IACxD,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAC5C;AA0BD;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,qBAAqB,EAAE,UAAU,CAAC,WAAW,CAAC,EAC9C,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,KAAK,EAAE,mBAAmB,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC,CAO5E;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,mBAAmB,EAC1B,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAmB7B;AAID;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,aAAa,EAAE,YAAY,EAC3B,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,EACjC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,GAChC,OAAO,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,QAAQ,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;CAAE,CAAC,CAc1E"}

package/dist/relay/handshake.js

@@ -0,0 +1,100 @@
+// relay/handshake.ts
+//
+// The end-to-end (E2E) authenticated key exchange that runs INSIDE a relay pipe
+// before any application byte flows. It follows the Noise "NK" shape: the
+// initiator (client/surface) already knows the responder's (daemon's) static
+// public key — it was pinned from the pairing payload — and stays anonymous
+// itself. This gives three properties that make the relay zero-knowledge:
+//
+//   * Daemon authentication: the derived keys mix a static-ephemeral DH
+//     (dh_se) against the daemon's static key. Only the real daemon holds that
+//     private key, so a malicious or curious relay that tried to sit in the
+//     middle cannot derive the session keys — its forged confirmation fails and
+//     the client tears the pipe down.
+//   * Forward secrecy: an ephemeral-ephemeral DH (dh_ee) means recording the
+//     ciphertext and later stealing the daemon's static key still does not
+//     reveal past sessions.
+//   * Confidentiality from the relay: every derived key comes from DH secrets
+//     the relay never sees. It only forwards the two public ephemerals and
+//     ciphertext.
+//
+// Primitives (all from crypto.ts / Web Crypto): ECDH P-256 for DH, HKDF-SHA-256
+// for key derivation, AES-256-GCM for the confirmation tag and the channel.
+import { aeadOpen, aeadSeal, concatBytes, deriveSharedSecret, encodeUtf8, exportRawPublicKey, generateEcdhKeyPair, hkdf, importAeadKey, importRawPublicKey, RELAY_NONCE_BYTES, RELAY_PUBLIC_KEY_BYTES, sha256, } from './crypto.js';
+import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
+const HANDSHAKE_LABEL = encodeUtf8('gv-relay-e2e/v1');
+const CONFIRM_PLAINTEXT = encodeUtf8('gv-relay-confirm');
+const ZERO_NONCE = new Uint8Array(RELAY_NONCE_BYTES);
+const CONFIRM_TAG_BYTES = CONFIRM_PLAINTEXT.length + 16; // GCM tag is 16 bytes
+async function buildTranscript(ridBytes, initiatorPub, responderPub, staticPub) {
+    return sha256(concatBytes(HANDSHAKE_LABEL, ridBytes, initiatorPub, responderPub, staticPub));
+}
+async function deriveKeys(dhEe, dhSe, transcriptHash) {
+    const ikm = concatBytes(dhEe, dhSe);
+    const material = await hkdf(ikm, transcriptHash, HANDSHAKE_LABEL, 96);
+    const clientToDaemonKey = await importAeadKey(material.subarray(0, 32));
+    const daemonToClientKey = await importAeadKey(material.subarray(32, 64));
+    const confirmKey = await importAeadKey(material.subarray(64, 96));
+    return { keys: { clientToDaemonKey, daemonToClientKey, transcriptHash }, confirmKey };
+}
+// ─── Initiator (client / surface) ─────────────────────────────────────────────
+/**
+ * Begin the handshake. `daemonStaticPublicRaw` is the 65-byte pinned daemon key
+ * from the pairing payload; `ridBytes` are the UTF-8 bytes of the rendezvous id.
+ * Returns the state to keep and `message1` to send through the pipe.
+ */
+export async function startInitiatorHandshake(daemonStaticPublicRaw, ridBytes) {
+    const ephemeral = await generateEcdhKeyPair();
+    const ephemeralPublicRaw = await exportRawPublicKey(ephemeral.publicKey);
+    return {
+        state: { ephemeral, ephemeralPublicRaw, daemonStaticPublicRaw, ridBytes },
+        message1: ephemeralPublicRaw,
+    };
+}
+/**
+ * Complete the handshake on the initiator side. `message2` is the daemon's
+ * reply: its 65-byte ephemeral public key followed by an AEAD confirmation tag.
+ * Throws if the confirmation fails to verify (daemon impersonation / MITM).
+ */
+export async function finishInitiatorHandshake(state, message2) {
+    if (message2.length !== RELAY_PUBLIC_KEY_BYTES + CONFIRM_TAG_BYTES) {
+        throw new GoodVibesSdkError('Malformed relay handshake response.', { category: 'protocol', source: 'transport', recoverable: false });
+    }
+    const responderPub = message2.subarray(0, RELAY_PUBLIC_KEY_BYTES);
+    const confirmTag = message2.subarray(RELAY_PUBLIC_KEY_BYTES);
+    const responderKey = await importRawPublicKey(responderPub);
+    const staticKey = await importRawPublicKey(state.daemonStaticPublicRaw);
+    const dhEe = await deriveSharedSecret(state.ephemeral.privateKey, responderKey);
+    const dhSe = await deriveSharedSecret(state.ephemeral.privateKey, staticKey);
+    const transcriptHash = await buildTranscript(state.ridBytes, state.ephemeralPublicRaw, responderPub, state.daemonStaticPublicRaw);
+    const { keys, confirmKey } = await deriveKeys(dhEe, dhSe, transcriptHash);
+    // Verifying the daemon's confirmation authenticates it: only the holder of
+    // the pinned static private key could have derived confirmKey.
+    const opened = await aeadOpen(confirmKey, ZERO_NONCE, confirmTag, transcriptHash);
+    if (opened.length !== CONFIRM_PLAINTEXT.length) {
+        throw new GoodVibesSdkError('Relay handshake confirmation mismatch.', { category: 'protocol', source: 'transport', recoverable: false });
+    }
+    return keys;
+}
+// ─── Responder (daemon) ───────────────────────────────────────────────────────
+/**
+ * Complete the handshake on the responder (daemon) side. `staticKeyPair` is the
+ * daemon's persistent identity key; `message1` is the initiator's ephemeral
+ * public key. Returns the derived channel keys and `message2` to send back
+ * (daemon ephemeral public key + AEAD confirmation tag).
+ */
+export async function respondToHandshake(staticKeyPair, ridBytes, message1) {
+    if (message1.length !== RELAY_PUBLIC_KEY_BYTES) {
+        throw new GoodVibesSdkError('Malformed relay handshake initiation.', { category: 'protocol', source: 'transport', recoverable: false });
+    }
+    const initiatorKey = await importRawPublicKey(message1);
+    const ephemeral = await generateEcdhKeyPair();
+    const ephemeralPublicRaw = await exportRawPublicKey(ephemeral.publicKey);
+    const staticPublicRaw = await exportRawPublicKey(staticKeyPair.publicKey);
+    const dhEe = await deriveSharedSecret(ephemeral.privateKey, initiatorKey);
+    const dhSe = await deriveSharedSecret(staticKeyPair.privateKey, initiatorKey);
+    const transcriptHash = await buildTranscript(ridBytes, message1, ephemeralPublicRaw, staticPublicRaw);
+    const { keys, confirmKey } = await deriveKeys(dhEe, dhSe, transcriptHash);
+    const confirmTag = await aeadSeal(confirmKey, ZERO_NONCE, CONFIRM_PLAINTEXT, transcriptHash);
+    return { keys, message2: concatBytes(ephemeralPublicRaw, confirmTag) };
+}

package/dist/relay/identity.d.ts

@@ -0,0 +1,19 @@
+import { type RelayKeyPair } from './crypto.js';
+/** Serializable form of a relay identity, safe to hand to a secret store. */
+export interface SerializedRelayIdentity {
+    /** Format version. */
+    readonly v: 1;
+    /** Full private key in JWK form (contains the `d` scalar — treat as a secret). */
+    readonly privateKeyJwk: JsonWebKey;
+    /** Raw uncompressed public key, base64url — safe to publish in pairing payloads. */
+    readonly publicKeyRaw: string;
+}
+/** Generate a fresh daemon relay identity key pair. */
+export declare function generateRelayIdentity(): Promise<RelayKeyPair>;
+/** Serialize an identity for durable storage (JWK private + raw public). */
+export declare function serializeRelayIdentity(pair: RelayKeyPair): Promise<SerializedRelayIdentity>;
+/** Reconstruct an identity key pair from its serialized form. */
+export declare function deserializeRelayIdentity(serialized: SerializedRelayIdentity): Promise<RelayKeyPair>;
+/** The base64url raw public key for a pairing payload. */
+export declare function relayIdentityPublicKeyBase64Url(pair: RelayKeyPair): Promise<string>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/relay/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/relay/identity.ts"],"names":[],"mappings":"AAcA,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAGrB,6EAA6E;AAC7E,MAAM,WAAW,uBAAuB;IACtC,sBAAsB;IACtB,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC;IACd,kFAAkF;IAClF,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC;IACnC,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAcD,uDAAuD;AACvD,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,YAAY,CAAC,CAEnE;AAED,4EAA4E;AAC5E,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAIjG;AAED,iEAAiE;AACjE,wBAAsB,wBAAwB,CAAC,UAAU,EAAE,uBAAuB,GAAG,OAAO,CAAC,YAAY,CAAC,CAYzG;AAED,0DAA0D;AAC1D,wBAAsB,+BAA+B,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAEzF"}

package/dist/relay/identity.js

@@ -0,0 +1,54 @@
+// relay/identity.ts
+//
+// The daemon's persistent relay identity key pair. The codebase had no existing
+// asymmetric daemon identity (identities were random UUIDs and shared-secret
+// tokens), so this mints one, modelled on the existing VapidManager pattern:
+// generate once, persist the whole key pair through the daemon's SecretsManager
+// (custody is the caller's responsibility — this module only (de)serializes),
+// and expose the public half for pinning in pairing payloads.
+//
+// The private key never leaves the daemon process. Its public key is what a
+// surface pins to authenticate the daemon during the E2E handshake, so the
+// security of the whole relay path rests on the pairing payload being delivered
+// out-of-band (QR / trusted LAN), exactly like an SSH host key fingerprint.
+import { exportRawPublicKey, generateEcdhKeyPair, toBase64Url, } from './crypto.js';
+import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
+function subtle() {
+    const c = globalThis.crypto;
+    if (!c || typeof c.subtle === 'undefined') {
+        throw new GoodVibesSdkError('Web Crypto (crypto.subtle) is unavailable in this runtime.', {
+            category: 'config',
+            source: 'transport',
+            recoverable: false,
+        });
+    }
+    return c.subtle;
+}
+/** Generate a fresh daemon relay identity key pair. */
+export async function generateRelayIdentity() {
+    return generateEcdhKeyPair();
+}
+/** Serialize an identity for durable storage (JWK private + raw public). */
+export async function serializeRelayIdentity(pair) {
+    const jwk = await subtle().exportKey('jwk', pair.privateKey);
+    const publicKeyRaw = toBase64Url(await exportRawPublicKey(pair.publicKey));
+    return { v: 1, privateKeyJwk: jwk, publicKeyRaw };
+}
+/** Reconstruct an identity key pair from its serialized form. */
+export async function deserializeRelayIdentity(serialized) {
+    if (serialized.v !== 1) {
+        throw new GoodVibesSdkError('Unsupported relay identity format version.', { category: 'bad_request', source: 'transport', recoverable: false });
+    }
+    const jwk = serialized.privateKeyJwk;
+    const privateKey = await subtle().importKey('jwk', jwk, { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']);
+    // Derive a public-only JWK by dropping the private scalar `d`.
+    const publicJwk = { ...jwk };
+    delete publicJwk['d'];
+    publicJwk.key_ops = [];
+    const publicKey = await subtle().importKey('jwk', publicJwk, { name: 'ECDH', namedCurve: 'P-256' }, true, []);
+    return { publicKey, privateKey };
+}
+/** The base64url raw public key for a pairing payload. */
+export async function relayIdentityPublicKeyBase64Url(pair) {
+    return toBase64Url(await exportRawPublicKey(pair.publicKey));
+}

package/dist/relay/index.d.ts

@@ -0,0 +1,8 @@
+export { RELAY_CURVE, RELAY_PUBLIC_KEY_BYTES, RELAY_NONCE_BYTES, RELAY_KEY_BYTES, randomBytes, toBase64Url, fromBase64Url, bytesEqual, concatBytes, encodeUtf8, decodeUtf8, generateEcdhKeyPair, exportRawPublicKey, importRawPublicKey, deriveSharedSecret, sha256, hkdf, importAeadKey, aeadSeal, aeadOpen, type RelayKeyPair, } from './crypto.js';
+export { RELAY_PROTOCOL_VERSION, RELAY_PIPE_ID_BYTES, encodeControlFrame, decodeControlFrame, framePipePayload, unframePipePayload, type RendezvousId, type PipeId, type RelayRole, type RelayErrorCode, type RelayControlFrame, type RelayRegisterFrame, type RelayRegisteredFrame, type RelayConnectFrame, type RelayConnectedFrame, type RelayPipeOpenFrame, type RelayPipeCloseFrame, type RelayErrorFrame, } from './protocol.js';
+export { startInitiatorHandshake, finishInitiatorHandshake, respondToHandshake, type RelayHandshakeKeys, type RelayInitiatorState, } from './handshake.js';
+export { RelaySecureChannel } from './secure-channel.js';
+export { generateRelayIdentity, serializeRelayIdentity, deserializeRelayIdentity, relayIdentityPublicKeyBase64Url, type SerializedRelayIdentity, } from './identity.js';
+export { PAIRING_SCHEME, createRelayPairingPayload, encodeRelayPairingString, decodeRelayPairingString, type RelayPairingPayload, } from './pairing.js';
+export { encodeTunnelFrame, decodeTunnelFrame, type TunnelHeader, type TunnelRequestHeader, type TunnelResponseHeader, type TunnelStreamOpenHeader, type TunnelStreamDataHeader, type TunnelStreamOverflowHeader, type TunnelStreamCloseHeader, } from './tunnel.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/relay/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/relay/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,eAAe,EACf,WAAW,EACX,WAAW,EACX,aAAa,EACb,UAAU,EACV,WAAW,EACX,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,MAAM,EACN,IAAI,EACJ,aAAa,EACb,QAAQ,EACR,QAAQ,EACR,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,uBAAuB,EACvB,wBAAwB,EACxB,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,+BAA+B,EAC/B,KAAK,uBAAuB,GAC7B,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,wBAAwB,EACxB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC"}

package/dist/relay/index.js

@@ -0,0 +1,14 @@
+// relay/index.ts
+//
+// Runtime-neutral building blocks for the zero-knowledge, self-hostable relay:
+// the hop protocol the relay operator can read, and the end-to-end crypto it
+// cannot. Consumed by the relay server (daemon-sdk), the client relay transport
+// (transport-realtime), and the daemon-side termination. Kept off the main
+// transport-core barrel so it stays an explicit, opt-in subpath import.
+export { RELAY_CURVE, RELAY_PUBLIC_KEY_BYTES, RELAY_NONCE_BYTES, RELAY_KEY_BYTES, randomBytes, toBase64Url, fromBase64Url, bytesEqual, concatBytes, encodeUtf8, decodeUtf8, generateEcdhKeyPair, exportRawPublicKey, importRawPublicKey, deriveSharedSecret, sha256, hkdf, importAeadKey, aeadSeal, aeadOpen, } from './crypto.js';
+export { RELAY_PROTOCOL_VERSION, RELAY_PIPE_ID_BYTES, encodeControlFrame, decodeControlFrame, framePipePayload, unframePipePayload, } from './protocol.js';
+export { startInitiatorHandshake, finishInitiatorHandshake, respondToHandshake, } from './handshake.js';
+export { RelaySecureChannel } from './secure-channel.js';
+export { generateRelayIdentity, serializeRelayIdentity, deserializeRelayIdentity, relayIdentityPublicKeyBase64Url, } from './identity.js';
+export { PAIRING_SCHEME, createRelayPairingPayload, encodeRelayPairingString, decodeRelayPairingString, } from './pairing.js';
+export { encodeTunnelFrame, decodeTunnelFrame, } from './tunnel.js';

package/dist/relay/pairing.d.ts

@@ -0,0 +1,28 @@
+import { type RendezvousId } from './protocol.js';
+/** Self-describing prefix so a scanner can recognize a relay pairing string. */
+export declare const PAIRING_SCHEME = "gvrelay1";
+/** The decoded contents of a pairing payload. */
+export interface RelayPairingPayload {
+    /** Pairing format / protocol version. */
+    readonly protocol: number;
+    /** Public relay URL the surface should dial (wss://…). */
+    readonly relayUrl: string;
+    /** Unguessable rendezvous id the daemon registered under. */
+    readonly rid: RendezvousId;
+    /** Daemon static public key (raw uncompressed P-256), base64url. */
+    readonly daemonPublicKey: string;
+    /** Optional human-facing label for the daemon (shown in the surface UI). */
+    readonly label?: string;
+}
+/** Mint a pairing payload object from its parts. */
+export declare function createRelayPairingPayload(input: {
+    readonly relayUrl: string;
+    readonly rid: RendezvousId;
+    readonly daemonPublicKey: string;
+    readonly label?: string;
+}): RelayPairingPayload;
+/** Encode a pairing payload to a compact, QR-friendly string. */
+export declare function encodeRelayPairingString(payload: RelayPairingPayload): string;
+/** Decode a pairing string back into a payload. Throws on malformed input. */
+export declare function decodeRelayPairingString(text: string): RelayPairingPayload;
+//# sourceMappingURL=pairing.d.ts.map

package/dist/relay/pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.d.ts","sourceRoot":"","sources":["../../src/relay/pairing.ts"],"names":[],"mappings":"AAeA,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAG1E,gFAAgF;AAChF,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAUD,oDAAoD;AACpD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,mBAAmB,CAQtB;AAED,iEAAiE;AACjE,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAS7E;AAED,8EAA8E;AAC9E,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAmC1E"}

package/dist/relay/pairing.js

@@ -0,0 +1,75 @@
+// relay/pairing.ts
+//
+// The pairing payload is the out-of-band bootstrap for a relay connection: it
+// carries everything a surface needs to reach a daemon and authenticate it —
+// the relay URL, the unguessable rendezvous id, and the daemon's pinned static
+// public key. It is deliberately compact and QR-encodable (base64url of a small
+// JSON object, prefixed with a self-describing scheme tag) because the intended
+// delivery is a QR code scanned from the daemon's screen, the same trust model
+// as pairing a phone by scanning a code.
+//
+// Delivering this payload over a trusted channel (QR on the same LAN, a copied
+// string) is what bootstraps trust. Whoever holds a valid pairing payload can
+// reach the daemon through the relay; treat it like a credential.
+import { fromBase64Url, toBase64Url, decodeUtf8, encodeUtf8 } from './crypto.js';
+import { RELAY_PROTOCOL_VERSION } from './protocol.js';
+import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
+/** Self-describing prefix so a scanner can recognize a relay pairing string. */
+export const PAIRING_SCHEME = 'gvrelay1';
+/** Mint a pairing payload object from its parts. */
+export function createRelayPairingPayload(input) {
+    return {
+        protocol: RELAY_PROTOCOL_VERSION,
+        relayUrl: input.relayUrl,
+        rid: input.rid,
+        daemonPublicKey: input.daemonPublicKey,
+        ...(input.label !== undefined ? { label: input.label } : {}),
+    };
+}
+/** Encode a pairing payload to a compact, QR-friendly string. */
+export function encodeRelayPairingString(payload) {
+    const wire = {
+        p: payload.protocol,
+        u: payload.relayUrl,
+        r: payload.rid,
+        k: payload.daemonPublicKey,
+        ...(payload.label !== undefined ? { l: payload.label } : {}),
+    };
+    return `${PAIRING_SCHEME}.${toBase64Url(encodeUtf8(JSON.stringify(wire)))}`;
+}
+/** Decode a pairing string back into a payload. Throws on malformed input. */
+export function decodeRelayPairingString(text) {
+    const trimmed = text.trim();
+    const dot = trimmed.indexOf('.');
+    if (dot < 0 || trimmed.slice(0, dot) !== PAIRING_SCHEME) {
+        throw new GoodVibesSdkError('Not a recognizable relay pairing string.', {
+            category: 'bad_request',
+            source: 'transport',
+            recoverable: false,
+            hint: `Expected a "${PAIRING_SCHEME}." prefixed pairing code.`,
+        });
+    }
+    let wire;
+    try {
+        wire = JSON.parse(decodeUtf8(fromBase64Url(trimmed.slice(dot + 1))));
+    }
+    catch {
+        throw new GoodVibesSdkError('Corrupt relay pairing string.', { category: 'bad_request', source: 'transport', recoverable: false });
+    }
+    if (typeof wire !== 'object' ||
+        wire === null ||
+        typeof wire.p !== 'number' ||
+        typeof wire.u !== 'string' ||
+        typeof wire.r !== 'string' ||
+        typeof wire.k !== 'string') {
+        throw new GoodVibesSdkError('Relay pairing string is missing required fields.', { category: 'bad_request', source: 'transport', recoverable: false });
+    }
+    const w = wire;
+    return {
+        protocol: w.p,
+        relayUrl: w.u,
+        rid: w.r,
+        daemonPublicKey: w.k,
+        ...(typeof w.l === 'string' ? { label: w.l } : {}),
+    };
+}

package/dist/relay/protocol.d.ts

@@ -0,0 +1,79 @@
+/** Wire protocol version. Bumped only on incompatible control-frame changes. */
+export declare const RELAY_PROTOCOL_VERSION = 1;
+/** Length in bytes of a multiplexed pipe identifier. */
+export declare const RELAY_PIPE_ID_BYTES = 16;
+/** Rendezvous id: unguessable string a daemon registers under and a client dials. */
+export type RendezvousId = string;
+/** Opaque multiplexed pipe id (one client<->daemon tunnel through the relay). */
+export type PipeId = string;
+/** Endpoint role on a relay connection. */
+export type RelayRole = 'daemon' | 'client';
+/** Machine-readable relay failure codes (surfaced to callers as honest errors). */
+export type RelayErrorCode = 'daemon-offline' | 'rid-taken' | 'capacity' | 'protocol-version' | 'malformed' | 'rate-limited' | 'unauthorized' | 'internal';
+/** Daemon → relay: claim a rendezvous id and accept client pipes for it. */
+export interface RelayRegisterFrame {
+    readonly t: 'register';
+    readonly role: 'daemon';
+    readonly protocol: number;
+    readonly rid: RendezvousId;
+}
+/** Relay → daemon: the rendezvous id is claimed; the daemon is now reachable. */
+export interface RelayRegisteredFrame {
+    readonly t: 'registered';
+    readonly rid: RendezvousId;
+}
+/** Client → relay: dial a rendezvous id. */
+export interface RelayConnectFrame {
+    readonly t: 'connect';
+    readonly role: 'client';
+    readonly protocol: number;
+    readonly rid: RendezvousId;
+}
+/** Relay → client: a pipe to the daemon is open; begin the E2E handshake. */
+export interface RelayConnectedFrame {
+    readonly t: 'connected';
+    readonly pipe: PipeId;
+}
+/** Relay → daemon: a new client pipe opened for this daemon's rendezvous id. */
+export interface RelayPipeOpenFrame {
+    readonly t: 'pipe-open';
+    readonly pipe: PipeId;
+}
+/** Relay → daemon/client: a pipe closed (peer gone or torn down). */
+export interface RelayPipeCloseFrame {
+    readonly t: 'pipe-close';
+    readonly pipe: PipeId;
+    readonly reason?: string;
+}
+/** Relay → endpoint: an error occurred. `code` is machine-readable. */
+export interface RelayErrorFrame {
+    readonly t: 'error';
+    readonly code: RelayErrorCode;
+    readonly message: string;
+    readonly pipe?: PipeId;
+}
+/** Any endpoint ↔ relay control frame. */
+export type RelayControlFrame = RelayRegisterFrame | RelayRegisteredFrame | RelayConnectFrame | RelayConnectedFrame | RelayPipeOpenFrame | RelayPipeCloseFrame | RelayErrorFrame;
+/** Serialize a control frame to a WebSocket text payload. */
+export declare function encodeControlFrame(frame: RelayControlFrame): string;
+/**
+ * Parse a WebSocket text payload into a control frame, or return null if it is
+ * not a recognizable, well-typed relay control frame. Callers treat null as a
+ * `malformed` protocol violation.
+ */
+export declare function decodeControlFrame(text: string): RelayControlFrame | null;
+/**
+ * Prefix an opaque ciphertext payload with its 16-byte pipe id, for the
+ * daemon<->relay leg where a single socket multiplexes many client pipes.
+ * `pipeIdBytes` is the raw 16-byte random pipe id; its base64url encoding is the
+ * `PipeId` string carried in control frames (the daemon correlates the two by
+ * base64url-encoding this prefix). The relay reads this prefix as routing
+ * metadata and never inspects the payload that follows.
+ */
+export declare function framePipePayload(pipeIdBytes: Uint8Array<ArrayBuffer>, payload: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+/** Split a daemon<->relay binary frame into its pipe-id prefix and opaque payload. */
+export declare function unframePipePayload(frame: Uint8Array<ArrayBuffer>): {
+    readonly pipeId: Uint8Array<ArrayBuffer>;
+    readonly payload: Uint8Array<ArrayBuffer>;
+} | null;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/relay/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/relay/protocol.ts"],"names":[],"mappings":"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"}

package/dist/relay/protocol.js

@@ -0,0 +1,109 @@
+// relay/protocol.ts
+//
+// The relay-hop wire protocol. This is the ONLY part of the traffic the relay
+// operator can read: connection-control frames (who is a daemon, who is a
+// client, which rendezvous id, which multiplexed pipe) plus opaque binary
+// payloads it forwards verbatim. The relay never sees the end-to-end keys or
+// plaintext — every binary payload is ciphertext produced by secure-channel.ts.
+//
+// Two message shapes travel over each relay WebSocket:
+//   1. Control frames  — JSON text messages (this module encodes/decodes them).
+//   2. Data frames     — binary messages: on the daemon<->relay leg they carry a
+//      16-byte pipe-id prefix (relay-hop routing metadata) followed by opaque
+//      ciphertext; on the client<->relay leg they are bare opaque ciphertext
+//      (a client owns exactly one pipe).
+//
+// Keeping the framing tiny and explicit is deliberate: a public relay instance
+// must be auditable at a glance for exactly what it can observe.
+/** Wire protocol version. Bumped only on incompatible control-frame changes. */
+export const RELAY_PROTOCOL_VERSION = 1;
+/** Length in bytes of a multiplexed pipe identifier. */
+export const RELAY_PIPE_ID_BYTES = 16;
+/** Serialize a control frame to a WebSocket text payload. */
+export function encodeControlFrame(frame) {
+    return JSON.stringify(frame);
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Parse a WebSocket text payload into a control frame, or return null if it is
+ * not a recognizable, well-typed relay control frame. Callers treat null as a
+ * `malformed` protocol violation.
+ */
+export function decodeControlFrame(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed) || typeof parsed['t'] !== 'string')
+        return null;
+    const t = parsed['t'];
+    switch (t) {
+        case 'register':
+            return isRid(parsed) && parsed['role'] === 'daemon' && typeof parsed['protocol'] === 'number'
+                ? { t, role: 'daemon', protocol: parsed['protocol'], rid: parsed['rid'] }
+                : null;
+        case 'connect':
+            return isRid(parsed) && parsed['role'] === 'client' && typeof parsed['protocol'] === 'number'
+                ? { t, role: 'client', protocol: parsed['protocol'], rid: parsed['rid'] }
+                : null;
+        case 'registered':
+            return isRid(parsed) ? { t, rid: parsed['rid'] } : null;
+        case 'connected':
+            return isPipe(parsed) ? { t, pipe: parsed['pipe'] } : null;
+        case 'pipe-open':
+            return isPipe(parsed) ? { t, pipe: parsed['pipe'] } : null;
+        case 'pipe-close':
+            return isPipe(parsed)
+                ? { t, pipe: parsed['pipe'], ...(typeof parsed['reason'] === 'string' ? { reason: parsed['reason'] } : {}) }
+                : null;
+        case 'error':
+            return typeof parsed['code'] === 'string' && typeof parsed['message'] === 'string'
+                ? {
+                    t,
+                    code: parsed['code'],
+                    message: parsed['message'],
+                    ...(typeof parsed['pipe'] === 'string' ? { pipe: parsed['pipe'] } : {}),
+                }
+                : null;
+        default:
+            return null;
+    }
+}
+function isRid(v) {
+    return typeof v['rid'] === 'string' && v['rid'].length > 0;
+}
+function isPipe(v) {
+    return typeof v['pipe'] === 'string' && v['pipe'].length > 0;
+}
+// ─── Data frames (binary, daemon<->relay leg carries a pipe-id prefix) ─────────
+/**
+ * Prefix an opaque ciphertext payload with its 16-byte pipe id, for the
+ * daemon<->relay leg where a single socket multiplexes many client pipes.
+ * `pipeIdBytes` is the raw 16-byte random pipe id; its base64url encoding is the
+ * `PipeId` string carried in control frames (the daemon correlates the two by
+ * base64url-encoding this prefix). The relay reads this prefix as routing
+ * metadata and never inspects the payload that follows.
+ */
+export function framePipePayload(pipeIdBytes, payload) {
+    if (pipeIdBytes.length !== RELAY_PIPE_ID_BYTES) {
+        throw new Error(`pipe id must be ${RELAY_PIPE_ID_BYTES} bytes`);
+    }
+    const out = new Uint8Array(RELAY_PIPE_ID_BYTES + payload.length);
+    out.set(pipeIdBytes, 0);
+    out.set(payload, RELAY_PIPE_ID_BYTES);
+    return out;
+}
+/** Split a daemon<->relay binary frame into its pipe-id prefix and opaque payload. */
+export function unframePipePayload(frame) {
+    if (frame.length < RELAY_PIPE_ID_BYTES)
+        return null;
+    return {
+        pipeId: frame.subarray(0, RELAY_PIPE_ID_BYTES),
+        payload: frame.subarray(RELAY_PIPE_ID_BYTES),
+    };
+}

package/dist/relay/secure-channel.d.ts

@@ -0,0 +1,21 @@
+import type { RelayHandshakeKeys } from './handshake.js';
+/**
+ * An authenticated, ordered channel between one client and one daemon,
+ * established from a completed handshake. `role` selects which directional key
+ * is used for sending vs receiving.
+ */
+export declare class RelaySecureChannel {
+    private readonly sendKey;
+    private readonly recvKey;
+    private readonly sendPrefix;
+    private readonly recvPrefix;
+    private readonly aad;
+    private sendCounter;
+    private lastRecvCounter;
+    constructor(keys: RelayHandshakeKeys, role: 'client' | 'daemon');
+    /** Seal an application payload into a wire frame (counter prefix + ciphertext). */
+    seal(plaintext: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
+    /** Open a received wire frame, enforcing strictly-increasing counters. */
+    open(frame: Uint8Array<ArrayBuffer>): Promise<Uint8Array<ArrayBuffer>>;
+}
+//# sourceMappingURL=secure-channel.d.ts.map

package/dist/relay/secure-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-channel.d.ts","sourceRoot":"","sources":["../../src/relay/secure-channel.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAoBzD;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA0B;IAC9C,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,eAAe,CAAM;gBAEjB,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,QAAQ,GAAG,QAAQ;IAe/D,mFAAmF;IAC7E,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAmBhF,0EAA0E;IACpE,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;CAkB7E"}

package/dist/relay/secure-channel.js

@@ -0,0 +1,97 @@
+// relay/secure-channel.ts
+//
+// The AEAD record layer that rides on top of a completed handshake. It turns the
+// two directional AES-256-GCM keys into an ordered, replay-resistant stream of
+// sealed frames. This is what actually makes the bytes the relay forwards
+// opaque: application payloads never touch the wire except as GCM ciphertext.
+//
+// Frame layout (all binary, forwarded verbatim by the relay):
+//   [ counter : 8 bytes big-endian ][ AES-256-GCM ciphertext+tag ]
+// The nonce is derived, never transmitted as free bytes: a 4-byte direction
+// prefix plus the 8-byte counter. Counters strictly increase per direction, so
+// a replayed or reordered frame is rejected — GCM never reuses a (key, nonce)
+// pair, which is the one catastrophic failure mode for GCM.
+import { aeadOpen, aeadSeal, RELAY_NONCE_BYTES } from './crypto.js';
+import { GoodVibesSdkError } from '@pellux/goodvibes-errors';
+const COUNTER_BYTES = 8;
+const DIRECTION_PREFIX_BYTES = RELAY_NONCE_BYTES - COUNTER_BYTES; // 4
+const PREFIX_CLIENT_TO_DAEMON = new Uint8Array([0x63, 0x32, 0x64, 0x00]); // "c2d\0"
+const PREFIX_DAEMON_TO_CLIENT = new Uint8Array([0x64, 0x32, 0x63, 0x00]); // "d2c\0"
+// Guard against counter exhaustion far below the 2^64 ceiling. In practice a
+// channel is torn down long before this; hitting it is a hard error, never a
+// silent wrap (which would reuse a nonce).
+const MAX_COUNTER = 0xffff_ffff_ffff_ff00;
+function nonceFor(prefix, counter) {
+    const nonce = new Uint8Array(RELAY_NONCE_BYTES);
+    nonce.set(prefix, 0);
+    const view = new DataView(nonce.buffer);
+    view.setBigUint64(DIRECTION_PREFIX_BYTES, BigInt(counter), false);
+    return nonce;
+}
+/**
+ * An authenticated, ordered channel between one client and one daemon,
+ * established from a completed handshake. `role` selects which directional key
+ * is used for sending vs receiving.
+ */
+export class RelaySecureChannel {
+    sendKey;
+    recvKey;
+    sendPrefix;
+    recvPrefix;
+    aad;
+    sendCounter = 0;
+    lastRecvCounter = -1;
+    constructor(keys, role) {
+        if (role === 'client') {
+            this.sendKey = keys.clientToDaemonKey;
+            this.recvKey = keys.daemonToClientKey;
+            this.sendPrefix = PREFIX_CLIENT_TO_DAEMON;
+            this.recvPrefix = PREFIX_DAEMON_TO_CLIENT;
+        }
+        else {
+            this.sendKey = keys.daemonToClientKey;
+            this.recvKey = keys.clientToDaemonKey;
+            this.sendPrefix = PREFIX_DAEMON_TO_CLIENT;
+            this.recvPrefix = PREFIX_CLIENT_TO_DAEMON;
+        }
+        this.aad = keys.transcriptHash;
+    }
+    /** Seal an application payload into a wire frame (counter prefix + ciphertext). */
+    async seal(plaintext) {
+        if (this.sendCounter >= MAX_COUNTER) {
+            throw new GoodVibesSdkError('Relay secure channel counter exhausted; reconnect required.', {
+                category: 'protocol',
+                source: 'transport',
+                recoverable: true,
+                hint: 'Tear down and re-establish the relay pipe to rotate keys.',
+            });
+        }
+        const counter = this.sendCounter;
+        this.sendCounter += 1;
+        const nonce = nonceFor(this.sendPrefix, counter);
+        const ciphertext = await aeadSeal(this.sendKey, nonce, plaintext, this.aad);
+        const frame = new Uint8Array(COUNTER_BYTES + ciphertext.length);
+        new DataView(frame.buffer).setBigUint64(0, BigInt(counter), false);
+        frame.set(ciphertext, COUNTER_BYTES);
+        return frame;
+    }
+    /** Open a received wire frame, enforcing strictly-increasing counters. */
+    async open(frame) {
+        if (frame.length <= COUNTER_BYTES) {
+            throw new GoodVibesSdkError('Truncated relay channel frame.', { category: 'protocol', source: 'transport', recoverable: false });
+        }
+        const counter = Number(new DataView(frame.buffer, frame.byteOffset, COUNTER_BYTES).getBigUint64(0, false));
+        if (counter <= this.lastRecvCounter) {
+            throw new GoodVibesSdkError('Relay channel frame replay or reorder detected.', {
+                category: 'protocol',
+                source: 'transport',
+                recoverable: false,
+                hint: 'Frame counter did not strictly increase; the channel integrity is compromised.',
+            });
+        }
+        const nonce = nonceFor(this.recvPrefix, counter);
+        const plaintext = await aeadOpen(this.recvKey, nonce, frame.subarray(COUNTER_BYTES), this.aad);
+        this.lastRecvCounter = counter;
+        return plaintext;
+    }
+}

package/dist/relay/tunnel.d.ts

@@ -0,0 +1,54 @@
+/** A tunneled HTTP request (surface → daemon). */
+export interface TunnelRequestHeader {
+    readonly id: string;
+    readonly kind: 'request';
+    readonly method: string;
+    /** Path + query only (no host); the daemon resolves it against its local base. */
+    readonly path: string;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+}
+/** A tunneled HTTP response (daemon → surface). */
+export interface TunnelResponseHeader {
+    readonly id: string;
+    readonly kind: 'response';
+    readonly status: number;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+}
+/** Open a live event subscription (surface → daemon). Shape mirrors a request. */
+export interface TunnelStreamOpenHeader {
+    readonly id: string;
+    readonly kind: 'stream-open';
+    readonly method: string;
+    readonly path: string;
+    readonly headers: ReadonlyArray<readonly [string, string]>;
+}
+/** One chunk of a subscription's event bytes (daemon → surface). */
+export interface TunnelStreamDataHeader {
+    readonly id: string;
+    readonly kind: 'stream-data';
+    /** Monotonic per-stream sequence number (gaps after an overflow notice are expected). */
+    readonly seq: number;
+}
+/** The bounded send buffer dropped chunks — an honest overflow notice (daemon → surface). */
+export interface TunnelStreamOverflowHeader {
+    readonly id: string;
+    readonly kind: 'stream-overflow';
+    /** How many chunks were dropped since the previous notice. */
+    readonly dropped: number;
+}
+/** Clean subscription teardown (either direction). */
+export interface TunnelStreamCloseHeader {
+    readonly id: string;
+    readonly kind: 'stream-close';
+    readonly reason?: string;
+}
+/** Any tunnel frame header. */
+export type TunnelHeader = TunnelRequestHeader | TunnelResponseHeader | TunnelStreamOpenHeader | TunnelStreamDataHeader | TunnelStreamOverflowHeader | TunnelStreamCloseHeader;
+/** Encode a tunnel header + body into a single frame for the secure channel. */
+export declare function encodeTunnelFrame(header: TunnelHeader, body: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
+/** Decode a tunnel frame into its header and raw body. Returns null if malformed. */
+export declare function decodeTunnelFrame(frame: Uint8Array<ArrayBuffer>): {
+    readonly header: TunnelHeader;
+    readonly body: Uint8Array<ArrayBuffer>;
+} | null;
+//# sourceMappingURL=tunnel.d.ts.map

package/dist/relay/tunnel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","sourceRoot":"","sources":["../../src/relay/tunnel.ts"],"names":[],"mappings":"AA2BA,kDAAkD;AAClD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D;AAED,mDAAmD;AACnD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D;AAED,kFAAkF;AAClF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5D;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,6FAA6F;AAC7F,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,+BAA+B;AAC/B,MAAM,MAAM,YAAY,GACpB,mBAAmB,GACnB,oBAAoB,GACpB,sBAAsB,GACtB,sBAAsB,GACtB,0BAA0B,GAC1B,uBAAuB,CAAC;AAE5B,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC,WAAW,CAAC,CAK9G;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,WAAW,CAAC,CAAA;CAAE,GAAG,IAAI,CAYlF"}

package/dist/relay/tunnel.js

@@ -0,0 +1,69 @@
+// relay/tunnel.ts
+//
+// The application framing that rides inside the E2E secure channel: whole HTTP
+// request/response pairs AND live event subscriptions, tunneled opaquely between
+// a surface and the daemon. Because the operator protocol is contract-driven
+// REST-over-JSON, tunneling HTTP is all it takes for the existing typed client
+// to work unchanged over the relay — the client's transport just swaps its
+// `fetch` for one that serializes the Request here, and the daemon replays it
+// against its own route dispatcher.
+//
+// Frame layout (this is what the secure channel seals, never the relay's
+// business):
+//   [ headerLen : 4 bytes BE ][ header JSON (UTF-8) ][ raw body bytes ]
+// Keeping the body as raw bytes (not base64 inside JSON) avoids inflating
+// payloads and keeps binary bodies exact.
+//
+// Streaming frames (a live subscription, e.g. Server-Sent Events) reuse the same
+// sealed-frame layout and multiplex over the same pipe by a shared `id`:
+//   - `stream-open`     surface → daemon: open a subscription (like `request`).
+//   - `stream-data`     daemon → surface: one chunk of the event source's bytes.
+//   - `stream-overflow` daemon → surface: the bounded send buffer dropped N
+//                       chunks — an honest notice, never a silent gap.
+//   - `stream-close`    either direction: clean teardown (surface unsubscribes,
+//                       or the daemon's source ended/errored).
+import { concatBytes, decodeUtf8, encodeUtf8 } from './crypto.js';
+/** Encode a tunnel header + body into a single frame for the secure channel. */
+export function encodeTunnelFrame(header, body) {
+    const headerBytes = encodeUtf8(JSON.stringify(header));
+    const prefix = new Uint8Array(4);
+    new DataView(prefix.buffer).setUint32(0, headerBytes.length, false);
+    return concatBytes(prefix, headerBytes, body);
+}
+/** Decode a tunnel frame into its header and raw body. Returns null if malformed. */
+export function decodeTunnelFrame(frame) {
+    if (frame.length < 4)
+        return null;
+    const headerLen = new DataView(frame.buffer, frame.byteOffset, 4).getUint32(0, false);
+    if (frame.length < 4 + headerLen)
+        return null;
+    let header;
+    try {
+        header = JSON.parse(decodeUtf8(frame.subarray(4, 4 + headerLen)));
+    }
+    catch {
+        return null;
+    }
+    if (!isTunnelHeader(header))
+        return null;
+    return { header, body: frame.subarray(4 + headerLen).slice() };
+}
+function isTunnelHeader(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (typeof v['id'] !== 'string')
+        return false;
+    if (v['kind'] === 'request' || v['kind'] === 'stream-open') {
+        return Array.isArray(v['headers']) && typeof v['method'] === 'string' && typeof v['path'] === 'string';
+    }
+    if (v['kind'] === 'response')
+        return Array.isArray(v['headers']) && typeof v['status'] === 'number';
+    if (v['kind'] === 'stream-data')
+        return typeof v['seq'] === 'number';
+    if (v['kind'] === 'stream-overflow')
+        return typeof v['dropped'] === 'number';
+    if (v['kind'] === 'stream-close')
+        return v['reason'] === undefined || typeof v['reason'] === 'string';
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-transport-core",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "engines": {
     "bun": "1.3.10",
     "node": ">=22.0.0"
@@ -42,6 +42,10 @@
       "types": "./dist/observer.d.ts",
       "import": "./dist/observer.js"
     },
+    "./relay": {
+      "types": "./dist/relay/index.d.ts",
+      "import": "./dist/relay/index.js"
+    },
     "./otel": {
       "types": "./dist/otel.d.ts",
       "import": "./dist/otel.js"
@@ -57,7 +61,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@pellux/goodvibes-errors": "1.6.1"
+    "@pellux/goodvibes-errors": "1.7.0"
   },
   "license": "MIT",
   "repository": {