@interocitor/core 0.0.0-beta.2

package/dist/handshake/channel.js

@@ -0,0 +1,246 @@
+/**
+ * interocitor/handshake/channel
+ *
+ * Ephemeral ECDH-P256 key exchange over the shared cloud backend (relay).
+ * No extra server required — the backend the mesh already uses is the relay.
+ *
+ * ## Roles (determined by QR intent, not by which device is "bigger")
+ *
+ *   Generator  — device that created the QR (has the ECDH private key).
+ *                Receives credentials from the scanner via the relay.
+ *
+ *   Scanner    — device that scanned the QR (has generatorPub from the QR).
+ *                Pushes credentials to the generator via the relay.
+ *
+ * ## Protocol
+ *
+ *   intent = "share"  →  Generator already has credentials.
+ *                         Scanner is joining → Scanner reads relay → gets credentials.
+ *                         (Scanner pushes scannerPub so Generator can encrypt for it.)
+ *
+ *   intent = "join"   →  Generator wants credentials.
+ *                         Scanner has credentials → Scanner writes to relay.
+ *                         (Generator just waits and reads.)
+ *
+ * Both intents use identical wire mechanics; only which side writes
+ * credentials differs.
+ *
+ * ## Wire sequence (both intents)
+ *
+ *   Scanner                                  Relay                    Generator
+ *   ───────                                  ─────                    ─────────
+ *   [has generatorPub from QR]
+ *   generate ephemeral keypair (Es, es)
+ *   sharedSecret = ECDH(generatorPub, es)
+ *   wrappingKey  = HKDF(sharedSecret)
+ *                                  write scanner-pub.json (Es) →
+ *                                                                  read scanner-pub.json
+ *                                                                  sharedSecret = ECDH(Es, eg)
+ *                                                                  wrappingKey  = HKDF(sharedSecret)
+ *
+ *   ── if intent == "join": Generator has credentials, Scanner receives ──
+ *                                                                  encrypt {remotePath, meshKey}
+ *                                  ← write credentials.json
+ *   read credentials.json
+ *   decrypt → remotePath, meshKey
+ *
+ *   ── if intent == "share": Scanner has credentials, Generator receives ──
+ *   encrypt {remotePath, meshKey}
+ *                                  write credentials.json →
+ *                                                                  read credentials.json
+ *                                                                  decrypt → remotePath, meshKey
+ *
+ *   [whoever received credentials deletes relay files — best-effort]
+ *
+ * ## Relay files (scoped by handshakeId)
+ *
+ *   {relayBase}/scanner-pub.json   — scanner's ephemeral ECDH public key
+ *   {relayBase}/credentials.json   — encrypted {remotePath, meshKey?}
+ *
+ * ## Security
+ *
+ *   wrappingKey is derived from ECDH(generatorPub, scannerPriv)
+ *              = ECDH(scannerPub, generatorPriv)   (commutativity)
+ *
+ *   Anyone with cloud access sees scanner-pub.json and credentials.json.
+ *   Without generatorPriv (which never leaves the generating device) they
+ *   cannot derive wrappingKey and cannot decrypt credentials.json.
+ *   generatorPriv is only accessible to someone who physically held the
+ *   device that generated the QR.
+ */
+// ─── ECDH / crypto helpers ───────────────────────────────────────────
+const ECDH_PARAMS = { name: 'ECDH', namedCurve: 'P-256' };
+const HKDF_PARAMS = { name: 'HKDF', hash: 'SHA-256' };
+const WRAP_ALGO = { name: 'AES-GCM', length: 256 };
+const IV_LEN = 12;
+const HKDF_INFO = 'interocitor-handshake-v1';
+function uint8ToB64url(b) {
+    let s = '';
+    for (let i = 0; i < b.length; i++)
+        s += String.fromCodePoint(b[i]);
+    return btoa(s).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+function b64urlToUint8(s) {
+    const p = s.replaceAll('-', '+').replaceAll('_', '/');
+    const pad = (4 - (p.length % 4)) % 4;
+    const bin = atob(p + '='.repeat(pad));
+    const b = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        b[i] = bin.charCodeAt(i);
+    return b;
+}
+function toBuffer(b) {
+    return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+}
+export async function generateECDHKeypair() {
+    return crypto.subtle.generateKey(ECDH_PARAMS, true, ['deriveKey', 'deriveBits']);
+}
+export async function exportECDHPublicKey(key) {
+    return uint8ToB64url(new Uint8Array(await crypto.subtle.exportKey('spki', key)));
+}
+export async function importECDHPublicKey(spki) {
+    return crypto.subtle.importKey('spki', toBuffer(b64urlToUint8(spki)), ECDH_PARAMS, true, []);
+}
+async function deriveWrappingKey(myPriv, peerPub) {
+    const bits = await crypto.subtle.deriveBits({ name: 'ECDH', public: peerPub }, myPriv, 256);
+    const ikm = await crypto.subtle.importKey('raw', bits, 'HKDF', false, ['deriveKey']);
+    const info = new TextEncoder().encode(HKDF_INFO);
+    return crypto.subtle.deriveKey({ ...HKDF_PARAMS, salt: new ArrayBuffer(32), info: toBuffer(info) }, ikm, WRAP_ALGO, false, ['encrypt', 'decrypt']);
+}
+async function encryptCredentials(wrappingKey, creds) {
+    const payload = { remotePath: creds.remotePath };
+    if (creds.passphrase !== null) {
+        payload.passphrase = creds.passphrase;
+    }
+    const pt = new TextEncoder().encode(JSON.stringify(payload));
+    const ivRaw = crypto.getRandomValues(new Uint8Array(IV_LEN));
+    const iv = toBuffer(ivRaw);
+    const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, wrappingKey, pt);
+    const env = { v: 1, iv: uint8ToB64url(ivRaw), ct: uint8ToB64url(new Uint8Array(ct)) };
+    return JSON.stringify(env);
+}
+async function decryptCredentials(wrappingKey, envelope) {
+    const { v, iv, ct } = JSON.parse(envelope);
+    if (v !== 1)
+        throw new Error(`Unknown handshake envelope version: ${v}`);
+    const ivBytes = b64urlToUint8(iv);
+    const ctBytes = b64urlToUint8(ct);
+    const pt = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: toBuffer(ivBytes) }, wrappingKey, toBuffer(ctBytes));
+    const raw = JSON.parse(new TextDecoder().decode(pt));
+    return { remotePath: raw.remotePath, passphrase: raw.passphrase ?? null };
+}
+// ─── Relay paths ─────────────────────────────────────────────────────
+function relayPaths(handshakeId, relayBase) {
+    const base = `${relayBase}/handshake/${handshakeId}`;
+    return {
+        scannerPub: `${base}/scanner-pub.json`,
+        credentials: `${base}/credentials.json`,
+    };
+}
+// ─── Polling ─────────────────────────────────────────────────────────
+async function pollFor(fn, intervalMs, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const r = await fn();
+        if (r !== null)
+            return r;
+        await new Promise((resolve) => {
+            setTimeout(resolve, intervalMs);
+        });
+    }
+    throw new Error(`Handshake timed out after ${timeoutMs}ms`);
+}
+// ─── Relay I/O ───────────────────────────────────────────────────────
+async function relayRead(adapter, path) {
+    try {
+        const bytes = await adapter.readFile(path);
+        return new TextDecoder().decode(bytes);
+    }
+    catch {
+        return null;
+    }
+}
+async function relayWrite(adapter, path, data) {
+    await adapter.writeFile(path, data);
+}
+async function relayCleanup(adapter, paths) {
+    await Promise.allSettled([
+        adapter.deleteFile(paths.scannerPub),
+        adapter.deleteFile(paths.credentials),
+    ]);
+}
+export async function createGeneratorSession() {
+    const keypair = await generateECDHKeypair();
+    const generatorPub = await exportECDHPublicKey(keypair.publicKey);
+    return {
+        generatorPub,
+        async complete(adapter, handshakeId, relayBase, intent, ownCredentials, options = {}) {
+            const { pollIntervalMs = 2000, timeoutMs = 120000 } = options;
+            const paths = relayPaths(handshakeId, relayBase);
+            // Wait for the scanner to upload their ephemeral public key.
+            const scannerPubSpki = await pollFor(async () => {
+                const data = await relayRead(adapter, paths.scannerPub);
+                if (!data)
+                    return null;
+                return JSON.parse(data).pub ?? null;
+            }, pollIntervalMs, timeoutMs);
+            const scannerPublicKey = await importECDHPublicKey(scannerPubSpki);
+            const wrappingKey = await deriveWrappingKey(keypair.privateKey, scannerPublicKey);
+            if (intent === 'share') {
+                // Generator has credentials → encrypt and push them for the scanner.
+                if (!ownCredentials)
+                    throw new Error('intent=share requires ownCredentials');
+                const envelope = await encryptCredentials(wrappingKey, ownCredentials);
+                await relayWrite(adapter, paths.credentials, envelope);
+                // Generator does not clean up — scanner deletes after reading.
+                return null; // Generator already has credentials; nothing new to return.
+            }
+            // intent === 'join': scanner will push credentials to us.
+            const envelope = await pollFor(() => relayRead(adapter, paths.credentials), pollIntervalMs, timeoutMs);
+            const credentials = await decryptCredentials(wrappingKey, envelope);
+            // Clean up relay files after reading.
+            relayCleanup(adapter, paths).catch(() => { });
+            return credentials;
+        },
+    };
+}
+// ─── Scanner side ────────────────────────────────────────────────────
+/**
+ * Run the scanner side of the handshake.
+ *
+ * intent = "share":  generator has credentials and will push them →
+ *                    scanner uploads scannerPub, waits for credentials,
+ *                    decrypts and returns them.
+ *
+ * intent = "join":   generator wants credentials → scanner uploads
+ *                    scannerPub, then writes encrypted credentials,
+ *                    resolves with null (scanner already has them).
+ */
+export async function runScannerHandshake(adapter, payload, ownCredentials, relayBase, options = {}) {
+    const { intent, handshakeId, generatorPub } = payload;
+    const { pollIntervalMs = 2000, timeoutMs = 120000 } = options;
+    const paths = relayPaths(handshakeId, relayBase);
+    // Generate our ephemeral keypair.
+    const keypair = await generateECDHKeypair();
+    const scannerPub = await exportECDHPublicKey(keypair.publicKey);
+    // Upload our public key — this signals the generator we are here.
+    await relayWrite(adapter, paths.scannerPub, JSON.stringify({ pub: scannerPub }));
+    // Derive the shared wrapping key using the generator's public key from the QR.
+    const generatorPublicKey = await importECDHPublicKey(generatorPub);
+    const wrappingKey = await deriveWrappingKey(keypair.privateKey, generatorPublicKey);
+    if (intent === 'share') {
+        // Generator will push credentials → wait and decrypt.
+        const envelope = await pollFor(() => relayRead(adapter, paths.credentials), pollIntervalMs, timeoutMs);
+        const credentials = await decryptCredentials(wrappingKey, envelope);
+        relayCleanup(adapter, paths).catch(() => { });
+        return credentials;
+    }
+    // intent === 'join': we push credentials to the generator.
+    if (!ownCredentials)
+        throw new Error('intent=join requires scanner to have ownCredentials');
+    const envelope = await encryptCredentials(wrappingKey, ownCredentials);
+    await relayWrite(adapter, paths.credentials, envelope);
+    // Scanner already has credentials; nothing new to return.
+    return null;
+}
+//# sourceMappingURL=channel.js.map

package/dist/handshake/channel.js.map

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

package/dist/handshake/index.d.ts

@@ -0,0 +1,213 @@
+/**
+ * interocitor/handshake
+ *
+ * Secure device pairing via QR code.
+ *
+ * Both devices run an interocitor instance with a preconfigured backend
+ * adapter. Neither device needs to know the mesh `remotePath` or master
+ * key beforehand — everything is bootstrapped through the handshake.
+ *
+ * ## Two intents
+ *
+ * A QR code is generated with one of two intents, declared by the
+ * **generator** (the device showing the QR):
+ *
+ *   "share" — I have mesh credentials. Scan me and I will push them to
+ *             you through the relay.
+ *
+ *   "join"  — I want to join a mesh. Scan me and push your credentials
+ *             to me through the relay.
+ *
+ * The **scanner** (the device that reads the QR) always does the
+ * opposite: it receives when the generator shares, and it pushes when
+ * the generator joins.
+ *
+ * ## Which device shows the QR?
+ *
+ *   Desktop already in mesh, Mobile wants to join
+ *     → Desktop generates "share" QR, Mobile scans → Mobile joins.
+ *
+ *   Mobile wants to join, shows QR to Desktop that is already in mesh
+ *     → Mobile generates "join" QR, Desktop scans → Mobile joins.
+ *
+ * ## QR payload — two pieces
+ *
+ *   Cloud piece  →  handshakeId
+ *                   Scopes two relay files on the shared backend.
+ *                   Visible in the cloud but useless without the key.
+ *
+ *   Eyes-only    →  generatorPub (ephemeral ECDH-P256 public key)
+ *                   The scanner derives a wrapping key from it via ECDH.
+ *                   Only someone who physically saw the QR can do this.
+ *
+ * remotePath and meshKey are NEVER in the QR. They travel through the
+ * relay, encrypted with the ECDH-derived wrapping key.
+ *
+ * ## Usage
+ *
+ * ### Generate a "share" QR (device already in mesh)
+ *
+ * ```ts
+ * import { generateShareQR } from 'interocitor';
+ *
+ * const { qrEncoded, pairUrl, complete } = await generateShareQR({
+ *   adapter,
+ *   relayBase:  '/Interocitor',   // any path on the shared backend
+ *   remotePath: '/Interocitor/team-alpha',
+ *   meshKey,                       // CryptoKey | null
+ *   pairBaseUrl: 'https://app.example.com/pair',
+ * });
+ *
+ * renderQR(qrEncoded);   // show QR on screen
+ * await complete();      // wait for scanner to pick up credentials
+ * ```
+ *
+ * ### Generate a "join" QR (device wanting to join)
+ *
+ * ```ts
+ * import { generateJoinQR } from 'interocitor';
+ *
+ * const { qrEncoded, pairUrl, credentials } = await generateJoinQR({
+ *   adapter,
+ *   relayBase: '/Interocitor',
+ *   pairBaseUrl: 'https://app.example.com/pair',
+ * });
+ *
+ * renderQR(qrEncoded);
+ * const { remotePath, meshKey } = await credentials;
+ * // configure engine and connect
+ * ```
+ *
+ * ### Handle a scanned QR / opened pair URL
+ *
+ * ```ts
+ * import { handleScannedQR, parseQRFromUrl } from 'interocitor';
+ *
+ * const payload = parseQRFromUrl(window.location.hash);
+ * // or: const payload = decodeQRPayload(rawQRString);
+ *
+ * const result = await handleScannedQR({
+ *   adapter,
+ *   relayBase: '/Interocitor',
+ *   payload,
+ *   // required when payload.intent === 'join' (scanner must have credentials):
+ *   ownCredentials: { remotePath, meshKey },
+ * });
+ *
+ * if (result) {
+ *   // intent was 'share' — we received credentials
+ *   const { remotePath, meshKey } = result;
+ *   if (meshKey) engine.setEncryptionKey(meshKey);
+ *   await engine.connect(remotePath);
+ * }
+ * // intent was 'join' — we pushed credentials, nothing to do on scanner side
+ * ```
+ */
+import type { StorageAdapter } from '../core/types.ts';
+import { type HandshakeQRPayload } from './qr.ts';
+import { type HandshakeCredentials } from './channel.ts';
+export { encodeQRPayload, decodeQRPayload, buildPairUrl, parseQRFromUrl, } from './qr.ts';
+export type { HandshakeQRPayload, HandshakeIntent } from './qr.ts';
+export { generateECDHKeypair, exportECDHPublicKey, importECDHPublicKey, createGeneratorSession, runScannerHandshake, } from './channel.ts';
+export type { HandshakeCredentials, GeneratorSession } from './channel.ts';
+export interface GenerateShareQROptions {
+    /** Storage adapter connected to the shared backend. */
+    adapter: StorageAdapter;
+    /**
+     * Base path on the backend used for relay files.
+     * Relay files are written under `{relayBase}/handshake/{handshakeId}/`.
+     * Typically the same root path your mesh uses.
+     */
+    relayBase: string;
+    /** The mesh cloud folder path to share with the joiner. */
+    remotePath: string;
+    /** Base58 passphrase for the mesh encryption key, or null for unencrypted. */
+    passphrase: string | null;
+    /** Base URL for the pair link embedded in the QR payload (optional). */
+    pairBaseUrl?: string;
+    /** Polling interval while waiting for the scanner (ms, default 2000). */
+    pollIntervalMs?: number;
+    /** Give up after this long (ms, default 120000). */
+    timeoutMs?: number;
+}
+export interface GenerateShareQRResult {
+    /** The raw QR payload object. */
+    qrPayload: HandshakeQRPayload;
+    /** Compact base64url string — pass to any QR library. */
+    qrEncoded: string;
+    /** Full pair URL with payload in fragment. null if pairBaseUrl not provided. */
+    pairUrl: string | null;
+    /**
+     * Wait for the scanner to pick up the credentials.
+     * Resolves when the scanner has read the relay and cleaned up.
+     */
+    complete(): Promise<void>;
+}
+/**
+ * Generate a "share" QR code. Call this on a device that already belongs
+ * to a mesh and wants to invite another device.
+ */
+export declare function generateShareQR(options: GenerateShareQROptions): Promise<GenerateShareQRResult>;
+export interface GenerateJoinQROptions {
+    /** Storage adapter connected to the shared backend. */
+    adapter: StorageAdapter;
+    /**
+     * Base path on the backend used for relay files.
+     * Must match the relayBase used by the scanning device.
+     */
+    relayBase: string;
+    /** Base URL for the pair link embedded in the QR payload (optional). */
+    pairBaseUrl?: string;
+    /** Polling interval while waiting for credentials (ms, default 2000). */
+    pollIntervalMs?: number;
+    /** Give up after this long (ms, default 120000). */
+    timeoutMs?: number;
+}
+export interface GenerateJoinQRResult {
+    /** The raw QR payload object. */
+    qrPayload: HandshakeQRPayload;
+    /** Compact base64url string — pass to any QR library. */
+    qrEncoded: string;
+    /** Full pair URL with payload in fragment. null if pairBaseUrl not provided. */
+    pairUrl: string | null;
+    /**
+     * Resolves with the received credentials once the scanner has pushed them.
+     * Configure your engine with these and connect.
+     */
+    credentials: Promise<HandshakeCredentials>;
+}
+/**
+ * Generate a "join" QR code. Call this on a device that wants to join a mesh
+ * but does not yet have credentials. Show this QR to a device that is already
+ * in the mesh; that device scans it and pushes credentials.
+ */
+export declare function generateJoinQR(options: GenerateJoinQROptions): Promise<GenerateJoinQRResult>;
+export interface HandleScannedQROptions {
+    /** Storage adapter connected to the shared backend. */
+    adapter: StorageAdapter;
+    /**
+     * Base path on the backend used for relay files.
+     * Must match the relayBase used by the generating device.
+     */
+    relayBase: string;
+    /** Payload decoded from the scanned QR or opened pair URL. */
+    payload: HandshakeQRPayload;
+    /**
+     * The scanner's own mesh credentials.
+     * Required when payload.intent === 'join' (you must push credentials).
+     * Ignored when payload.intent === 'share' (you will receive credentials).
+     */
+    ownCredentials?: HandshakeCredentials;
+    /** Polling interval (ms, default 2000). */
+    pollIntervalMs?: number;
+    /** Give up after this long (ms, default 120000). */
+    timeoutMs?: number;
+}
+/**
+ * Handle a scanned QR code or opened pair URL.
+ *
+ * Returns the received credentials when intent === 'share' (null otherwise,
+ * because the scanner already has credentials when intent === 'join').
+ */
+export declare function handleScannedQR(options: HandleScannedQROptions): Promise<HandshakeCredentials | null>;
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/handshake/index.js

@@ -0,0 +1,182 @@
+/**
+ * interocitor/handshake
+ *
+ * Secure device pairing via QR code.
+ *
+ * Both devices run an interocitor instance with a preconfigured backend
+ * adapter. Neither device needs to know the mesh `remotePath` or master
+ * key beforehand — everything is bootstrapped through the handshake.
+ *
+ * ## Two intents
+ *
+ * A QR code is generated with one of two intents, declared by the
+ * **generator** (the device showing the QR):
+ *
+ *   "share" — I have mesh credentials. Scan me and I will push them to
+ *             you through the relay.
+ *
+ *   "join"  — I want to join a mesh. Scan me and push your credentials
+ *             to me through the relay.
+ *
+ * The **scanner** (the device that reads the QR) always does the
+ * opposite: it receives when the generator shares, and it pushes when
+ * the generator joins.
+ *
+ * ## Which device shows the QR?
+ *
+ *   Desktop already in mesh, Mobile wants to join
+ *     → Desktop generates "share" QR, Mobile scans → Mobile joins.
+ *
+ *   Mobile wants to join, shows QR to Desktop that is already in mesh
+ *     → Mobile generates "join" QR, Desktop scans → Mobile joins.
+ *
+ * ## QR payload — two pieces
+ *
+ *   Cloud piece  →  handshakeId
+ *                   Scopes two relay files on the shared backend.
+ *                   Visible in the cloud but useless without the key.
+ *
+ *   Eyes-only    →  generatorPub (ephemeral ECDH-P256 public key)
+ *                   The scanner derives a wrapping key from it via ECDH.
+ *                   Only someone who physically saw the QR can do this.
+ *
+ * remotePath and meshKey are NEVER in the QR. They travel through the
+ * relay, encrypted with the ECDH-derived wrapping key.
+ *
+ * ## Usage
+ *
+ * ### Generate a "share" QR (device already in mesh)
+ *
+ * ```ts
+ * import { generateShareQR } from 'interocitor';
+ *
+ * const { qrEncoded, pairUrl, complete } = await generateShareQR({
+ *   adapter,
+ *   relayBase:  '/Interocitor',   // any path on the shared backend
+ *   remotePath: '/Interocitor/team-alpha',
+ *   meshKey,                       // CryptoKey | null
+ *   pairBaseUrl: 'https://app.example.com/pair',
+ * });
+ *
+ * renderQR(qrEncoded);   // show QR on screen
+ * await complete();      // wait for scanner to pick up credentials
+ * ```
+ *
+ * ### Generate a "join" QR (device wanting to join)
+ *
+ * ```ts
+ * import { generateJoinQR } from 'interocitor';
+ *
+ * const { qrEncoded, pairUrl, credentials } = await generateJoinQR({
+ *   adapter,
+ *   relayBase: '/Interocitor',
+ *   pairBaseUrl: 'https://app.example.com/pair',
+ * });
+ *
+ * renderQR(qrEncoded);
+ * const { remotePath, meshKey } = await credentials;
+ * // configure engine and connect
+ * ```
+ *
+ * ### Handle a scanned QR / opened pair URL
+ *
+ * ```ts
+ * import { handleScannedQR, parseQRFromUrl } from 'interocitor';
+ *
+ * const payload = parseQRFromUrl(window.location.hash);
+ * // or: const payload = decodeQRPayload(rawQRString);
+ *
+ * const result = await handleScannedQR({
+ *   adapter,
+ *   relayBase: '/Interocitor',
+ *   payload,
+ *   // required when payload.intent === 'join' (scanner must have credentials):
+ *   ownCredentials: { remotePath, meshKey },
+ * });
+ *
+ * if (result) {
+ *   // intent was 'share' — we received credentials
+ *   const { remotePath, meshKey } = result;
+ *   if (meshKey) engine.setEncryptionKey(meshKey);
+ *   await engine.connect(remotePath);
+ * }
+ * // intent was 'join' — we pushed credentials, nothing to do on scanner side
+ * ```
+ */
+import { encodeQRPayload, buildPairUrl, } from "./qr.js";
+import { createGeneratorSession, runScannerHandshake, } from "./channel.js";
+export { encodeQRPayload, decodeQRPayload, buildPairUrl, parseQRFromUrl, } from "./qr.js";
+export { generateECDHKeypair, exportECDHPublicKey, importECDHPublicKey, createGeneratorSession, runScannerHandshake, } from "./channel.js";
+// ─── Helpers ─────────────────────────────────────────────────────────
+function generateHandshakeId() {
+    const b = crypto.getRandomValues(new Uint8Array(12));
+    return Array.from(b, x => x.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Generate a "share" QR code. Call this on a device that already belongs
+ * to a mesh and wants to invite another device.
+ */
+export async function generateShareQR(options) {
+    const { adapter, relayBase, remotePath, passphrase, pairBaseUrl, pollIntervalMs, timeoutMs } = options;
+    const session = await createGeneratorSession();
+    const handshakeId = generateHandshakeId();
+    const adapterConfig = adapter.getHandshakeConfig?.();
+    const qrPayload = {
+        intent: 'share',
+        handshakeId,
+        generatorPub: session.generatorPub,
+        ...(adapterConfig !== undefined && { adapterConfig }),
+    };
+    return {
+        qrPayload,
+        qrEncoded: encodeQRPayload(qrPayload),
+        pairUrl: pairBaseUrl ? buildPairUrl(pairBaseUrl, qrPayload) : null,
+        async complete() {
+            await session.complete(adapter, handshakeId, relayBase, 'share', { remotePath, passphrase }, { pollIntervalMs, timeoutMs });
+        },
+    };
+}
+/**
+ * Generate a "join" QR code. Call this on a device that wants to join a mesh
+ * but does not yet have credentials. Show this QR to a device that is already
+ * in the mesh; that device scans it and pushes credentials.
+ */
+export async function generateJoinQR(options) {
+    const { adapter, relayBase, pairBaseUrl, pollIntervalMs, timeoutMs } = options;
+    const session = await createGeneratorSession();
+    const handshakeId = generateHandshakeId();
+    const adapterConfig = adapter.getHandshakeConfig?.();
+    const qrPayload = {
+        intent: 'join',
+        handshakeId,
+        generatorPub: session.generatorPub,
+        ...(adapterConfig !== undefined && { adapterConfig }),
+    };
+    const credentialsPromise = session.complete(adapter, handshakeId, relayBase, 'join', null, // generator doesn't have credentials — it wants them
+    { pollIntervalMs, timeoutMs }).then(result => {
+        if (!result)
+            throw new Error('join handshake produced no credentials');
+        return result;
+    });
+    return {
+        qrPayload,
+        qrEncoded: encodeQRPayload(qrPayload),
+        pairUrl: pairBaseUrl ? buildPairUrl(pairBaseUrl, qrPayload) : null,
+        credentials: credentialsPromise,
+    };
+}
+/**
+ * Handle a scanned QR code or opened pair URL.
+ *
+ * Returns the received credentials when intent === 'share' (null otherwise,
+ * because the scanner already has credentials when intent === 'join').
+ */
+export async function handleScannedQR(options) {
+    const { adapter, relayBase, payload, ownCredentials, pollIntervalMs, timeoutMs } = options;
+    if (payload.intent === 'join' && !ownCredentials) {
+        throw new Error('handleScannedQR: ownCredentials required when scanning a "join" QR ' +
+            '(the scanner must push credentials to the generator)');
+    }
+    return runScannerHandshake(adapter, payload, ownCredentials ?? null, relayBase, { pollIntervalMs, timeoutMs });
+}
+//# sourceMappingURL=index.js.map

package/dist/handshake/index.js.map

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