@moxxy/e2e 0.27.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @moxxy/e2e
+
+End-to-end-encrypted secure channel for the **proxy** tunnel. It lets a phone and
+a locally-running agent talk through an untrusted relay (`<uuid>.proxy.moxxy.ai`)
+such that the relay sees only ciphertext it can neither read nor forge.
+
+## Why
+
+The relay terminates the outer TLS, so on its own it would see plaintext — the
+same position ngrok/cloudflared are in today. This package closes that gap with an
+application-layer handshake **inside** the tunnel, authenticated out-of-band via
+the fingerprint printed in the QR code.
+
+## Design
+
+- **Identity** — the agent holds a long-lived Ed25519 keypair. Its public key is
+  the identity: the QR carries `fp = base64url(pubkey)`, and the subdomain is
+  `uuid = base32(sha256(pubkey))`. The phone recomputes the expected uuid from the
+  pinned `fp`, so the subdomain is verifiable, not just trusted. No accounts.
+- **Handshake** — signed ephemeral ECDH (station-to-station-lite): the phone sends
+  an X25519 ephemeral; the agent replies with its own ephemeral, its identity key,
+  and an Ed25519 signature over the transcript. The phone pins the identity key
+  (constant-time) and verifies the signature, so a relay without the private key
+  cannot impersonate the agent. Ephemerals give forward secrecy.
+- **Framing** — XChaCha20-Poly1305 per message, with a strictly-increasing
+  sequence number bound as AAD, so the relay cannot replay, reorder, or tamper.
+  Directional keys prevent reflection.
+
+The phone is authenticated to the agent by the existing bearer token, which now
+travels encrypted inside this channel.
+
+## Entry points
+
+- `@moxxy/e2e` — pure JS (`@noble/*`), **no Node built-ins**, bundles under
+  Metro/React Native. Identity math, handshake, framing, `SecureChannel`.
+- `@moxxy/e2e/node` — `loadOrCreateIdentity()` (persists the secret key 0600 at
+  `~/.moxxy/proxy-identity.key`). Node only.
+
+> RN note: `@noble`'s randomness uses WebCrypto `getRandomValues`; an Expo app
+> must import a polyfill (`react-native-get-random-values`) at startup.

package/dist/bytes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Small, dependency-free byte helpers shared by the handshake/frame/identity
+ * modules. Encodings are hand-rolled (not `node:buffer`) so the `.` export stays
+ * RN-safe — React Native has no global `Buffer`.
+ */
+/** Concatenate byte arrays into one fresh `Uint8Array`. */
+export declare function concatBytes(...parts: readonly Uint8Array[]): Uint8Array;
+/**
+ * Constant-time equality for two byte arrays. Returns false immediately on a
+ * length mismatch (lengths here are public — fixed-size keys), then XOR-folds
+ * every byte so the compare time doesn't depend on where the first difference
+ * is. Used for the pinned-fingerprint check, where a timing leak would let an
+ * attacker probe the expected key byte by byte.
+ */
+export declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+/** UTF-8 encode without depending on `Buffer` (TextEncoder is in Node + RN). */
+export declare function utf8(s: string): Uint8Array;
+/** UTF-8 decode (TextDecoder is in Node + modern RN/Hermes). */
+export declare function utf8Decode(b: Uint8Array): string;
+/**
+ * Big-endian 8-byte encoding of a non-negative JS number. Written as two 32-bit
+ * halves to avoid `BigInt`/`setBigUint64` (Hermes/older RN engines are spotty);
+ * safe for any sequence counter below `Number.MAX_SAFE_INTEGER`.
+ */
+export declare function u64be(n: number): Uint8Array;
+/** Decode a big-endian 8-byte counter back to a JS number. */
+export declare function readU64be(b: Uint8Array, off?: number): number;
+export declare function base64urlEncode(bytes: Uint8Array): string;
+export declare function base64urlDecode(s: string): Uint8Array;
+export declare function base32Encode(bytes: Uint8Array): string;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAUvE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,OAAO,CAKvE;AAED,gFAAgF;AAChF,wBAAgB,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAE1C;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAgB3C;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,SAAI,GAAG,MAAM,CAYxD;AASD,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAYzD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,UAAU,CAmBrD;AAUD,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CActD"}

package/dist/bytes.js

@@ -0,0 +1,140 @@
+/**
+ * Small, dependency-free byte helpers shared by the handshake/frame/identity
+ * modules. Encodings are hand-rolled (not `node:buffer`) so the `.` export stays
+ * RN-safe — React Native has no global `Buffer`.
+ */
+/** Concatenate byte arrays into one fresh `Uint8Array`. */
+export function concatBytes(...parts) {
+    let total = 0;
+    for (const p of parts)
+        total += p.length;
+    const out = new Uint8Array(total);
+    let off = 0;
+    for (const p of parts) {
+        out.set(p, off);
+        off += p.length;
+    }
+    return out;
+}
+/**
+ * Constant-time equality for two byte arrays. Returns false immediately on a
+ * length mismatch (lengths here are public — fixed-size keys), then XOR-folds
+ * every byte so the compare time doesn't depend on where the first difference
+ * is. Used for the pinned-fingerprint check, where a timing leak would let an
+ * attacker probe the expected key byte by byte.
+ */
+export function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ b[i];
+    return diff === 0;
+}
+/** UTF-8 encode without depending on `Buffer` (TextEncoder is in Node + RN). */
+export function utf8(s) {
+    return new TextEncoder().encode(s);
+}
+/** UTF-8 decode (TextDecoder is in Node + modern RN/Hermes). */
+export function utf8Decode(b) {
+    return new TextDecoder().decode(b);
+}
+/**
+ * Big-endian 8-byte encoding of a non-negative JS number. Written as two 32-bit
+ * halves to avoid `BigInt`/`setBigUint64` (Hermes/older RN engines are spotty);
+ * safe for any sequence counter below `Number.MAX_SAFE_INTEGER`.
+ */
+export function u64be(n) {
+    if (!Number.isInteger(n) || n < 0 || n > Number.MAX_SAFE_INTEGER) {
+        throw new RangeError(`u64be: out of range: ${n}`);
+    }
+    const out = new Uint8Array(8);
+    const hi = Math.floor(n / 0x1_0000_0000);
+    const lo = n >>> 0;
+    out[0] = (hi >>> 24) & 0xff;
+    out[1] = (hi >>> 16) & 0xff;
+    out[2] = (hi >>> 8) & 0xff;
+    out[3] = hi & 0xff;
+    out[4] = (lo >>> 24) & 0xff;
+    out[5] = (lo >>> 16) & 0xff;
+    out[6] = (lo >>> 8) & 0xff;
+    out[7] = lo & 0xff;
+    return out;
+}
+/** Decode a big-endian 8-byte counter back to a JS number. */
+export function readU64be(b, off = 0) {
+    const hi = (b[off] << 24) |
+        (b[off + 1] << 16) |
+        (b[off + 2] << 8) |
+        b[off + 3];
+    const lo = (b[off + 4] << 24) |
+        (b[off + 5] << 16) |
+        (b[off + 6] << 8) |
+        b[off + 7];
+    return (hi >>> 0) * 0x1_0000_0000 + (lo >>> 0);
+}
+// ---------------------------------------------------------------------------
+// base64url (RFC 4648 §5, no padding) — used to carry the 32-byte Ed25519
+// public-key fingerprint in the QR/connect URL.
+// ---------------------------------------------------------------------------
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+export function base64urlEncode(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        out += B64URL[b0 >> 2];
+        out += B64URL[((b0 & 0x03) << 4) | (b1 >> 4)];
+        if (i + 1 < bytes.length)
+            out += B64URL[((b1 & 0x0f) << 2) | (b2 >> 6)];
+        if (i + 2 < bytes.length)
+            out += B64URL[b2 & 0x3f];
+    }
+    return out;
+}
+export function base64urlDecode(s) {
+    const lut = new Int16Array(128).fill(-1);
+    for (let i = 0; i < B64URL.length; i++)
+        lut[B64URL.charCodeAt(i)] = i;
+    const clean = s.trim();
+    const out = [];
+    let buf = 0;
+    let bits = 0;
+    for (const ch of clean) {
+        const code = ch.charCodeAt(0);
+        const v = code < 128 ? lut[code] : -1;
+        if (v === undefined || v < 0)
+            throw new Error('base64urlDecode: invalid character');
+        buf = (buf << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out.push((buf >> bits) & 0xff);
+        }
+    }
+    return Uint8Array.from(out);
+}
+// ---------------------------------------------------------------------------
+// base32 (RFC 4648 §6, lowercase, no padding) — used for the uuid subdomain
+// label. Lowercase a-z + 2-7 is a valid DNS label, and the alphabet avoids the
+// visually ambiguous 0/1/8/9.
+// ---------------------------------------------------------------------------
+const B32 = 'abcdefghijklmnopqrstuvwxyz234567';
+export function base32Encode(bytes) {
+    let out = '';
+    let buf = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buf = (buf << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            out += B32[(buf >> bits) & 0x1f];
+        }
+    }
+    if (bits > 0)
+        out += B32[(buf << (5 - bits)) & 0x1f];
+    return out;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,2DAA2D;AAC3D,MAAM,UAAU,WAAW,CAAC,GAAG,KAA4B;IACzD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,KAAK,IAAI,CAAC,CAAC,MAAM,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAChB,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,CAAa,EAAE,CAAa;IAC5D,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,IAAK,CAAC,CAAC,CAAC,CAAY,GAAI,CAAC,CAAC,CAAC,CAAY,CAAC;IAC/E,OAAO,IAAI,KAAK,CAAC,CAAC;AACpB,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,IAAI,CAAC,CAAS;IAC5B,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,CAAa;IACtC,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,CAAS;IAC7B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QACjE,MAAM,IAAI,UAAU,CAAC,wBAAwB,CAAC,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC;IACzC,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IACnB,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;IAC3B,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IACnB,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC;IAC3B,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IACnB,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,SAAS,CAAC,CAAa,EAAE,GAAG,GAAG,CAAC;IAC9C,MAAM,EAAE,GACN,CAAE,CAAC,CAAC,GAAG,CAAY,IAAI,EAAE,CAAC;QAC1B,CAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;QAC9B,CAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,CAAC;IACzB,MAAM,EAAE,GACN,CAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;QAC9B,CAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,EAAE,CAAC;QAC9B,CAAE,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC,GAAG,GAAG,CAAC,CAAY,CAAC;IACzB,OAAO,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,aAAa,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,8EAA8E;AAC9E,0EAA0E;AAC1E,gDAAgD;AAChD,8EAA8E;AAE9E,MAAM,MAAM,GAAG,kEAAkE,CAAC;AAElF,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,CAAW,CAAC;QAC9B,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,GAAG,IAAI,MAAM,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QACvB,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM;YAAE,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;QACxE,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM;YAAE,GAAG,IAAI,MAAM,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAS;IACvC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACzC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtE,MAAM,KAAK,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IACvB,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,CAAC,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACpF,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QACrB,IAAI,IAAI,CAAC,CAAC;QACV,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;YACd,IAAI,IAAI,CAAC,CAAC;YACV,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC9B,CAAC;AAED,8EAA8E;AAC9E,4EAA4E;AAC5E,+EAA+E;AAC/E,8BAA8B;AAC9B,8EAA8E;AAE9E,MAAM,GAAG,GAAG,kCAAkC,CAAC;AAE/C,MAAM,UAAU,YAAY,CAAC,KAAiB;IAC5C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC;QACxB,IAAI,IAAI,CAAC,CAAC;QACV,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;YACjB,IAAI,IAAI,CAAC,CAAC;YACV,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,IAAI,IAAI,GAAG,CAAC;QAAE,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACrD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/channel.d.ts

@@ -0,0 +1,27 @@
+import type { Identity } from './identity.js';
+/** A minimal duplex transport of discrete, ordered binary messages. */
+export interface MessageTransport {
+    /** Send one binary message. */
+    send(data: Uint8Array): void;
+    /** Register the (single) handler for inbound binary messages. */
+    onMessage(handler: (data: Uint8Array) => void): void;
+    /** Register the (single) handler for transport close. */
+    onClose(handler: () => void): void;
+    /** Close the underlying transport. */
+    close(): void;
+}
+export interface SecureChannel {
+    /** Encrypt and send one plaintext message. */
+    send(plaintext: Uint8Array): void;
+    /** Register the handler for decrypted inbound messages. Buffered until set. */
+    onMessage(handler: (plaintext: Uint8Array) => void): void;
+    /** Register a close handler (fires on transport close or fatal frame error). */
+    onClose(handler: () => void): void;
+    /** Tear down the channel and the underlying transport. */
+    close(): void;
+}
+/** Phone side: pin the agent's public key (from the QR `fp`) and connect. */
+export declare function connectInitiator(transport: MessageTransport, pinnedPublicKey: Uint8Array): Promise<SecureChannel>;
+/** Agent side: respond with a signed ServerHello and connect. */
+export declare function connectResponder(transport: MessageTransport, identity: Identity): Promise<SecureChannel>;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,+BAA+B;IAC/B,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IAC7B,iEAAiE;IACjE,SAAS,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IACrD,yDAAyD;IACzD,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACnC,sCAAsC;IACtC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,IAAI,CAAC;IAClC,+EAA+E;IAC/E,SAAS,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1D,gFAAgF;IAChF,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACnC,0DAA0D;IAC1D,KAAK,IAAI,IAAI,CAAC;CACf;AA4DD,6EAA6E;AAC7E,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,gBAAgB,EAC3B,eAAe,EAAE,UAAU,GAC1B,OAAO,CAAC,aAAa,CAAC,CAMxB;AAED,iEAAiE;AACjE,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,gBAAgB,EAC3B,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,aAAa,CAAC,CAKxB"}

package/dist/channel.js

@@ -0,0 +1,89 @@
+/**
+ * `SecureChannel` ties the handshake + framing to a concrete message transport
+ * (a WebSocket, or anything that delivers discrete binary messages in order).
+ *
+ * It runs the two-message handshake first, then transparently seals everything
+ * the caller `send()`s and opens everything that arrives, emitting plaintext via
+ * `onMessage`. Both ends use the same channel object; only the constructor
+ * (`connectInitiator` for the phone, `connectResponder` for the agent shim)
+ * differs. The returned promise resolves once the channel is encrypted and
+ * ready — any handshake failure (length, pin mismatch, bad signature, early
+ * close) rejects it, and the caller must abort the connection.
+ */
+import { FrameOpener, FrameSealer } from './frame.js';
+import { finishInitiator, respond, startInitiator, } from './handshake.js';
+function makeChannel(transport, keys) {
+    const sealer = new FrameSealer(keys.sendKey);
+    const opener = new FrameOpener(keys.recvKey);
+    let onMsg = null;
+    let onClose = null;
+    const backlog = [];
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        transport.close();
+        onClose?.();
+    };
+    transport.onMessage((data) => {
+        let pt;
+        try {
+            pt = opener.open(data);
+        }
+        catch {
+            // A frame that fails to open is a tampering/replay attempt on the wire —
+            // tear the whole channel down rather than skipping the message.
+            close();
+            return;
+        }
+        if (onMsg)
+            onMsg(pt);
+        else
+            backlog.push(pt);
+    });
+    transport.onClose(() => {
+        if (closed)
+            return;
+        closed = true;
+        onClose?.();
+    });
+    return {
+        send: (plaintext) => transport.send(sealer.seal(plaintext)),
+        onMessage: (handler) => {
+            onMsg = handler;
+            while (backlog.length > 0)
+                handler(backlog.shift());
+        },
+        onClose: (handler) => {
+            onClose = handler;
+        },
+        close,
+    };
+}
+/**
+ * Wait for exactly the next inbound transport message (the handshake reply),
+ * rejecting if the transport closes first. Used only during the handshake.
+ */
+function nextMessage(transport) {
+    return new Promise((resolve, reject) => {
+        transport.onMessage((data) => resolve(data));
+        transport.onClose(() => reject(new Error('proxy-e2e: transport closed during handshake')));
+    });
+}
+/** Phone side: pin the agent's public key (from the QR `fp`) and connect. */
+export async function connectInitiator(transport, pinnedPublicKey) {
+    const { clientHello, state } = startInitiator();
+    const reply = nextMessage(transport);
+    transport.send(clientHello);
+    const keys = finishInitiator(await reply, state, pinnedPublicKey);
+    return makeChannel(transport, keys);
+}
+/** Agent side: respond with a signed ServerHello and connect. */
+export async function connectResponder(transport, identity) {
+    const clientHello = await nextMessage(transport);
+    const { serverHello, keys } = respond(clientHello, identity);
+    transport.send(serverHello);
+    return makeChannel(transport, keys);
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

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

package/dist/frame.d.ts

@@ -0,0 +1,16 @@
+/** Seals outgoing plaintext into authenticated frames with a monotonic counter. */
+export declare class FrameSealer {
+    private readonly key;
+    private seq;
+    constructor(key: Uint8Array);
+    seal(plaintext: Uint8Array): Uint8Array;
+}
+/** Opens incoming frames, rejecting any whose sequence is not strictly increasing. */
+export declare class FrameOpener {
+    private readonly key;
+    /** Highest sequence accepted so far; -1 means "nothing yet". */
+    private lastSeq;
+    constructor(key: Uint8Array);
+    open(frame: Uint8Array): Uint8Array;
+}
+//# sourceMappingURL=frame.d.ts.map

package/dist/frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAqBA,mFAAmF;AACnF,qBAAa,WAAW;IAEV,OAAO,CAAC,QAAQ,CAAC,GAAG;IADhC,OAAO,CAAC,GAAG,CAAK;gBACa,GAAG,EAAE,UAAU;IAE5C,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU;CAOxC;AAED,sFAAsF;AACtF,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAM;gBACQ,GAAG,EAAE,UAAU;IAE5C,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;CAcpC"}

package/dist/frame.js

@@ -0,0 +1,59 @@
+/**
+ * Per-message AEAD framing for the post-handshake channel.
+ *
+ * Each frame: seq(8 BE) ‖ nonce(24) ‖ XChaCha20-Poly1305(key, nonce, aad=seq).
+ *
+ * The sequence number is bound as AAD and enforced strictly increasing by the
+ * receiver, so the relay (the adversary on the wire) cannot replay, reorder, or
+ * drop-and-resend a frame without the open failing. XChaCha's 192-bit random
+ * nonce means we never have to synchronise a nonce counter across the wire.
+ *
+ * A sealer/opener pair is one-directional; a SecureChannel keeps one of each,
+ * keyed by the directional keys from the handshake.
+ */
+import { xchacha20poly1305 } from '@noble/ciphers/chacha.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { concatBytes, readU64be, u64be } from './bytes.js';
+const SEQ = 8;
+const NONCE = 24;
+const HEADER = SEQ + NONCE; // 32
+/** Seals outgoing plaintext into authenticated frames with a monotonic counter. */
+export class FrameSealer {
+    key;
+    seq = 0;
+    constructor(key) {
+        this.key = key;
+    }
+    seal(plaintext) {
+        const seqBytes = u64be(this.seq);
+        const nonce = randomBytes(NONCE);
+        const ct = xchacha20poly1305(this.key, nonce, seqBytes).encrypt(plaintext);
+        this.seq += 1;
+        return concatBytes(seqBytes, nonce, ct);
+    }
+}
+/** Opens incoming frames, rejecting any whose sequence is not strictly increasing. */
+export class FrameOpener {
+    key;
+    /** Highest sequence accepted so far; -1 means "nothing yet". */
+    lastSeq = -1;
+    constructor(key) {
+        this.key = key;
+    }
+    open(frame) {
+        if (frame.length < HEADER)
+            throw new Error('proxy-e2e: frame too short');
+        const seqBytes = frame.slice(0, SEQ);
+        const seq = readU64be(seqBytes);
+        if (seq <= this.lastSeq) {
+            throw new Error(`proxy-e2e: out-of-order/replayed frame (seq ${seq} <= ${this.lastSeq})`);
+        }
+        const nonce = frame.slice(SEQ, HEADER);
+        const ct = frame.slice(HEADER);
+        // Throws if the tag (over ciphertext + seq AAD) doesn't verify.
+        const pt = xchacha20poly1305(this.key, nonce, seqBytes).decrypt(ct);
+        this.lastSeq = seq;
+        return pt;
+    }
+}
+//# sourceMappingURL=frame.js.map

package/dist/frame.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame.js","sourceRoot":"","sources":["../src/frame.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAE3D,MAAM,GAAG,GAAG,CAAC,CAAC;AACd,MAAM,KAAK,GAAG,EAAE,CAAC;AACjB,MAAM,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,CAAC,KAAK;AAEjC,mFAAmF;AACnF,MAAM,OAAO,WAAW;IAEO;IADrB,GAAG,GAAG,CAAC,CAAC;IAChB,YAA6B,GAAe;QAAf,QAAG,GAAH,GAAG,CAAY;IAAG,CAAC;IAEhD,IAAI,CAAC,SAAqB;QACxB,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjC,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACjC,MAAM,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC3E,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;QACd,OAAO,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,sFAAsF;AACtF,MAAM,OAAO,WAAW;IAGO;IAF7B,gEAAgE;IACxD,OAAO,GAAG,CAAC,CAAC,CAAC;IACrB,YAA6B,GAAe;QAAf,QAAG,GAAH,GAAG,CAAY;IAAG,CAAC;IAEhD,IAAI,CAAC,KAAiB;QACpB,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QACzE,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;QAChC,IAAI,GAAG,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,+CAA+C,GAAG,OAAO,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;QAC5F,CAAC;QACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACvC,MAAM,EAAE,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC/B,gEAAgE;QAChE,MAAM,EAAE,GAAG,iBAAiB,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,OAAO,EAAE,CAAC;IACZ,CAAC;CACF"}

package/dist/handshake.d.ts

@@ -0,0 +1,39 @@
+export declare const CLIENT_HELLO_LEN: number;
+export declare const SERVER_HELLO_LEN: number;
+/** Directional session keys, named from the owner's point of view. */
+export interface SessionKeys {
+    /** Key for frames this side SENDS. */
+    readonly sendKey: Uint8Array;
+    /** Key for frames this side RECEIVES. */
+    readonly recvKey: Uint8Array;
+}
+/** Opaque initiator state carried between {@link startInitiator} and {@link finishInitiator}. */
+export interface InitiatorState {
+    readonly ephSecret: Uint8Array;
+    readonly ephPublic: Uint8Array;
+    readonly clientNonce: Uint8Array;
+}
+/** Initiator (phone) step 1: produce the ClientHello and the state to finish later. */
+export declare function startInitiator(): {
+    clientHello: Uint8Array;
+    state: InitiatorState;
+};
+/**
+ * Responder (agent) step: consume the ClientHello, produce the signed
+ * ServerHello, and derive the session keys. Throws on a malformed ClientHello.
+ */
+export declare function respond(clientHello: Uint8Array, identity: {
+    secretKey: Uint8Array;
+    publicKey: Uint8Array;
+}): {
+    serverHello: Uint8Array;
+    keys: SessionKeys;
+};
+/**
+ * Initiator (phone) step 2: consume the ServerHello, verify the agent's pinned
+ * identity + signature, and derive the session keys. Throws on length mismatch,
+ * a fingerprint that doesn't match the pin, or an invalid signature — every
+ * failure means "this is not the agent the QR named", so the caller must abort.
+ */
+export declare function finishInitiator(serverHello: Uint8Array, state: InitiatorState, pinnedPublicKey: Uint8Array): SessionKeys;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../src/handshake.ts"],"names":[],"mappings":"AAmCA,eAAO,MAAM,gBAAgB,QAAmB,CAAC;AACjD,eAAO,MAAM,gBAAgB,QAAkC,CAAC;AAEhE,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;CAC9B;AAED,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;CAClC;AAgBD,uFAAuF;AACvF,wBAAgB,cAAc,IAAI;IAAE,WAAW,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAOnF;AAED;;;GAGG;AACH,wBAAgB,OAAO,CACrB,WAAW,EAAE,UAAU,EACvB,QAAQ,EAAE;IAAE,SAAS,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,UAAU,CAAA;CAAE,GACzD;IAAE,WAAW,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAkBhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,UAAU,EACvB,KAAK,EAAE,cAAc,EACrB,eAAe,EAAE,UAAU,GAC1B,WAAW,CAqBb"}

package/dist/handshake.js

@@ -0,0 +1,98 @@
+/**
+ * The proxy E2E handshake: an authenticated, forward-secret key agreement run
+ * as the first two messages inside the tunnel, before any session traffic.
+ *
+ * Shape (station-to-station-lite / signed ephemeral ECDH):
+ *   initiator (phone) ──ClientHello──▶ responder (agent)
+ *     ClientHello = ephI_pub(32) ‖ nC(16)
+ *   responder ──ServerHello──▶ initiator
+ *     ServerHello = ephR_pub(32) ‖ nS(16) ‖ idPub(32) ‖ sig(64)
+ *     sig = Ed25519.sign(transcript, idSecret)
+ *     transcript = LABEL ‖ ephI_pub ‖ ephR_pub ‖ nC ‖ nS
+ *
+ * The initiator pins `idPub` against the QR fingerprint (constant-time) and
+ * verifies `sig` over the transcript — so a relay (or anyone without the private
+ * key) cannot impersonate the agent. Both sides derive the session keys from the
+ * X25519 shared secret via HKDF; the ephemeral keys give forward secrecy. Keys
+ * are split per direction to prevent reflection.
+ *
+ * The phone is NOT authenticated by key here — it authenticates with the bearer
+ * token at the app layer (unchanged), which now travels encrypted inside this
+ * channel.
+ */
+import { x25519 } from '@noble/curves/ed25519.js';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { randomBytes } from '@noble/hashes/utils.js';
+import { concatBytes, constantTimeEqual, utf8 } from './bytes.js';
+import { sign, verify } from './identity.js';
+const LABEL = utf8('moxxy/proxy-e2e/v1');
+const HS_NONCE = 16;
+const X_PUB = 32;
+const ID_PUB = 32;
+const SIG = 64;
+export const CLIENT_HELLO_LEN = X_PUB + HS_NONCE; // 48
+export const SERVER_HELLO_LEN = X_PUB + HS_NONCE + ID_PUB + SIG; // 144
+function transcript(ephIPub, ephRPub, nC, nS) {
+    return concatBytes(LABEL, ephIPub, ephRPub, nC, nS);
+}
+function deriveKeys(shared, nC, nS) {
+    const okm = hkdf(sha256, shared, concatBytes(nC, nS), LABEL, 64);
+    return { i2r: okm.slice(0, 32), r2i: okm.slice(32, 64) };
+}
+/** Initiator (phone) step 1: produce the ClientHello and the state to finish later. */
+export function startInitiator() {
+    const { secretKey: ephSecret, publicKey: ephPublic } = x25519.keygen();
+    const clientNonce = randomBytes(HS_NONCE);
+    return {
+        clientHello: concatBytes(ephPublic, clientNonce),
+        state: { ephSecret, ephPublic, clientNonce },
+    };
+}
+/**
+ * Responder (agent) step: consume the ClientHello, produce the signed
+ * ServerHello, and derive the session keys. Throws on a malformed ClientHello.
+ */
+export function respond(clientHello, identity) {
+    if (clientHello.length !== CLIENT_HELLO_LEN) {
+        throw new Error(`proxy-e2e: bad ClientHello length ${clientHello.length}`);
+    }
+    const ephIPub = clientHello.slice(0, X_PUB);
+    const nC = clientHello.slice(X_PUB, X_PUB + HS_NONCE);
+    const { secretKey: ephSecret, publicKey: ephRPub } = x25519.keygen();
+    const nS = randomBytes(HS_NONCE);
+    const sig = sign(transcript(ephIPub, ephRPub, nC, nS), identity.secretKey);
+    const shared = x25519.getSharedSecret(ephSecret, ephIPub);
+    const { i2r, r2i } = deriveKeys(shared, nC, nS);
+    return {
+        serverHello: concatBytes(ephRPub, nS, identity.publicKey, sig),
+        keys: { sendKey: r2i, recvKey: i2r },
+    };
+}
+/**
+ * Initiator (phone) step 2: consume the ServerHello, verify the agent's pinned
+ * identity + signature, and derive the session keys. Throws on length mismatch,
+ * a fingerprint that doesn't match the pin, or an invalid signature — every
+ * failure means "this is not the agent the QR named", so the caller must abort.
+ */
+export function finishInitiator(serverHello, state, pinnedPublicKey) {
+    if (serverHello.length !== SERVER_HELLO_LEN) {
+        throw new Error(`proxy-e2e: bad ServerHello length ${serverHello.length}`);
+    }
+    let off = 0;
+    const ephRPub = serverHello.slice(off, (off += X_PUB));
+    const nS = serverHello.slice(off, (off += HS_NONCE));
+    const idPub = serverHello.slice(off, (off += ID_PUB));
+    const sig = serverHello.slice(off, (off += SIG));
+    if (!constantTimeEqual(idPub, pinnedPublicKey)) {
+        throw new Error('proxy-e2e: identity key does not match pinned fingerprint (possible spoofing)');
+    }
+    const t = transcript(state.ephPublic, ephRPub, state.clientNonce, nS);
+    if (!verify(sig, t, idPub)) {
+        throw new Error('proxy-e2e: handshake signature invalid (possible spoofing)');
+    }
+    const shared = x25519.getSharedSecret(state.ephSecret, ephRPub);
+    const { i2r, r2i } = deriveKeys(shared, state.clientNonce, nS);
+    return { sendKey: i2r, recvKey: r2i };
+}
+//# sourceMappingURL=handshake.js.map

package/dist/handshake.js.map

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

package/dist/identity.d.ts

@@ -0,0 +1,23 @@
+/** Number of base32 chars in the uuid label (16 × 5 = 80 bits of preimage strength). */
+export declare const UUID_LABEL_LENGTH = 16;
+export interface Identity {
+    /** Ed25519 secret key (32 bytes). Never leaves the agent. */
+    readonly secretKey: Uint8Array;
+    /** Ed25519 public key (32 bytes). The identity. */
+    readonly publicKey: Uint8Array;
+}
+/** Generate a fresh agent identity. */
+export declare function generateIdentity(): Identity;
+/** Recover the public key from a stored secret key. */
+export declare function publicKeyFromSecret(secretKey: Uint8Array): Uint8Array;
+/** The QR-carried fingerprint: base64url of the raw 32-byte public key. */
+export declare function fingerprint(publicKey: Uint8Array): string;
+/** Parse a fingerprint string back to the 32-byte public key (throws if malformed). */
+export declare function publicKeyFromFingerprint(fp: string): Uint8Array;
+/** Derive the stable uuid subdomain label from a public key. */
+export declare function deriveUuid(publicKey: Uint8Array): string;
+/** Sign a message with the identity's secret key (Ed25519). */
+export declare function sign(message: Uint8Array, secretKey: Uint8Array): Uint8Array;
+/** Verify an Ed25519 signature against a public key. */
+export declare function verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array): boolean;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAkBA,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;IAC/B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,UAAU,CAAC;CAChC;AAED,uCAAuC;AACvC,wBAAgB,gBAAgB,IAAI,QAAQ,CAG3C;AAED,uDAAuD;AACvD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAErE;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAEzD;AAED,uFAAuF;AACvF,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,CAI/D;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,SAAS,EAAE,UAAU,GAAG,MAAM,CAExD;AAED,+DAA+D;AAC/D,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,UAAU,CAE3E;AAED,wDAAwD;AACxD,wBAAgB,MAAM,CACpB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,GACpB,OAAO,CAMT"}