replica-bridge 0.0.0-stage → 0.2.0

package/src/protocol.js

@@ -0,0 +1,262 @@
+// Shared protocol for replica-relay, replica-bridge and the test phone (Relay/PROTOCOL.md).
+// Everything here is plain Node: X25519, HKDF-SHA256, ChaCha20-Poly1305 and HMAC-SHA256 match CryptoKit's
+// Curve25519.KeyAgreement, HKDF<SHA256>, ChaChaPoly and HMAC<SHA256>, so the Swift side can follow the same steps.
+import crypto from "node:crypto";
+
+export const PROTOCOL = "chatreplica-relay-v1";
+export const LINK_SCHEME = "chatreplica:";
+/** Pairing codes avoid 0/O, 1/I/L and U so they survive being read aloud or typed. */
+export const CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTVWXYZ";
+export const CODE_LENGTH = 8;
+export const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export const b64url = (data            )         => Buffer.from(data).toString("base64url");
+export const fromB64url = (text        )         => Buffer.from(text, "base64url");
+export const sha256 = (...parts              )         => {
+  const hash = crypto.createHash("sha256");
+  for (const part of parts) hash.update(part);
+  return hash.digest();
+};
+export const randomToken = ()         => b64url(crypto.randomBytes(32));
+export const tokenHash = (token        )         => sha256(Buffer.from(token, "utf8")).toString("hex");
+
+export function randomCode()         {
+  let code = "";
+  while (code.length < CODE_LENGTH) {
+    const byte = crypto.randomBytes(1)[0];
+    if (byte < 240) code += CODE_ALPHABET[byte % CODE_ALPHABET.length]; // 240 = 8 * 30, no modulo bias
+  }
+  return code;
+}
+
+/** Uppercases and drops spaces and dashes, so "abcd-2345" and "ABCD 2345" find the same pairing. */
+export const normalizeCode = (code        )         => code.toUpperCase().replace(/[\s-]/g, "");
+export const formatCode = (code        )         => `${code.slice(0, 4)}-${code.slice(4)}`;
+
+// MARK: - X25519 keys as raw 32-byte values (what CryptoKit's rawRepresentation holds)
+
+const PKCS8_X25519_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+const SPKI_X25519_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+
+                                                                  
+
+export function generateKeyPair()          {
+  return keyPairFromPrivate(crypto.randomBytes(32));
+}
+
+export function keyPairFromPrivate(privateKey        )          {
+  const key = crypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, privateKey]), format: "der", type: "pkcs8" });
+  const spki = crypto.createPublicKey(key).export({ format: "der", type: "spki" });
+  return { privateKey, publicKey: Buffer.from(spki.subarray(SPKI_X25519_PREFIX.length)) };
+}
+
+export function dh(privateKey        , publicKey        )         {
+  if (publicKey.length !== 32) throw new Error("X25519 public keys are 32 bytes");
+  return crypto.diffieHellman({
+    privateKey: crypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, privateKey]), format: "der", type: "pkcs8" }),
+    publicKey: crypto.createPublicKey({ key: Buffer.concat([SPKI_X25519_PREFIX, publicKey]), format: "der", type: "spki" }),
+  });
+}
+
+// MARK: - Pairing
+
+                              
+                
+                 
+                        
+               
+                 
+                    
+ 
+
+/** chatreplica://pair?v=1&r=<relay URL>&h=<hostId>&k=<host key>&c=<code>&s=<secret>&n=<host name> */
+export function buildPairingLink(link             )         {
+  const params = new URLSearchParams({ v: "1", r: link.relay, h: link.hostId, k: b64url(link.hostPublicKey), c: link.code, s: b64url(link.secret) });
+  if (link.hostName) params.set("n", link.hostName);
+  return `chatreplica://pair?${params}`;
+}
+
+export function parsePairingLink(text        )              {
+  const url = new URL(text.trim());
+  if (url.protocol !== LINK_SCHEME || url.hostname !== "pair") throw new Error("not a chatreplica://pair link");
+  const get = (name        ) => {
+    const value = url.searchParams.get(name);
+    if (!value) throw new Error(`pairing link is missing ${name}`);
+    return value;
+  };
+  if (get("v") !== "1") throw new Error("unsupported pairing link version");
+  const relay = new URL(get("r"));
+  if (relay.protocol !== "https:" && relay.protocol !== "http:") throw new Error("relay must be an http(s) URL");
+  const hostPublicKey = fromB64url(get("k"));
+  const secret = fromB64url(get("s"));
+  if (hostPublicKey.length !== 32 || secret.length !== 32) throw new Error("pairing link key or secret has the wrong length");
+  return { relay: get("r"), hostId: get("h"), hostPublicKey, code: normalizeCode(get("c")), secret, hostName: url.searchParams.get("n") ?? undefined };
+}
+
+/** What the relay keeps instead of the secret, so it cannot compute the proof itself. */
+export const secretHash = (secret        )         => b64url(sha256(secret));
+
+/** HMAC-SHA256(secret, PROTOCOL "|pair|" code devicePublicKey): proves the phone saw the QR code. */
+export function pairingProof(secret        , code        , devicePublicKey        )         {
+  return crypto.createHmac("sha256", secret).update(`${PROTOCOL}|pair|${normalizeCode(code)}`).update(devicePublicKey).digest();
+}
+
+export function verifyPairingProof(secret        , code        , devicePublicKey        , proof        )          {
+  const expected = pairingProof(secret, code, devicePublicKey);
+  return proof.length === expected.length && crypto.timingSafeEqual(proof, expected);
+}
+
+/** Six digits both screens show when pairing by typed code, where the phone got the host key from the relay. */
+export function safetyCode(hostPublicKey        , devicePublicKey        )         {
+  const digest = sha256(Buffer.from(`${PROTOCOL}|safety`), hostPublicKey, devicePublicKey);
+  return String(digest.readUInt32BE(0) % 1_000_000).padStart(6, "0");
+}
+
+// MARK: - Session handshake and frames
+
+                              
+                                                        
+                     
+                       
+                       
+ 
+
+/**
+ * Both static keys and both ephemeral keys go into the transcript; the shared secret mixes ee, es and se, so only the
+ * paired phone (device static key) talking to the real host (host static key) derives the same keys.
+ */
+export function deriveSessionKeys(args   
+                                                                                           
+                                     
+ )              {
+  const transcript = sha256(Buffer.from(PROTOCOL), args.hostStatic, args.deviceStatic, args.deviceEphemeral, args.hostEphemeral);
+  const okm = Buffer.from(crypto.hkdfSync("sha256", Buffer.concat([args.ee, args.es, args.se]), transcript, Buffer.from(`${PROTOCOL}|keys`), 64));
+  return { transcript, deviceToHost: okm.subarray(0, 32), hostToDevice: okm.subarray(32, 64) };
+}
+
+/** The phone's side: ee = DH(De, He), es = DH(De, Hs), se = DH(Ds, He). */
+export function deviceSessionKeys(device         , deviceEphemeral         , hostStatic        , hostEphemeral        )              {
+  return deriveSessionKeys({
+    hostStatic, deviceStatic: device.publicKey, deviceEphemeral: deviceEphemeral.publicKey, hostEphemeral,
+    ee: dh(deviceEphemeral.privateKey, hostEphemeral), es: dh(deviceEphemeral.privateKey, hostStatic), se: dh(device.privateKey, hostEphemeral),
+  });
+}
+
+/** The host's side of the same three DH values. */
+export function hostSessionKeys(host         , hostEphemeral         , deviceStatic        , deviceEphemeral        )              {
+  return deriveSessionKeys({
+    hostStatic: host.publicKey, deviceStatic, deviceEphemeral, hostEphemeral: hostEphemeral.publicKey,
+    ee: dh(hostEphemeral.privateKey, deviceEphemeral), es: dh(host.privateKey, deviceEphemeral), se: dh(hostEphemeral.privateKey, deviceStatic),
+  });
+}
+
+/** 96-bit nonce: four zero bytes, then the frame counter as a big-endian UInt64. */
+export function frameNonce(counter        )         {
+  const nonce = Buffer.alloc(12);
+  nonce.writeBigUInt64BE(BigInt(counter), 4);
+  return nonce;
+}
+
+export function seal(key        , counter        , aad        , plaintext        )         {
+  const cipher = crypto.createCipheriv("chacha20-poly1305", key, frameNonce(counter), { authTagLength: 16 });
+  cipher.setAAD(aad, { plaintextLength: plaintext.length });
+  return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+
+export function open(key        , counter        , aad        , sealed        )         {
+  if (sealed.length < 16) throw new Error("frame too short");
+  const decipher = crypto.createDecipheriv("chacha20-poly1305", key, frameNonce(counter), { authTagLength: 16 });
+  decipher.setAAD(aad, { plaintextLength: sealed.length - 16 });
+  decipher.setAuthTag(sealed.subarray(sealed.length - 16));
+  return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - 16)), decipher.final()]);
+}
+
+/** One direction of an established session: counts frames and refuses gaps or replays. */
+export class FrameCipher {
+          sendCounter = 0;
+          receiveCounter = 0;
+                   sendKey        ;
+                   receiveKey        ;
+                   aad        ;
+  constructor(sendKey        , receiveKey        , aad        ) { this.sendKey = sendKey; this.receiveKey = receiveKey; this.aad = aad; }
+
+  sealFrame(message              )            {
+    const n = this.sendCounter++;
+    return { type: "data", n, c: b64url(seal(this.sendKey, n, this.aad, Buffer.from(JSON.stringify(message), "utf8"))) };
+  }
+
+  openFrame(frame                          )               {
+    if (frame.n !== this.receiveCounter) throw new Error(`frame ${frame.n} out of order (expected ${this.receiveCounter})`);
+    const plaintext = open(this.receiveKey, frame.n, this.aad, fromB64url(frame.c));
+    this.receiveCounter++;
+    return JSON.parse(plaintext.toString("utf8"))                ;
+  }
+}
+
+/** What travels between the phone and the host through the relay; the relay only sees these. */
+                       
+                                      
+                                        
+                                          
+                                                     
+
+/** What is inside a data frame. */
+                          
+                                                       
+                                                                 
+                                           
+                             
+                                    
+
+/** Relay ↔ host multiplexing: one host WebSocket carries every phone connection. */
+                          
+                                                  
+                                                    
+                                                      
+
+/** WebSocket close codes the relay and the bridge use. */
+export const CloseCode = {
+  hostOffline: 4404,
+  revoked: 4403,
+  replaced: 4409,
+  protocolError: 4400,
+  streamGone: 4410,
+}         ;
+
+/**
+ * Keeps one direction of a stream's messages until the peer acknowledges them, so a reconnect can resend exactly
+ * what was lost. Sequence numbers start at 1; `received` is the highest contiguous seq taken from the peer.
+ */
+export class StreamBuffer {
+  nextSeq = 1;
+  received = 0;
+          unacked                                                = [];
+          bytes = 0;
+
+                   maxBytes        ;
+  constructor(maxBytes = 32 * 1024 * 1024) { this.maxBytes = maxBytes; }
+
+  push(line        )                                {
+    const item = { seq: this.nextSeq++, line, size: Buffer.byteLength(line) };
+    this.unacked.push(item);
+    this.bytes += item.size;
+    if (this.bytes > this.maxBytes) throw new Error("unacknowledged buffer full");
+    return item;
+  }
+
+  ack(seq        ) {
+    while (this.unacked.length && this.unacked[0].seq <= seq) this.bytes -= this.unacked.shift() .size;
+  }
+
+  pending(after        )                                  {
+    return this.unacked.filter((item) => item.seq > after);
+  }
+
+  /** True when the line is new; duplicates from a resend are dropped. Gaps cannot happen on one ordered socket. */
+  accept(seq        )          {
+    if (seq <= this.received) return false;
+    if (seq !== this.received + 1) throw new Error(`message ${seq} skips ahead of ${this.received}`);
+    this.received = seq;
+    return true;
+  }
+}

package/src/relay/config.js

@@ -0,0 +1,76 @@
+// Reads ~/.config/replica-relay/relay.env (Relay/deploy/relay.env.example). Real environment variables win over
+// the file, so a systemd Environment= line or a one-off `RELAY_PORT=… node …` still works.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/** RELAY_ENV points somewhere else (the quick-tunnel script and the tests use it). */
+export const defaultEnvPath = () => process.env.RELAY_ENV ?? path.join(os.homedir(), ".config", "replica-relay", "relay.env");
+
+export function readEnvFile(file        )                         {
+  let text        ;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (error) {
+    if ((error                         ).code === "ENOENT") return {};
+    throw error;
+  }
+  const values                         = {};
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const eq = line.indexOf("=");
+    if (eq < 1) continue;
+    let value = line.slice(eq + 1).trim();
+    if (/^(".*"|'.*')$/.test(value)) value = value.slice(1, -1);
+    values[line.slice(0, eq).trim()] = value;
+  }
+  return values;
+}
+
+                              
+                 
+               
+                              
+                      
+                  
+                                                                          
+                    
+                                
+                                    
+                                   
+                             
+ 
+
+/** "github:583231, 12345, *" → ["583231", "12345", "*"]; anything that is not a numeric id or * is refused. */
+export function parseAllowedIds(text        )           {
+  return text.split(",").map((item) => item.trim()).filter(Boolean).map((item) => {
+    const id = item.replace(/^github:/, "");
+    if (id !== "*" && !/^[0-9]{1,20}$/.test(id)) throw new Error(`GITHUB_ALLOWED_USERS takes numeric GitHub ids (github:123) or *, not "${item}"`);
+    return id;
+  });
+}
+
+const expandHome = (value        ) => (value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value);
+
+export function loadRelayConfig(envPath = defaultEnvPath())              {
+  const file = readEnvFile(envPath);
+  const get = (name        ) => {
+    const value = process.env[name] ?? file[name];
+    return value === undefined || value === "" ? null : value;
+  };
+  const origin = get("RELAY_PUBLIC_ORIGIN");
+  if (origin && !/^https?:\/\/[^/]+\/?$/.test(origin)) throw new Error(`RELAY_PUBLIC_ORIGIN must look like https://host[:port], got ${origin}`);
+  return {
+    listen: get("RELAY_LISTEN") ?? "127.0.0.1",
+    port: Number(get("RELAY_PORT") ?? 8790),
+    publicOrigin: origin?.replace(/\/$/, "") ?? null,
+    trustProxy: get("RELAY_TRUST_PROXY") === "1",
+    dataDir: expandHome(get("RELAY_DATA_DIR") ?? "~/.local/share/replica-relay"),
+    devLogin: get("RELAY_DEV_LOGIN") === "1",
+    githubClientId: get("GITHUB_CLIENT_ID"),
+    githubClientSecret: get("GITHUB_CLIENT_SECRET"),
+    githubCallbackUrl: get("GITHUB_CALLBACK_URL"),
+    githubAllowedIds: parseAllowedIds(get("GITHUB_ALLOWED_USERS") ?? ""),
+  };
+}