studiograph 1.3.47 → 1.3.48-beta.0

package/dist/services/auth-service.js

@@ -5,63 +5,339 @@
  * Database lives at .studiograph/auth.db inside the workspace.
  *
  * Auth state is portable via .studiograph/auth-seed.json — a JSON export of
- * all users (with bcrypt hashes) and the JWT secret. The seed file is
- * committed to the config repo so it syncs between local and Railway:
+ * all users (with bcrypt hashes) and the JWT signing secret. The seed file
+ * is committed to the config repo so it syncs between local and Railway:
  *   local setup → commit → push → Railway redeploy → users restored from seed
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * SECURITY — config repo is a secret store
+ * ─────────────────────────────────────────────────────────────────────────
+ * `auth-seed.json` carries:
+ *   • the JWT signing secret (anyone holding this can mint sessions for any
+ *     user in the workspace, bypassing password auth entirely)
+ *   • bcrypt password hashes for every user (offline-crackable; bcrypt cost
+ *     12 buys time but not invulnerability against weak passwords)
+ *
+ * Treat the .studiograph/ config repo with the same operational care as any
+ * other secret store: private remote, restricted contributors, never made
+ * public. The audit (2026-05) flagged this surface specifically — `getSeedData`
+ * returns these fields by design (they're how the seed-restore flow works on
+ * Railway redeploys) but every caller needs to understand they are exporting
+ * raw secrets.
+ *
+ * To override the file-based JWT secret in production (e.g. Railway), set
+ * the STUDIOGRAPH_JWT_SECRET environment variable. The env var wins over the
+ * `auth-secret` file and the seed file: a leaked seed file alone won't let
+ * an attacker mint tokens for an environment with a different in-process
+ * secret. Rotation: change the env var and restart — all extant tokens
+ * invalidate together.
  */
 import Database from 'better-sqlite3';
 import bcrypt from 'bcryptjs';
 import jwt from 'jsonwebtoken';
-import { randomBytes } from 'crypto';
+import { randomBytes, createHash } from 'crypto';
 import { spawnSync } from 'child_process';
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync, chmodSync } from 'fs';
 import { join } from 'path';
+import { pickDefaultAccentColor } from '../core/accent-palette.js';
+import { sanitizeAuthSeed } from '../core/secrets/bundle.js';
+import { assertAuthDbConsistent, decryptOAuthTokenData, decryptUserPreferencesSettings, encryptOAuthTokenData, encryptUserPreferencesSettings, isAuthDbPhase8Migrated, markAuthDbPhase8Migrated, } from '../core/secrets/auth-db-migration.js';
+import { sanitize } from '../server/middleware/sanitize.js';
+import { createOAuthStateSigner, deriveStateSigningKey, } from '../mcp/state-signer.js';
+import { log } from '../utils/log.js';
+/**
+ * Resolve the JWT signing secret. Priority order:
+ *   1. STUDIOGRAPH_JWT_SECRET env var — production override; not committed,
+ *      not on disk, can rotate by restarting the process.
+ *   2. .studiograph/auth-secret file — local-dev / single-host stable secret.
+ *   3. auth-seed.json's `jwtSecret` field — restored from a portable seed.
+ *   4. Freshly generated 32-byte random — first-run fallback; written to
+ *      auth-secret so subsequent restarts pick path 2.
+ *
+ * Phase 4: production (RAILWAY_ENVIRONMENT set) MUST hit path 1. The
+ * file/seed/generated fallbacks are local-dev only — a misconfigured
+ * Railway service should fail loud rather than silently mint a fresh
+ * secret per restart (which would invalidate every active session and
+ * mask the misconfiguration).
+ *
+ * Returns the secret AND the source so the caller can log/operator-visible
+ * which path won (without leaking the secret itself).
+ */
+function resolveJwtSecret(sgDir) {
+    // 1. Env var wins. Trim — accidental newline at the end of `secret > file`
+    // happens often enough that we shouldn't punish operators for it.
+    const envSecret = process.env.STUDIOGRAPH_JWT_SECRET?.trim();
+    if (envSecret) {
+        if (envSecret.length < 16) {
+            // Refuse comically weak secrets so an operator who set
+            // STUDIOGRAPH_JWT_SECRET=hunter2 doesn't accidentally weaken the
+            // workspace versus the auto-generated 64-hex-char fallback.
+            throw new Error('STUDIOGRAPH_JWT_SECRET is set but too short (need ≥16 chars). ' +
+                'Generate one with: openssl rand -hex 32');
+        }
+        return { secret: envSecret, source: 'env' };
+    }
+    // Phase 4 production gate. File/seed/generated paths below are local-dev
+    // only; a Railway deploy reaching them indicates the backfill missed this
+    // service (or someone unset the var). Hard-fail so an operator notices
+    // immediately instead of silently rotating the JWT on every restart.
+    if (process.env.RAILWAY_ENVIRONMENT) {
+        throw new Error('auth: STUDIOGRAPH_JWT_SECRET is required in production (RAILWAY_ENVIRONMENT is set). ' +
+            'Generate one with: openssl rand -hex 32 — then set on the Railway service. ' +
+            'Use scripts/backfill-railway-secrets.ts to provision across all services.');
+    }
+    // 2. On-disk secret file (local-dev path).
+    const secretPath = join(sgDir, 'auth-secret');
+    if (existsSync(secretPath)) {
+        return { secret: readFileSync(secretPath, 'utf-8').trim(), source: 'file' };
+    }
+    // 3. Seed file may have been imported just before us (applySeed path).
+    const seedPath = join(sgDir, 'auth-seed.json');
+    if (existsSync(seedPath)) {
+        try {
+            const seed = JSON.parse(readFileSync(seedPath, 'utf-8'));
+            if (typeof seed.jwtSecret === 'string' && seed.jwtSecret.length >= 16) {
+                // Persist to auth-secret so subsequent boots pick the file path
+                // without re-parsing the seed JSON.
+                writeFileSync(secretPath, seed.jwtSecret, { mode: 0o600 });
+                return { secret: seed.jwtSecret, source: 'seed' };
+            }
+        }
+        catch { /* fall through to generation */ }
+    }
+    // 4. First-run: generate and persist. 32 bytes of entropy = 64-char hex.
+    const generated = randomBytes(32).toString('hex');
+    writeFileSync(secretPath, generated, { mode: 0o600 });
+    return { secret: generated, source: 'generated' };
+}
+/**
+ * Warn loudly if `auth-seed.json` is world-readable. Anyone with read access
+ * to the file holds the workspace's JWT secret + bcrypt hashes; on a shared
+ * host that's an instant credential-store leak. We can't `chmod` it ourselves
+ * because the user may want their checkout group-readable for collaborators —
+ * but we WILL tell them the risk.
+ *
+ * Idempotent: the warning prints at boot once. Posix only — Windows mode bits
+ * don't carry the same meaning, so we skip there.
+ */
+function warnIfSeedWorldReadable(sgDir) {
+    if (process.platform === 'win32')
+        return;
+    const seedPath = join(sgDir, 'auth-seed.json');
+    if (!existsSync(seedPath))
+        return;
+    try {
+        const mode = statSync(seedPath).mode;
+        // Other-readable bit (S_IROTH = 0o004).
+        if ((mode & 0o004) !== 0) {
+            log.warn(`[auth] WARNING: ${seedPath} is world-readable (mode ${(mode & 0o777).toString(8)}). ` +
+                'It contains the JWT signing secret and bcrypt password hashes — anyone with ' +
+                'read access to this file can impersonate workspace users. Attempting chmod 600...');
+            // Best-effort tightening. The seed lives inside the .studiograph/ git
+            // repo; a fresh `git checkout` restores files at 0644 by default. Trying
+            // to fix it on every boot is harmless (already-0600 is a no-op) and
+            // defends against the most common leak path. NEVER throw — this is a
+            // boot-time hygiene step, not a hard gate.
+            try {
+                chmodSync(seedPath, 0o600);
+            }
+            catch { /* non-fatal */ }
+        }
+    }
+    catch { /* stat failure is non-fatal */ }
+}
+/** Check if a user has workspace-owner privileges. */
+export function isWorkspaceOwner(role) {
+    return role === 'owner';
+}
 const BCRYPT_ROUNDS = 12;
 const JWT_EXPIRY = '7d';
+function hashToken(token) {
+    return createHash('sha256').update(token).digest('hex');
+}
+/**
+ * Slug-ify a name into a handle candidate. Lowercases, strips combining
+ * diacritics, replaces non-alphanumerics with hyphens, trims edge hyphens.
+ * Falls back to 'user' if the input has nothing usable (emoji-only, etc.) —
+ * the caller is responsible for ensuring uniqueness via collision suffix.
+ */
+function slugifyHandle(name) {
+    const cleaned = name
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return cleaned || 'user';
+}
 export class AuthService {
     db;
     jwtSecret;
-    apiKey;
     sgDir;
-    constructor(workspacePath) {
+    crypto;
+    /**
+     * True once we've confirmed `data_ciphertext` exists on `oauth_tokens`
+     * (post-migration shape). The encrypted code path keys off this rather
+     * than re-running PRAGMA on every call.
+     */
+    oauthTokensEncrypted = false;
+    /** True once `settings_ciphertext` is available on `user_preferences`. */
+    userPrefsEncrypted = false;
+    /**
+     * Listeners for OAuth-token mutations. Fires after `saveOAuthData` or
+     * `clearOAuthData` lands a row. Used by the agent orchestrator to evict
+     * the user's pooled agent so the next chat builds a fresh tool list
+     * that reflects the new per-user connector state (otherwise the agent
+     * keeps the toolset it had at first session creation, missing any
+     * connector the user just OAuthed). Mirrors the `onSecretMutation`
+     * pattern in `src/core/secrets/index.ts`.
+     *
+     * Listener errors are swallowed — never let a stray subscriber take
+     * down the OAuth write path.
+     */
+    oauthMutationListeners = new Set();
+    /**
+     * OAuth state signer. Initialized lazily from the master key (HKDF-derived,
+     * domain-separated from the AEAD key). When `cryptoOpts` is missing — e.g.
+     * tests that don't exercise the OAuth init/callback paths — sign/verify
+     * throw on use rather than silently falling back to unsigned state.
+     */
+    oauthStateSigner = null;
+    constructor(workspacePath, cryptoOpts) {
         this.sgDir = join(workspacePath, '.studiograph');
+        this.crypto = cryptoOpts;
+        if (cryptoOpts) {
+            const key = deriveStateSigningKey(cryptoOpts.masterKey);
+            this.oauthStateSigner = createOAuthStateSigner(key);
+        }
         if (!existsSync(this.sgDir)) {
             mkdirSync(this.sgDir, { recursive: true });
         }
         // Open/create SQLite database
         const dbPath = join(this.sgDir, 'auth.db');
         this.db = new Database(dbPath);
+        // Tighten file mode immediately after open. The DB embeds the JWT signing
+        // secret-equivalent (bcrypt hashes + per-user OAuth tokens via
+        // oauth_tokens.data_json) — leaving it 0644 on a shared host is an
+        // instant-credential-leak vector. Posix only; Windows ACLs differ.
+        if (process.platform !== 'win32') {
+            try {
+                chmodSync(dbPath, 0o600);
+            }
+            catch { /* non-fatal */ }
+        }
         this.db.pragma('journal_mode = WAL');
-        // Create users table
+        // Create users table. CHECK tolerates legacy 'admin' rows so existing
+        // databases don't error on load; app code only ever writes 'owner' or
+        // 'member' going forward.
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS users (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         email TEXT UNIQUE NOT NULL,
+        handle TEXT UNIQUE NOT NULL,
         password_hash TEXT NOT NULL,
         display_name TEXT NOT NULL,
-        role TEXT NOT NULL DEFAULT 'member' CHECK(role IN ('admin', 'member')),
+        role TEXT NOT NULL DEFAULT 'member' CHECK(role IN ('owner', 'admin', 'member')),
         created_at TEXT NOT NULL DEFAULT (datetime('now')),
         updated_at TEXT NOT NULL DEFAULT (datetime('now'))
       )
     `);
-        // Create collection_access table for per-collection permissions
+        // Migration: backfill `handle` on databases created before commit 26d3d6f9
+        // (Apr 25 2026). The original commit said "wipe manually" — fine for dev,
+        // but Railway tenants can't be wiped without losing data. Idempotent:
+        // ALTER fails harmlessly when the column already exists, and the
+        // backfill loop only touches NULL rows.
+        const userCols = this.db.prepare("PRAGMA table_info(users)").all();
+        if (!userCols.some(c => c.name === 'handle')) {
+            this.db.exec("ALTER TABLE users ADD COLUMN handle TEXT");
+            const needHandle = this.db.prepare("SELECT id, display_name, email FROM users WHERE handle IS NULL").all();
+            const update = this.db.prepare("UPDATE users SET handle = ? WHERE id = ?");
+            const seen = new Set();
+            for (const row of needHandle) {
+                const baseSource = row.display_name?.trim() || row.email.split('@')[0];
+                let candidate = slugifyHandle(baseSource);
+                if (seen.has(candidate)) {
+                    for (let n = 2; n < 1000; n++) {
+                        const next = `${candidate}-${n}`;
+                        if (!seen.has(next)) {
+                            candidate = next;
+                            break;
+                        }
+                    }
+                }
+                seen.add(candidate);
+                update.run(candidate, row.id);
+            }
+            // App code expects UNIQUE; a unique index gives us that without
+            // recreating the table.
+            try {
+                this.db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_users_handle ON users(handle)");
+            }
+            catch { /* ignore */ }
+        }
+        // Create folder_access table for per-folder membership + role (admin | editor).
+        // `folder_name` stores the repo slug — the underlying git-backed container
+        // is still called a repo internally; the column value equals the repo name.
         this.db.exec(`
-      CREATE TABLE IF NOT EXISTS collection_access (
+      CREATE TABLE IF NOT EXISTS folder_access (
         user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
-        collection_name TEXT NOT NULL,
+        folder_name TEXT NOT NULL,
+        role TEXT NOT NULL DEFAULT 'editor',
         created_at TEXT NOT NULL DEFAULT (datetime('now')),
-        PRIMARY KEY (user_id, collection_name)
+        PRIMARY KEY (user_id, folder_name)
       )
     `);
-        // Per-user OAuth tokens for MCP connectors
+        // Per-user OAuth tokens for MCP connectors.
+        //
+        // Phase 8: `data_json` is nullable on freshly-provisioned DBs because
+        // encrypted values land in `data_ciphertext` instead. Pre-existing
+        // databases were created with `data_json TEXT NOT NULL`; the Phase 8
+        // migration (`auth-db-migration.ts`) rebuilds the table to relax that
+        // constraint. CREATE TABLE IF NOT EXISTS is a no-op on those — the
+        // migrate path handles them.
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS oauth_tokens (
         user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
         connector_name TEXT NOT NULL,
-        data_json TEXT NOT NULL,
+        data_json TEXT,
+        data_ciphertext TEXT,
+        key_version TEXT,
         updated_at TEXT NOT NULL DEFAULT (datetime('now')),
         PRIMARY KEY (user_id, connector_name)
       )
+    `);
+        // Defensive: on a pre-migration DB the table was created without the
+        // ciphertext columns, but the migration may not yet have run (tests
+        // construct AuthService directly without the boot path). Add them
+        // idempotently so the read/write paths can branch on column presence.
+        {
+            const oauthCols = this.db.prepare("PRAGMA table_info(oauth_tokens)").all();
+            if (!oauthCols.some(c => c.name === 'data_ciphertext')) {
+                try {
+                    this.db.exec("ALTER TABLE oauth_tokens ADD COLUMN data_ciphertext TEXT");
+                }
+                catch { /* idempotent */ }
+            }
+            if (!oauthCols.some(c => c.name === 'key_version')) {
+                try {
+                    this.db.exec("ALTER TABLE oauth_tokens ADD COLUMN key_version TEXT");
+                }
+                catch { /* idempotent */ }
+            }
+            this.oauthTokensEncrypted = true;
+        }
+        // Per-user API tokens. Used by MCP clients (HTTP and stdio) so every
+        // call carries a real user identity and access control can be enforced.
+        // Only the sha256 hash is stored — the raw token is shown once at mint.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS api_tokens (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+        token_hash TEXT NOT NULL UNIQUE,
+        name TEXT NOT NULL,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        last_used_at TEXT
+      )
     `);
         // Per-user saved views
         this.db.exec(`
@@ -72,51 +348,122 @@ export class AuthService {
         view_type TEXT NOT NULL DEFAULT 'list',
         config_json TEXT NOT NULL DEFAULT '{}',
         sort_order INTEGER NOT NULL DEFAULT 0,
+        visibility TEXT NOT NULL DEFAULT 'private',
+        created_by_name TEXT,
         created_at TEXT NOT NULL DEFAULT (datetime('now')),
         updated_at TEXT NOT NULL DEFAULT (datetime('now'))
       )
     `);
-        // Per-user preferences (home brief, cached insights, accent color)
+        // Migration: add columns if missing (existing databases)
+        try {
+            this.db.exec(`ALTER TABLE user_views ADD COLUMN visibility TEXT NOT NULL DEFAULT 'private'`);
+        }
+        catch { }
+        try {
+            this.db.exec(`ALTER TABLE user_views ADD COLUMN created_by_name TEXT`);
+        }
+        catch { }
+        // Workspace-shared views (folder-views redesign). Scope-keyed, one per
+        // (scope, view_type), no per-user column — everyone sees the same set.
+        // Fresh table: born here via CREATE TABLE IF NOT EXISTS, no migration.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS workspace_views (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        scope TEXT NOT NULL,
+        view_type TEXT NOT NULL,
+        config_json TEXT NOT NULL DEFAULT '{}',
+        position INTEGER NOT NULL DEFAULT 0,
+        name TEXT,
+        created_by TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+        UNIQUE(scope, view_type)
+      )
+    `);
+        // Per-user preferences (accent color, onboarding flag, meeting-capture settings)
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS user_preferences (
         user_id INTEGER PRIMARY KEY DEFAULT 0,
-        home_brief TEXT NOT NULL DEFAULT '',
         accent_color TEXT,
-        insights_json TEXT NOT NULL DEFAULT '[]',
-        insights_generated_at TEXT,
         updated_at TEXT NOT NULL DEFAULT (datetime('now'))
       )
     `);
-        // Migration: add accent_color column if missing (existing installs)
+        // Migration: add columns if missing (existing installs)
         const cols = this.db.prepare("PRAGMA table_info(user_preferences)").all();
         if (!cols.some(c => c.name === 'accent_color')) {
             this.db.exec("ALTER TABLE user_preferences ADD COLUMN accent_color TEXT");
         }
+        if (!cols.some(c => c.name === 'onboarded')) {
+            this.db.exec("ALTER TABLE user_preferences ADD COLUMN onboarded INTEGER NOT NULL DEFAULT 0");
+        }
+        // Meeting capture: per-user settings stored as JSON (deepgram key, calendar tokens, default folder)
+        if (!cols.some(c => c.name === 'settings_json')) {
+            this.db.exec("ALTER TABLE user_preferences ADD COLUMN settings_json TEXT NOT NULL DEFAULT '{}'");
+        }
+        // Phase 8: split user_preferences.settings_json by classification —
+        // `user-secret` keys land in the encrypted column. Migration handles
+        // pre-existing rows; here we just make sure the columns exist so
+        // fresh DBs can use the new code path immediately.
+        if (!cols.some(c => c.name === 'settings_ciphertext')) {
+            try {
+                this.db.exec("ALTER TABLE user_preferences ADD COLUMN settings_ciphertext TEXT");
+            }
+            catch { /* idempotent */ }
+        }
+        if (!cols.some(c => c.name === 'key_version')) {
+            try {
+                this.db.exec("ALTER TABLE user_preferences ADD COLUMN key_version TEXT");
+            }
+            catch { /* idempotent */ }
+        }
+        this.userPrefsEncrypted = true;
         this.db.pragma('foreign_keys = ON');
+        // Half-state guard. If a previous run committed partial migration
+        // state (rows with both data_json AND data_ciphertext populated),
+        // refuse to start. Better to fail-fast than silently serve corrupt
+        // OAuth data. See auth-db-migration.ts for the migration's own
+        // transactional safety net — this is the last-resort detector.
+        assertAuthDbConsistent(this.db);
+        // On a fresh DB (no pre-existing rows in either secret-carrying
+        // table) we can mark Phase 8 as already migrated, so a later
+        // `migrateAuthDbPhase8` invocation short-circuits. This matters for
+        // the test path and for first-run installs where no legacy data
+        // ever existed.
+        if (this.crypto && !isAuthDbPhase8Migrated(this.db)) {
+            const hasOauthRows = this.db.prepare('SELECT COUNT(*) AS n FROM oauth_tokens').get().n > 0;
+            const hasSecretPrefRows = this.db.prepare(`SELECT COUNT(*) AS n FROM user_preferences WHERE settings_json IS NOT NULL AND settings_json != '' AND settings_json != '{}'`).get().n > 0;
+            if (!hasOauthRows && !hasSecretPrefRows) {
+                markAuthDbPhase8Migrated(this.db);
+            }
+        }
         // Ensure auth.db and auth-secret are gitignored (only seed file should be committed)
         this.ensureGitignore();
-        // If DB is empty, try restoring from seed file (synced via config repo)
+        // If DB is empty, try restoring from seed file (synced via config repo).
+        // Best-effort during boot — a corrupt or partial seed shouldn't prevent
+        // the server from starting. Explicit pull/import callers still get the
+        // throw and can surface the error to the user.
         if (!this.hasUsers()) {
-            this.applySeed();
-        }
-        // Load or generate JWT secret (seed import may have set it)
-        const secretPath = join(this.sgDir, 'auth-secret');
-        if (existsSync(secretPath)) {
-            this.jwtSecret = readFileSync(secretPath, 'utf-8').trim();
-        }
-        else {
-            this.jwtSecret = randomBytes(32).toString('hex');
-            writeFileSync(secretPath, this.jwtSecret, { mode: 0o600 });
+            try {
+                this.applySeed();
+            }
+            catch { /* already logged inside applySeed */ }
         }
-        // Load or generate API key (seed import may have set it)
-        const apiKeyPath = join(this.sgDir, 'api-keys');
-        if (existsSync(apiKeyPath)) {
-            this.apiKey = readFileSync(apiKeyPath, 'utf-8').trim();
+        // Load JWT secret. Priority: env var > auth-secret file > seed file >
+        // freshly generated. The env-var path lets production deployments
+        // (Railway, etc.) hold the signing secret outside the config repo, so a
+        // leaked auth-seed.json is not by itself a session-forgery risk for
+        // that environment. See resolveJwtSecret for the full ordering.
+        const resolved = resolveJwtSecret(this.sgDir);
+        this.jwtSecret = resolved.secret;
+        if (resolved.source === 'env') {
+            log.info('[auth] JWT secret loaded from STUDIOGRAPH_JWT_SECRET env var');
         }
-        else {
-            this.apiKey = randomBytes(32).toString('hex');
-            writeFileSync(apiKeyPath, this.apiKey, { mode: 0o600 });
+        else if (resolved.source === 'generated') {
+            log.info('[auth] JWT secret generated (first run)');
         }
+        // One-shot operator warning if the seed file is world-readable. Loud
+        // because the file embeds the signing secret + bcrypt hashes.
+        warnIfSeedWorldReadable(this.sgDir);
     }
     createUser(email, password, displayName, role = 'member') {
         const normalized = email.toLowerCase().trim();
@@ -127,17 +474,67 @@ export class AuthService {
             throw new Error('Password must be at least 8 characters');
         }
         const hash = bcrypt.hashSync(password, BCRYPT_ROUNDS);
-        const stmt = this.db.prepare('INSERT INTO users (email, password_hash, display_name, role) VALUES (?, ?, ?, ?)');
-        const result = stmt.run(normalized, hash, displayName.trim(), role);
+        const handle = this.allocateHandle(displayName);
+        const stmt = this.db.prepare('INSERT INTO users (email, handle, password_hash, display_name, role) VALUES (?, ?, ?, ?, ?)');
+        const result = stmt.run(normalized, handle, hash, displayName.trim(), role);
+        const userId = result.lastInsertRowid;
+        // Assign a default avatar accent color so the user shows up distinct
+        // across presence / member lists immediately, without having to open
+        // their profile.
+        this.setAccentColor(userId, pickDefaultAccentColor(userId));
         this.exportSeed();
         return {
-            id: result.lastInsertRowid,
+            id: userId,
             email: normalized,
+            handle,
             displayName: displayName.trim(),
             role,
             createdAt: new Date().toISOString(),
         };
     }
+    upsertCloudManagedUser(input) {
+        const normalized = input.email.toLowerCase().trim();
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized)) {
+            throw new Error('Invalid email address');
+        }
+        const displayName = input.displayName.trim() || normalized.split('@')[0];
+        const existing = this.findUserByEmail(normalized);
+        if (!existing) {
+            const unguessablePassword = randomBytes(32).toString('base64url');
+            return this.createUser(normalized, unguessablePassword, displayName, input.role);
+        }
+        const nextRole = existing.role === 'owner' ? 'owner' : input.role;
+        this.db.prepare(`
+      UPDATE users
+      SET display_name = ?,
+          role = ?,
+          updated_at = datetime('now')
+      WHERE id = ?
+    `).run(displayName, nextRole, existing.id);
+        this.exportSeed();
+        return this.findUserById(existing.id);
+    }
+    /**
+     * Pick a unique handle by slugifying the display name (or email local-part
+     * fallback) and appending `-2`, `-3`, … on collision. Handles are immutable
+     * once assigned, so we don't have to worry about two parallel inserts
+     * racing — SQLite's UNIQUE constraint will reject the loser and the caller
+     * can retry.
+     */
+    allocateHandle(displayName) {
+        const base = slugifyHandle(displayName.trim());
+        const exists = this.db.prepare('SELECT 1 FROM users WHERE handle = ? LIMIT 1');
+        if (!exists.get(base))
+            return base;
+        for (let suffix = 2; suffix < 1000; suffix++) {
+            const candidate = `${base}-${suffix}`;
+            if (!exists.get(candidate))
+                return candidate;
+        }
+        // Pathological: 1000 collisions on the same slug. Fall back to a random
+        // tail so we don't block account creation.
+        return `${base}-${randomBytes(3).toString('hex')}`;
+    }
     authenticate(email, password) {
         const normalized = email.toLowerCase().trim();
         const row = this.db.prepare('SELECT * FROM users WHERE email = ?').get(normalized);
@@ -145,9 +542,12 @@ export class AuthService {
             return null;
         }
         const user = this.toAuthUser(row);
-        const token = jwt.sign({ userId: user.id, email: user.email, role: user.role }, this.jwtSecret, { expiresIn: JWT_EXPIRY });
+        const token = this.createSessionToken(user);
         return { user, token };
     }
+    createSessionToken(user) {
+        return jwt.sign({ userId: user.id, email: user.email, role: user.role }, this.jwtSecret, { expiresIn: JWT_EXPIRY });
+    }
     verifyToken(token) {
         try {
             const payload = jwt.verify(token, this.jwtSecret);
@@ -158,6 +558,21 @@ export class AuthService {
             return null;
         }
     }
+    findUserById(userId) {
+        const row = this.db.prepare('SELECT * FROM users WHERE id = ?').get(userId);
+        return row ? this.toAuthUser(row) : null;
+    }
+    /** Look up a user by their stable handle (e.g. `christian-marc-schmidt`). */
+    findUserByHandle(handle) {
+        const row = this.db.prepare('SELECT * FROM users WHERE handle = ?').get(handle);
+        return row ? this.toAuthUser(row) : null;
+    }
+    /** Look up a user by email (case-insensitive). */
+    findUserByEmail(email) {
+        const normalized = email.toLowerCase().trim();
+        const row = this.db.prepare('SELECT * FROM users WHERE email = ?').get(normalized);
+        return row ? this.toAuthUser(row) : null;
+    }
     listUsers() {
         const rows = this.db.prepare('SELECT * FROM users ORDER BY created_at ASC').all();
         return rows.map(r => this.toAuthUser(r));
@@ -169,6 +584,58 @@ export class AuthService {
             this.exportSeed();
         return result.changes > 0;
     }
+    /**
+     * Before deleting `targetUserId`, transfer folder-admin rights to
+     * `actorUserId` for every folder where the target is the sole admin.
+     * Inserts an admin folder_access row for the actor (or upgrades an
+     * existing editor row). Returns the list of folder names that were
+     * transferred so the caller can surface them in UX.
+     *
+     * This prevents folders from becoming orphaned (no admins) after the
+     * target user's folder_access rows cascade-delete. Folders with other
+     * admins are left alone — no redundant membership added.
+     */
+    transferFoldersOnDelete(targetUserId, actorUserId) {
+        if (targetUserId === actorUserId)
+            return [];
+        const targetAdminFolders = this.db.prepare(`SELECT folder_name FROM folder_access WHERE user_id = ? AND role = 'admin'`).all(targetUserId);
+        const transferred = [];
+        const countAdminsStmt = this.db.prepare(`SELECT COUNT(*) as count FROM folder_access WHERE folder_name = ? AND role = 'admin'`);
+        const upsertStmt = this.db.prepare(`
+      INSERT INTO folder_access (user_id, folder_name, role)
+      VALUES (?, ?, 'admin')
+      ON CONFLICT(user_id, folder_name) DO UPDATE SET role = 'admin'
+    `);
+        for (const { folder_name } of targetAdminFolders) {
+            const { count } = countAdminsStmt.get(folder_name);
+            if (count > 1)
+                continue; // Other admins remain — nothing to transfer.
+            upsertStmt.run(actorUserId, folder_name);
+            transferred.push(folder_name);
+        }
+        if (transferred.length > 0)
+            this.exportSeed();
+        return transferred;
+    }
+    updateProfile(userId, fields) {
+        const updates = [];
+        const params = [];
+        if (fields.displayName !== undefined) {
+            updates.push('display_name = ?');
+            params.push(fields.displayName);
+        }
+        if (fields.email !== undefined) {
+            updates.push('email = ?');
+            params.push(fields.email.toLowerCase().trim());
+        }
+        if (updates.length === 0)
+            return this.findUserById(userId);
+        updates.push("updated_at = datetime('now')");
+        params.push(userId);
+        this.db.prepare(`UPDATE users SET ${updates.join(', ')} WHERE id = ?`).run(...params);
+        this.exportSeed();
+        return this.findUserById(userId);
+    }
     updatePassword(email, newPassword) {
         if (!newPassword || newPassword.length < 8) {
             throw new Error('Password must be at least 8 characters');
@@ -180,38 +647,136 @@ export class AuthService {
             this.exportSeed();
         return result.changes > 0;
     }
-    // ── Collection access management ──
-    grantCollectionAccess(userId, collectionName) {
-        this.db.prepare('INSERT OR IGNORE INTO collection_access (user_id, collection_name) VALUES (?, ?)').run(userId, collectionName);
+    /**
+     * Get the workspace owner (the single user with role 'owner').
+     * Returns null if no owner exists (e.g., legacy workspace not yet migrated).
+     */
+    getOwner() {
+        const row = this.db.prepare("SELECT * FROM users WHERE role = 'owner' LIMIT 1").get();
+        return row ? this.toAuthUser(row) : null;
+    }
+    /**
+     * Transfer ownership to another user. The current owner becomes a regular member.
+     * Both changes happen in a single transaction.
+     */
+    transferOwnership(currentOwnerId, newOwnerId) {
+        const target = this.db.prepare('SELECT * FROM users WHERE id = ?').get(newOwnerId);
+        if (!target)
+            throw new Error('Target user not found');
+        const current = this.db.prepare('SELECT * FROM users WHERE id = ?').get(currentOwnerId);
+        if (!current || current.role !== 'owner')
+            throw new Error('Current user is not the owner');
+        const transfer = this.db.transaction(() => {
+            this.db.prepare("UPDATE users SET role = 'member', updated_at = datetime('now') WHERE id = ?").run(currentOwnerId);
+            this.db.prepare("UPDATE users SET role = 'owner', updated_at = datetime('now') WHERE id = ?").run(newOwnerId);
+        });
+        transfer();
+        this.exportSeed();
+    }
+    // ── Folder access management ──
+    /** Grant folder membership. `role` defaults to 'editor'. Upserts the role if the row exists. */
+    grantFolderAccess(userId, folder, role = 'editor') {
+        this.db.prepare(`
+      INSERT INTO folder_access (user_id, folder_name, role) VALUES (?, ?, ?)
+      ON CONFLICT (user_id, folder_name) DO UPDATE SET role = excluded.role
+    `).run(userId, folder, role);
         this.exportSeed();
     }
-    revokeCollectionAccess(userId, collectionName) {
-        this.db.prepare('DELETE FROM collection_access WHERE user_id = ? AND collection_name = ?').run(userId, collectionName);
+    revokeFolderAccess(userId, folder) {
+        this.db.prepare('DELETE FROM folder_access WHERE user_id = ? AND folder_name = ?').run(userId, folder);
         this.exportSeed();
     }
-    getUserCollections(userId) {
-        const rows = this.db.prepare('SELECT collection_name FROM collection_access WHERE user_id = ? ORDER BY collection_name').all(userId);
-        return rows.map(r => r.collection_name);
+    /** Folder names the user is a member of. */
+    getUserFolders(userId) {
+        const rows = this.db.prepare('SELECT folder_name FROM folder_access WHERE user_id = ? ORDER BY folder_name').all(userId);
+        return rows.map(r => r.folder_name);
     }
-    getCollectionUsers(collectionName) {
+    /** All users with any role on a folder. */
+    getFolderUsers(folder) {
         const rows = this.db.prepare(`
       SELECT u.* FROM users u
-      JOIN collection_access ca ON ca.user_id = u.id
-      WHERE ca.collection_name = ?
+      JOIN folder_access fa ON fa.user_id = u.id
+      WHERE fa.folder_name = ?
       ORDER BY u.display_name
-    `).all(collectionName);
+    `).all(folder);
         return rows.map(r => this.toAuthUser(r));
     }
-    renameCollection(oldName, newName) {
-        this.db.prepare('UPDATE collection_access SET collection_name = ? WHERE collection_name = ?').run(newName, oldName);
+    /** (user, role) pairs for every member of a folder. */
+    getFolderMembers(folder) {
+        const rows = this.db.prepare(`
+      SELECT u.*, fa.role AS folder_role FROM users u
+      JOIN folder_access fa ON fa.user_id = u.id
+      WHERE fa.folder_name = ?
+      ORDER BY u.display_name
+    `).all(folder);
+        return rows.map(r => ({ user: this.toAuthUser(r), role: r.folder_role }));
+    }
+    /** Folder role for a specific user, or null if they aren't a member. */
+    getFolderRole(userId, folder) {
+        const row = this.db.prepare('SELECT role FROM folder_access WHERE user_id = ? AND folder_name = ?').get(userId, folder);
+        return row?.role ?? null;
+    }
+    /** True if the user is a folder admin on that folder. */
+    isFolderAdmin(userId, folder) {
+        return this.getFolderRole(userId, folder) === 'admin';
+    }
+    /** All users with folder-admin role on a folder. */
+    getFolderAdmins(folder) {
+        const rows = this.db.prepare(`
+      SELECT u.* FROM users u
+      JOIN folder_access fa ON fa.user_id = u.id
+      WHERE fa.folder_name = ? AND fa.role = 'admin'
+      ORDER BY u.display_name
+    `).all(folder);
+        return rows.map(r => this.toAuthUser(r));
+    }
+    /**
+     * Transfer folder admin role from one user to another. Used during member
+     * removal to pass orphaned folders to the workspace owner.
+     */
+    transferFolderAdmin(folder, fromUserId, toUserId) {
+        const transfer = this.db.transaction(() => {
+            this.db.prepare('DELETE FROM folder_access WHERE user_id = ? AND folder_name = ?')
+                .run(fromUserId, folder);
+            this.db.prepare(`
+        INSERT INTO folder_access (user_id, folder_name, role) VALUES (?, ?, 'admin')
+        ON CONFLICT (user_id, folder_name) DO UPDATE SET role = 'admin'
+      `).run(toUserId, folder);
+        });
+        transfer();
+        this.exportSeed();
+    }
+    /** Rename the folder slug across all membership rows. */
+    renameFolder(oldName, newName) {
+        this.db.prepare('UPDATE folder_access SET folder_name = ? WHERE folder_name = ?').run(newName, oldName);
         this.exportSeed();
     }
     // ── OAuth token management ──
     /** Get stored OAuth data (tokens, clientInfo, codeVerifier) for a user+connector. */
     getOAuthData(userId, connectorName) {
-        const row = this.db.prepare('SELECT data_json FROM oauth_tokens WHERE user_id = ? AND connector_name = ?').get(userId, connectorName);
+        const row = this.db.prepare('SELECT data_json, data_ciphertext, key_version FROM oauth_tokens WHERE user_id = ? AND connector_name = ?').get(userId, connectorName);
         if (!row)
             return null;
+        // Encrypted-path: ciphertext present. Decryption errors throw — a row
+        // bound to user A cannot be decrypted with user B's AAD, and tampering
+        // is detected. Callers should let the error propagate.
+        if (row.data_ciphertext) {
+            if (!this.crypto) {
+                throw new Error(`oauth_tokens row for user_id=${userId} connector=${connectorName} is encrypted but ` +
+                    `AuthService was constructed without a master key. Wire the crypto options in serve.ts.`);
+            }
+            try {
+                const plaintext = decryptOAuthTokenData(this.crypto.masterKey, userId, row.data_ciphertext, row.key_version);
+                return JSON.parse(plaintext);
+            }
+            catch (err) {
+                log.error(`[auth] OAuth token decrypt failed for user_id=${userId} connector=${connectorName}: ${err instanceof Error ? err.message : String(err)}`);
+                throw err;
+            }
+        }
+        // Pre-migration fallback: legacy plaintext column.
+        if (!row.data_json)
+            return null;
         try {
             return JSON.parse(row.data_json);
         }
@@ -219,14 +784,81 @@ export class AuthService {
             return null;
         }
     }
+    /**
+     * Sign an OAuth state parameter for outbound flows. Throws when the service
+     * was constructed without crypto options (the signing key is HKDF-derived
+     * from the master key). Callers in OAuth init paths must ensure the
+     * AuthService is constructed with crypto options — production always is;
+     * tests that exercise OAuth flows should provide a master key.
+     */
+    signOAuthState(claims) {
+        if (!this.oauthStateSigner) {
+            throw new Error('AuthService: cannot sign OAuth state — master key not configured. ' +
+                'OAuth flows require AuthService to be constructed with cryptoOpts.');
+        }
+        return this.oauthStateSigner.sign(claims);
+    }
+    /**
+     * Verify a signed OAuth state. Returns null on:
+     *   - missing/invalid signing key (defensive — should not happen in
+     *     production where serve.ts wires the master key)
+     *   - tampered / forged / unsigned state
+     *   - state older than 10 minutes (replay window)
+     *   - state with future-skewed `t` beyond a small tolerance
+     * Callers should treat null as "invalid/expired state" and surface a
+     * generic error to the browser without echoing details.
+     */
+    verifyOAuthState(state) {
+        if (!this.oauthStateSigner)
+            return null;
+        return this.oauthStateSigner.verify(state);
+    }
+    /**
+     * Subscribe to OAuth-token mutations. Returns an unsubscribe fn.
+     * Listeners fire AFTER the row write commits. Both connect and disconnect
+     * paths emit; subscribers that only care about one should filter
+     * themselves.
+     */
+    onOAuthMutation(fn) {
+        this.oauthMutationListeners.add(fn);
+        return () => { this.oauthMutationListeners.delete(fn); };
+    }
+    notifyOAuthMutation(userId, connectorName) {
+        for (const fn of this.oauthMutationListeners) {
+            try {
+                fn(userId, connectorName);
+            }
+            catch { /* listener bugs must not break the write path */ }
+        }
+    }
     /** Save OAuth data (upsert). */
     saveOAuthData(userId, connectorName, data) {
+        const payload = JSON.stringify(data);
+        // When crypto is wired up, every new write goes to data_ciphertext —
+        // data_json stays NULL on insert and is explicitly nulled on update
+        // so a row never carries both plaintext and ciphertext (the
+        // half-state guard would refuse to boot if it did).
+        if (this.crypto && this.oauthTokensEncrypted) {
+            const enc = encryptOAuthTokenData(this.crypto.masterKey, userId, payload, this.crypto.keyVersion);
+            this.db.prepare(`
+        INSERT INTO oauth_tokens (user_id, connector_name, data_json, data_ciphertext, key_version, updated_at)
+        VALUES (?, ?, NULL, ?, ?, datetime('now'))
+        ON CONFLICT (user_id, connector_name)
+        DO UPDATE SET data_json = NULL, data_ciphertext = excluded.data_ciphertext,
+                      key_version = excluded.key_version, updated_at = excluded.updated_at
+      `).run(userId, connectorName, enc.ciphertext, enc.keyVersion);
+            this.notifyOAuthMutation(userId, connectorName);
+            return;
+        }
+        // Legacy path (tests / flag-off boots / pre-migration). Writes
+        // plaintext to data_json the way the v1 code always did.
         this.db.prepare(`
       INSERT INTO oauth_tokens (user_id, connector_name, data_json, updated_at)
       VALUES (?, ?, ?, datetime('now'))
       ON CONFLICT (user_id, connector_name)
       DO UPDATE SET data_json = excluded.data_json, updated_at = excluded.updated_at
-    `).run(userId, connectorName, JSON.stringify(data));
+    `).run(userId, connectorName, payload);
+        this.notifyOAuthMutation(userId, connectorName);
     }
     /** List all connected connectors for a user. */
     getUserConnectedConnectors(userId) {
@@ -235,6 +867,7 @@ export class AuthService {
     /** Clear OAuth data for a user+connector. */
     clearOAuthData(userId, connectorName) {
         this.db.prepare('DELETE FROM oauth_tokens WHERE user_id = ? AND connector_name = ?').run(userId, connectorName);
+        this.notifyOAuthMutation(userId, connectorName);
     }
     /** Check if a user has OAuth tokens for a connector. */
     hasOAuthTokens(userId, connectorName) {
@@ -249,41 +882,56 @@ export class AuthService {
         const row = this.db.prepare('SELECT COUNT(*) as count FROM users').get();
         return row.count;
     }
-    /** Get the workspace API key (for MCP and programmatic access). */
-    getApiKey() {
-        return this.apiKey;
+    // ── Per-user API tokens (MCP auth, CLI, git HTTP) ──
+    /**
+     * Mint a new per-user API token. Returns the raw token once — only its
+     * sha256 hash is stored in the database. The raw value cannot be recovered
+     * later, matching how GitHub personal access tokens work.
+     */
+    createApiToken(userId, name) {
+        const cleanName = (name || '').trim();
+        if (!cleanName)
+            throw new Error('Token name is required');
+        const token = `sg_${randomBytes(24).toString('hex')}`;
+        const hash = hashToken(token);
+        const result = this.db.prepare('INSERT INTO api_tokens (user_id, token_hash, name) VALUES (?, ?, ?)').run(userId, hash, cleanName);
+        return { id: result.lastInsertRowid, token, name: cleanName };
     }
-    /** Check whether the given string matches the workspace API key. */
-    validateApiKey(key) {
-        return !!key && key === this.apiKey;
+    /**
+     * Resolve a raw API token to its owning user, updating `last_used_at`
+     * on success. Returns null if the token is unknown or the owning user
+     * has been deleted.
+     */
+    verifyApiToken(token) {
+        return this.verifyApiTokenWithMeta(token)?.user ?? null;
     }
     /**
-     * Ensure the current API key is present in auth-seed.json and pushed to the
-     * config repo. Called on server startup so the key is always reachable by CLI.
-     * Non-fatal — never throws.
+     * Same as verifyApiToken but also returns the token's user-set name (e.g.
+     * "Cursor", "Claude Desktop"). Used by surfaces that need to attribute an
+     * action to a specific named integration — most importantly the
+     * agent-activity feature, which renders "<owner>'s <token name>" chips.
      */
-    syncApiKeyToSeed() {
-        try {
-            const seedPath = join(this.sgDir, 'auth-seed.json');
-            if (!existsSync(seedPath)) {
-                this.exportSeed();
-                return;
-            }
-            const seed = JSON.parse(readFileSync(seedPath, 'utf-8'));
-            if (seed.apiKey !== this.apiKey) {
-                this.exportSeed();
-            }
-        }
-        catch (err) {
-            console.warn(`Auth: syncApiKeyToSeed failed — ${err.message}`);
-        }
+    verifyApiTokenWithMeta(token) {
+        if (!token)
+            return null;
+        const hash = hashToken(token);
+        const row = this.db.prepare('SELECT user_id, name FROM api_tokens WHERE token_hash = ?').get(hash);
+        if (!row)
+            return null;
+        this.db.prepare('UPDATE api_tokens SET last_used_at = datetime(\'now\') WHERE token_hash = ?').run(hash);
+        const user = this.findUserById(row.user_id);
+        if (!user)
+            return null;
+        return { user, tokenName: row.name };
     }
-    /** Regenerate the workspace API key. Returns the new key. */
-    regenerateApiKey() {
-        this.apiKey = randomBytes(32).toString('hex');
-        writeFileSync(join(this.sgDir, 'api-keys'), this.apiKey, { mode: 0o600 });
-        this.exportSeed();
-        return this.apiKey;
+    /** List a user's API tokens. Never returns the raw token — only metadata. */
+    listApiTokens(userId) {
+        return this.db.prepare('SELECT id, name, created_at, last_used_at FROM api_tokens WHERE user_id = ? ORDER BY created_at DESC').all(userId);
+    }
+    /** Revoke (delete) an API token owned by the given user. No-op if not found. */
+    revokeApiToken(tokenId, userId) {
+        const result = this.db.prepare('DELETE FROM api_tokens WHERE id = ? AND user_id = ?').run(tokenId, userId);
+        return result.changes > 0;
     }
     /**
      * Ensure auth.db and auth-secret are in .studiograph/.gitignore.
@@ -305,21 +953,44 @@ export class AuthService {
         }
     }
     /**
-     * Build and return the current auth seed data (users + JWT secret + collection access).
+     * Build and return the current auth seed data (users + JWT secret + folder access).
      * Does not write to disk — use exportSeed() for that.
+     *
+     * SECURITY: the returned object embeds raw secrets:
+     *   • `jwtSecret` — signing key for ALL session tokens. Anyone holding this
+     *     can mint a valid session for any user. Rotate by setting
+     *     STUDIOGRAPH_JWT_SECRET in production and restarting.
+     *   • `users[].password_hash` — bcrypt hashes (cost 12). Offline-crackable
+     *     against weak passwords; treat as compromise of the listed accounts
+     *     if leaked.
+     *
+     * Only call this from paths that write to a trusted location (auth-seed.json
+     * inside the .studiograph/ config repo). Never expose over HTTP, never log,
+     * never include in error messages or telemetry.
      */
     getSeedData() {
-        const rows = this.db.prepare('SELECT email, password_hash, display_name, role, created_at FROM users ORDER BY id ASC').all();
+        const rows = this.db.prepare('SELECT email, handle, password_hash, display_name, role, created_at FROM users ORDER BY id ASC').all();
         const accessRows = this.db.prepare(`
-      SELECT u.email AS user_email, ca.collection_name
-      FROM collection_access ca JOIN users u ON u.id = ca.user_id
-      ORDER BY u.email, ca.collection_name
+      SELECT u.email AS user_email, fa.folder_name AS folder_name, fa.role
+      FROM folder_access fa JOIN users u ON u.id = fa.user_id
+      ORDER BY u.email, fa.folder_name
     `).all();
+        // Phase 3: in production (Railway), drop the JWT secret from the
+        // returned seed entirely. Hosted instances read the JWT secret from
+        // STUDIOGRAPH_JWT_SECRET env-var and never need it embedded in the
+        // committed seed file. In dev / single-host, callers (applySeed,
+        // first-run import) still need the value to keep the
+        // env > file > seed > generated chain working.
+        //
+        // The exportSeed() / pushSeed() paths run the result through the
+        // bundle-sanitizer regardless, so even a dev seed never reaches the
+        // committed file with `jwtSecret`. This split keeps in-process API
+        // callers (which never write to disk) backwards-compatible.
+        const inProduction = Boolean(process.env.RAILWAY_ENVIRONMENT);
         return {
-            jwtSecret: this.jwtSecret,
-            apiKey: this.apiKey,
+            jwtSecret: inProduction ? '' : this.jwtSecret,
             users: rows,
-            collection_access: accessRows,
+            folder_access: accessRows,
         };
     }
     /**
@@ -328,9 +999,24 @@ export class AuthService {
      * the seed file so it syncs between environments.
      */
     exportSeed() {
-        const seed = this.getSeedData();
+        // Phase 3: route the seed through sanitizeAuthSeed() so the
+        // committed seed file NEVER carries jwtSecret or the deprecated
+        // top-level apiKey. Bcrypt hashes (users[].password_hash) are
+        // retained — that's the workspace-replication mechanism, see
+        // docs/SECURITY.md for the product decision.
+        const seed = sanitizeAuthSeed(this.getSeedData());
         const seedPath = join(this.sgDir, 'auth-seed.json');
-        writeFileSync(seedPath, JSON.stringify(seed, null, 2), 'utf-8');
+        // Restrictive mode by default. Even with jwtSecret stripped, the
+        // file still carries every user's bcrypt hash — world-readable mode
+        // would enable offline cracking by any local user.
+        writeFileSync(seedPath, JSON.stringify(seed, null, 2), { mode: 0o600 });
+        if (process.platform !== 'win32') {
+            // Force-tighten when the file pre-existed with looser mode bits.
+            try {
+                chmodSync(seedPath, 0o600);
+            }
+            catch { /* non-fatal */ }
+        }
         this.pushSeed();
     }
     /**
@@ -370,7 +1056,10 @@ export class AuthService {
                 cwd: this.sgDir, encoding: 'utf-8', stdio: 'pipe',
             });
             if (commit.status !== 0) {
-                console.warn(`Auth: failed to commit seed — ${(commit.stderr || '').trim()}`);
+                // Phase 11: git's stderr can carry the remote URL with embedded
+                // credentials when push fails (https://x-access-token:<jwt>@host).
+                // Route stderr through sanitize() before logging.
+                log.warn(`Auth: failed to commit seed — ${sanitize((commit.stderr || '').trim())}`);
                 return;
             }
             // Push
@@ -378,62 +1067,139 @@ export class AuthService {
                 cwd: this.sgDir, encoding: 'utf-8', stdio: 'pipe', timeout: 30_000,
             });
             if (push.status !== 0) {
-                console.warn(`Auth: failed to push seed — ${(push.stderr || '').trim()}`);
+                log.warn(`Auth: failed to push seed — ${sanitize((push.stderr || '').trim())}`);
             }
         }
         catch (err) {
-            console.warn(`Auth: seed sync failed — ${err.message}`);
+            log.warn(`Auth: seed sync failed — ${sanitize(err.message)}`);
         }
     }
     /**
      * Import users and JWT secret from .studiograph/auth-seed.json.
-     * Uses INSERT OR IGNORE so it's safe to call on non-empty databases
-     * (e.g. after `studiograph pull` brings a new seed file).
+     * Two modes:
+     *   • `merge` (default) — INSERT OR IGNORE on email. Existing local rows win
+     *     on conflict. Safe for boot-time recovery when the local DB may carry
+     *     legitimate state the seed shouldn't clobber.
+     *   • `overwrite` — UPSERT on email. Seed values win on conflict. Correct
+     *     for explicit "remote is authoritative" callers (`studiograph pull`,
+     *     `studiograph clone`, admin bundle import) where any local divergence
+     *     was almost certainly the post-clone setup-wizard stamping fresh
+     *     credentials over the real ones. `merge` mode silently shadowed
+     *     production credentials in that exact scenario — see 2026-05 incident.
      */
-    applySeed() {
+    applySeed(options = {}) {
+        const mode = options.mode ?? 'merge';
         const seedPath = join(this.sgDir, 'auth-seed.json');
         if (!existsSync(seedPath))
             return;
         try {
             const seed = JSON.parse(readFileSync(seedPath, 'utf-8'));
-            // Restore JWT secret so existing tokens remain valid
+            // Restore JWT secret if the seed carried one. With our uniform sanitizer
+            // this is empty on production-server pulls; the local server then generates
+            // its own (sovereign-instance model).
             if (seed.jwtSecret) {
                 const secretPath = join(this.sgDir, 'auth-secret');
                 writeFileSync(secretPath, seed.jwtSecret, { mode: 0o600 });
             }
-            // Restore API key
-            if (seed.apiKey) {
-                const apiKeyPath = join(this.sgDir, 'api-keys');
-                writeFileSync(apiKeyPath, seed.apiKey, { mode: 0o600 });
+            // Normalize WAL state before writing. We've seen apply-seed writes
+            // silently disappear when the WAL was bloated by a prior crashed server
+            // — checkpointing first guarantees the page cache reflects the on-disk
+            // committed state. RESTART (vs TRUNCATE) is the gentler form: it waits
+            // for readers but doesn't unlink the WAL file.
+            try {
+                this.db.pragma('wal_checkpoint(RESTART)');
             }
-            // Restore users with their original password hashes (no re-hashing needed)
-            const stmt = this.db.prepare('INSERT OR IGNORE INTO users (email, password_hash, display_name, role, created_at) VALUES (?, ?, ?, ?, ?)');
-            for (const u of seed.users) {
-                stmt.run(u.email, u.password_hash, u.display_name, u.role, u.created_at);
+            catch { /* non-fatal */ }
+            // Apply users + folder_access atomically. Explicit transaction means
+            // any failure aborts the whole import (no half-applied state) and
+            // commit semantics are unambiguous — there's no "implicit autocommit"
+            // path that can be silently skipped under WAL weirdness.
+            //
+            // UPSERT keyed on email preserves the autoincrement id so foreign keys
+            // (folder_access, oauth_tokens, api_tokens) stay valid across an
+            // overwrite. handle gets updated too — if the seed renames a handle,
+            // we want the rename to land.
+            const userStmt = mode === 'overwrite'
+                ? this.db.prepare(`
+            INSERT INTO users (email, handle, password_hash, display_name, role, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+            ON CONFLICT(email) DO UPDATE SET
+              handle = excluded.handle,
+              password_hash = excluded.password_hash,
+              display_name = excluded.display_name,
+              role = excluded.role,
+              created_at = excluded.created_at
+          `)
+                : this.db.prepare('INSERT OR IGNORE INTO users (email, handle, password_hash, display_name, role, created_at) VALUES (?, ?, ?, ?, ?, ?)');
+            const accessStmt = this.db.prepare(`
+        INSERT INTO folder_access (user_id, folder_name, role)
+        SELECT id, ?, ? FROM users WHERE email = ?
+        ON CONFLICT (user_id, folder_name) DO UPDATE SET role = excluded.role
+      `);
+            const accessRows = seed.folder_access ?? [];
+            const apply = this.db.transaction(() => {
+                for (const u of seed.users) {
+                    userStmt.run(u.email, u.handle, u.password_hash, u.display_name, u.role, u.created_at);
+                }
+                for (const fa of accessRows) {
+                    accessStmt.run(fa.folder_name, fa.role ?? 'editor', fa.user_email);
+                }
+            });
+            apply();
+            // Verify the writes survived. If the post-commit count doesn't reflect
+            // at least the seed's user set, something is rolling our writes back —
+            // throw loudly rather than letting the caller think the import succeeded.
+            // In overwrite mode we additionally verify password_hash equality:
+            // the 2026-05 incident was specifically about a stale local hash
+            // surviving import, so "row exists" wasn't enough to catch it.
+            const seedEmails = new Set(seed.users.map(u => u.email));
+            const presentRows = this.db.prepare(`SELECT email, password_hash FROM users WHERE email IN (${seed.users.map(() => '?').join(',')})`).all(...seed.users.map(u => u.email));
+            const missing = [...seedEmails].filter(e => !presentRows.some(r => r.email === e));
+            if (missing.length > 0) {
+                throw new Error(`seed apply verification failed — ${missing.length} user(s) not present after commit: ${missing.slice(0, 3).join(', ')}${missing.length > 3 ? '…' : ''}`);
             }
-            // Restore collection access grants (uses email as portable key)
-            if (seed.collection_access?.length) {
-                const accessStmt = this.db.prepare('INSERT OR IGNORE INTO collection_access (user_id, collection_name) SELECT id, ? FROM users WHERE email = ?');
-                for (const ca of seed.collection_access) {
-                    accessStmt.run(ca.collection_name, ca.user_email);
+            if (mode === 'overwrite') {
+                const drift = seed.users
+                    .filter(u => {
+                    const row = presentRows.find(r => r.email === u.email);
+                    return row && row.password_hash !== u.password_hash;
+                })
+                    .map(u => u.email);
+                if (drift.length > 0) {
+                    throw new Error(`seed apply verification failed — ${drift.length} user(s) have stale password_hash after overwrite: ${drift.slice(0, 3).join(', ')}${drift.length > 3 ? '…' : ''}`);
                 }
             }
-            console.log(`Auth: restored ${seed.users.length} user(s) from seed`);
+            // Flush WAL to main so a subsequent reader (sqlite3 CLI, another process)
+            // sees the same state we just wrote. Non-fatal — pages are committed
+            // either way; this just shortens the window where the WAL is the truth.
+            try {
+                this.db.pragma('wal_checkpoint(TRUNCATE)');
+            }
+            catch { /* non-fatal */ }
+            log.info(`Auth: restored ${seed.users.length} user(s) from seed`);
         }
         catch (err) {
-            console.warn(`Auth: failed to import seed — ${err.message}`);
+            log.warn(`Auth: failed to import seed — ${sanitize(err.message)}`);
+            throw err;
         }
     }
     // ── Views ──
     getUserViews(userId) {
-        const rows = this.db.prepare('SELECT * FROM user_views WHERE user_id = ? ORDER BY sort_order, id').all(userId);
-        return rows.map(r => this.toUserView(r));
+        // Return user's own views + all workspace-visible views from other users
+        const rows = this.db.prepare(`SELECT * FROM user_views WHERE user_id = ? OR visibility = 'workspace' ORDER BY sort_order, id`).all(userId);
+        // Deduplicate (a user's own workspace view would appear once)
+        const seen = new Set();
+        return rows.filter(r => { if (seen.has(r.id))
+            return false; seen.add(r.id); return true; }).map(r => this.toUserView(r));
     }
-    createUserView(userId, name, viewType = 'list', config = {}) {
+    createUserView(userId, name, viewType = 'list', config = {}, createdByName) {
         const maxOrder = this.db.prepare('SELECT MAX(sort_order) as max_order FROM user_views WHERE user_id = ?').get(userId)?.max_order ?? -1;
-        const result = this.db.prepare('INSERT INTO user_views (user_id, name, view_type, config_json, sort_order) VALUES (?, ?, ?, ?, ?)').run(userId, name, viewType, JSON.stringify(config), maxOrder + 1);
+        const result = this.db.prepare('INSERT INTO user_views (user_id, name, view_type, config_json, sort_order, created_by_name) VALUES (?, ?, ?, ?, ?, ?)').run(userId, name, viewType, JSON.stringify(config), maxOrder + 1, createdByName ?? null);
         return this.getUserView(Number(result.lastInsertRowid), userId);
     }
+    setViewVisibility(viewId, userId, visibility) {
+        this.db.prepare(`UPDATE user_views SET visibility = ?, updated_at = datetime('now') WHERE id = ? AND user_id = ?`).run(visibility, viewId, userId);
+    }
     getUserView(viewId, userId) {
         const row = this.db.prepare('SELECT * FROM user_views WHERE id = ? AND user_id = ?').get(viewId, userId);
         return row ? this.toUserView(row) : null;
@@ -459,8 +1225,157 @@ export class AuthService {
     deleteUserView(viewId, userId) {
         this.db.prepare('DELETE FROM user_views WHERE id = ? AND user_id = ?').run(viewId, userId);
     }
-    ensureDefaultViews(_userId, _hasTasks) {
-        // No default views — users create their own via the + button
+    // ── Workspace views (folder-views redesign) ──
+    toWorkspaceView(row) {
+        let config = {};
+        try {
+            config = JSON.parse(row.config_json);
+        }
+        catch { /* default {} */ }
+        return {
+            id: row.id,
+            scope: row.scope,
+            viewType: row.view_type,
+            config,
+            position: row.position,
+            name: row.name,
+            createdBy: row.created_by,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+    /** All views for a scope, in tab order. */
+    getViewsForScope(scope) {
+        const rows = this.db.prepare('SELECT * FROM workspace_views WHERE scope = ? ORDER BY position, id').all(scope);
+        return rows.map(r => this.toWorkspaceView(r));
+    }
+    getWorkspaceView(viewId) {
+        const row = this.db.prepare('SELECT * FROM workspace_views WHERE id = ?').get(viewId);
+        return row ? this.toWorkspaceView(row) : null;
+    }
+    /**
+     * Add a view to a scope. One-of-each is enforced by UNIQUE(scope, view_type):
+     * a duplicate is a no-op that returns the existing row, so callers (and the
+     * "+" menu) never create dupes.
+     */
+    createWorkspaceView(scope, viewType, config = {}, createdBy) {
+        const maxPos = this.db.prepare('SELECT MAX(position) AS m FROM workspace_views WHERE scope = ?').get(scope)?.m ?? -1;
+        this.db.prepare(`INSERT OR IGNORE INTO workspace_views (scope, view_type, config_json, position, created_by) VALUES (?, ?, ?, ?, ?)`).run(scope, viewType, JSON.stringify(config), maxPos + 1, createdBy ?? null);
+        const row = this.db.prepare('SELECT * FROM workspace_views WHERE scope = ? AND view_type = ?').get(scope, viewType);
+        return this.toWorkspaceView(row);
+    }
+    updateWorkspaceView(viewId, fields) {
+        const sets = ["updated_at = datetime('now')"];
+        const params = [];
+        if (fields.config !== undefined) {
+            sets.push('config_json = ?');
+            params.push(JSON.stringify(fields.config));
+        }
+        if (fields.position !== undefined) {
+            sets.push('position = ?');
+            params.push(fields.position);
+        }
+        if (fields.name !== undefined) {
+            sets.push('name = ?');
+            params.push(fields.name);
+        }
+        params.push(viewId);
+        this.db.prepare(`UPDATE workspace_views SET ${sets.join(', ')} WHERE id = ?`).run(...params);
+    }
+    deleteWorkspaceView(viewId) {
+        this.db.prepare('DELETE FROM workspace_views WHERE id = ?').run(viewId);
+    }
+    /**
+     * Idempotently seed a scope's default views (called on first GET for a scope).
+     * Folder/type scopes get a List; `recent` gets List + Calendar(updated_at) +
+     * Graph. INSERT OR IGNORE + UNIQUE(scope, view_type) makes this safe to call
+     * on every access and race-safe across concurrent loads.
+     */
+    ensureViewsForScope(scope) {
+        const seeds = scope === 'recent'
+            ? [
+                { viewType: 'list', config: {} },
+                { viewType: 'calendar', config: { dateField: 'updated_at' } },
+                { viewType: 'graph', config: {} },
+            ]
+            : [{ viewType: 'list', config: {} }];
+        const insert = this.db.prepare(`INSERT OR IGNORE INTO workspace_views (scope, view_type, config_json, position, created_by) VALUES (?, ?, ?, ?, ?)`);
+        seeds.forEach((s, i) => insert.run(scope, s.viewType, JSON.stringify(s.config), i, 'Studiograph'));
+        return this.getViewsForScope(scope);
+    }
+    _viewMigrationDone = false;
+    /**
+     * Create default workspace views based on which entity types have data.
+     * "Recent" is always created. Other views are created for the top entity
+     * types by count (up to 5). Only creates views that don't already exist.
+     * Additive: runs on every page load but only adds missing views.
+     *
+     * @param typeCounts Map of entity_type → count (from workspace scan)
+     */
+    ensureDefaultViews(userId, typeCounts) {
+        // One-time cleanup of broken workspace views (old format migration)
+        if (!this._viewMigrationDone) {
+            this._viewMigrationDone = true;
+            // (caused by ListView auto-save overwriting the old format)
+            const SYSTEM_CREATOR = 'Studiograph';
+            const oldViews = this.db.prepare(`SELECT id, name, config_json, created_by_name FROM user_views WHERE visibility = 'workspace'`).all();
+            for (const old of oldViews) {
+                if (old.created_by_name !== SYSTEM_CREATOR)
+                    continue; // don't touch user-created workspace views
+                try {
+                    const cfg = JSON.parse(old.config_json);
+                    const isBroken = Array.isArray(cfg.filters) || (old.name !== 'Recent' && !cfg.selectedType);
+                    if (isBroken) {
+                        this.db.prepare('DELETE FROM user_views WHERE id = ?').run(old.id);
+                    }
+                }
+                catch {
+                    this.db.prepare('DELETE FROM user_views WHERE id = ?').run(old.id);
+                }
+            }
+        } // end migration block
+        const existingNames = new Set(this.db.prepare(`SELECT name FROM user_views WHERE visibility = 'workspace'`).all().map(r => r.name));
+        // Always include "Recent"
+        const views = [
+            { name: 'Recent', viewType: 'list', config: { selectedType: null, sortKey: 'updated_at', sortAsc: false, groupBy: null, filters: { version: 1 } } },
+        ];
+        // Display name + sort config per type
+        const TYPE_LABELS = {
+            event: 'Events', task: 'Tasks', person: 'People',
+            project: 'Projects', organization: 'Organizations', deal: 'Deals',
+            document: 'Documents', note: 'Notes', deliverable: 'Deliverables',
+            reference: 'References', publication: 'Publications', service: 'Services',
+            'case-study': 'Case Studies', position: 'Positions', skill: 'Skills',
+            deck: 'Decks',
+        };
+        // Types whose default list view sorts by their date, desc (newest
+        // first). After the date-vocabulary consolidation every type's salient
+        // date lives on the universal `date` field (a task's due date, a deal's
+        // close, an event's day), so there's a single sort key for all of them.
+        const DATE_SORT_TYPES = new Set(['event', 'deal', 'task', 'note']);
+        // Sort types by count descending, take top 5 with at least 1 entity
+        const topTypes = Object.entries(typeCounts)
+            .filter(([, count]) => count > 0)
+            .sort(([, a], [, b]) => b - a)
+            .slice(0, 5)
+            .map(([type]) => type);
+        for (const type of topTypes) {
+            const name = TYPE_LABELS[type] ?? type.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()) + 's';
+            const sortByDate = DATE_SORT_TYPES.has(type);
+            const sortKey = sortByDate ? 'date' : 'name';
+            const sortAsc = !sortByDate;
+            views.push({
+                name,
+                viewType: 'list',
+                config: { selectedType: type, sortKey, sortAsc, groupBy: null, filters: { version: 1 } },
+            });
+        }
+        for (const view of views) {
+            if (existingNames.has(view.name))
+                continue;
+            const created = this.createUserView(userId, view.name, view.viewType, view.config, 'Studiograph');
+            this.setViewVisibility(created.id, userId, 'workspace');
+        }
     }
     toUserView(row) {
         return {
@@ -469,6 +1384,8 @@ export class AuthService {
             viewType: row.view_type,
             config: JSON.parse(row.config_json),
             sortOrder: row.sort_order,
+            visibility: row.visibility ?? 'private',
+            createdByName: row.created_by_name ?? null,
             createdAt: row.created_at,
             updatedAt: row.updated_at,
         };
@@ -478,32 +1395,101 @@ export class AuthService {
         const row = this.db.prepare('SELECT accent_color FROM user_preferences WHERE user_id = ?').get(userId);
         return row?.accent_color ?? null;
     }
+    /** Get accent colors for all users. Returns userId → color (only users with a color set). */
+    getAllAccentColors() {
+        const rows = this.db.prepare('SELECT user_id, accent_color FROM user_preferences WHERE accent_color IS NOT NULL').all();
+        const result = {};
+        for (const r of rows)
+            result[r.user_id] = r.accent_color;
+        return result;
+    }
     setAccentColor(userId, color) {
         this.db.prepare(`INSERT INTO user_preferences (user_id, accent_color, updated_at) VALUES (?, ?, datetime('now'))
        ON CONFLICT(user_id) DO UPDATE SET accent_color = excluded.accent_color, updated_at = excluded.updated_at`).run(userId, color);
     }
-    getHomeBrief(userId) {
-        const row = this.db.prepare('SELECT home_brief FROM user_preferences WHERE user_id = ?').get(userId);
-        return row?.home_brief ?? '';
+    getOnboarded(userId) {
+        const row = this.db.prepare('SELECT onboarded FROM user_preferences WHERE user_id = ?').get(userId);
+        return row?.onboarded === 1;
     }
-    setHomeBrief(userId, brief) {
-        this.db.prepare(`INSERT INTO user_preferences (user_id, home_brief, updated_at) VALUES (?, ?, datetime('now'))
-       ON CONFLICT(user_id) DO UPDATE SET home_brief = excluded.home_brief, updated_at = excluded.updated_at`).run(userId, brief);
+    setOnboarded(userId, value) {
+        this.db.prepare(`INSERT INTO user_preferences (user_id, onboarded, updated_at) VALUES (?, ?, datetime('now'))
+       ON CONFLICT(user_id) DO UPDATE SET onboarded = excluded.onboarded, updated_at = excluded.updated_at`).run(userId, value ? 1 : 0);
     }
-    getCachedInsights(userId) {
-        const row = this.db.prepare('SELECT insights_json, insights_generated_at FROM user_preferences WHERE user_id = ?').get(userId);
+    /**
+     * Reset per-user state used by the agent: onboarding flag and meeting-capture
+     * settings (Deepgram key, calendar, default folder). Preserves the user
+     * account, accent color, and minted API tokens. Used by `POST /api/reset` to
+     * put a tester back to a clean slate without a redeploy or DB surgery.
+     */
+    resetUserState(userId) {
+        // Phase 8: also wipe settings_ciphertext + key_version so the reset
+        // matches the conceptual contract ("user state is gone"). Otherwise
+        // a previously-stored Deepgram key would survive a reset.
+        this.db.prepare(`INSERT INTO user_preferences
+         (user_id, onboarded, settings_json, settings_ciphertext, key_version, updated_at)
+       VALUES (?, 0, '{}', NULL, NULL, datetime('now'))
+       ON CONFLICT(user_id) DO UPDATE SET
+         onboarded = 0,
+         settings_json = '{}',
+         settings_ciphertext = NULL,
+         key_version = NULL,
+         updated_at = datetime('now')`).run(userId);
+    }
+    // ── Meeting capture: per-user settings (Deepgram key, calendar, default folder) ──
+    getUserSettings(userId) {
+        const row = this.db.prepare('SELECT settings_json, settings_ciphertext, key_version FROM user_preferences WHERE user_id = ?').get(userId);
         if (!row)
-            return { insights: [], generatedAt: null };
+            return {};
+        // When the ciphertext column is populated we MUST have a master key
+        // available — otherwise we'd silently drop the secret half of the
+        // user's settings (e.g. lose their Deepgram key) and the meeting-
+        // capture UI would re-prompt them. Refuse to read.
+        if (row.settings_ciphertext) {
+            if (!this.crypto) {
+                throw new Error(`user_preferences row for user_id=${userId} has encrypted secrets but AuthService was ` +
+                    `constructed without a master key. Wire crypto options in serve.ts.`);
+            }
+            try {
+                return decryptUserPreferencesSettings(this.crypto.masterKey, userId, row.settings_json, row.settings_ciphertext, row.key_version);
+            }
+            catch (err) {
+                log.error(`[auth] user_preferences decrypt failed for user_id=${userId}: ${err instanceof Error ? err.message : String(err)}`);
+                throw err;
+            }
+        }
+        if (!row.settings_json)
+            return {};
         try {
-            return { insights: JSON.parse(row.insights_json), generatedAt: row.insights_generated_at };
+            return JSON.parse(row.settings_json);
         }
         catch {
-            return { insights: [], generatedAt: null };
+            return {};
         }
     }
-    setCachedInsights(userId, insights) {
-        this.db.prepare(`INSERT INTO user_preferences (user_id, insights_json, insights_generated_at, updated_at) VALUES (?, ?, datetime('now'), datetime('now'))
-       ON CONFLICT(user_id) DO UPDATE SET insights_json = excluded.insights_json, insights_generated_at = excluded.insights_generated_at, updated_at = excluded.updated_at`).run(userId, JSON.stringify(insights));
+    setUserSettings(userId, settings) {
+        const current = this.getUserSettings(userId);
+        const merged = { ...current, ...settings };
+        // Crypto on: partition by classification, encrypt the secret subset,
+        // write both halves atomically. Crypto off: behave exactly like v1.
+        if (this.crypto && this.userPrefsEncrypted) {
+            const split = encryptUserPreferencesSettings(this.crypto.masterKey, userId, merged, this.crypto.keyVersion ?? 'mk_v1');
+            this.db.prepare(`INSERT INTO user_preferences (user_id, settings_json, settings_ciphertext, key_version, updated_at)
+         VALUES (?, ?, ?, ?, datetime('now'))
+         ON CONFLICT(user_id) DO UPDATE SET
+           settings_json = excluded.settings_json,
+           settings_ciphertext = excluded.settings_ciphertext,
+           key_version = excluded.key_version,
+           updated_at = excluded.updated_at`).run(userId, split.settingsJson, split.settingsCiphertext, split.keyVersion);
+            return;
+        }
+        this.db.prepare(`INSERT INTO user_preferences (user_id, settings_json, updated_at) VALUES (?, ?, datetime('now'))
+       ON CONFLICT(user_id) DO UPDATE SET settings_json = excluded.settings_json, updated_at = excluded.updated_at`).run(userId, JSON.stringify(merged));
+    }
+    getUserSetting(userId, key) {
+        return this.getUserSettings(userId)[key] ?? null;
+    }
+    setUserSetting(userId, key, value) {
+        this.setUserSettings(userId, { [key]: value });
     }
     close() {
         this.db.close();
@@ -512,6 +1498,7 @@ export class AuthService {
         return {
             id: row.id,
             email: row.email,
+            handle: row.handle,
             displayName: row.display_name,
             role: row.role,
             createdAt: row.created_at,