@cordfuse/crosstalk 7.0.0-alpha.16 → 7.0.0-alpha.18

package/src/auth/users.ts

@@ -0,0 +1,267 @@
+// User store — username, name, scrypt-hashed passphrase, admin flag.
+//
+// Trust context: SERVICE. The service-user daemon owns /var/lib/llmux/users.json
+// and is the only thing that reads/writes it. Workers receive their
+// identity via env vars + token validation, not by reading the user store
+// directly.
+//
+// References:
+//   V2-SYSTEM-AUTH-DESIGN.md § "User model (v2)"
+//   V2-SYSTEM-AUTH-DESIGN.md § "Data plane (v2)" — users.json row
+//   V2-SYSTEM-AUTH-DESIGN.md § "Build plan" — Phase 3
+
+import { existsSync, readFileSync, writeFileSync, renameSync, chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
+
+export interface User {
+  /** Stable identifier. Application-layer only — does NOT need to match any OS user on the host.
+   *  Also the user's orch alias. Format: [a-z0-9_-]+ */
+  username: string;
+  /** Display name. */
+  name: string;
+  /** scrypt-hashed passphrase + salt + params. Plaintext never written. */
+  passphraseHash: string;
+  /** Admin can create/delete other users + mint tokens for them. */
+  admin: boolean;
+  /** ISO-8601. */
+  createdAt: string;
+}
+
+export interface CreateUserInput {
+  username: string;
+  name: string;
+  /** Plaintext — hashed by createUser before persistence. NEVER persisted. */
+  passphrase: string;
+  /** Defaults false. Only admins can set this. */
+  admin?: boolean;
+}
+
+export interface UserStore {
+  /** Create a new user. Validates username format + uniqueness + passphrase strength. */
+  createUser(input: CreateUserInput): Promise<User>;
+  /** Look up by username. Returns undefined if not present. */
+  getUser(username: string): Promise<User | undefined>;
+  /** List all users. Admin-callable; non-admin must filter to self. */
+  listUsers(): Promise<User[]>;
+  /** Update name. Username + admin status + passphrase have their own methods. */
+  updateName(username: string, newName: string): Promise<void>;
+  /** Replace the passphrase hash. Caller verifies the old one separately. */
+  setPassphrase(username: string, newPassphrase: string): Promise<void>;
+  /** Delete user record. Caller responsible for revoking tokens + reaping orch claims. */
+  deleteUser(username: string): Promise<void>;
+  /** Toggle admin flag. Caller enforces "can't demote yourself" / "last admin" rules. */
+  setAdmin(username: string, admin: boolean): Promise<void>;
+  /** Verify a candidate passphrase against the stored hash. */
+  verifyPassphrase(username: string, candidate: string): Promise<boolean>;
+  /** Whether ANY users exist. Used by the setup wizard to detect first-run. */
+  isEmpty(): Promise<boolean>;
+}
+
+// ── scrypt format ─────────────────────────────────────────────────────────
+// Self-describing string so we can tune N over time without breaking old
+// hashes. Format: `scrypt$<N>$<saltBase64>$<hashBase64>`.
+//
+// N=2^17 (131072) is the modern OWASP recommendation for interactive auth
+// (~100ms on commodity hardware). r=8, p=1 are scrypt's standard tuning.
+const SCRYPT_N = 1 << 17;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const SCRYPT_KEYLEN = 64;
+const SALT_BYTES = 16;
+// Memory required by scrypt is ≈ 128 * N * r bytes; for N=2^17 r=8 that's
+// ~128 MB. Node's default maxmem is 32 MB, so we raise it explicitly.
+const SCRYPT_MAXMEM = 256 * 1024 * 1024;
+
+function hashPassphrase(plain: string): string {
+  const salt = randomBytes(SALT_BYTES);
+  const hash = scryptSync(plain, salt, SCRYPT_KEYLEN, { N: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM });
+  return `scrypt$${SCRYPT_N}$${salt.toString('base64')}$${hash.toString('base64')}`;
+}
+
+function verifyHash(plain: string, stored: string): boolean {
+  const parts = stored.split('$');
+  if (parts.length !== 4 || parts[0] !== 'scrypt') return false;
+  const n = Number(parts[1]);
+  const salt = Buffer.from(parts[2]!, 'base64');
+  const expected = Buffer.from(parts[3]!, 'base64');
+  if (!Number.isInteger(n) || n <= 0 || salt.length === 0 || expected.length === 0) return false;
+  let candidate: Buffer;
+  try {
+    candidate = scryptSync(plain, salt, expected.length, { N: n, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM });
+  } catch {
+    return false;
+  }
+  if (candidate.length !== expected.length) return false;
+  return timingSafeEqual(candidate, expected);
+}
+
+// ── validation ────────────────────────────────────────────────────────────
+const USERNAME_RE = /^[a-z0-9_-]+$/;
+const USERNAME_MAX = 32;
+const PASSPHRASE_MIN = 8;
+
+export class UserValidationError extends Error {
+  constructor(message: string) { super(message); this.name = 'UserValidationError'; }
+}
+
+function validateUsername(username: string): void {
+  if (typeof username !== 'string' || username.length === 0) {
+    throw new UserValidationError('username required');
+  }
+  if (username.length > USERNAME_MAX) {
+    throw new UserValidationError(`username too long (max ${USERNAME_MAX})`);
+  }
+  if (!USERNAME_RE.test(username)) {
+    throw new UserValidationError('username must match [a-z0-9_-]+ (lowercase, no spaces)');
+  }
+}
+
+function validatePassphrase(passphrase: string): void {
+  if (typeof passphrase !== 'string' || passphrase.length < PASSPHRASE_MIN) {
+    throw new UserValidationError(`passphrase must be at least ${PASSPHRASE_MIN} characters`);
+  }
+}
+
+/**
+ * File-backed user store. Reads/writes /var/lib/llmux/users.json (or
+ * config.dataDir/users.json).
+ *
+ * Concurrency model: in-process mutex on writes (the daemon is single-process).
+ * Reads load + cache; writes invalidate the cache.
+ */
+export class FileUserStore implements UserStore {
+  private cache: User[] | undefined;
+  private writeQueue: Promise<void> = Promise.resolve();
+
+  constructor(private storePath: string) {}
+
+  async createUser(input: CreateUserInput): Promise<User> {
+    validateUsername(input.username);
+    validatePassphrase(input.passphrase);
+    if (typeof input.name !== 'string' || input.name.trim().length === 0) {
+      throw new UserValidationError('name required');
+    }
+    return this.withLock(async () => {
+      const users = this.load();
+      if (users.some(u => u.username === input.username)) {
+        throw new UserValidationError(`username '${input.username}' already exists`);
+      }
+      const user: User = {
+        username: input.username,
+        name: input.name.trim(),
+        passphraseHash: hashPassphrase(input.passphrase),
+        admin: input.admin === true,
+        createdAt: new Date().toISOString(),
+      };
+      users.push(user);
+      this.save(users);
+      return user;
+    });
+  }
+
+  async getUser(username: string): Promise<User | undefined> {
+    return this.load().find(u => u.username === username);
+  }
+
+  async listUsers(): Promise<User[]> {
+    return [...this.load()];
+  }
+
+  async updateName(username: string, newName: string): Promise<void> {
+    if (typeof newName !== 'string' || newName.trim().length === 0) {
+      throw new UserValidationError('name required');
+    }
+    return this.withLock(async () => {
+      const users = this.load();
+      const u = users.find(x => x.username === username);
+      if (!u) throw new UserValidationError(`user '${username}' not found`);
+      u.name = newName.trim();
+      this.save(users);
+    });
+  }
+
+  async setPassphrase(username: string, newPassphrase: string): Promise<void> {
+    validatePassphrase(newPassphrase);
+    return this.withLock(async () => {
+      const users = this.load();
+      const u = users.find(x => x.username === username);
+      if (!u) throw new UserValidationError(`user '${username}' not found`);
+      u.passphraseHash = hashPassphrase(newPassphrase);
+      this.save(users);
+    });
+  }
+
+  async deleteUser(username: string): Promise<void> {
+    return this.withLock(async () => {
+      const users = this.load();
+      const idx = users.findIndex(u => u.username === username);
+      if (idx < 0) throw new UserValidationError(`user '${username}' not found`);
+      users.splice(idx, 1);
+      this.save(users);
+    });
+  }
+
+  async setAdmin(username: string, admin: boolean): Promise<void> {
+    return this.withLock(async () => {
+      const users = this.load();
+      const u = users.find(x => x.username === username);
+      if (!u) throw new UserValidationError(`user '${username}' not found`);
+      u.admin = admin === true;
+      this.save(users);
+    });
+  }
+
+  async verifyPassphrase(username: string, candidate: string): Promise<boolean> {
+    const u = this.load().find(x => x.username === username);
+    if (!u) return false;
+    return verifyHash(candidate, u.passphraseHash);
+  }
+
+  async isEmpty(): Promise<boolean> {
+    return this.load().length === 0;
+  }
+
+  // ── private ─────────────────────────────────────────────────────────────
+
+  private load(): User[] {
+    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(`users.json: invalid JSON at ${this.storePath}: ${(err as Error).message}`);
+    }
+    if (!Array.isArray(parsed)) {
+      throw new Error(`users.json: expected array at ${this.storePath}`);
+    }
+    this.cache = parsed as User[];
+    return this.cache;
+  }
+
+  private save(users: User[]): void {
+    mkdirSync(dirname(this.storePath), { recursive: true });
+    const tmp = this.storePath + '.tmp';
+    writeFileSync(tmp, JSON.stringify(users, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, this.storePath);
+    try { chmodSync(this.storePath, 0o600); } catch { /* best-effort */ }
+    this.cache = users;
+  }
+
+  /**
+   * Serialize writes through a single promise chain. The daemon is
+   * single-process so we don't need cross-process locking, but two
+   * concurrent createUser calls in the same process would otherwise
+   * race on load/save.
+   */
+  private withLock<T>(fn: () => Promise<T>): Promise<T> {
+    const run = this.writeQueue.then(fn);
+    this.writeQueue = run.then(() => undefined, () => undefined);
+    return run;
+  }
+}

package/src/channel.ts

@@ -0,0 +1,202 @@
+// crosstalkd channel — channel operations.
+//
+// Three operations on one subcommand (V7-SPEC §7):
+//   crosstalkd channel <name>                            — create
+//   crosstalkd channel <name-or-uuid> --rename <new>     — rename
+//   crosstalkd channel <name-or-uuid> --delete           — hard delete (typed-name confirmation)
+//
+// No archive, no restore, no purge, no --force. History stays in git log
+// if recovery is ever needed.
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'fs';
+import { resolve, join } from 'path';
+import { randomUUID } from 'crypto';
+import { spawnSync } from 'child_process';
+import { parseFrontmatter, serializeFrontmatter } from './frontmatter.js';
+import { gitCommitAndPush, discoverChannels } from './transport.js';
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+interface ChannelMeta {
+  uuid: string;
+  name: string | null;
+  parent: string | null;
+}
+
+function readChannelMeta(uuid: string): ChannelMeta {
+  const chPath = join(transportRoot, 'data', 'channels', uuid, 'CHANNEL.md');
+  if (!existsSync(chPath)) return { uuid, name: null, parent: null };
+  const raw = readFileSync(chPath, 'utf-8');
+  const { data } = parseFrontmatter<{ name?: unknown; parent?: unknown }>(raw);
+  return {
+    uuid,
+    name: typeof data.name === 'string' ? data.name : null,
+    parent: typeof data.parent === 'string' ? data.parent : null,
+  };
+}
+
+function allChannelMeta(): ChannelMeta[] {
+  return discoverChannels(transportRoot).map(readChannelMeta);
+}
+
+function resolveChannel(input: string): ChannelMeta | null {
+  if (UUID_RE.test(input)) {
+    const path = join(transportRoot, 'data', 'channels', input);
+    if (!existsSync(path)) return null;
+    return readChannelMeta(input);
+  }
+  for (const meta of allChannelMeta()) {
+    if (meta.name === input) return meta;
+  }
+  return null;
+}
+
+function nameExists(name: string): boolean {
+  return allChannelMeta().some((m) => m.name === name);
+}
+
+function commit(message: string): void {
+  const r = gitCommitAndPush(transportRoot, message);
+  if (!r.ok && r.error) {
+    console.error(`git ${r.committed ? 'push' : 'commit'} FAILED: ${r.error.slice(0, 300)}`);
+    process.exit(3);
+  }
+}
+
+function create(name: string): void {
+  if (UUID_RE.test(name)) {
+    console.error(`crosstalkd channel: '${name}' looks like a UUID — channel names cannot be UUID-shaped.`);
+    process.exit(1);
+  }
+  if (nameExists(name)) {
+    console.error(`crosstalkd channel: a channel named '${name}' already exists.`);
+    process.exit(1);
+  }
+  const uuid = randomUUID();
+  const dir = join(transportRoot, 'data', 'channels', uuid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'CHANNEL.md'), serializeFrontmatter({ name }, ''));
+  commit(`channel(create): ${name} (${uuid.slice(0, 8)})`);
+  console.log(`Created channel: ${uuid}`);
+  console.log(`  name: ${name}`);
+}
+
+function rename(input: string, newName: string): void {
+  if (UUID_RE.test(newName)) {
+    console.error(`crosstalkd channel: '${newName}' looks like a UUID — channel names cannot be UUID-shaped.`);
+    process.exit(1);
+  }
+  const meta = resolveChannel(input);
+  if (!meta) {
+    console.error(`crosstalkd channel: '${input}' not found.`);
+    process.exit(1);
+  }
+  if (meta.name === newName) {
+    console.log(`crosstalkd channel: '${meta.name}' already has that name — no-op.`);
+    return;
+  }
+  if (nameExists(newName)) {
+    console.error(`crosstalkd channel: a channel named '${newName}' already exists.`);
+    process.exit(1);
+  }
+  const chPath = join(transportRoot, 'data', 'channels', meta.uuid, 'CHANNEL.md');
+  const fm: Record<string, unknown> = { name: newName };
+  if (meta.parent) fm['parent'] = meta.parent;
+  writeFileSync(chPath, serializeFrontmatter(fm, ''));
+  commit(`channel(rename): ${meta.name ?? '(unnamed)'} -> ${newName} (${meta.uuid.slice(0, 8)})`);
+  console.log(`Renamed: ${meta.name ?? '(unnamed)'} -> ${newName}`);
+}
+
+function readStdinLine(): string {
+  try {
+    const raw = readFileSync(0, 'utf-8');
+    return raw.split('\n')[0]!.trim();
+  } catch {
+    return '';
+  }
+}
+
+function del(input: string): void {
+  const meta = resolveChannel(input);
+  if (!meta) {
+    console.error(`crosstalkd channel: '${input}' not found.`);
+    process.exit(1);
+  }
+  const displayName = meta.name ?? '(unnamed)';
+  const confirmTarget = meta.name ?? meta.uuid;
+
+  // If stdin is a TTY, prompt; otherwise read one line of piped input.
+  // Either way, the user/script must type the name back to confirm.
+  if (process.stdin.isTTY) {
+    process.stderr.write(
+      `type "${confirmTarget}" to confirm deletion of channel ${displayName} (${meta.uuid}): `,
+    );
+    // Naive blocking read of one line via spawnSync — bun + tsx don't
+    // expose a clean blocking readline in pure ESM.
+    const r = spawnSync('sh', ['-c', 'IFS= read -r line; echo "$line"'], { stdio: ['inherit', 'pipe', 'inherit'] });
+    const typed = (r.stdout?.toString() ?? '').trim();
+    if (typed !== confirmTarget) {
+      console.error('crosstalkd channel: confirmation mismatch; nothing deleted.');
+      process.exit(1);
+    }
+  } else {
+    const typed = readStdinLine();
+    if (typed !== confirmTarget) {
+      console.error(`crosstalkd channel: confirmation mismatch (expected '${confirmTarget}', got '${typed}'); nothing deleted.`);
+      process.exit(1);
+    }
+  }
+
+  const dir = join(transportRoot, 'data', 'channels', meta.uuid);
+  rmSync(dir, { recursive: true, force: true });
+  commit(`channel(delete): ${displayName} (${meta.uuid.slice(0, 8)})`);
+  console.log(`Deleted channel: ${displayName} (${meta.uuid})`);
+}
+
+// arg parsing — find the positional (first arg not starting with --, not the
+// value of a flag we recognise).
+const flagsTakingValue = new Set(['--rename']);
+let positional: string | undefined;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i]!;
+  if (a.startsWith('--')) {
+    if (flagsTakingValue.has(a)) i++;
+    continue;
+  }
+  positional = a;
+  break;
+}
+
+const renameTarget = flag('--rename');
+const deleteMode = argv.includes('--delete');
+
+if (!positional) {
+  console.error('Usage:');
+  console.error('  crosstalkd channel <name>                            # create');
+  console.error('  crosstalkd channel <name-or-uuid> --rename <new>     # rename');
+  console.error('  crosstalkd channel <name-or-uuid> --delete           # hard delete (typed-name confirmation)');
+  process.exit(1);
+}
+
+const channelsDir = join(transportRoot, 'data', 'channels');
+if (!existsSync(channelsDir)) mkdirSync(channelsDir, { recursive: true });
+
+if (renameTarget && deleteMode) {
+  console.error('crosstalkd channel: --rename and --delete are mutually exclusive.');
+  process.exit(1);
+} else if (renameTarget) {
+  rename(positional, renameTarget);
+} else if (deleteMode) {
+  del(positional);
+} else {
+  create(positional);
+}