@proteinjs/user-server 1.17.0 → 1.19.0

package/src/services/Roles.ts

@@ -1,4 +1,4 @@
-import { getDbAsSystem } from '@proteinjs/db';
+import { getDbAsSystem, QueryBuilderFactory } from '@proteinjs/db';
 import { RolesService, RolesCatalog, UserAuth, UserRepo, tables, USER_PERMISSIONS } from '@proteinjs/user';
 import { Logger } from '@proteinjs/logger';
 import { Service } from '@proteinjs/service';
@@ -9,7 +9,9 @@ import { Service } from '@proteinjs/service';
  * audited: the role update and its `role_grant_event` row (actor, target, role, action; `created`
  * is the timestamp) commit in one transaction, so the trail cannot diverge from the grants.
  *
- * Break-glass roles are never granted here — see `changeRole`; revoking one stays allowed.
+ * Break-glass roles are never granted through the service door — see `changeRole`; revoking one
+ * stays allowed. The ONE break-glass grant in code is `bootstrapAdmin`, the dev first-admin door
+ * (server-internal; reachable only through `/dev/login`'s gates, never over RPC).
  *
  * Nobody edits their OWN roles: separating 'roles' from 'users' means nothing if the holder can
  * simply grant themselves more, and a self-revoke is the mirror hazard (the last holder locking
@@ -30,6 +32,41 @@ export class Roles implements RolesService {
     await this.changeRole(userId, role, 'revoke');
   }
 
+  /**
+   * The dev first-admin door's grant — `/dev/login` honoring `DEV_BOOTSTRAP_ADMIN_EMAIL`
+   * (routes/devLogin.ts). A fresh dev database has no privileged account to grant from, and the
+   * only other path to break-glass is a manual UPDATE in Spanner Studio — right for prod and every
+   * clone-backed instance, wrong for a lane's throwaway estate on a real dev database, where raw
+   * writes are forbidden. So this grants 'admin' to `email`'s account exactly when NO account
+   * carries it yet (the membership test `UserAuth.hasRole` makes, over every row), audited like
+   * any grant — actor = the account itself, because the door acts for nobody else. Once an admin
+   * exists it never grants again: every later grant rides Admin → Users.
+   *
+   * Server-internal, like `Signup.createAccount`: absent from `RolesService`, so never
+   * RPC-reachable. The caller's two gates (DEVELOPMENT + DEV_AUTO_LOGIN_EMAIL) are the only way
+   * in, and test/prod never set the variable.
+   */
+  async bootstrapAdmin(email: string): Promise<'granted' | 'admin-exists' | 'no-account'> {
+    const logger = new Logger({ name: 'Roles.bootstrapAdmin' });
+    const db = getDbAsSystem();
+    if (await this.adminExists()) {
+      return 'admin-exists';
+    }
+
+    const user = await db.get(tables.User, { email: email.toLowerCase() });
+    if (!user) {
+      return 'no-account';
+    }
+
+    const roles = user.roles ?? [];
+    await db.runTransaction(async () => {
+      await db.update(tables.User, { id: user.id, roles: [...roles, 'admin'] });
+      await db.insert(tables.RoleGrantEvent, { actor: user.id, target: user.id, role: 'admin', action: 'grant' });
+    });
+    logger.info({ message: 'Break-glass admin granted by the dev first-admin door', obj: { target: user.id, email } });
+    return 'granted';
+  }
+
   private async changeRole(userId: string, role: string, action: 'grant' | 'revoke'): Promise<void> {
     const logger = new Logger({ name: `Roles.${action}Role` });
     const entry = RolesCatalog.getEntry(role);
@@ -39,8 +76,9 @@ export class Roles implements RolesService {
 
     // Break-glass passes every permission check, so no permission-mapped role — including
     // 'roles' — may mint it: the only path to break-glass is a manual UPDATE on the user row
-    // in Spanner Studio, by a human, on purpose. Revoke stays open: de-escalation toward
-    // "held by nobody day-to-day" should ride the audited path, not require database access.
+    // in Spanner Studio, by a human, on purpose (and, on a DEV server only, the first-admin door
+    // `bootstrapAdmin`). Revoke stays open: de-escalation toward "held by nobody day-to-day"
+    // should ride the audited path, not require database access.
     if (entry.breakGlass && action === 'grant') {
       throw new Error(
         `'${role}' is a break-glass role — this service refuses to grant it. The only path to ` +
@@ -106,4 +144,11 @@ export class Roles implements RolesService {
       obj: { actor: actor.id, target: userId, role },
     });
   }
+
+  /** Whether any account carries the break-glass role — `UserAuth.hasRole`'s membership test, over every row. */
+  private async adminExists(): Promise<boolean> {
+    const qb = new QueryBuilderFactory().getQueryBuilder(tables.User).select({ fields: ['id', 'roles'] });
+    const users = await getDbAsSystem().query(tables.User, qb);
+    return users.some((user) => (user.roles ?? []).includes('admin'));
+  }
 }

package/src/services/UserPresence.ts

@@ -0,0 +1,26 @@
+import { Service } from '@proteinjs/service';
+import { UserPresenceService, UserRepo, type User } from '@proteinjs/user';
+import { UserActivityStamp } from '../authorization/UserActivityStamp';
+
+/**
+ * The server end of the human-input presence door (UserActivityTable's contract): the page
+ * reports "a person interacted just now" and this writes the `user_activity` stamp for the
+ * CALLING user — the one write path onto presence. Any signed-in user may report their own
+ * presence and nobody else's (the user is the session's, never an argument); the guest identity
+ * and machine accounts are refused inside the stamp. `doNotAwait`: the page never waits on its
+ * own stamp, and a lost stamp is minutes of staleness at day grain, never a failed call.
+ */
+export class UserPresence implements UserPresenceService {
+  public serviceMetadata: Service['serviceMetadata'] = {
+    auth: {
+      allUsers: true,
+    },
+    doNotAwait: true,
+  };
+
+  private stamp = new UserActivityStamp();
+
+  async recordPresence(): Promise<void> {
+    await this.stamp.recordHumanInput(new UserRepo().getUser() as Pick<User, 'id' | 'machine'>);
+  }
+}

package/test/DevLogin.test.ts

@@ -1,8 +1,7 @@
 import { getDbAsSystem } from '@proteinjs/db';
 import { tables } from '@proteinjs/user';
 import { PasswordHasher } from '../src/authentication/PasswordHasher';
-import { devLogin } from '../src/routes/devLogin';
-import { createPassportRequest } from './passportSessionHarness';
+import { invokeDevLogin } from './devLoginHarness';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 
 const testEnv = new UserServerTestEnvironment();
@@ -15,50 +14,19 @@ const testEnv = new UserServerTestEnvironment();
  * - Double gate: `DEVELOPMENT` AND `DEV_AUTO_LOGIN_EMAIL` both present, else 404 (unchanged).
  * - Domain rail: a `?email=` param must share `DEV_AUTO_LOGIN_EMAIL`'s domain — even a dev server
  *   must not mint sessions (much less accounts) for arbitrary domains. Others 400.
+ * The first-admin door (`DEV_BOOTSTRAP_ADMIN_EMAIL`) has its own suite, DevLoginBootstrapAdmin.test.ts;
+ * here the variable is unset, so every created account is role-less.
  */
 
 const ENV_EMAIL = 'dev@test.local';
 
-type RouteOutcome = {
-  loggedInAs?: string;
-  sessionRegenerated: boolean;
-  sessionSaved: boolean;
-  status?: number;
-  body?: unknown;
-  redirect?: string;
-};
-
-const invokeDevLogin = async (query?: Record<string, unknown>): Promise<RouteOutcome> => {
-  // REAL passport login machinery (see passportSessionHarness): the full contract
-  // (regenerate → login → save) is pinned by SignupRoute.test.ts — here we assert the dev door
-  // INHERITS it.
-  const { request, events } = await createPassportRequest({ query });
-  const outcome: RouteOutcome = { sessionRegenerated: false, sessionSaved: false };
-  const response = {
-    status(code: number) {
-      outcome.status = code;
-      return this;
-    },
-    send(body?: unknown) {
-      outcome.body = body;
-    },
-    redirect(path: string) {
-      outcome.redirect = path;
-    },
-  };
-  await devLogin.onRequest(request as never, response as never);
-  outcome.loggedInAs = request.session.passport?.user;
-  outcome.sessionRegenerated = events.includes('regenerate');
-  outcome.sessionSaved = events.includes('save');
-  return outcome;
-};
-
 const getUserRow = async (email: string) => await getDbAsSystem().get(tables.User, { email });
 
 describe('devLogin route', () => {
   const originalEnv = {
     DEVELOPMENT: process.env.DEVELOPMENT,
     DEV_AUTO_LOGIN_EMAIL: process.env.DEV_AUTO_LOGIN_EMAIL,
+    DEV_BOOTSTRAP_ADMIN_EMAIL: process.env.DEV_BOOTSTRAP_ADMIN_EMAIL,
   };
 
   beforeAll(async () => {
@@ -72,6 +40,7 @@ describe('devLogin route', () => {
   beforeEach(() => {
     process.env.DEVELOPMENT = 'true';
     process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
+    delete process.env.DEV_BOOTSTRAP_ADMIN_EMAIL;
   });
 
   afterEach(() => {

package/test/DevLoginBootstrapAdmin.test.ts

@@ -0,0 +1,175 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables } from '@proteinjs/user';
+import { invokeDevLogin } from './devLoginHarness';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `DEV_BOOTSTRAP_ADMIN_EMAIL` — the first-admin door INSIDE `/dev/login` (n3xa plans/DEV_ESTATES.md
+ * D3, founder-ruled 2026-09-04). A dev estate on a fresh real database has no privileged account
+ * to grant from, and the no-raw-DB rule forbids the emulator-era seed scripts there — so the ONE
+ * sanctioned account door mints break-glass, once:
+ *  - behind the door's existing two gates (DEVELOPMENT AND DEV_AUTO_LOGIN_EMAIL): closed = 404 as
+ *    before, and the variable changes nothing;
+ *  - only while NO account carries 'admin' (the same membership test the app's admin checks make);
+ *  - only for the request whose resolved address equals the variable exactly (case-normalized
+ *    the way every account email is);
+ *  - once, audited like any grant (a role_grant_event row; actor = the account itself — the door
+ *    acts for nobody else); a later call finds an admin and grants nothing.
+ * Outcomes are asserted on the rows (roles, audit), never on calls.
+ */
+
+const ENV_EMAIL = 'dev@test.local';
+const BOOTSTRAP_EMAIL = 'owner@test.local';
+
+const userRow = async (email: string) => await getDbAsSystem().get(tables.User, { email });
+const auditRows = async () => await getDbAsSystem().query(tables.RoleGrantEvent, {});
+const adminRows = async () =>
+  (await getDbAsSystem().query(tables.User, {})).filter((user) => (user.roles ?? []).includes('admin'));
+
+describe('devLogin — the DEV_BOOTSTRAP_ADMIN_EMAIL first-admin door', () => {
+  const originalEnv = {
+    DEVELOPMENT: process.env.DEVELOPMENT,
+    DEV_AUTO_LOGIN_EMAIL: process.env.DEV_AUTO_LOGIN_EMAIL,
+    DEV_BOOTSTRAP_ADMIN_EMAIL: process.env.DEV_BOOTSTRAP_ADMIN_EMAIL,
+  };
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    process.env.DEVELOPMENT = 'true';
+    process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
+    process.env.DEV_BOOTSTRAP_ADMIN_EMAIL = BOOTSTRAP_EMAIL;
+    // Every case starts from a fresh database: no accounts, no audit trail.
+    const db = getDbAsSystem();
+    await db.delete(tables.RoleGrantEvent, {});
+    await db.delete(tables.User, {});
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(originalEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it('a fresh database + the matching address: the account is created carrying admin, audited once, and logged in', async () => {
+    expect(await userRow(BOOTSTRAP_EMAIL)).toBeUndefined();
+
+    const outcome = await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+    expect(outcome.loggedInAs).toBe(BOOTSTRAP_EMAIL);
+    expect(outcome.sessionSaved).toBe(true);
+    expect(outcome.redirect).toBe('/');
+    const owner = await userRow(BOOTSTRAP_EMAIL);
+    expect(owner!.roles).toEqual(['admin']);
+    const events = await auditRows();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ actor: owner!.id, target: owner!.id, role: 'admin', action: 'grant' });
+    expect(await adminRows()).toHaveLength(1);
+  });
+
+  it('a second call for the same address changes nothing: still exactly one admin, one grant', async () => {
+    await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+    const outcome = await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+    expect(outcome.loggedInAs).toBe(BOOTSTRAP_EMAIL);
+    expect((await userRow(BOOTSTRAP_EMAIL))!.roles).toEqual(['admin']);
+    expect(await auditRows()).toHaveLength(1);
+    expect(await adminRows()).toHaveLength(1);
+  });
+
+  it('an existing role-less account at the matching address is granted admin on its next login — the door serves created and loaded accounts alike', async () => {
+    await testEnv.createUser({ name: 'Owner', email: BOOTSTRAP_EMAIL });
+
+    const outcome = await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+    expect(outcome.loggedInAs).toBe(BOOTSTRAP_EMAIL);
+    expect((await userRow(BOOTSTRAP_EMAIL))!.roles).toEqual(['admin']);
+    expect(await auditRows()).toHaveLength(1);
+  });
+
+  it('the default path is a request for DEV_AUTO_LOGIN_EMAIL: when that IS the bootstrap address, the default account carries admin', async () => {
+    process.env.DEV_BOOTSTRAP_ADMIN_EMAIL = ENV_EMAIL;
+
+    const outcome = await invokeDevLogin();
+
+    expect(outcome.loggedInAs).toBe(ENV_EMAIL);
+    expect((await userRow(ENV_EMAIL))!.roles).toEqual(['admin']);
+    expect(await auditRows()).toHaveLength(1);
+  });
+
+  it('the match is case-normalized like every account email — never a second account for a differently-cased address', async () => {
+    process.env.DEV_BOOTSTRAP_ADMIN_EMAIL = 'Owner@Test.local';
+
+    await invokeDevLogin({ email: 'owner@test.local' });
+
+    expect((await userRow(BOOTSTRAP_EMAIL))!.roles).toEqual(['admin']);
+    expect(await adminRows()).toHaveLength(1);
+  });
+
+  it('an admin already exists: the matching address gets an ordinary account — no grant, no audit row', async () => {
+    await testEnv.createUser({ name: 'Standing admin', email: 'standing-admin@test.local', roles: ['admin'] });
+
+    const outcome = await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+    expect(outcome.loggedInAs).toBe(BOOTSTRAP_EMAIL);
+    expect((await userRow(BOOTSTRAP_EMAIL))!.roles).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+    expect((await adminRows()).map((user) => user.email)).toEqual(['standing-admin@test.local']);
+  });
+
+  it('a different same-domain address: an ordinary account, no grant — and the bootstrap address itself stays uncreated', async () => {
+    const outcome = await invokeDevLogin({ email: 'agent@test.local' });
+
+    expect(outcome.loggedInAs).toBe('agent@test.local');
+    expect((await userRow('agent@test.local'))!.roles).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+    expect(await userRow(BOOTSTRAP_EMAIL)).toBeUndefined();
+    expect(await adminRows()).toHaveLength(0);
+  });
+
+  it('the address must match exactly — a plus-suffixed variant is a different account and gets nothing', async () => {
+    const outcome = await invokeDevLogin({ email: 'owner+lane@test.local' });
+
+    expect(outcome.loggedInAs).toBe('owner+lane@test.local');
+    expect((await userRow('owner+lane@test.local'))!.roles).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+  });
+
+  it('with the variable unset the matching address is an ordinary account — the omission is the safety (test/prod never set it)', async () => {
+    delete process.env.DEV_BOOTSTRAP_ADMIN_EMAIL;
+
+    await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+    expect((await userRow(BOOTSTRAP_EMAIL))!.roles).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+  });
+
+  it.each([['DEVELOPMENT'], ['DEV_AUTO_LOGIN_EMAIL']])(
+    'gate closed (%s unset): 404 exactly as before — no session, no account, no admin; the variable changes nothing',
+    async (gate) => {
+      delete process.env[gate];
+
+      const outcome = await invokeDevLogin({ email: BOOTSTRAP_EMAIL });
+
+      expect(outcome.status).toBe(404);
+      expect(outcome.loggedInAs).toBeUndefined();
+      expect(outcome.sessionSaved).toBe(false);
+      expect(await userRow(BOOTSTRAP_EMAIL)).toBeUndefined();
+      expect(await auditRows()).toHaveLength(0);
+      expect(await adminRows()).toHaveLength(0);
+    }
+  );
+});

package/test/UserActivityStamp.integration.test.ts

@@ -1,8 +1,8 @@
 import moment from 'moment';
 import { getDbAsSystem } from '@proteinjs/db';
-import { tables, type User, type UserActivity } from '@proteinjs/user';
-import { userCache } from '../src/authorization/userCache';
+import { guestUser, tables, type User, type UserActivity } from '@proteinjs/user';
 import { UserActivityStamp } from '../src/authorization/UserActivityStamp';
+import { UserPresence } from '../src/services/UserPresence';
 import { UserServerTestEnvironment } from './UserServerTestEnvironment';
 
 const testEnv = new UserServerTestEnvironment();
@@ -16,26 +16,15 @@ const stampInternals = (stamp: UserActivityStamp) => (stamp as unknown as StampI
 const activityRows = async (scope: string): Promise<UserActivity[]> =>
   await getDbAsSystem().query(tables.UserActivity, { scope });
 
-/** The stamp write is fire-and-forget off userCache — poll the OUTCOME (row present) briefly. */
-const waitForActivityRow = async (scope: string): Promise<UserActivity> => {
-  for (let attempt = 0; attempt < 50; attempt++) {
-    const rows = await activityRows(scope);
-    if (rows.length > 0) {
-      return rows[0];
-    }
-    await new Promise((resolve) => setTimeout(resolve, 100));
-  }
-  throw new Error(`No user_activity row appeared for scope ${scope}`);
-};
-
 /**
- * LAST ACTIVITY = HUMAN PRESENCE (UserActivityTable's contract): the stamp fires from
- * userCache.create — the once-per-interactive-request session-cache build — and from nowhere
- * else. These tests pin the seam's outcomes: a human's request lands the presence row; machine
- * accounts (real sessions, e.g. the error bridge's polling login) never do; repeated stamps
- * keep ONE row per user; the throttle holds writes to the interval.
+ * LAST ACTIVITY = HUMAN PRESENCE (UserActivityTable's contract): the stamp is written from the
+ * page's human-input report — the UserPresence service door — and from nowhere else (the
+ * session build's non-stamp is pinned in UserCacheDoesNotStampPresence). These tests pin the
+ * door's outcomes: a person's report lands the presence row for the CALLING user; machine
+ * accounts and the guest identity never do; repeated reports keep ONE row per user; the
+ * throttle holds writes to the interval.
  */
-describe('UserActivityStamp — interactive presence', () => {
+describe('UserActivityStamp — human-input presence', () => {
   beforeAll(async () => {
     await testEnv.beforeAll();
   });
@@ -49,34 +38,36 @@ describe('UserActivityStamp — interactive presence', () => {
     stampInternals(new UserActivityStamp()).lastStampMs.clear();
   });
 
-  it('stamps presence when a signed-in human makes an interactive request (through userCache.create)', async () => {
+  it('the presence door stamps the calling user: a page report under her session lands her row', async () => {
     const user = await testEnv.createUser({ name: 'Present Human', email: 'present-human@test.local' });
+    testEnv.actAs(user);
 
-    const resolved = await userCache.create('interactive-session', user.email);
-    expect(resolved.id).toBe(user.id);
+    await new UserPresence().recordPresence();
 
-    const row = await waitForActivityRow(user.id);
-    expect(moment(row.lastActiveAt).isAfter(moment().subtract(1, 'minute'))).toBe(true);
+    const rows = await activityRows(user.id);
+    expect(rows).toHaveLength(1);
+    expect(moment(rows[0].lastActiveAt).isAfter(moment().subtract(1, 'minute'))).toBe(true);
   });
 
-  it('keeps ONE row per user and advances it on later stamps (scope-unique invariant)', async () => {
+  it('keeps ONE row per user and advances it on later reports (scope-unique invariant)', async () => {
     const user = await testEnv.createUser({ name: 'Returning Human', email: 'returning-human@test.local' });
     const stamp = new UserActivityStamp();
 
-    await stamp.recordInteractiveRequest(user);
-    const first = await waitForActivityRow(user.id);
+    await stamp.recordHumanInput(user);
+    const [first] = await activityRows(user.id);
+    expect(first).toBeDefined();
 
-    // Clear the throttle so the second request stamps immediately.
+    // Clear the throttle so the second report stamps immediately.
     stampInternals(stamp).lastStampMs.clear();
     await new Promise((resolve) => setTimeout(resolve, 5));
-    await stamp.recordInteractiveRequest(user);
+    await stamp.recordHumanInput(user);
 
     const rows = await activityRows(user.id);
     expect(rows).toHaveLength(1);
     expect(moment(rows[0].lastActiveAt).valueOf()).toBeGreaterThanOrEqual(moment(first.lastActiveAt).valueOf());
   });
 
-  it('never stamps a machine account, even though its requests ride a real session', async () => {
+  it('never stamps a machine account (`machine` — the one owner of "is this a machine"), even through the door', async () => {
     const machine = await getDbAsSystem().insert(tables.User, {
       name: 'Ops machine',
       email: 'stamp-machine@test.local',
@@ -84,39 +75,36 @@ describe('UserActivityStamp — interactive presence', () => {
       emailVerified: true,
       roles: [],
       isLoadedFromSource: true,
+      machine: true,
     } as unknown as User);
 
-    // Await the stamp DIRECTLY (deterministic absence — no fire-and-forget race), then confirm
-    // the transport seam agrees by resolving the machine session through userCache too.
-    await new UserActivityStamp().recordInteractiveRequest(machine);
-    const resolved = await userCache.create('machine-session', machine.email);
-    expect(resolved.id).toBe(machine.id);
-    await new Promise((resolve) => setTimeout(resolve, 300));
+    await new UserActivityStamp().recordHumanInput(machine);
+    testEnv.actAs(machine);
+    await new UserPresence().recordPresence();
 
     expect(await activityRows(machine.id)).toHaveLength(0);
   });
 
-  it('throttles: a second request inside the interval writes nothing', async () => {
+  it('never stamps the guest identity (a door reached with no signed-in user)', async () => {
+    const before = (await getDbAsSystem().query(tables.UserActivity, {})).length;
+    await new UserActivityStamp().recordHumanInput(guestUser);
+    expect((await getDbAsSystem().query(tables.UserActivity, {})).length).toBe(before);
+  });
+
+  it('throttles: a second report inside the interval writes nothing', async () => {
     const user = await testEnv.createUser({ name: 'Rapid Human', email: 'rapid-human@test.local' });
     const stamp = new UserActivityStamp();
 
-    await stamp.recordInteractiveRequest(user);
-    const first = await waitForActivityRow(user.id);
+    await stamp.recordHumanInput(user);
+    const [first] = await activityRows(user.id);
+    expect(first).toBeDefined();
 
-    // Throttle history now holds this user; a second stamp inside the interval must not write.
-    await stamp.recordInteractiveRequest(user);
+    // Throttle history now holds this user; a second report inside the interval must not write.
+    await stamp.recordHumanInput(user);
     await new Promise((resolve) => setTimeout(resolve, 300));
 
     const rows = await activityRows(user.id);
     expect(rows).toHaveLength(1);
     expect(moment(rows[0].lastActiveAt).valueOf()).toBe(moment(first.lastActiveAt).valueOf());
   });
-
-  it('a session for a missing account still resolves guest and stamps nothing (no throw)', async () => {
-    const before = (await getDbAsSystem().query(tables.UserActivity, {})).length;
-    const resolved = await userCache.create('stale-session', 'no-such-account@test.local');
-    expect(resolved.id).toBe('guest');
-    await new Promise((resolve) => setTimeout(resolve, 200));
-    expect((await getDbAsSystem().query(tables.UserActivity, {})).length).toBe(before);
-  });
 });

package/test/UserCacheDoesNotStampPresence.integration.test.ts

@@ -0,0 +1,44 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables, type UserActivity } from '@proteinjs/user';
+import { userCache } from '../src/authorization/userCache';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+const activityRows = async (scope: string): Promise<UserActivity[]> =>
+  await getDbAsSystem().query(tables.UserActivity, { scope });
+
+/**
+ * TRANSPORT IS NOT PRESENCE (UserActivityTable's contract; founder finding 2026-09-12 — every
+ * user on the admin usage page "last active today"). The per-request session-cache build
+ * (`userCache.create`) runs for EVERY request that rides a session cookie: an open tab's polls,
+ * a socket's room re-joins on every reconnect, the reload a deploy pushes onto every idle tab.
+ * None of that is a person. The build must therefore never write the presence stamp — the
+ * only door is the page's human-input report (UserPresence.recordPresence).
+ *
+ * Pre-fix, `userCache.create` stamped on every build: this test reads one row where the
+ * contract says none.
+ */
+describe('userCache.create — the session build does not stamp presence', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  it('resolving a human session (any request over a session cookie) writes NO user_activity row', async () => {
+    const user = await testEnv.createUser({ name: 'Idle Tab', email: 'idle-tab@test.local' });
+
+    // Three request-shaped builds: a poll, a reconnect re-join, a deploy reload — all the same seam.
+    for (const sessionId of ['poll', 'socket-rejoin', 'deploy-reload']) {
+      const resolved = await userCache.create(sessionId, user.email);
+      expect(resolved.id).toBe(user.id);
+    }
+    // The pre-fix stamp was fire-and-forget off the build — give it every chance to land.
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    expect(await activityRows(user.id)).toHaveLength(0);
+  });
+});

package/test/devLoginHarness.ts

@@ -0,0 +1,39 @@
+import { devLogin } from '../src/routes/devLogin';
+import { createPassportRequest } from './passportSessionHarness';
+
+/** What one `GET /dev/login` did, seen from outside: the session it minted (or not) and the response it sent. */
+export type DevLoginOutcome = {
+  loggedInAs?: string;
+  sessionRegenerated: boolean;
+  sessionSaved: boolean;
+  status?: number;
+  body?: unknown;
+  redirect?: string;
+};
+
+/**
+ * Drives the devLogin route once over the REAL passport login machinery (see
+ * passportSessionHarness): the full session-establishment contract (regenerate → login → save)
+ * is pinned by SignupRoute.test.ts — the dev-door suites assert the door INHERITS it.
+ */
+export const invokeDevLogin = async (query?: Record<string, unknown>): Promise<DevLoginOutcome> => {
+  const { request, events } = await createPassportRequest({ query });
+  const outcome: DevLoginOutcome = { sessionRegenerated: false, sessionSaved: false };
+  const response = {
+    status(code: number) {
+      outcome.status = code;
+      return this;
+    },
+    send(body?: unknown) {
+      outcome.body = body;
+    },
+    redirect(path: string) {
+      outcome.redirect = path;
+    },
+  };
+  await devLogin.onRequest(request as never, response as never);
+  outcome.loggedInAs = request.session.passport?.user;
+  outcome.sessionRegenerated = events.includes('regenerate');
+  outcome.sessionSaved = events.includes('save');
+  return outcome;
+};