@sleep2agi/commhub-server 0.8.8 → 0.9.0-preview.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.8.8",
-  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
+  "version": "0.9.0-preview.1",
+  "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",
   "bin": {

package/src/auth-kdf-migration.test.ts

@@ -0,0 +1,378 @@
+// Round-6 A1 — salted KDF password hash + lazy migration.
+//
+// Pins the 5 behaviours called out in the dispatch:
+//   1. old-format hash verifies + auto-rehashes to new on login
+//   2. new-format hash round-trips
+//   3. wrong password rejected (both old and new format paths)
+//   4. after a successful login against a legacy hash, the legacy
+//      hash NO LONGER EXISTS in the DB (single source of truth)
+//   5. bootstrap admin (register flow) writes new format from row 1
+//
+// Plus regression pins:
+//   - timing-safe verify path doesn't throw on adversarial input
+//   - malformed new-format string is rejected (not silently accepted)
+//
+// All COMMHUB_SCRYPT_N=10 to keep the suite fast (~5ms/scrypt vs
+// 50ms at production N=14).
+
+import { describe, expect, test, beforeAll, beforeEach } from "bun:test";
+import { db, hashPassword, verifyPassword } from "./db.js";
+import { register, login } from "./auth.js";
+
+// Fast scrypt for tests — 2^10 = 1024 iter is ~5ms. Production stays at N=14.
+beforeAll(() => {
+  process.env.COMMHUB_SCRYPT_N = "10";
+});
+
+beforeEach(() => {
+  db.run("DELETE FROM users");
+  db.run("DELETE FROM api_tokens");
+  db.run("DELETE FROM network_members");
+  db.run("DELETE FROM networks");
+  db.run("DELETE FROM audit_log");
+});
+
+// Mimic the pre-A1 unsalted SHA-256 path. Used to seed legacy rows.
+function legacyHash(plain: string): string {
+  return new Bun.CryptoHasher("sha256").update(`anet:${plain}`).digest("hex");
+}
+
+function getStoredHash(username: string): string | null {
+  const row = db.get<{ password_hash: string }>(
+    "SELECT password_hash FROM users WHERE username = ?1",
+    username
+  );
+  return row?.password_hash ?? null;
+}
+
+function insertLegacyUser(username: string, plain: string): string {
+  const userId = `usr_${username}`;
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role)
+     VALUES (?1, ?2, ?3, 'user')`,
+    [userId, username, legacyHash(plain)]
+  );
+  return userId;
+}
+
+describe("hashPassword — new format shape", () => {
+  test("produces scrypt$N$salt$hash with non-zero salt and hash", () => {
+    const stored = hashPassword("PasswordWith8+");
+    const parts = stored.split("$");
+    expect(parts.length).toBe(4);
+    expect(parts[0]).toBe("scrypt");
+    const N = parseInt(parts[1], 10);
+    expect(N).toBeGreaterThanOrEqual(8);
+    expect(N).toBeLessThanOrEqual(20);
+    expect(Buffer.from(parts[2], "base64").length).toBeGreaterThan(0);
+    expect(Buffer.from(parts[3], "base64").length).toBe(64); // SCRYPT_KEYLEN
+  });
+
+  test("salt + hash differ on every call (no static derivation)", () => {
+    const a = hashPassword("same");
+    const b = hashPassword("same");
+    const c = hashPassword("same");
+    expect(a).not.toBe(b);
+    expect(b).not.toBe(c);
+    expect(a).not.toBe(c);
+  });
+});
+
+describe("verifyPassword — new format round-trip", () => {
+  test("hashPassword + verifyPassword round-trips, needsRehash=false", () => {
+    const stored = hashPassword("MyPassw0rd!");
+    const v = verifyPassword("MyPassw0rd!", stored);
+    expect(v.ok).toBe(true);
+    expect(v.needsRehash).toBe(false);
+  });
+
+  test("wrong password rejected, needsRehash=false", () => {
+    const stored = hashPassword("MyPassw0rd!");
+    const v = verifyPassword("wrong", stored);
+    expect(v.ok).toBe(false);
+    expect(v.needsRehash).toBe(false);
+  });
+
+  test("malformed new-format strings rejected (not silently passed)", () => {
+    // Each of these tries to abuse the parser. None should yield ok=true.
+    const bad = [
+      "scrypt$$salt$hash",                       // missing N
+      "scrypt$14$$hash",                         // empty salt
+      "scrypt$14$c2FsdA==$",                     // empty hash
+      "scrypt$abc$c2FsdA==$aGFzaA==",            // non-numeric N
+      "scrypt$14$c2FsdA==$aGFzaA==$extra",       // 5 parts
+      "scrypt$14$c2FsdA==",                      // 3 parts
+      "argon2$1$c2FsdA==$aGFzaA==",              // unknown scheme
+      "scrypt$5$c2FsdA==$aGFzaA==",              // N below floor (8)
+      "scrypt$30$c2FsdA==$aGFzaA==",             // N above ceiling (20)
+    ];
+    for (const s of bad) {
+      const v = verifyPassword("anything", s);
+      expect(v.ok).toBe(false);
+    }
+  });
+});
+
+describe("verifyPassword — legacy format compatibility (A1's load-bearing claim)", () => {
+  test("legacy unsalted SHA-256 hash verifies", () => {
+    const plain = "OldUserPassw0rd";
+    const stored = legacyHash(plain);
+    const v = verifyPassword(plain, stored);
+    expect(v.ok).toBe(true);
+    expect(v.needsRehash).toBe(true); // ← KEY: caller MUST rehash
+  });
+
+  test("legacy wrong-password rejected, needsRehash=false", () => {
+    const stored = legacyHash("OldUserPassw0rd");
+    const v = verifyPassword("wrong", stored);
+    expect(v.ok).toBe(false);
+    expect(v.needsRehash).toBe(false);
+  });
+
+  test("legacy hash with wrong length rejected (not crash)", () => {
+    const v = verifyPassword("anything", "deadbeef"); // 8 hex chars, not 64
+    expect(v.ok).toBe(false);
+    expect(v.needsRehash).toBe(false);
+  });
+});
+
+describe("login() — lazy migration on success", () => {
+  test("legacy user logs in successfully AND is auto-upgraded to new format", () => {
+    insertLegacyUser("legacy-alice", "AliceP@ss123");
+
+    // Sanity: the seeded hash IS bare-hex sha256 (no $).
+    const before = getStoredHash("legacy-alice")!;
+    expect(before).not.toContain("$");
+    expect(before).toHaveLength(64);
+
+    const result = login("legacy-alice", "AliceP@ss123");
+    expect(result.ok).toBe(true);
+
+    // The load-bearing assertion: after login, the legacy hash is GONE.
+    const after = getStoredHash("legacy-alice")!;
+    expect(after).toContain("$");
+    expect(after.startsWith("scrypt$")).toBe(true);
+    expect(after).not.toBe(before);
+  });
+
+  test("legacy user wrong-password fails AND legacy hash is preserved", () => {
+    insertLegacyUser("legacy-bob", "BobP@ss123");
+    const before = getStoredHash("legacy-bob")!;
+
+    const result = login("legacy-bob", "wrong");
+    expect(result.ok).toBe(false);
+
+    // Failed login MUST NOT rehash (would leak info about format).
+    const after = getStoredHash("legacy-bob")!;
+    expect(after).toBe(before);
+    expect(after).not.toContain("$");
+  });
+
+  test("new-format user logs in without rehash (already current)", () => {
+    // First login auto-migrates; second login should not rewrite again.
+    insertLegacyUser("legacy-charlie", "CharlieP@ss");
+    const r1 = login("legacy-charlie", "CharlieP@ss");
+    expect(r1.ok).toBe(true);
+    const afterFirst = getStoredHash("legacy-charlie")!;
+
+    const r2 = login("legacy-charlie", "CharlieP@ss");
+    expect(r2.ok).toBe(true);
+    const afterSecond = getStoredHash("legacy-charlie")!;
+
+    // Same hash on consecutive logins — no spurious rewrites.
+    expect(afterSecond).toBe(afterFirst);
+  });
+});
+
+describe("register() — new users always start in new format (bootstrap admin)", () => {
+  test("freshly-registered user has scrypt$ format from row 1", () => {
+    const r = register("dave", "DaveBootstr@p", "dave@example.com", "Dave");
+    expect(r.ok).toBe(true);
+
+    const stored = getStoredHash("dave")!;
+    expect(stored.startsWith("scrypt$")).toBe(true);
+  });
+
+  test("registered user can log in (smoke for the whole pipeline)", () => {
+    register("eve", "EveP@ssword99", undefined, "Eve");
+    const login_r = login("eve", "EveP@ssword99");
+    expect(login_r.ok).toBe(true);
+  });
+
+  test("registered user wrong-password fails (smoke for new-format reject)", () => {
+    register("frank", "FrankP@ssword99", undefined, "Frank");
+    const login_r = login("frank", "wrong");
+    expect(login_r.ok).toBe(false);
+  });
+});
+
+describe("login — username enumeration timing-oracle close (round-6 A1 hardening)", () => {
+  // Independent pre-review on #285: post-A1 the user-exists +
+  // wrong-password path runs ~50ms scrypt, the user-not-found path
+  // returns sub-ms — that's a web-measurable oracle for "is this
+  // username registered". Fix: run a throwaway verifyPassword
+  // against a module-constant dummy hash on the not-found branch
+  // so wall-clock cost is comparable on both paths.
+  //
+  // The test asserts ORDER-OF-MAGNITUDE timing parity, not exact
+  // equality — scrypt timings have natural jitter and we don't
+  // want a flaky test that hammers CI on busy hosts. The check
+  // is "both paths are slow" (both > some floor), proving the
+  // dummy-verify codepath actually runs on the not-found branch.
+  test("not-found user takes scrypt-class time (not sub-ms early-return)", () => {
+    register("real-user-z", "RealUserZ123");
+
+    // Warm the JIT + paging on both paths so the first call's
+    // amortized cost doesn't skew the comparison.
+    login("real-user-z", "wrong");
+    login("does-not-exist-warmup", "wrong");
+
+    // Sample multiple times and take the median so single-call
+    // jitter doesn't dominate.
+    const sample = (fn: () => void): number => {
+      const N = 5;
+      const xs: number[] = [];
+      for (let i = 0; i < N; i++) {
+        const start = performance.now();
+        fn();
+        xs.push(performance.now() - start);
+      }
+      xs.sort((a, b) => a - b);
+      return xs[Math.floor(N / 2)];
+    };
+
+    const tExists = sample(() => { login("real-user-z", "wrong"); });
+    const tMissing = sample(() => { login("nobody-here-" + Math.random(), "wrong"); });
+
+    // The fix's load-bearing claim: BOTH paths run scrypt. At test
+    // N=10 (~5ms per scrypt), an early-return path would be < 1ms.
+    // Loose lower bound of 1ms catches an "early return" regression
+    // without being flaky on slow CI runners.
+    expect(tExists).toBeGreaterThan(1);
+    expect(tMissing).toBeGreaterThan(1);
+
+    // Ratio: both paths should be the same order of magnitude.
+    // 5x is a generous bound to avoid CI flakiness from
+    // co-scheduled scrypt workloads or paging. Pre-fix this would
+    // be 50x+ trivially.
+    const ratio = Math.max(tExists, tMissing) / Math.max(0.1, Math.min(tExists, tMissing));
+    expect(ratio).toBeLessThan(5);
+  });
+
+  test("not-found user still returns the generic error string (no info leak)", () => {
+    register("user-exists", "ExistsP@ss1");
+
+    const a = login("user-exists", "wrong");
+    const b = login("user-does-not-exist", "wrong");
+
+    expect(a.ok).toBe(false);
+    expect(b.ok).toBe(false);
+    // Both must return EXACTLY the same error string. If they
+    // diverge, the username-enumeration oracle reopens at the
+    // string-comparison layer regardless of timing.
+    expect(a.error).toBe(b.error);
+    expect(a.error).toBe("invalid username or password");
+  });
+});
+
+describe("login — timing parity across all 3 failure paths (round-6 round-2)", () => {
+  // Independent reviewer's round-2 catch on #285: the round-1 dummy-
+  // scrypt fix only equalized the !user (missing) path. legacy-user-
+  // wrong-password still ran SHA-256 only (sub-ms) while new-format-
+  // user-wrong-password ran scrypt (~50ms). That ~50x gap let an
+  // attacker distinguish "this username exists on a legacy hash" from
+  // "this username has been migrated" or "doesn't exist". Fix: burn
+  // an equal-time scrypt on the legacy-wrong-password path so all
+  // three failure paths cost SHA-256 + 1 scrypt.
+  //
+  // The test asserts ORDER-OF-MAGNITUDE timing parity (max/min ratio
+  // < 5x) — generous to avoid CI flake but pre-fix would be 50x+.
+  test("all 3 wrong-password paths take comparable scrypt-class time", () => {
+    // Setup: one user with new-format hash, one with legacy SHA-256
+    // seeded directly.
+    register("new-user", "NewUserP@ss1");
+
+    const legacyUserId = "usr_legacy_oracle";
+    const legacyHashed = new Bun.CryptoHasher("sha256").update("anet:LegacyP@ss1").digest("hex");
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role) VALUES (?1, ?2, ?3, 'user')`,
+      [legacyUserId, "legacy-user", legacyHashed]
+    );
+
+    // Warm JIT + scrypt code paths
+    login("new-user", "wrong");
+    login("legacy-user", "wrong");
+    login("nobody-here-warmup", "wrong");
+
+    const sample = (fn: () => void): number => {
+      const N = 5;
+      const xs: number[] = [];
+      for (let i = 0; i < N; i++) {
+        const start = performance.now();
+        fn();
+        xs.push(performance.now() - start);
+      }
+      xs.sort((a, b) => a - b);
+      return xs[Math.floor(N / 2)];
+    };
+
+    const tNewWrong = sample(() => { login("new-user", "wrong"); });
+    const tLegacyWrong = sample(() => { login("legacy-user", "wrong"); });
+    const tMissing = sample(() => { login("nobody-here-" + Math.random(), "wrong"); });
+
+    // All three must run scrypt (> 1ms floor — early returns are sub-ms)
+    expect(tNewWrong).toBeGreaterThan(1);
+    expect(tLegacyWrong).toBeGreaterThan(1);
+    expect(tMissing).toBeGreaterThan(1);
+
+    // Order-of-magnitude parity. Pre-fix tLegacyWrong vs tNewWrong
+    // would be 50x+. Generous 5x cap absorbs CI scheduling jitter.
+    const maxT = Math.max(tNewWrong, tLegacyWrong, tMissing);
+    const minT = Math.max(0.1, Math.min(tNewWrong, tLegacyWrong, tMissing));
+    expect(maxT / minT).toBeLessThan(5);
+  });
+
+  test("legacy-wrong-password returns the same generic error string as the other paths", () => {
+    const legacyUserId = "usr_legacy_str";
+    const legacyHashed = new Bun.CryptoHasher("sha256").update("anet:Pw1").digest("hex");
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role) VALUES (?1, ?2, ?3, 'user')`,
+      [legacyUserId, "legacy-str", legacyHashed]
+    );
+    register("new-str", "NewP@ss1");
+
+    const a = login("legacy-str", "wrong");
+    const b = login("new-str", "wrong");
+    const c = login("does-not-exist", "wrong");
+
+    expect(a.ok).toBe(false);
+    expect(b.ok).toBe(false);
+    expect(c.ok).toBe(false);
+    // All three must say EXACTLY the same thing or the oracle reopens
+    // at the response-body layer.
+    expect(a.error).toBe("invalid username or password");
+    expect(b.error).toBe(a.error);
+    expect(c.error).toBe(a.error);
+  });
+});
+
+describe("ordering invariant — single login transition (round-6 spec)", () => {
+  // The dispatch's load-bearing post-condition: "post-upgrade 旧串
+  // 不再存在 in DB". One concise pin.
+  test("after first login, legacy hash is provably absent from the row", () => {
+    const plain = "TransitionPw1";
+    insertLegacyUser("legacy-tx", plain);
+    const legacy = legacyHash(plain);
+
+    login("legacy-tx", plain);
+
+    const after = getStoredHash("legacy-tx")!;
+    expect(after).not.toBe(legacy);          // not the same string
+    expect(after.startsWith("scrypt$")).toBe(true);
+    // The legacy string is exactly 64 hex chars. The new string is
+    // markedly longer (scrypt$N$salt$hash). Verify length disjoint
+    // so any future regression that re-stores a 64-char bare hex
+    // would be caught.
+    expect(after.length).toBeGreaterThan(64);
+  });
+});

package/src/auth-tokens.test.ts

@@ -104,18 +104,27 @@ describe("hashToken — deterministic sha256", () => {
   });
 });
 
-describe("hashPassword — sha256('anet:' + password)", () => {
-  it("returns 64-char lowercase hex", () => {
-    expect(hashPassword("StrongPassw0rd")).toMatch(HEX_RE(64));
+describe("hashPassword — salted scrypt (round-6 A1)", () => {
+  it("returns scrypt$N$salt$hash self-describing format", () => {
+    const stored = hashPassword("StrongPassw0rd");
+    expect(stored).toMatch(/^scrypt\$\d+\$[A-Za-z0-9+/=]+\$[A-Za-z0-9+/=]+$/);
   });
-  it("deterministic", () => {
-    expect(hashPassword("foo")).toBe(hashPassword("foo"));
+
+  it("NON-deterministic — same password produces different salts (the whole point)", () => {
+    // The pre-A1 hashPassword was deterministic SHA-256 — rainbow-
+    // table vulnerable. Salted scrypt MUST produce different output
+    // for repeated calls. If this fails, the salt isn't random.
+    const a = hashPassword("foo");
+    const b = hashPassword("foo");
+    expect(a).not.toBe(b);
   });
-  it("uses 'anet:' salt → different from hashToken on same input", () => {
-    // This pins the 'anet:' prefix — if someone drops it, this fails,
-    // and existing user password hashes will silently stop matching.
+
+  it("does not collide with hashToken's surface (separate concerns)", () => {
+    // Pin the separation. Pre-A1 had hashPassword("foo") === hashToken("anet:foo"),
+    // which was an accidental coincidence of unsalted hashes; post-A1 the
+    // password hash carries randomness and never equals a token hash.
     expect(hashPassword("foo")).not.toBe(hashToken("foo"));
-    expect(hashPassword("foo")).toBe(hashToken("anet:foo"));
+    expect(hashPassword("foo")).not.toBe(hashToken("anet:foo"));
   });
 });
 

package/src/auth.ts

@@ -1,9 +1,33 @@
 /**
  * V3 Auth module — user registration, login, token management
  */
-import { db, generateId, hashPassword, hashToken, generateToken, generateUserToken, generateNetworkToken, uuidv4 } from "./db.js";
+import { db, generateId, hashPassword, verifyPassword, hashToken, generateToken, generateUserToken, generateNetworkToken, uuidv4 } from "./db.js";
 import { WEAK_PASSWORDS } from "./password-dict.js";
 
+// Round-6 A1 hardening — dummy hash for username-enumeration timing
+// close. We compute ONE scrypt hash of a throwaway password and reuse
+// it on every `!user` branch in login. The verify call against this
+// dummy always fails the timingSafeEqual (the candidate password is
+// unrelated), but the wall-clock cost of the scrypt() invocation is
+// identical to the user-exists path — closing the ~50ms username-
+// exists oracle that opened up when we moved off SHA-256 to scrypt.
+//
+// **Lazy** (memoized) rather than module-load constant: COMMHUB_SCRYPT_N
+// may be set after this module loads (tests do this), and the dummy
+// MUST match the current N so its scrypt cost matches the cost of
+// verifying a real stored hash. Computing on first use captures the
+// env-current N. After that it's a single fixed string for the
+// process lifetime — one scrypt per process, not per request.
+let _enumerationDummyHash: string | null = null;
+function getEnumerationDummyHash(): string {
+  if (_enumerationDummyHash === null) {
+    _enumerationDummyHash = hashPassword(
+      "agent-network::enumeration-oracle-close::do-not-match"
+    );
+  }
+  return _enumerationDummyHash;
+}
+
 export interface AuthUser {
   user_id: string;
   username: string;
@@ -19,6 +43,14 @@ export interface AuthResult {
   token?: string;           // user token (utok_)
   network_token?: string;   // network token (ntok_) for default network
   network_id?: string;
+  // #261 P0-2 (2026-06-28): true when the logged-in user still has the
+  // bootstrap-default password. The CLI client uses this to print a
+  // prominent "must change password" warning after login succeeds. NOT
+  // a login-blocker — we don't lock out anyone whose deployment ran on
+  // the old `admin/anethub` default (back-compat per 通信龙 spec). The
+  // field is intentionally absent (rather than `false`) on the normal
+  // case so old clients don't even see it.
+  must_change_password?: boolean;
 }
 
 function validatePasswordStrength(password: string, label = "password"): string | null {
@@ -93,11 +125,41 @@ export function register(username: string, password: string, email?: string, dis
 
 export function login(username: string, password: string): AuthResult {
   const user = db.get<any>(
-    "SELECT user_id, username, password_hash, display_name, email, role FROM users WHERE username = ?1",
+    "SELECT user_id, username, password_hash, display_name, email, role, must_change_password FROM users WHERE username = ?1",
     username);
 
-  if (!user) return { ok: false, error: "invalid username or password" };
-  if (user.password_hash !== hashPassword(password)) return { ok: false, error: "invalid username or password" };
+  if (!user) {
+    // Round-6 A1 hardening (timing-oracle close): pre-A1 the user-
+    // exists vs user-doesn't-exist branches both ran a µs-scale
+    // SHA-256, so wall-clock difference was lost in noise. Post-A1
+    // the user-exists path runs ~50ms scrypt while user-doesn't
+    // returns sub-ms — that ~50ms gap is web-measurable and turns
+    // login into a username-enumeration oracle (rate limiter only
+    // partially mitigates). Equalize by running scrypt against a
+    // module-constant dummy hash on the not-found path. Dummy is
+    // pre-generated at module load (not per call) so we don't burn
+    // a fresh scryptSync on every miss.
+    verifyPassword(password, getEnumerationDummyHash());
+    return { ok: false, error: "invalid username or password" };
+  }
+  // Round-6 A1: verifyPassword accepts both new scrypt format and
+  // legacy bare-sha256. On successful legacy verify, lazy-upgrade the
+  // stored hash in place (zero downtime, no forced password change).
+  const verify = verifyPassword(password, user.password_hash);
+  if (!verify.ok) return { ok: false, error: "invalid username or password" };
+  if (verify.needsRehash) {
+    try {
+      const upgraded = hashPassword(password);
+      db.run(
+        "UPDATE users SET password_hash = ?1, updated_at = datetime('now') WHERE user_id = ?2",
+        [upgraded, user.user_id]
+      );
+    } catch (e: any) {
+      // Don't fail the login if the rehash write hits a transient
+      // error — the user authenticated, we'll try again next login.
+      console.log(`[commhub auth] lazy-rehash failed for user ${user.user_id}: ${e?.message ?? e}`);
+    }
+  }
 
   // Issue a NEW user token — do NOT rotate/invalidate existing ones. Each
   // login (cli, dashboard, second machine) gets its own row so they don't
@@ -123,6 +185,9 @@ export function login(username: string, password: string): AuthResult {
     user: { user_id: user.user_id, username: user.username, display_name: user.display_name, email: user.email, role: user.role },
     token,
     network_id: networkId,
+    // #261 P0-2 — only include field when truthy (back-compat; old clients
+    // don't see this field at all unless their account is flagged).
+    ...(user.must_change_password === 1 ? { must_change_password: true } : {}),
   };
 }
 
@@ -276,12 +341,33 @@ export function changePassword(userId: string, oldPassword: string, newPassword:
   if (passwordError) return { ok: false, error: passwordError };
   const user = db.get<any>("SELECT password_hash FROM users WHERE user_id = ?1", userId);
   if (!user) return { ok: false, error: "user not found" };
-  if (user.password_hash !== hashPassword(oldPassword)) return { ok: false, error: "incorrect current password" };
-  db.run("UPDATE users SET password_hash = ?1, updated_at = datetime('now') WHERE user_id = ?2", [hashPassword(newPassword), userId]);
+  // Round-6 A1: verifyPassword accepts both formats. No need to
+  // lazy-rehash here separately because we're about to overwrite
+  // password_hash with the new password's scrypt hash below anyway.
+  const verify = verifyPassword(oldPassword, user.password_hash);
+  if (!verify.ok) return { ok: false, error: "incorrect current password" };
+  // #261 P0-2 — clearing must_change_password as a side-effect of a real
+  // password change. If the user changes via `anet passwd`, the bootstrap
+  // nudge goes away on next login. SET to 0 explicitly (rather than skip)
+  // so a future flag flip can't drift the state.
+  db.run("UPDATE users SET password_hash = ?1, must_change_password = 0, updated_at = datetime('now') WHERE user_id = ?2", [hashPassword(newPassword), userId]);
   const revoked = revokeOtherUserTokens(userId, currentTokenId);
   return { ok: true, revoked };
 }
 
+/**
+ * #261 P0-2 — mark a user as needing to change their password on first
+ * login. Called by the hub-bootstrap path (`anet hub start`) AFTER it
+ * auto-registers the admin with a random bootstrap password. Idempotent.
+ * Returns true if a row was affected (i.e. the user exists), false
+ * otherwise. NOT exposed via any HTTP endpoint — internal-only, called
+ * via direct module import or a local-process SQLite handle.
+ */
+export function markMustChangePassword(userId: string): boolean {
+  const r = db.run("UPDATE users SET must_change_password = 1 WHERE user_id = ?1", [userId]);
+  return r.changes > 0;
+}
+
 export function resetUserPassword(targetUsername: string, callerIsHubAdmin: boolean): { ok: boolean; error?: string; username?: string; user_id?: string; password?: string; token?: string; token_id?: string; revoked?: number } {
   if (!callerIsHubAdmin) return { ok: false, error: "hub admin required" };
   const user = db.get<any>("SELECT user_id, username FROM users WHERE username = ?1", targetUsername);