@threadedstack/wmd-web 0.0.0-stage → 0.1.13

package/relay/keys.ts

@@ -0,0 +1,53 @@
+// W59: optional owner keys for a standalone relay (off by default; the default needs no key).
+// A key is an id and a secret. The relay stores only an scrypt hash of the secret:
+//
+//   scrypt:<N>:<r>:<p>:<salt base64url>:<hash base64url>
+//
+// and a client presents the key with Wisp v2 password auth (username = id, password = secret).
+
+import { randomBytes, scrypt, timingSafeEqual } from 'node:crypto'
+
+export type OwnerKey = {
+  id: string
+  hash: string
+  origins?: string[] // page origins this key may be used from (any when unset)
+  allowHosts?: string[] // replaces the relay's host allowlist for this key's sessions
+  rateDown?: number // bandwidth shared by every session of this key
+  rateUp?: number
+}
+
+const N = 1 << 14
+const R = 8
+const P = 1
+const LEN = 32
+
+function scryptAsync(secret: string, salt: Buffer, n: number, r: number, p: number): Promise<Buffer> {
+  return new Promise((res, rej) =>
+    scrypt(secret, salt, LEN, { N: n, r, p, maxmem: 256 * n * r + (1 << 20) }, (e, k) => (e ? rej(e) : res(k))),
+  )
+}
+
+export async function hashSecret(secret: string): Promise<string> {
+  const salt = randomBytes(16)
+  const k = await scryptAsync(secret, salt, N, R, P)
+  return `scrypt:${N}:${R}:${P}:${salt.toString('base64url')}:${k.toString('base64url')}`
+}
+
+/** True when `secret` matches the stored hash. Constant time in the comparison; a malformed hash is false. */
+export async function verifySecret(secret: string, stored: string): Promise<boolean> {
+  const f = stored.split(':')
+  if (f.length !== 6 || f[0] !== 'scrypt') return false
+  const [n, r, p] = f.slice(1, 4).map(Number)
+  if (!(n >= 2 && n <= 1 << 20 && (n & (n - 1)) === 0 && r >= 1 && r <= 32 && p >= 1 && p <= 16)) return false
+  const salt = Buffer.from(f[4], 'base64url')
+  const want = Buffer.from(f[5], 'base64url')
+  if (want.length !== LEN) return false
+  const got = await scryptAsync(secret, salt, n, r, p)
+  return timingSafeEqual(got, want)
+}
+
+/** A new random key: the secret is shown once, the hash is kept. */
+export async function newKey(id: string): Promise<{ id: string; secret: string; hash: string }> {
+  const secret = randomBytes(24).toString('base64url')
+  return { id, secret, hash: await hashSecret(secret) }
+}

package/relay/local-tls.ts

@@ -0,0 +1,121 @@
+// W59 S4: `wmd-relay --local-tls`. WebKit and Safari block ws:// to loopback from https pages
+// (S0), so a Safari reader needs wss://localhost. This makes one self-signed leaf certificate
+// for localhost, 127.0.0.1 and ::1 (CA:FALSE, serverAuth only: it cannot sign anything else, plan
+// §7 A10) in ~/.wmd/relay/ (0700, key 0600), reuses it while it is valid, and gives the command
+// the person runs to trust it. wmd never touches a keychain itself.
+
+import { X509Certificate, createPrivateKey, generateKeyPairSync } from 'node:crypto'
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { breakIfStale, release, tryTake } from './lock.ts'
+
+export const DAYS = 800 // macOS trusts TLS server certificates of at most 825 days
+const RENEW_MS = 30 * 86400_000 // a new one when less than this is left
+
+export type LocalTls = { cert: string; key: string; certPath: string; keyPath: string; made: boolean; trust: string[] }
+
+export function relayDir(home = homedir()): string {
+  return join(home, '.wmd', 'relay')
+}
+
+/** One process at a time makes or reads the pair (relays started together on a fresh home raced on the temp names, and could leave a key and a certificate that do not belong together). mkdir is the atomic step. */
+function withDirLock<T>(lock: string, fn: () => T): T {
+  const t0 = Date.now()
+  while (!tryTake(lock, 'dir')) {
+    breakIfStale(lock, 'dir') // left by a killed process
+    if (Date.now() - t0 > 20_000) throw new Error(`${lock} is held by another wmd-relay; if none is running, delete it`)
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25)
+  }
+  try {
+    return fn()
+  } finally {
+    release(lock)
+  }
+}
+
+export function localTls(dir = relayDir(), openssl = findOpenssl()): LocalTls {
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  chmodSync(dir, 0o700)
+  return withDirLock(join(dir, 'local-tls.lock'), () => makeOrRead(dir, openssl))
+}
+
+function makeOrRead(dir: string, openssl: string | null): LocalTls {
+  const certPath = join(dir, 'local-tls.crt')
+  const keyPath = join(dir, 'local-tls.key')
+  let made = false
+  if (!usable(certPath, keyPath)) {
+    if (!openssl) throw new Error('--local-tls needs openssl to make the certificate, and none was found on PATH or in /usr/bin')
+    const tmpC = `${certPath}.new`
+    const tmpK = `${keyPath}.new`
+    const conf = join(dir, 'openssl.cnf.new')
+    try {
+      // A config of our own: the system openssl on macOS is LibreSSL 3.3, which refuses `-subj` without a
+      // [req] distinguished_name, and a missing config file is not an option for it (OPENSSL_CONF=/dev/null failed there).
+      writeFileSync(
+        conf,
+        [
+          '[req]', 'distinguished_name = dn', 'prompt = no', 'x509_extensions = ext', '[dn]', 'CN = wmd-relay local',
+          '[ext]', 'subjectAltName = DNS:localhost,IP:127.0.0.1,IP:::1', 'basicConstraints = critical,CA:FALSE',
+          'keyUsage = critical,digitalSignature', 'extendedKeyUsage = serverAuth', '',
+        ].join('\n'),
+        { mode: 0o600 },
+      )
+      // The key is made here (LibreSSL 3.3 writes P-256 keys Bun cannot read) and is 0600 from its first byte; openssl only signs.
+      rmSync(tmpK, { force: true })
+      writeFileSync(tmpK, generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600, flag: 'wx' })
+      const r = Bun.spawnSync([openssl, 'req', '-x509', '-new', '-key', tmpK, '-days', String(DAYS), '-config', conf, '-out', tmpC], {
+        stdout: 'ignore', stderr: 'pipe', env: { ...process.env, OPENSSL_CONF: conf },
+      })
+      if (r.exitCode !== 0 || !existsSync(tmpC) || !existsSync(tmpK)) {
+        throw new Error(`openssl could not make the certificate: ${r.stderr.toString().trim().split('\n').pop()}`)
+      }
+      chmodSync(tmpK, 0o600)
+      chmodSync(tmpC, 0o644)
+      renameSync(tmpK, keyPath)
+      renameSync(tmpC, certPath)
+      made = true
+    } finally {
+      for (const f of [conf, tmpC, tmpK]) rmSync(f, { force: true }) // after a success only the renamed ones are gone already
+    }
+  }
+  chmodSync(keyPath, 0o600)
+  return { cert: readFileSync(certPath, 'utf8'), key: readFileSync(keyPath, 'utf8'), certPath, keyPath, made, trust: trustWords(certPath) }
+}
+
+function usable(certPath: string, keyPath: string): boolean {
+  try {
+    if (!statSync(keyPath).isFile()) return false
+    const c = new X509Certificate(readFileSync(certPath))
+    if (!c.checkPrivateKey(createPrivateKey(readFileSync(keyPath)))) return false // a cert and a key that do not belong together are made anew
+    if (c.ca) return false
+    if (!/DNS:localhost/.test(c.subjectAltName || '') || !/IP Address:127\.0\.0\.1/.test(c.subjectAltName || '')) return false
+    return Date.parse(c.validTo) - Date.now() > RENEW_MS
+  } catch {
+    return false
+  }
+}
+
+function findOpenssl(): string | null {
+  return Bun.which('openssl') ?? (existsSync('/usr/bin/openssl') ? '/usr/bin/openssl' : null)
+}
+
+/** A path as one shell word (single-quoted when it has anything but safe characters). */
+export function shq(p: string): string {
+  return /^[A-Za-z0-9_@%+=:,./-]+$/.test(p) ? p : `'${p.replace(/'/g, `'\\''`)}'`
+}
+
+/** What the person runs to trust the leaf (they run it; a password or Touch ID prompt follows on macOS). */
+export function trustWords(certPath: string): string[] {
+  if (process.platform === 'darwin') {
+    return [
+      'To let Safari use it, trust this certificate once (macOS asks for your password):',
+      `  security add-trusted-cert -r trustRoot -p ssl -k ~/Library/Keychains/login.keychain-db ${shq(certPath)}`,
+      'To undo: security remove-trusted-cert ' + shq(certPath),
+      'It is a leaf for localhost only (not a CA): it cannot vouch for any other site.',
+    ]
+  }
+  return [
+    `To use it from a browser, add ${certPath} to the browser's trusted certificates (a leaf for localhost only, not a CA).`,
+  ]
+}

package/relay/lock.ts

@@ -0,0 +1,81 @@
+// W59 S4: the two lock kinds wmd-relay uses (a file next to the keys file, a directory next to the
+// local certificate). Both are taken with an atomic create, hold the owner's pid, and are given up
+// by their owner. A lock a killed process left behind is broken when its owner is gone or it is
+// older than a minute, and breaking is itself done under a lock (`<lock>.break`): two waiters that
+// both saw the same stale lock used to both remove it, and the second removal could take a lock
+// the first waiter had just made.
+
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type LockKind = 'file' | 'dir'
+export const STALE_MS = 60_000
+// A lock with no readable owner pid is one whose owner was killed between making it and writing its pid (a window of microseconds), or whose pid file holds junk. It is judged by a short age, not STALE_MS: waiters give up after 20 s, so 60 s wedged every start.
+export const OWNERLESS_MS = 2_000
+
+/** True when this call made the lock. */
+export function tryTake(lock: string, kind: LockKind): boolean {
+  try {
+    if (kind === 'dir') {
+      mkdirSync(lock, { mode: 0o700 })
+      writeFileSync(join(lock, 'pid'), String(process.pid))
+    } else {
+      const fd = openSync(lock, 'wx', 0o600)
+      writeSync(fd, String(process.pid))
+      closeSync(fd)
+    }
+    return true
+  } catch (e: any) {
+    if (e?.code === 'EEXIST') return false
+    throw e
+  }
+}
+
+export function release(lock: string): void {
+  rmSync(lock, { recursive: true, force: true })
+}
+
+function ownerPid(lock: string, kind: LockKind): number | null {
+  try {
+    const n = Number(readFileSync(kind === 'dir' ? join(lock, 'pid') : lock, 'utf8').trim())
+    return Number.isInteger(n) && n > 0 ? n : null // an empty one is a lock whose owner has not written yet: judged by its age only
+  } catch {
+    return null
+  }
+}
+
+function alive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (e: any) {
+    return e?.code !== 'ESRCH' // EPERM: it exists
+  }
+}
+
+function stale(lock: string, kind: LockKind, ms: number): boolean {
+  let age: number
+  try {
+    age = Date.now() - statSync(lock).mtimeMs
+  } catch {
+    return false // gone already
+  }
+  if (age > ms) return true
+  const pid = ownerPid(lock, kind)
+  if (pid === null) return age > Math.min(ms, OWNERLESS_MS)
+  return pid !== process.pid && !alive(pid)
+}
+
+/** Remove the lock when its owner is gone (or it is older than `ms`). Only one waiter at a time judges and removes. */
+export function breakIfStale(lock: string, kind: LockKind, ms = STALE_MS): void {
+  const brk = `${lock}.break`
+  if (!tryTake(brk, 'file')) {
+    if (stale(brk, 'file', ms)) rmSync(brk, { force: true }) // the breaker itself was killed
+    return
+  }
+  try {
+    if (stale(lock, kind, ms)) rmSync(lock, { recursive: true, force: true })
+  } finally {
+    rmSync(brk, { force: true })
+  }
+}

package/relay/logfile.ts

@@ -0,0 +1,138 @@
+// W59 S7: the hosted relay's log file. Connection metadata only (the engine never hands it payloads or secrets), one JSON
+// object per line, rotated by size and by age, and files past the retention are removed. Rotation renames the live file
+// to relay-<time>.log; removal is by the file's last write time. The default retention (14 days) is provisional.
+
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type LogFileOptions = {
+  dir: string
+  maxBytes?: number // rotate when the live file would pass this (50 MiB)
+  maxAgeMs?: number // rotate when the live file is this old (1 day)
+  retainDays?: number // remove rotated files older than this (14)
+  maxLogDirBytes?: number // the whole directory stays under this: the oldest rotated files go first (1 GiB)
+  warn?: (line: string) => void // a write problem, once per kind (stderr)
+  append?: (path: string, text: string) => void // the write itself (tests make it fail)
+  now?: () => number
+}
+
+const LIVE = 'relay.log'
+const ROTATED = /^relay-\d{8}T\d{9}(-\d+)?\.log$/
+
+export function createLogFile(o: LogFileOptions) {
+  const now = o.now ?? Date.now
+  const maxBytes = o.maxBytes ?? 50 * 2 ** 20
+  const maxAgeMs = o.maxAgeMs ?? 24 * 3600_000
+  const retainMs = (o.retainDays ?? 14) * 24 * 3600_000
+  const maxDir = o.maxLogDirBytes ?? 2 ** 30
+  const warn = o.warn ?? ((m: string) => void process.stderr.write(`${m}\n`))
+  const append = o.append ?? ((p: string, t: string) => appendFileSync(p, t, { mode: 0o600 }))
+  // the directory holds connection metadata: owner only, also when it already existed with a looser mode
+  mkdirSync(o.dir, { recursive: true, mode: 0o700 })
+  try {
+    chmodSync(o.dir, 0o700)
+  } catch (e: any) {
+    throw new Error(`the log directory ${o.dir} must be owner-only (0700) and cannot be made so: ${e?.message ?? e}`)
+  }
+  const live = join(o.dir, LIVE)
+  let size = existsSync(live) ? statSync(live).size : 0
+  let born = existsSync(live) ? statSync(live).birthtimeMs || statSync(live).mtimeMs : now()
+  let buf: string[] = []
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const stamp = (t: number) => new Date(t).toISOString().replace(/[-:]/g, '').replace('.', '').replace('Z', '') // 20261016T123456789
+
+  function rotate() {
+    if (!existsSync(live) || size === 0) {
+      born = now()
+      return
+    }
+    let name = join(o.dir, `relay-${stamp(now())}.log`)
+    for (let i = 1; existsSync(name); i++) name = join(o.dir, `relay-${stamp(now())}-${i}.log`)
+    renameSync(live, name)
+    size = 0
+    born = now()
+    prune()
+  }
+
+  /** Remove rotated files whose last write is past the retention. Returns the names removed. */
+  function prune(): string[] {
+    const gone: string[] = []
+    for (const f of readdirSync(o.dir)) {
+      if (!ROTATED.test(f)) continue
+      const p = join(o.dir, f)
+      if (now() - statSync(p).mtimeMs > retainMs) {
+        rmSync(p, { force: true })
+        gone.push(f)
+      }
+    }
+    // the total cap: the oldest rotated files go until the directory fits
+    const files = readdirSync(o.dir).filter(f => ROTATED.test(f)).sort()
+    let total = existsSync(live) ? statSync(live).size : 0
+    const sizes = files.map(f => statSync(join(o.dir, f)).size)
+    total += sizes.reduce((a, b) => a + b, 0)
+    for (let i = 0; i < files.length && total > maxDir; i++) {
+      rmSync(join(o.dir, files[i]), { force: true })
+      total -= sizes[i]
+      gone.push(files[i])
+    }
+    return gone
+  }
+
+  const reported = new Set<string>()
+  const MAX_PENDING = 8 * 2 ** 20 // while writes fail, hold at most this much text; the oldest lines go first
+  function flush() {
+    if (timer) clearTimeout(timer)
+    timer = null
+    if (!buf.length) return
+    const text = buf.join('')
+    try {
+      if (size > 0 && (size + text.length > maxBytes || now() - born > maxAgeMs)) rotate()
+      else if (size === 0) born = now()
+      try {
+        append(live, text)
+      } catch (e: any) {
+        if (e?.code !== 'ENOENT') throw e
+        mkdirSync(o.dir, { recursive: true, mode: 0o700 }) // the directory was removed: make it again and try once more
+        chmodSync(o.dir, 0o700)
+        size = 0
+        append(live, text)
+      }
+      buf = []
+      size += Buffer.byteLength(text)
+      reported.clear()
+    } catch (e: any) {
+      const kind = String(e?.code ?? e?.name ?? 'error')
+      if (!reported.has(kind)) {
+        reported.add(kind)
+        warn(`wmd-relay: cannot write the log ${live} (${kind}: ${e?.message ?? e}); it keeps trying on every flush`)
+      }
+      let held = buf.reduce((n, l) => n + l.length, 0)
+      while (held > MAX_PENDING && buf.length > 1) held -= buf.shift()!.length
+      timer = setTimeout(flush, 5000)
+      ;(timer as any).unref?.()
+    }
+  }
+
+  prune()
+  const pruner = setInterval(prune, 3600_000)
+  pruner.unref?.()
+  return {
+    path: live,
+    write(e: Record<string, unknown>) {
+      buf.push(JSON.stringify({ t: now(), ...e }) + '\n')
+      if (buf.length >= 512) flush()
+      else if (!timer) {
+        timer = setTimeout(flush, 200)
+        ;(timer as any).unref?.()
+      }
+    },
+    flush,
+    prune,
+    rotate: () => (flush(), rotate()),
+    close() {
+      flush()
+      clearInterval(pruner)
+    },
+  }
+}