@proteinjs/user-server 1.19.0 → 1.20.1

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/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/UserCacheDoesNotStampPresence.integration.test.ts

@@ -9,8 +9,8 @@ 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
+ * TRANSPORT IS NOT PRESENCE (UserActivityTable's contract; the defect it names: every user read
+ * as "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