@cordfuse/crosstalk 7.0.0-alpha.9 → 7.0.0-beta.1

package/src/auth/setup.ts

@@ -0,0 +1,263 @@
+// First-run setup wizard.
+//
+// Trust context: SERVICE. The setup wizard runs in the daemon process
+// (service user), gated by a one-time setup token printed to the daemon's
+// terminal/journal at boot time when the user store is empty.
+//
+// Flow:
+//   1. Daemon boots; if userStore.isEmpty() → SetupState.mint() prints
+//      the URL to stdout/journal AND writes the token to
+//      /var/run/llmux/setup-token so operators with shell access can
+//      recover it.
+//   2. Every incoming request: setupGate() — if no users exist AND the
+//      request isn't to /setup/* or /api/setup/* → 503 with "setup needed."
+//      Token validation happens in the handler, not the gate.
+//   3. /setup wizard collects name + username + passphrase
+//   4. POST /api/setup validates + creates user + mints bootstrap token
+//      + invalidates the setup token
+//   5. Subsequent requests go through normal auth
+//
+// References:
+//   V2-SYSTEM-AUTH-DESIGN.md § "Setup wizard — what invokes it (v2)"
+//   V2-SYSTEM-AUTH-DESIGN.md § "Build plan" — Phase 5
+
+import { mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+
+import type { UserStore } from './users.js';
+import { UserValidationError } from './users.js';
+import type { TokenStore, MintTokenResult } from './tokens.js';
+
+export interface SetupTokenRecord {
+  /** Plaintext — kept in memory only, printed to operator out-of-band. */
+  token: string;
+  createdAt: string;
+  /** Soft expiry; the daemon clears the token on successful setup OR on restart. */
+  expiresAt: string;
+}
+
+export interface SetupSubmitInput {
+  /** From the URL ?token=... query param or hidden form field. */
+  setupToken: string;
+  name: string;
+  username: string;
+  passphrase: string;
+}
+
+export interface SetupSubmitResult {
+  ok: boolean;
+  /** On success: bootstrap token for the new admin user (returned once). */
+  bootstrapToken?: MintTokenResult;
+  error?: string;
+}
+
+export interface GateResult {
+  allow: boolean;
+  status?: number;
+  body?: unknown;
+}
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h soft expiry
+const SETUP_TOKEN_BYTES = 24;               // 192 bits → 32-char base64url
+
+/**
+ * Holds the active setup token for the daemon process. One instance per
+ * daemon — constructed in the boot path. Lifecycle:
+ *
+ *   - mint()  — boot calls this if userStore is empty. Writes plaintext
+ *               to disk for shell-access recovery, returns the record so
+ *               the boot path can format the URL + print the banner.
+ *   - isValid() — handler calls this when a setup-token bearing request
+ *               arrives. Constant-time compare.
+ *   - clear() — called by handleSetupSubmit on success. Wipes in-memory
+ *               state + removes the on-disk file.
+ *
+ * Token state is intentionally NOT persisted across daemon restarts —
+ * if the daemon restarts mid-setup, the operator re-runs setup with a
+ * fresh token. This is by design.
+ */
+export class SetupState {
+  private activeToken: string | undefined;
+  private mintedAt: Date | undefined;
+  private readonly ttlMs: number;
+  private readonly fileMode: number;
+
+  constructor(
+    private readonly tokenFilePath: string,
+    opts?: { ttlMs?: number; fileMode?: number },
+  ) {
+    this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+    this.fileMode = opts?.fileMode ?? 0o600;
+  }
+
+  mint(): SetupTokenRecord {
+    const token = randomBytes(SETUP_TOKEN_BYTES).toString('base64url');
+    const now = new Date();
+    this.activeToken = token;
+    this.mintedAt = now;
+
+    mkdirSync(dirname(this.tokenFilePath), { recursive: true });
+    writeFileSync(this.tokenFilePath, token + '\n', { mode: this.fileMode });
+
+    return {
+      token,
+      createdAt: now.toISOString(),
+      expiresAt: new Date(now.getTime() + this.ttlMs).toISOString(),
+    };
+  }
+
+  isValid(presented: unknown): boolean {
+    if (!this.activeToken || typeof presented !== 'string') return false;
+    if (this.isExpired()) return false;
+    const a = Buffer.from(this.activeToken);
+    const b = Buffer.from(presented);
+    if (a.length !== b.length) return false;
+    return timingSafeEqual(a, b);
+  }
+
+  clear(): void {
+    this.activeToken = undefined;
+    this.mintedAt = undefined;
+    try { unlinkSync(this.tokenFilePath); } catch { /* file may not exist; ignore */ }
+  }
+
+  get hasActiveToken(): boolean {
+    return this.activeToken !== undefined && !this.isExpired();
+  }
+
+  /** Read the active token if one is present + unexpired. Used by the
+   *  HTTP layer to include the token in setup-redirect URLs so the
+   *  operator never has to fish it out of the daemon log. Returns
+   *  undefined if there's no active token or it has expired. */
+  get currentToken(): string | undefined {
+    return this.hasActiveToken ? this.activeToken : undefined;
+  }
+
+  private isExpired(): boolean {
+    if (!this.mintedAt) return true;
+    return Date.now() > this.mintedAt.getTime() + this.ttlMs;
+  }
+}
+
+/**
+ * Per-request gate. In first-run mode (no users exist), only /setup and
+ * /api/setup paths are allowed through; everything else gets 503.
+ * Token validation is the handler's responsibility — keeps the gate
+ * stateless and lets the HTTP layer add nuance (HTML vs JSON responses,
+ * static assets, etc.) without re-implementing token checks.
+ */
+export async function setupGate(
+  userStore: UserStore,
+  path: string,
+): Promise<GateResult> {
+  if (!(await userStore.isEmpty())) return { allow: true };
+  if (
+    path === '/setup' || path.startsWith('/setup/') || path.startsWith('/setup?') ||
+    path === '/api/setup' || path.startsWith('/api/setup/') || path.startsWith('/api/setup?')
+  ) {
+    return { allow: true };
+  }
+  return {
+    allow: false,
+    status: 503,
+    body: {
+      error: 'setup needed',
+      hint: 'Visit /setup?token=... with the token printed by the daemon at boot (or read /var/run/llmux/setup-token).',
+    },
+  };
+}
+
+/**
+ * Handle POST /api/setup. Validates token + input, creates the admin
+ * user, mints the bootstrap token, invalidates the setup token. Returns
+ * the bootstrap token (plaintext) ONCE for the wizard to display and
+ * set as a session cookie.
+ */
+export async function handleSetupSubmit(
+  input: SetupSubmitInput,
+  userStore: UserStore,
+  tokenStore: TokenStore,
+  setup: SetupState,
+): Promise<SetupSubmitResult> {
+  if (!setup.isValid(input.setupToken)) {
+    return { ok: false, error: 'invalid or expired setup token' };
+  }
+  if (!(await userStore.isEmpty())) {
+    // Belt-and-suspenders: setupGate would already have routed this
+    // through normal auth, but if we got here somehow, refuse.
+    return { ok: false, error: 'setup already complete' };
+  }
+
+  try {
+    const user = await userStore.createUser({
+      username: input.username,
+      name: input.name,
+      passphrase: input.passphrase,
+      admin: true,
+    });
+    const bootstrapToken = await tokenStore.mint({
+      username: user.username,
+      name: `${user.name}'s first device`,
+    });
+    setup.clear();
+    return { ok: true, bootstrapToken };
+  } catch (err) {
+    return {
+      ok: false,
+      error: err instanceof UserValidationError ? err.message : `setup failed: ${(err as Error).message}`,
+    };
+  }
+}
+
+/**
+ * Non-interactive bootstrap from env vars. For Docker / CI / headless
+ * deploys — bypasses the setup token gate but still uses the user store
+ * + token store to enforce uniqueness and validation.
+ *
+ * Reads:
+ *   LLMUX_INIT_USERNAME, LLMUX_INIT_NAME, LLMUX_INIT_PASSPHRASE
+ *
+ * Returns undefined if no env vars are set (caller falls back to setup
+ * wizard). Throws if env vars are partial or if users already exist.
+ */
+export async function bootstrapFromEnv(
+  userStore: UserStore,
+  tokenStore: TokenStore,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<MintTokenResult | undefined> {
+  const username = env['LLMUX_INIT_USERNAME'];
+  const name = env['LLMUX_INIT_NAME'];
+  const passphrase = env['LLMUX_INIT_PASSPHRASE'];
+
+  const anySet = username !== undefined || name !== undefined || passphrase !== undefined;
+  if (!anySet) return undefined;
+
+  if (!username || !name || !passphrase) {
+    throw new Error(
+      'bootstrapFromEnv: LLMUX_INIT_USERNAME, LLMUX_INIT_NAME, LLMUX_INIT_PASSPHRASE must all be set',
+    );
+  }
+  if (!(await userStore.isEmpty())) {
+    throw new Error('bootstrapFromEnv: refusing — users already exist');
+  }
+
+  const user = await userStore.createUser({ username, name, passphrase, admin: true });
+  return tokenStore.mint({
+    username: user.username,
+    name: `${user.name}'s bootstrap device`,
+  });
+}
+
+/**
+ * Plain-text setup invocation banner — what the daemon prints to stdout
+ * when it mints a setup token at boot. Format is stable for log scrapers.
+ */
+export function setupBanner(setupUrl: string): string {
+  const sep = '─'.repeat(63);
+  return `\n┌${sep}┐\n` +
+    `│ llmux: first-run setup needed.${' '.repeat(31)}│\n` +
+    `│ Visit: ${setupUrl.padEnd(54)}│\n` +
+    `│ Don't share this URL — it grants admin to whoever uses it.    │\n` +
+    `└${sep}┘\n`;
+}

package/src/auth/tokens.ts

@@ -0,0 +1,285 @@
+// Identity-bound tokens.
+//
+// Every token is owned by exactly one user. The daemon enforces:
+//   - API requests authenticated by this token operate as that user
+//   - orch send/reply/next/etc. require the `from:` / `alias` field to
+//     match the token's owning user (no impersonation across users)
+//
+// Trust context: SERVICE.
+//
+// References:
+//   V2-SYSTEM-AUTH-DESIGN.md § "Token lifecycle (v2)"
+//   V2-SYSTEM-AUTH-DESIGN.md § "Data plane (v2)" — tokens.json row
+//   V2-SYSTEM-AUTH-DESIGN.md § "Build plan" — Phase 4
+
+import { existsSync, readFileSync, writeFileSync, renameSync, chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+
+export interface IdentityToken {
+  /** Server-side token id (URL-safe random). Stable; safe to log. */
+  tokenId: string;
+  /** SHA-256 hash of the secret (base64). Plaintext never persisted. */
+  secretHash: string;
+  /** The user this token authenticates as. Owning user enforces `from:`. */
+  username: string;
+  /** Human-readable label. e.g. "alice-iphone", "ci-pipeline". */
+  name: string;
+  /** ISO-8601. */
+  createdAt: string;
+  /** ISO-8601. Optional — tokens without expiry are long-lived by default. */
+  expiresAt?: string;
+  /** ISO-8601. Refreshed by the daemon on each successful validate. */
+  lastUsedAt?: string;
+}
+
+export interface MintTokenInput {
+  username: string;
+  name: string;
+  /** Optional expiry as ISO-8601. */
+  expiresAt?: string;
+}
+
+export interface MintTokenResult {
+  token: IdentityToken;
+  /** The plaintext wire secret (`sas_<tokenId>.<secret>`). RETURNED ONCE. */
+  plaintextSecret: string;
+}
+
+export interface TokenValidation {
+  ok: boolean;
+  token?: IdentityToken;
+  reason?: 'not-found' | 'expired' | 'malformed';
+}
+
+export interface TokenStore {
+  /** Create a new token; returns plaintext ONCE. */
+  mint(input: MintTokenInput): Promise<MintTokenResult>;
+  /** Look up by tokenId. Doesn't validate secret. */
+  get(tokenId: string): Promise<IdentityToken | undefined>;
+  /** List tokens (admin sees all; pass a username to filter). */
+  list(filterUsername?: string): Promise<IdentityToken[]>;
+  /** Revoke by tokenId. Idempotent — no-op if already gone. */
+  revoke(tokenId: string): Promise<void>;
+  /** Revoke all tokens owned by a user. Used on user deletion. */
+  revokeAllForUser(username: string): Promise<number>;
+  /** Rename a token's label. No-op if id missing. Returns the updated row,
+   *  or undefined if no token matched the id. */
+  rename(tokenId: string, newName: string): Promise<IdentityToken | undefined>;
+  /** Validate a presented wire secret. On success, touches lastUsedAt. */
+  validate(presentedSecret: string): Promise<TokenValidation>;
+}
+
+export class TokenValidationError extends Error {
+  constructor(message: string) { super(message); this.name = 'TokenValidationError'; }
+}
+
+/**
+ * Wire format for presented secrets: `sas_<tokenId>.<plaintextSecret>`.
+ * The tokenId prefix lets us look up the row in O(1) without scanning
+ * every hash. Same shape as GitHub PATs (`ghp_<id>_<secret>`).
+ */
+export const TOKEN_PREFIX = 'sas_'; // matches v1.x for migration
+export const TOKEN_WIRE_SEPARATOR = '.';
+
+const TOKEN_ID_BYTES = 12;      // 96 bits of randomness → 16-char base64url
+const TOKEN_SECRET_BYTES = 32;  // 256 bits of randomness → 43-char base64url
+
+function newTokenId(): string {
+  return randomBytes(TOKEN_ID_BYTES).toString('base64url');
+}
+
+function newSecret(): string {
+  return randomBytes(TOKEN_SECRET_BYTES).toString('base64url');
+}
+
+/** SHA-256 over the secret (base64). Tokens are 256-bit random so a fast
+ *  hash is appropriate — brute force is infeasible without slowing every
+ *  authenticated request to scrypt speeds. */
+function hashSecret(secret: string): string {
+  return createHash('sha256').update(secret).digest('base64');
+}
+
+interface WireParts { tokenId: string; secret: string; }
+
+function parseWire(presented: string): WireParts | undefined {
+  if (typeof presented !== 'string') return undefined;
+  if (!presented.startsWith(TOKEN_PREFIX)) return undefined;
+  const body = presented.slice(TOKEN_PREFIX.length);
+  const sepIdx = body.indexOf(TOKEN_WIRE_SEPARATOR);
+  if (sepIdx <= 0 || sepIdx >= body.length - 1) return undefined;
+  return { tokenId: body.slice(0, sepIdx), secret: body.slice(sepIdx + 1) };
+}
+
+function isExpired(token: IdentityToken, now: Date = new Date()): boolean {
+  if (!token.expiresAt) return false;
+  const expMs = Date.parse(token.expiresAt);
+  if (Number.isNaN(expMs)) return false;
+  return expMs <= now.getTime();
+}
+
+/**
+ * File-backed token store. Reads/writes config.dataDir/tokens.json.
+ *
+ * Concurrency model matches FileUserStore — single-process daemon, in-
+ * process write mutex, in-memory cache.
+ *
+ * lastUsedAt persistence: updated on every successful validate. At the
+ * daemon's expected request rate this is fine; if it ever becomes a
+ * hotspot we can debounce writes to once-per-N-seconds-per-token.
+ */
+export class FileTokenStore implements TokenStore {
+  private cache: IdentityToken[] | undefined;
+  private writeQueue: Promise<void> = Promise.resolve();
+
+  constructor(private storePath: string) {}
+
+  async mint(input: MintTokenInput): Promise<MintTokenResult> {
+    if (typeof input.username !== 'string' || input.username.length === 0) {
+      throw new TokenValidationError('username required');
+    }
+    if (typeof input.name !== 'string' || input.name.trim().length === 0) {
+      throw new TokenValidationError('name required');
+    }
+    if (input.expiresAt !== undefined) {
+      const t = Date.parse(input.expiresAt);
+      if (Number.isNaN(t)) throw new TokenValidationError('expiresAt must be ISO-8601');
+      if (t <= Date.now()) throw new TokenValidationError('expiresAt must be in the future');
+    }
+    return this.withLock(async () => {
+      const tokens = this.load();
+      let tokenId: string;
+      do { tokenId = newTokenId(); }
+      while (tokens.some(t => t.tokenId === tokenId));
+      const secret = newSecret();
+      const token: IdentityToken = {
+        tokenId,
+        secretHash: hashSecret(secret),
+        username: input.username,
+        name: input.name.trim(),
+        createdAt: new Date().toISOString(),
+        ...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+      };
+      tokens.push(token);
+      this.save(tokens);
+      return {
+        token,
+        plaintextSecret: `${TOKEN_PREFIX}${tokenId}${TOKEN_WIRE_SEPARATOR}${secret}`,
+      };
+    });
+  }
+
+  async get(tokenId: string): Promise<IdentityToken | undefined> {
+    return this.load().find(t => t.tokenId === tokenId);
+  }
+
+  async list(filterUsername?: string): Promise<IdentityToken[]> {
+    const all = this.load();
+    if (filterUsername === undefined) return [...all];
+    return all.filter(t => t.username === filterUsername);
+  }
+
+  async revoke(tokenId: string): Promise<void> {
+    return this.withLock(async () => {
+      const tokens = this.load();
+      const idx = tokens.findIndex(t => t.tokenId === tokenId);
+      if (idx < 0) return; // idempotent
+      tokens.splice(idx, 1);
+      this.save(tokens);
+    });
+  }
+
+  async revokeAllForUser(username: string): Promise<number> {
+    return this.withLock(async () => {
+      const tokens = this.load();
+      const before = tokens.length;
+      const remaining = tokens.filter(t => t.username !== username);
+      if (remaining.length === before) return 0;
+      this.save(remaining);
+      return before - remaining.length;
+    });
+  }
+
+  async rename(tokenId: string, newName: string): Promise<IdentityToken | undefined> {
+    if (typeof newName !== 'string' || newName.trim().length === 0) {
+      throw new TokenValidationError('name required');
+    }
+    return this.withLock(async () => {
+      const tokens = this.load();
+      const idx = tokens.findIndex(t => t.tokenId === tokenId);
+      if (idx < 0) return undefined;
+      tokens[idx]!.name = newName.trim();
+      this.save(tokens);
+      return tokens[idx];
+    });
+  }
+
+  async validate(presented: string): Promise<TokenValidation> {
+    const parts = parseWire(presented);
+    if (!parts) return { ok: false, reason: 'malformed' };
+    const tokens = this.load();
+    const row = tokens.find(t => t.tokenId === parts.tokenId);
+    if (!row) return { ok: false, reason: 'not-found' };
+
+    const presentedHashBuf = Buffer.from(hashSecret(parts.secret), 'base64');
+    const storedHashBuf = Buffer.from(row.secretHash, 'base64');
+    if (presentedHashBuf.length !== storedHashBuf.length) {
+      return { ok: false, reason: 'not-found' };
+    }
+    if (!timingSafeEqual(presentedHashBuf, storedHashBuf)) {
+      return { ok: false, reason: 'not-found' };
+    }
+    if (isExpired(row)) return { ok: false, reason: 'expired', token: row };
+
+    // Touch lastUsedAt. Use the write queue so we don't race with mint/revoke.
+    const now = new Date().toISOString();
+    row.lastUsedAt = now;
+    void this.withLock(async () => {
+      const live = this.load();
+      const liveRow = live.find(t => t.tokenId === row.tokenId);
+      if (liveRow) {
+        liveRow.lastUsedAt = now;
+        this.save(live);
+      }
+    });
+
+    return { ok: true, token: row };
+  }
+
+  // ── private ─────────────────────────────────────────────────────────────
+
+  private load(): IdentityToken[] {
+    if (this.cache) return this.cache;
+    if (!existsSync(this.storePath)) {
+      this.cache = [];
+      return this.cache;
+    }
+    const raw = readFileSync(this.storePath, 'utf-8');
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      throw new Error(`tokens.json: invalid JSON at ${this.storePath}: ${(err as Error).message}`);
+    }
+    if (!Array.isArray(parsed)) {
+      throw new Error(`tokens.json: expected array at ${this.storePath}`);
+    }
+    this.cache = parsed as IdentityToken[];
+    return this.cache;
+  }
+
+  private save(tokens: IdentityToken[]): void {
+    mkdirSync(dirname(this.storePath), { recursive: true });
+    const tmp = this.storePath + '.tmp';
+    writeFileSync(tmp, JSON.stringify(tokens, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, this.storePath);
+    try { chmodSync(this.storePath, 0o600); } catch { /* best-effort */ }
+    this.cache = tokens;
+  }
+
+  private withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.writeQueue.then(fn);
+    this.writeQueue = run.then(() => undefined, () => undefined);
+    return run;
+  }
+}