@proteinjs/user-server 1.18.0 → 1.20.0

package/src/routes/DevBootstrapRoles.ts

@@ -0,0 +1,50 @@
+import type { BootstrapRolesOutcome } from '../services/Roles';
+
+/**
+ * The `DEV_BOOTSTRAP_ROLES` contract of the dev role-bootstrap door (routes/devLogin.ts):
+ *
+ *   DEV_BOOTSTRAP_ROLES='email:role[,role];email:role…'
+ *
+ * Addresses and roles are trimmed; addresses are lowercased (the normalization every account
+ * email gets); a repeated address unions its roles; an entry with no `:`, no address or no role
+ * is ignored (malformed input is skipped, never fatal). The door grants the listed roles the
+ * account does not hold and logs ONE marker line per hit for a listed address —
+ * `[dev-bootstrap] <email>: granted a, b; held c; refused d (why)` — which tooling that provisions
+ * a development database can read back from the server log as proof of the grant.
+ */
+export class DevBootstrapRoles {
+  /** The roles listed for `email` in the process env (empty when the variable is unset or the address is not listed). */
+  static rolesFor(email: string): string[] {
+    return DevBootstrapRoles.parse(process.env.DEV_BOOTSTRAP_ROLES).get(email.trim().toLowerCase()) ?? [];
+  }
+
+  static parse(value: string | undefined): Map<string, string[]> {
+    const entries = new Map<string, string[]>();
+    for (const entry of (value ?? '').split(';')) {
+      const colon = entry.indexOf(':');
+      if (colon < 0) {
+        continue;
+      }
+      const email = entry.slice(0, colon).trim().toLowerCase();
+      const roles = entry
+        .slice(colon + 1)
+        .split(',')
+        .map((role) => role.trim())
+        .filter(Boolean);
+      if (!email || roles.length === 0) {
+        continue;
+      }
+      entries.set(email, Array.from(new Set([...(entries.get(email) ?? []), ...roles])));
+    }
+    return entries;
+  }
+
+  /** The one marker line per hit — a log contract its readers parse; change the shape only together with them. */
+  static markerLine(email: string, outcome: BootstrapRolesOutcome): string {
+    const list = (items: string[]) => (items.length ? items.join(', ') : '(none)');
+    return (
+      `[dev-bootstrap] ${email}: granted ${list(outcome.granted)}; held ${list(outcome.held)}; ` +
+      `refused ${list(outcome.refused.map((refusal) => `${refusal.role} (${refusal.why})`))}`
+    );
+  }
+}

package/src/routes/devLogin.ts

@@ -4,6 +4,7 @@ import { emailRegex } from '@proteinjs/util';
 import { establishSession } from '../authentication/establishSession';
 import { Roles } from '../services/Roles';
 import { Signup } from '../services/Signup';
+import { DevBootstrapRoles } from './DevBootstrapRoles';
 
 const logger = new Logger({ name: 'devLogin' });
 
@@ -45,6 +46,17 @@ const emailDomain = (address: string) => address.slice(address.lastIndexOf('@')
  * Test and prod never set it — the omission is the safety, the same idiom as the gates. The
  * outcome is logged as ONE marker line, `Dev bootstrap admin door: <granted|admin-exists>`,
  * which the n3xa compose-estate boot proof reads from the server log to PROVE the grant landed.
+ *
+ * Role-bootstrap door (`DEV_BOOTSTRAP_ROLES='email:role[,role];email:role…'`, the grammar in
+ * DevBootstrapRoles.ts): the first-admin door leaves every OTHER account role-less, and a
+ * consumer's admin-grant-only roles then need an admin's act on every fresh development database.
+ * Behind the same two gates, when the resolved address is listed, the listed roles the account
+ * does not hold are granted through `Roles.bootstrapRoles` — once each, audited, never revoking,
+ * never break-glass (refused and named, like a role the catalog does not know); the grant precedes
+ * the session so the first page load carries the roles. ONE marker line per hit for a listed
+ * address, `[dev-bootstrap] <email>: granted …; held …; refused …`, is what provisioning tooling
+ * reads back as proof. The variable absent = nothing changes; the gates closed = 404 regardless; a
+ * deployment outside development never sets it.
  */
 export const devLogin: Route = {
   path: '/dev/login',
@@ -94,6 +106,12 @@ export const devLogin: Route = {
       logger.info({ message: `Dev bootstrap admin door: ${outcome}`, obj: { email } });
     }
 
+    const bootstrapRoles = DevBootstrapRoles.rolesFor(email);
+    if (bootstrapRoles.length > 0) {
+      const outcome = await new Roles().bootstrapRoles(email, bootstrapRoles);
+      logger.info({ message: DevBootstrapRoles.markerLine(email, outcome) });
+    }
+
     // establishSession commits the session row before the redirect — the redirected GET / must
     // never read the store ahead of the write (observed: first /dev/login load landed on /login).
     await establishSession(request, email);

package/src/services/Roles.ts

@@ -11,12 +11,16 @@ import { Service } from '@proteinjs/service';
  *
  * 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).
+ * (server-internal; reachable only through `/dev/login`'s gates, never over RPC). Its sibling
+ * `bootstrapRoles` is the dev role-bootstrap door's grant — never break-glass, catalog-checked.
  *
  * 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
  * themselves out). Both directions are refused — see `changeRole`; ask another user manager.
  */
+/** What one `bootstrapRoles` call did, per role: written now, already on the row, or refused with the reason. */
+export type BootstrapRolesOutcome = { granted: string[]; held: string[]; refused: { role: string; why: string }[] };
+
 export class Roles implements RolesService {
   public serviceMetadata: Service['serviceMetadata'] = {
     auth: {
@@ -67,6 +71,62 @@ export class Roles implements RolesService {
     return 'granted';
   }
 
+  /**
+   * The dev role-bootstrap door's grant — `/dev/login` honoring `DEV_BOOTSTRAP_ROLES`
+   * (routes/devLogin.ts, the grammar in routes/DevBootstrapRoles.ts). A fresh development
+   * database has one admin at most (the first-admin door) and every other account role-less, and
+   * a consumer's `adminGrantOnly` roles can be handed out by an admin only — a manual act on
+   * every fresh database. So this grants `roles` to `email`'s account, each
+   * once: a role the account holds is `held` (no write, no audit row — idempotent); nothing is
+   * ever revoked; a role the catalog does not know or a break-glass role is `refused` and named
+   * (`bootstrapAdmin` is the ONE break-glass path, with its own rail). Admin-grant-only roles ARE
+   * granted here — that is the door's point. Every grant is audited like any grant, actor = the
+   * account itself (the door acts for nobody else), the role update and its rows in one
+   * transaction.
+   *
+   * Server-internal, like `bootstrapAdmin`: absent from `RolesService`, never RPC-reachable; the
+   * caller's two gates (DEVELOPMENT + DEV_AUTO_LOGIN_EMAIL) are the only way in, and a deployment
+   * outside development never sets the variable.
+   */
+  async bootstrapRoles(email: string, roles: string[]): Promise<BootstrapRolesOutcome> {
+    const logger = new Logger({ name: 'Roles.bootstrapRoles' });
+    const db = getDbAsSystem();
+    const user = await db.get(tables.User, { email: email.toLowerCase() });
+    if (!user) {
+      throw new Error(`bootstrapRoles: no account for ${email} — the door creates the account before it grants`);
+    }
+
+    const held = user.roles ?? [];
+    const outcome: BootstrapRolesOutcome = { granted: [], held: [], refused: [] };
+    for (const role of Array.from(new Set(roles))) {
+      const entry = RolesCatalog.getEntry(role);
+      if (!entry) {
+        outcome.refused.push({ role, why: 'unknown role' });
+      } else if (entry.breakGlass) {
+        outcome.refused.push({ role, why: 'break-glass' });
+      } else if (held.includes(role)) {
+        outcome.held.push(role);
+      } else {
+        outcome.granted.push(role);
+      }
+    }
+    if (outcome.granted.length === 0) {
+      return outcome;
+    }
+
+    await db.runTransaction(async () => {
+      await db.update(tables.User, { id: user.id, roles: [...held, ...outcome.granted] });
+      for (const role of outcome.granted) {
+        await db.insert(tables.RoleGrantEvent, { actor: user.id, target: user.id, role, action: 'grant' });
+      }
+    });
+    logger.info({
+      message: 'Roles granted by the dev role-bootstrap door',
+      obj: { target: user.id, email, granted: outcome.granted },
+    });
+    return outcome;
+  }
+
   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);

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

@@ -14,8 +14,9 @@ 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.
+ * The first-admin door (`DEV_BOOTSTRAP_ADMIN_EMAIL`) and the role-bootstrap door (`DEV_BOOTSTRAP_ROLES`)
+ * have their own suites (DevLoginBootstrapAdmin.test.ts, DevLoginBootstrapRoles.test.ts); here both
+ * variables are unset, so every created account is role-less.
  */
 
 const ENV_EMAIL = 'dev@test.local';
@@ -27,6 +28,7 @@ describe('devLogin route', () => {
     DEVELOPMENT: process.env.DEVELOPMENT,
     DEV_AUTO_LOGIN_EMAIL: process.env.DEV_AUTO_LOGIN_EMAIL,
     DEV_BOOTSTRAP_ADMIN_EMAIL: process.env.DEV_BOOTSTRAP_ADMIN_EMAIL,
+    DEV_BOOTSTRAP_ROLES: process.env.DEV_BOOTSTRAP_ROLES,
   };
 
   beforeAll(async () => {
@@ -41,6 +43,7 @@ describe('devLogin route', () => {
     process.env.DEVELOPMENT = 'true';
     process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
     delete process.env.DEV_BOOTSTRAP_ADMIN_EMAIL;
+    delete process.env.DEV_BOOTSTRAP_ROLES;
   });
 
   afterEach(() => {

package/test/DevLoginBootstrapAdmin.test.ts

@@ -33,6 +33,7 @@ describe('devLogin — the DEV_BOOTSTRAP_ADMIN_EMAIL first-admin door', () => {
     DEVELOPMENT: process.env.DEVELOPMENT,
     DEV_AUTO_LOGIN_EMAIL: process.env.DEV_AUTO_LOGIN_EMAIL,
     DEV_BOOTSTRAP_ADMIN_EMAIL: process.env.DEV_BOOTSTRAP_ADMIN_EMAIL,
+    DEV_BOOTSTRAP_ROLES: process.env.DEV_BOOTSTRAP_ROLES,
   };
 
   beforeAll(async () => {
@@ -47,6 +48,7 @@ describe('devLogin — the DEV_BOOTSTRAP_ADMIN_EMAIL first-admin door', () => {
     process.env.DEVELOPMENT = 'true';
     process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
     process.env.DEV_BOOTSTRAP_ADMIN_EMAIL = BOOTSTRAP_EMAIL;
+    delete process.env.DEV_BOOTSTRAP_ROLES; // the role-bootstrap door has its own suite; here it is closed
     // Every case starts from a fresh database: no accounts, no audit trail.
     const db = getDbAsSystem();
     await db.delete(tables.RoleGrantEvent, {});

package/test/DevLoginBootstrapRoles.test.ts

@@ -0,0 +1,248 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { Logger } from '@proteinjs/logger';
+import { SourceRepository } from '@proteinjs/reflection';
+import { RoleCatalogEntry, tables } from '@proteinjs/user';
+import { invokeDevLogin } from './devLoginHarness';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `DEV_BOOTSTRAP_ROLES` — the dev role-bootstrap door INSIDE `/dev/login`. A fresh development
+ * database has one admin at most (the first-admin door) and every other account is role-less —
+ * so a consumer's `adminGrantOnly` roles needed a manual admin act on every fresh database. The
+ * same door, the same two gates, one more variable: `email:role[,role];email:role…` — on a hit
+ * whose resolved address is listed, the listed roles the account does not hold are granted, once
+ * each:
+ *  - behind the door's existing two gates (DEVELOPMENT AND DEV_AUTO_LOGIN_EMAIL): closed = 404 as
+ *    before, and the variable changes nothing;
+ *  - only for the request whose resolved address equals a listed address exactly (case-normalized
+ *    the way every account email is) — every other address is untouched;
+ *  - idempotent: a role the account holds is reported `held`, never re-granted, never re-audited;
+ *    nothing is EVER revoked (a role the list does not name stays);
+ *  - admin-grant-only roles are granted (that is the point — a fresh development database has no
+ *    admin to grant them); break-glass and roles the catalog does not know are REFUSED and named;
+ *  - each grant is audited like any grant (a role_grant_event row; actor = the account itself);
+ *  - the outcome is ONE marker line, `[dev-bootstrap] <email>: granted …; held …; refused …`, the
+ *    line provisioning tooling reads back from the server log as its proof.
+ * Outcomes are asserted on the rows (roles, audit), the marker line on the logger (it IS the
+ * contract its readers parse).
+ */
+
+const ENV_EMAIL = 'dev@test.local';
+const TEAM_EMAIL = 'team@test.local';
+const OPS_EMAIL = 'ops@test.local';
+const ROLES_ENV = `${TEAM_EMAIL}:staff,dev;${OPS_EMAIL}:ops`;
+
+type SourceRepositoryInternals = { objectCache: Record<string, unknown[]> };
+
+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_ROLES role-bootstrap 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,
+    DEV_BOOTSTRAP_ROLES: process.env.DEV_BOOTSTRAP_ROLES,
+  };
+  let infoSpy: jest.SpyInstance;
+  const markerLines = () =>
+    infoSpy.mock.calls
+      .map((call) => String((call[0] as { message?: string })?.message ?? ''))
+      .filter((message) => message.startsWith('[dev-bootstrap]'));
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    // A consumer's catalog shape: 'staff' is admin-grant-only, 'dev'/'ops' plain.
+    (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache['@proteinjs/user/RoleCatalogEntry'] = [
+      { role: 'staff', description: 'Staff member', adminGrantOnly: true } as RoleCatalogEntry,
+      { role: 'dev', description: 'Developer tooling' } as RoleCatalogEntry,
+      { role: 'ops', description: 'Operations' } as RoleCatalogEntry,
+    ];
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    process.env.DEVELOPMENT = 'true';
+    process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
+    delete process.env.DEV_BOOTSTRAP_ADMIN_EMAIL;
+    process.env.DEV_BOOTSTRAP_ROLES = ROLES_ENV;
+    infoSpy = jest.spyOn(Logger.prototype, 'info');
+    // 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(() => {
+    infoSpy.mockRestore();
+    for (const [key, value] of Object.entries(originalEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it('a fresh database + a listed address: the account is created carrying the listed roles (the admin-grant-only one included), one audit row per role, logged in, and the marker line names the grants', async () => {
+    expect(await userRow(TEAM_EMAIL)).toBeUndefined();
+
+    const outcome = await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect(outcome.loggedInAs).toBe(TEAM_EMAIL);
+    expect(outcome.sessionSaved).toBe(true);
+    expect(outcome.redirect).toBe('/');
+    const team = await userRow(TEAM_EMAIL);
+    expect(team!.roles).toEqual(['staff', 'dev']);
+    const events = await auditRows();
+    expect(events.map((e) => ({ actor: e.actor, target: e.target, role: e.role, action: e.action }))).toEqual(
+      expect.arrayContaining([
+        { actor: team!.id, target: team!.id, role: 'staff', action: 'grant' },
+        { actor: team!.id, target: team!.id, role: 'dev', action: 'grant' },
+      ])
+    );
+    expect(events).toHaveLength(2);
+    expect(markerLines()).toEqual([`[dev-bootstrap] ${TEAM_EMAIL}: granted staff, dev; held (none); refused (none)`]);
+  });
+
+  it('a second hit for the same address writes nothing: the roles stand, the audit trail is unchanged, the marker line reports them held', async () => {
+    await invokeDevLogin({ email: TEAM_EMAIL });
+    infoSpy.mockClear();
+
+    const outcome = await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect(outcome.loggedInAs).toBe(TEAM_EMAIL);
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['staff', 'dev']);
+    expect(await auditRows()).toHaveLength(2);
+    expect(markerLines()).toEqual([`[dev-bootstrap] ${TEAM_EMAIL}: granted (none); held staff, dev; refused (none)`]);
+  });
+
+  it('an existing account holding one listed role and one unlisted role: only the missing role is granted, the unlisted one stays — the door never revokes', async () => {
+    await testEnv.createUser({ name: 'Team', email: TEAM_EMAIL, roles: ['dev', 'sessions'] });
+
+    await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['dev', 'sessions', 'staff']);
+    const events = await auditRows();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ role: 'staff', action: 'grant' });
+    expect(markerLines()).toEqual([`[dev-bootstrap] ${TEAM_EMAIL}: granted staff; held dev; refused (none)`]);
+  });
+
+  it('an address the list does not name: an ordinary account, no grant, no audit row, no marker line — and the listed addresses stay 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(markerLines()).toEqual([]);
+    expect(await userRow(TEAM_EMAIL)).toBeUndefined();
+    expect(await userRow(OPS_EMAIL)).toBeUndefined();
+  });
+
+  it('each listed address gets ITS roles only — the second entry never inherits the first', async () => {
+    await invokeDevLogin({ email: OPS_EMAIL });
+
+    expect((await userRow(OPS_EMAIL))!.roles).toEqual(['ops']);
+    expect(await auditRows()).toHaveLength(1);
+    expect(markerLines()).toEqual([`[dev-bootstrap] ${OPS_EMAIL}: granted ops; held (none); refused (none)`]);
+  });
+
+  it('the match is case-normalized like every account email, and the grammar tolerates whitespace around every token', async () => {
+    process.env.DEV_BOOTSTRAP_ROLES = ` Team@Test.local : staff , dev ; ${OPS_EMAIL}: ops `;
+
+    await invokeDevLogin({ email: 'team@test.local' });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['staff', 'dev']);
+    expect(await auditRows()).toHaveLength(2);
+  });
+
+  it('a role the catalog does not know is refused and named; the known roles in the same entry are still granted', async () => {
+    process.env.DEV_BOOTSTRAP_ROLES = `${TEAM_EMAIL}:staff,no-such-role`;
+
+    await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['staff']);
+    expect(await auditRows()).toHaveLength(1);
+    expect(markerLines()).toEqual([
+      `[dev-bootstrap] ${TEAM_EMAIL}: granted staff; held (none); refused no-such-role (unknown role)`,
+    ]);
+  });
+
+  it("break-glass is never this door's to grant: 'admin' in the list is refused and named (the first-admin door is the one path)", async () => {
+    process.env.DEV_BOOTSTRAP_ROLES = `${TEAM_EMAIL}:admin,dev`;
+
+    await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['dev']);
+    expect(await adminRows()).toHaveLength(0);
+    expect((await auditRows()).map((e) => e.role)).toEqual(['dev']);
+    expect(markerLines()).toEqual([
+      `[dev-bootstrap] ${TEAM_EMAIL}: granted dev; held (none); refused admin (break-glass)`,
+    ]);
+  });
+
+  it('the default path is a request for DEV_AUTO_LOGIN_EMAIL: when that address is listed, the default account carries the roles', async () => {
+    process.env.DEV_BOOTSTRAP_ROLES = `${ENV_EMAIL}:dev`;
+
+    const outcome = await invokeDevLogin();
+
+    expect(outcome.loggedInAs).toBe(ENV_EMAIL);
+    expect((await userRow(ENV_EMAIL))!.roles).toEqual(['dev']);
+    expect(await auditRows()).toHaveLength(1);
+  });
+
+  it('composes with the first-admin door: the same address listed in both gets admin first, then its roles — three audited grants, one account', async () => {
+    process.env.DEV_BOOTSTRAP_ADMIN_EMAIL = TEAM_EMAIL;
+
+    await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['admin', 'staff', 'dev']);
+    expect(await auditRows()).toHaveLength(3);
+    expect(await adminRows()).toHaveLength(1);
+  });
+
+  it('with the variable unset a listed address is an ordinary account — the omission is the safety (a deployment outside development never sets it)', async () => {
+    delete process.env.DEV_BOOTSTRAP_ROLES;
+
+    await invokeDevLogin({ email: TEAM_EMAIL });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+    expect(markerLines()).toEqual([]);
+  });
+
+  it('malformed entries (no colon, no roles) are ignored; the well-formed entries beside them are honored', async () => {
+    process.env.DEV_BOOTSTRAP_ROLES = `garbage;${OPS_EMAIL}:;${TEAM_EMAIL}:dev;:ops`;
+
+    await invokeDevLogin({ email: TEAM_EMAIL });
+    await invokeDevLogin({ email: OPS_EMAIL });
+
+    expect((await userRow(TEAM_EMAIL))!.roles).toEqual(['dev']);
+    expect((await userRow(OPS_EMAIL))!.roles).toEqual([]);
+    expect(await auditRows()).toHaveLength(1);
+  });
+
+  it.each([['DEVELOPMENT'], ['DEV_AUTO_LOGIN_EMAIL']])(
+    'gate closed (%s unset): 404 exactly as before — no session, no account, no grant; the variable changes nothing',
+    async (gate) => {
+      delete process.env[gate];
+
+      const outcome = await invokeDevLogin({ email: TEAM_EMAIL });
+
+      expect(outcome.status).toBe(404);
+      expect(outcome.loggedInAs).toBeUndefined();
+      expect(outcome.sessionSaved).toBe(false);
+      expect(await userRow(TEAM_EMAIL)).toBeUndefined();
+      expect(await auditRows()).toHaveLength(0);
+      expect(markerLines()).toEqual([]);
+    }
+  );
+});

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);
-  });
 });