Implement code word based remote authentication (#1)

Add comprehensive remote authentication system allowing users to log in from one device by authenticating from another trusted device. Features include:

- Proof of Work (PoW) protection using PBKDF2-SHA512 to prevent abuse
- Simple pairing codes (3 words) protected by dynamic PoW difficulty
- Autocomplete pairing code input with error checking
- Real-time WebSocket communication between devices

Unlike device addition links and reset links with QR codes that only allow adding an authentication method, and that work offline over the duration of several days, this mechanism is strictly online, with 5 minute time limit.

frontend/src/utils/awaitable-websocket.js

@@ -18,12 +18,36 @@ class AwaitableWebSocket extends WebSocket {
     }
     this.onclose = e => {
       if (!this.#opened) {
-        reject(new Error(`WebSocket ${this.url} failed to connect, code ${e.code}`))
+        reject(new Error(`Failed to connect to server (code ${e.code})`))
         return
       }
-      this.#err = e.wasClean
-        ? new Error(`Websocket ${this.url} closed ${e.code}`)
-        : new Error(`WebSocket ${this.url} closed with error ${e.code}`)
+      // Create user-friendly close messages
+      let message
+      if (e.wasClean) {
+        // Standard close codes
+        switch (e.code) {
+          case 1000: message = 'Connection closed normally'; break
+          case 1001: message = 'Server is going away'; break
+          case 1002: message = 'Protocol error'; break
+          case 1003: message = 'Unsupported data received'; break
+          case 1006: message = 'Connection lost unexpectedly'; break
+          case 1007: message = 'Invalid data received'; break
+          case 1008: message = 'Policy violation'; break
+          case 1009: message = 'Message too large'; break
+          case 1010: message = 'Extension negotiation failed'; break
+          case 1011: message = 'Server encountered an error'; break
+          case 1012: message = 'Server is restarting'; break
+          case 1013: message = 'Server is overloaded, try again later'; break
+          case 1014: message = 'Bad gateway'; break
+          case 1015: message = 'TLS handshake failed'; break
+          default: message = `Connection closed (code ${e.code})`
+        }
+      } else {
+        message = e.code === 1006
+          ? 'Connection lost unexpectedly'
+          : `Connection closed with error (code ${e.code})`
+      }
+      this.#err = new Error(message)
       this.#waiting.splice(0).forEach(p => p.reject(this.#err))
     }
   }

frontend/src/utils/base64url.js

@@ -0,0 +1,33 @@
+/**
+ * URL-safe Base64 encoding/decoding utilities.
+ *
+ * These functions handle base64url format (RFC 4648) which uses:
+ * - '-' instead of '+'
+ * - '_' instead of '/'
+ * - No padding '=' characters
+ */
+
+/**
+ * Decode a base64url string to Uint8Array.
+ * Handles both standard base64 and URL-safe base64 (with or without padding).
+ * @param {string} str - Base64url encoded string
+ * @returns {Uint8Array} - Decoded bytes
+ */
+export function dec(str) {
+  // Convert URL-safe characters to standard base64
+  const base64 = str.replace(/-/g, '+').replace(/_/g, '/')
+  // Add padding if needed
+  const padded = base64 + '='.repeat((4 - base64.length % 4) % 4)
+  return Uint8Array.from(atob(padded), c => c.charCodeAt(0))
+}
+
+/**
+ * Encode a Uint8Array to base64url string.
+ * @param {Uint8Array} bytes - Bytes to encode
+ * @returns {string} - Base64url encoded string (no padding)
+ */
+export function enc(bytes) {
+  const base64 = btoa(String.fromCharCode(...bytes))
+  // Convert to URL-safe and remove padding
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}

frontend/src/utils/pow-test.js

@@ -0,0 +1,37 @@
+import { solvePoW, verifyPoW } from './pow.js'
+
+const TRIALS = 5
+const WORK = 10
+
+async function test() {
+  console.log(`Running ${TRIALS} trials with ${WORK} work units...\n`)
+
+  const times = []
+
+  for (let trial = 1; trial <= TRIALS; trial++) {
+    const challenge = crypto.getRandomValues(new Uint8Array(8))
+
+    const start = performance.now()
+    const solution = await solvePoW(challenge, WORK)
+    const elapsed = performance.now() - start
+
+    const valid = await verifyPoW(challenge, solution, WORK)
+
+    times.push(elapsed)
+
+    console.log(`Trial ${trial.toString().padStart(2)}: ${(elapsed / 1000).toFixed(3)}s, valid=${valid}`)
+  }
+
+  const avgTime = times.reduce((a, b) => a + b, 0) / times.length
+  const minTime = Math.min(...times)
+  const maxTime = Math.max(...times)
+
+  console.log('\n--- Summary ---')
+  console.log(`Trials: ${TRIALS}`)
+  console.log(`Work units: ${WORK}`)
+  console.log(`Avg time: ${(avgTime / 1000).toFixed(3)}s`)
+  console.log(`Min time: ${(minTime / 1000).toFixed(3)}s`)
+  console.log(`Max time: ${(maxTime / 1000).toFixed(3)}s`)
+}
+
+test()

frontend/src/utils/pow.js

@@ -0,0 +1,68 @@
+/**
+ * Proof of Work utility using PBKDF2-SHA512
+ *
+ * The PoW requires finding nonces where PBKDF2(challenge, nonce) produces
+ * output with a zero first byte. Each work unit requires finding one such nonce.
+ * All valid nonces are concatenated into a solution for server verification.
+ */
+
+/**
+ * Solve a Proof of Work challenge
+ *
+ * @param {Uint8Array|ArrayBuffer} challenge - 8-byte server-provided challenge
+ * @param {number} work - Number of PBKDF2 work units required
+ * @param {object} [options] - Optional parameters
+ * @param {AbortSignal} [options.signal] - AbortSignal to cancel the operation
+ * @returns {Promise<Uint8Array>} Solution: concatenated 8-byte nonces (8 * work bytes)
+ * @throws {Error} If challenge is invalid or operation is aborted
+ */
+export async function solvePoW(challenge, work, options = {}) {
+  const { signal } = options
+  const startTime = performance.now()
+
+  // Validate inputs
+  const challengeBytes = challenge instanceof ArrayBuffer
+    ? new Uint8Array(challenge)
+    : challenge
+
+  if (!(challengeBytes instanceof Uint8Array) || challengeBytes.length !== 8) {
+    throw new Error('Challenge must be exactly 8 bytes')
+  }
+
+  // Import challenge as PBKDF2 key material
+  const baseKey = await crypto.subtle.importKey('raw', challengeBytes, 'PBKDF2', false, ['deriveBits'])
+
+  // Build solution from found nonces
+  const solution = new Uint8Array(8 * work)
+  let totalIterations = 0
+  const mask = 0x7FF  // The client must work 2048x harder than the server
+
+  // Sequential nonce starting at zero (little-endian, using Uint32Array for efficient increment)
+  const nonce = new Uint32Array(2)
+
+  for (let i = 0; i < work; i++) {
+    if (signal?.aborted) {
+      throw new DOMException('PoW operation aborted', 'AbortError')
+    }
+
+    // Find a nonce where PBKDF2 output passes the mask check
+    let result
+    do {
+      totalIterations++
+      if (++nonce[0] === 0x100000000) ++nonce[1]  // Increment 64-bit little-endian nonce
+      result = new Uint32Array(await crypto.subtle.deriveBits(
+        { name: 'PBKDF2', salt: nonce, iterations: 128, hash: 'SHA-512'},
+        baseKey,
+        32
+      ))
+    } while (result[0] & mask)
+    solution.set(new Uint8Array(nonce.buffer), i * 8)
+  }
+
+  const elapsed = (performance.now() - startTime) / 1000
+  const expectedIterations = work * (mask + 1)
+  const luckRatio = (totalIterations / expectedIterations).toFixed(1)
+  const bench = totalIterations / ((mask + 1) * elapsed)
+  console.log(`PoW work=${work} solved in ${elapsed.toFixed(2)}s (${luckRatio}x expected ${bench.toFixed(1)} work/s)`)
+  return solution
+}

frontend/src/utils/wordlist.js

@@ -0,0 +1,61 @@
+// Auto-generated from paskia/util/wordlist.py - do not edit manually
+// A custom list of 1024 common 3-6 letter words, with unique 3-prefixes and no prefix words
+
+export const words = ["able", "about", "absent", "abuse", "access", "acid", "across", "act", "adapt", "add", "adjust", "admit", "adult", "advice", "affair", "afraid", "again", "age", "agree", "ahead", "aim", "air", "aisle", "alarm", "album", "alert", "alien", "all", "almost", "alone", "alpha", "also", "alter", "always", "amazed", "among", "amused", "anchor", "angle", "animal", "ankle", "annual", "answer", "any", "apart", "appear", "april", "arch", "are", "argue", "army", "around", "array", "art", "ascent", "ash", "ask", "aspect", "assume", "asthma", "atom", "attack", "audit", "august", "aunt", "author", "avoid", "away", "awful", "axis", "baby", "back", "bad", "bag", "ball", "bamboo", "bank", "bar", "base", "battle", "beach", "become", "beef", "before", "begin", "behind", "below", "bench", "best", "better", "beyond", "bid", "bike", "bind", "bio", "birth", "bitter", "black", "bleak", "blind", "blood", "blue", "board", "body", "boil", "bomb", "bone", "book", "border", "boss", "bottom", "bounce", "bowl", "box", "boy", "brain", "bread", "bring", "brown", "brush", "bubble", "buck", "budget", "build", "bulk", "bundle", "burden", "bus", "but", "buyer", "buzz", "cable", "cache", "cage", "cake", "call", "came", "can", "car", "case", "catch", "cause", "cave", "celery", "cement", "census", "cereal", "change", "check", "child", "choice", "chunk", "cigar", "circle", "city", "civil", "class", "clean", "client", "close", "club", "coast", "code", "coffee", "coil", "cold", "come", "cool", "copy", "core", "cost", "cotton", "couch", "cover", "coyote", "craft", "cream", "crime", "cross", "cruel", "cry", "cube", "cue", "cult", "cup", "curve", "custom", "cute", "cycle", "dad", "damage", "danger", "daring", "dash", "dawn", "day", "deal", "debate", "decide", "deer", "define", "degree", "deity", "delay", "demand", "denial", "depth", "derive", "design", "detail", "device", "dial", "dice", "die", "differ", "dim", "dinner", "direct", "dish", "divert", "dizzy", "doctor", "dog", "dollar", "domain", "donate", "door", "dose", "double", "dove", "draft", "dream", "drive", "drop", "drum", "dry", "duck", "dumb", "dune", "during", "dust", "dutch", "dwarf", "eager", "early", "east", "echo", "eco", "edge", "edit", "effort", "egg", "eight", "either", "elbow", "elder", "elite", "else", "embark", "emerge", "emily", "employ", "enable", "end", "enemy", "engine", "enjoy", "enlist", "enough", "enrich", "ensure", "entire", "envy", "equal", "era", "erode", "error", "erupt", "escape", "essay", "estate", "ethics", "evil", "evoke", "exact", "excess", "exist", "exotic", "expect", "extent", "eye", "fabric", "face", "fade", "faith", "fall", "family", "fan", "far", "father", "fault", "feel", "female", "fence", "fetch", "fever", "few", "fiber", "field", "figure", "file", "find", "first", "fish", "fit", "fix", "flat", "flesh", "flight", "float", "fluid", "fly", "foam", "focus", "fog", "foil", "follow", "food", "force", "fossil", "found", "fox", "frame", "fresh", "friend", "frog", "fruit", "fuel", "fun", "fury", "future", "gadget", "gain", "galaxy", "game", "gap", "garden", "gas", "gate", "gauge", "gaze", "genius", "ghost", "giant", "gift", "giggle", "ginger", "girl", "give", "glass", "glide", "globe", "glue", "goal", "god", "gold", "good", "gospel", "govern", "gown", "grant", "great", "grid", "group", "grunt", "guard", "guess", "guide", "gulf", "gun", "gym", "habit", "hair", "half", "hammer", "hand", "happy", "hard", "hat", "have", "hawk", "hay", "hazard", "head", "hedge", "height", "help", "hen", "hero", "hidden", "high", "hill", "hint", "hip", "hire", "hobby", "hockey", "hold", "home", "honey", "hood", "hope", "horse", "host", "hotel", "hour", "hover", "how", "hub", "huge", "human", "hungry", "hurt", "hybrid", "ice", "icon", "idea", "idle", "ignore", "ill", "image", "immune", "impact", "income", "index", "infant", "inhale", "inject", "inmate", "inner", "input", "inside", "into", "invest", "iron", "island", "issue", "italy", "item", "ivory", "jacket", "jaguar", "james", "jar", "jazz", "jeans", "jelly", "jewel", "job", "joe", "joke", "joy", "judge", "juice", "july", "jump", "june", "just", "kansas", "kate", "keep", "kernel", "key", "kick", "kid", "kind", "kiss", "kit", "kiwi", "knee", "knife", "know", "labor", "lady", "lag", "lake", "lamp", "laptop", "large", "later", "laugh", "lava", "law", "layer", "lazy", "leader", "left", "legal", "lemon", "length", "lesson", "letter", "level", "liar", "libya", "lid", "life", "light", "like", "limit", "line", "lion", "liquid", "list", "little", "live", "lizard", "load", "local", "logic", "long", "loop", "lost", "loud", "love", "low", "loyal", "lucky", "lumber", "lunch", "lust", "luxury", "lyrics", "mad", "magic", "main", "major", "make", "male", "mammal", "man", "map", "market", "mass", "matter", "maze", "mccoy", "meadow", "media", "meet", "melt", "member", "men", "mercy", "mesh", "method", "middle", "milk", "mimic", "mind", "mirror", "miss", "mix", "mobile", "model", "mom", "monkey", "moon", "more", "mother", "mouse", "move"Line truncated
+
+// Pre-computed prefix map for autocomplete (maps 1-3 char prefixes to matching words)
+const prefixMap = new Map();
+
+// Build prefix map on module load
+for (const word of words) {
+  for (let i = 1; i <= Math.min(word.length, 6); i++) {
+    const prefix = word.slice(0, i);
+    if (!prefixMap.has(prefix)) {
+      prefixMap.set(prefix, []);
+    }
+    prefixMap.get(prefix).push(word);
+  }
+}
+
+/**
+ * Find words matching the given prefix.
+ * @param {string} prefix - The prefix to match (case-insensitive)
+ * @returns {string[]} Array of matching words
+ */
+export function findMatches(prefix) {
+  if (!prefix) return [];
+  const normalized = prefix.toLowerCase();
+  return prefixMap.get(normalized) || [];
+}
+
+/**
+ * Get unique autocomplete suggestion if prefix matches exactly one word.
+ * @param {string} prefix - The prefix to match (case-insensitive)
+ * @returns {string|null} The matching word if unique, null otherwise
+ */
+export function getUniqueMatch(prefix) {
+  const matches = findMatches(prefix);
+  return matches.length === 1 ? matches[0] : null;
+}
+
+/**
+ * Check if a word is valid (exists in the wordlist).
+ * @param {string} word - The word to check (case-insensitive)
+ * @returns {boolean} True if the word is valid
+ */
+export function isValidWord(word) {
+  if (!word) return false;
+  const normalized = word.toLowerCase();
+  return words.includes(normalized);
+}
+
+/**
+ * Check if a string is a valid prefix (could be the start of a valid word).
+ * @param {string} prefix - The prefix to check (case-insensitive)
+ * @returns {boolean} True if the prefix matches at least one word
+ */
+export function isValidPrefix(prefix) {
+  if (!prefix) return true;  // Empty is always valid
+  const normalized = prefix.toLowerCase();
+  return prefixMap.has(normalized);
+}