@proteinjs/user-server 1.5.1 → 1.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/user-server",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "User server components",
   "publishConfig": {
     "access": "public"
@@ -19,21 +19,22 @@
     "clean": "rm -rf dist/ generated/ node_modules/",
     "build": "reflection-build && tsc",
     "watch": "reflection-watch",
-    "test": "jest --passWithNoTests"
+    "test": "jest --runInBand --passWithNoTests"
   },
   "dependencies": {
-    "@proteinjs/db": "^1.27.0",
-    "@proteinjs/email-server": "^1.2.18",
+    "@proteinjs/db": "^1.28.0",
+    "@proteinjs/email-server": "^1.3.0",
     "@proteinjs/logger": "^1.0.21",
     "@proteinjs/reflection": "^1.1.12",
-    "@proteinjs/server": "^3.1.14",
+    "@proteinjs/server": "^3.2.0",
     "@proteinjs/server-api": "^3.0.10",
-    "@proteinjs/user": "^1.6.1",
+    "@proteinjs/user": "^1.7.0",
     "crypto-js": "4.0.0",
     "express-session": "1.17.1",
     "moment": "2.29.4"
   },
   "devDependencies": {
+    "@proteinjs/db-driver-spanner": "^1.14.3",
     "@proteinjs/reflection-build": "^1.4.10",
     "@types/crypto-js": "4.0.1",
     "@types/express-session": "1.17.0",

package/src/authorization/userCache.ts

@@ -16,7 +16,7 @@ export const userCache: SessionDataCache<User> = {
           email: adminCredentials.username,
           password: adminCredentials.password,
           emailVerified: true,
-          roles: 'admin',
+          roles: ['admin'],
           created: moment(),
           updated: moment(),
           id: 'admin',

package/src/migrations/BackfillUserRolesArray.ts

@@ -0,0 +1,69 @@
+import { Db, Migration, SourceRecordLoader, getDbAsSystem, tables as dbTables } from '@proteinjs/db';
+import { tables } from '@proteinjs/user';
+import { Logger } from '@proteinjs/logger';
+
+/**
+ * Cutover for `user.roles`: comma-separated free text (legacy `roles` STRING(255) column) → the
+ * typed array `role_list` column. Spanner cannot retype a column in place, so the change is
+ * three-part: the new column (added by schema sync at boot), THIS backfill, and the code cutover
+ * (`UserTable.roles` now reads/writes `role_list`; the legacy column stays physically present but
+ * undeclared).
+ *
+ * Reads the legacy column via raw SQL — it is no longer in the table definition, so the ORM
+ * cannot see it — and writes through the ORM so `role_list` serialization has exactly one owner.
+ * Parsing normalizes what free text accumulated: trim, drop empties, dedupe.
+ *
+ * Idempotent and safe everywhere: rows already carrying a `role_list` value are skipped (a
+ * re-run cannot clobber a post-cutover grant), and a database whose user table never had the
+ * legacy column (fresh installs) is a clean no-op via the information_schema check.
+ */
+export class BackfillUserRolesArray implements SourceRecordLoader<Migration> {
+  table = dbTables.Migration;
+  record = {
+    id: '65916145-71d3-49a1-bd07-154de33195f6',
+    description: 'Backfill user.role_list (typed array) from the legacy comma-separated roles column',
+    run: async () => {
+      const logger = new Logger({ name: this.constructor.name });
+      const dbDriver = Db.getDefaultDbDriver();
+      const userTableName = tables.User.name;
+
+      const legacyColumn = await dbDriver.runQuery(() => ({
+        sql:
+          `SELECT column_name FROM information_schema.columns ` +
+          `WHERE table_name = '${userTableName}' AND column_name = 'roles'`,
+      }));
+      if (legacyColumn.length === 0) {
+        logger.info({ message: `No legacy roles column on ${userTableName}; nothing to backfill` });
+        return { backfilled: 0 };
+      }
+
+      const rows = (await dbDriver.runQuery(() => ({
+        sql:
+          `SELECT id, roles FROM ${userTableName} ` + `WHERE roles IS NOT NULL AND roles != '' AND role_list IS NULL`,
+      }))) as unknown as Array<{ id: string; roles: string }>;
+
+      const db = getDbAsSystem();
+      let backfilled = 0;
+      try {
+        for (const row of rows) {
+          const roles = Array.from(
+            new Set(
+              row.roles
+                .split(',')
+                .map((role) => role.trim())
+                .filter((role) => role.length > 0)
+            )
+          );
+          await db.update(tables.User, { id: row.id, roles });
+          backfilled++;
+        }
+
+        logger.info({ message: `Backfilled user roles`, obj: { backfilled } });
+        return { backfilled };
+      } catch (error) {
+        logger.error({ message: `Error backfilling user roles`, obj: { error } });
+        throw error;
+      }
+    },
+  };
+}

package/src/services/Roles.ts

@@ -0,0 +1,61 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { RolesService, RolesCatalog, UserRepo, tables, USER_PERMISSIONS } from '@proteinjs/user';
+import { Logger } from '@proteinjs/logger';
+import { Service } from '@proteinjs/service';
+
+/**
+ * The ONE write path for user roles (the `user.roles` column is service-protected — generic
+ * record writes cannot touch it). Grants and revokes are validated against the roles catalog and
+ * 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.
+ */
+export class Roles implements RolesService {
+  public serviceMetadata: Service['serviceMetadata'] = {
+    auth: {
+      permission: USER_PERMISSIONS.roles,
+    },
+  };
+
+  async grantRole(userId: string, role: string): Promise<void> {
+    await this.changeRole(userId, role, 'grant');
+  }
+
+  async revokeRole(userId: string, role: string): Promise<void> {
+    await this.changeRole(userId, role, 'revoke');
+  }
+
+  private async changeRole(userId: string, role: string, action: 'grant' | 'revoke'): Promise<void> {
+    const logger = new Logger({ name: `Roles.${action}Role` });
+    if (!RolesCatalog.isKnownRole(role)) {
+      throw new Error(`'${role}' is not a known role. Pick one from the roles catalog.`);
+    }
+
+    const db = getDbAsSystem();
+    const user = await db.get(tables.User, { id: userId });
+    if (!user) {
+      throw new Error(`No user found for id: ${userId}`);
+    }
+
+    const roles = user.roles ?? [];
+    if (action === 'grant' ? roles.includes(role) : !roles.includes(role)) {
+      // No change, no audit row: the trail records what happened, not what was re-asked.
+      return;
+    }
+
+    const newRoles = action === 'grant' ? [...roles, role] : roles.filter((heldRole) => heldRole !== role);
+    const actor = new UserRepo().getUser();
+    await db.runTransaction(async () => {
+      await db.update(tables.User, { id: userId, roles: newRoles });
+      await db.insert(tables.RoleGrantEvent, {
+        actor: actor.id,
+        target: userId,
+        role,
+        action,
+      });
+    });
+    logger.info({
+      message: `Role ${action === 'grant' ? 'granted' : 'revoked'}`,
+      obj: { actor: actor.id, target: userId, role },
+    });
+  }
+}

package/src/services/Signup.ts

@@ -1,4 +1,4 @@
-import { getDb, getDbAsSystem } from '@proteinjs/db';
+import { getDbAsSystem } from '@proteinjs/db';
 import {
   SendInviteResponse,
   tables,
@@ -9,6 +9,7 @@ import {
   UserRepo,
   Invite,
   UserSignup,
+  USER_PERMISSIONS,
 } from '@proteinjs/user';
 import moment from 'moment';
 import { lib } from 'crypto-js';
@@ -57,11 +58,12 @@ export class Signup implements SignupService {
   public serviceMetadata = {
     auth: {
       canAccess: (methodName: string, args: any[]) => {
-        // Admin-only invite management. This previously evaluated hasRole WITHOUT returning it,
-        // which made sendInvite/revokeInvite effectively public — any caller (even logged out)
-        // could mint themselves a valid signup token and bypass invite-only signup.
+        // Invite management rides the 'users' permission (admin passes via break-glass). This
+        // previously evaluated the check WITHOUT returning it, which made sendInvite/revokeInvite
+        // effectively public — any caller (even logged out) could mint themselves a valid signup
+        // token and bypass invite-only signup.
         if (methodName === 'sendInvite' || methodName === 'revokeInvite') {
-          return UserAuth.hasRole('admin');
+          return UserAuth.hasPermission(USER_PERMISSIONS.users);
         }
 
         return true;
@@ -115,7 +117,7 @@ export class Signup implements SignupService {
       email,
       password: sha256(user.password).toString(),
       emailVerified: invite ? true : false, // because we retrieved the email from the invite record
-      roles: '',
+      roles: [],
       invitedBy: invite ? invite.invitedBy : null,
     });
 
@@ -193,7 +195,9 @@ export class Signup implements SignupService {
       throw new Error('No email was provided.');
     }
 
-    const db = getDb();
+    // The service door ('users' permission) is the wall; the write is the domain's own, so it
+    // runs as system like every other invite write here — the invite table's db door stays admin.
+    const db = getDbAsSystem();
     await db.delete(tables.Invite, { email: email.toLowerCase() });
   }
 

package/test/BackfillUserRolesArray.integration.test.ts

@@ -0,0 +1,113 @@
+import { Db, Table, getDbAsSystem } from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { SpannerEmulatorProvisioner, getDropTestTable } from '@proteinjs/db-driver-spanner/test';
+import { SourceRepository } from '@proteinjs/reflection';
+import { tables } from '@proteinjs/user';
+import { BackfillUserRolesArray } from '../src/migrations/BackfillUserRolesArray';
+
+/**
+ * The user.roles cutover migration against a real Spanner emulator, simulating a deployed
+ * database: the user table carries the NEW schema (role_list, added by schema sync) PLUS the
+ * legacy comma-string `roles` column with pre-cutover data — exactly the state a deployment is
+ * in when the migration runs.
+ *
+ * Pinned outcomes:
+ * - legacy comma strings land in role_list as normalized arrays (trim, drop empties, dedupe)
+ * - empty/NULL legacy values stay untouched (no roles then, no roles now)
+ * - rows already carrying role_list are never clobbered (idempotence / post-cutover grants win)
+ * - a database that never had the legacy column (fresh install) is a clean no-op
+ */
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+class DbDriverFactory {
+  getDbDriver() {
+    return spannerDriver;
+  }
+}
+
+const dropTable = getDropTestTable(spannerDriver);
+
+const runMigration = async () => await new BackfillUserRolesArray().record.run();
+
+const rawUserInsert = async (id: string, legacyRoles: string | null) => {
+  const rolesValue = legacyRoles === null ? 'NULL' : `'${legacyRoles}'`;
+  await spannerDriver.runDml(() => ({
+    sql:
+      `INSERT INTO ${tables.User.name} (id, name, email, password, email_verified, roles, created, updated) ` +
+      `VALUES ('${id}', 'User ${id}', '${id}@test.local', 'test', false, ${rolesValue}, ` +
+      `CURRENT_TIMESTAMP(), CURRENT_TIMESTAMP())`,
+  }));
+};
+
+const rawRoleList = async (id: string) =>
+  (
+    (await spannerDriver.runQuery(() => ({
+      sql: `SELECT role_list FROM ${tables.User.name} WHERE id = '${id}'`,
+    }))) as unknown as Array<{ role_list: string | null }>
+  )[0].role_list;
+
+describe('BackfillUserRolesArray — legacy comma-string roles → typed role_list', () => {
+  beforeAll(async () => {
+    (SourceRepository.get() as any).objectCache['@proteinjs/db/DefaultDbDriverFactory'] = [new DbDriverFactory()];
+    jest.spyOn(Db, 'getDefaultDbDriver').mockImplementation(() => spannerDriver);
+
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(tables.User as Table<any>);
+    await spannerDriver.getTableManager().loadTable(tables.User);
+  }, 120000);
+
+  afterAll(async () => {
+    await dropTable(tables.User as Table<any>);
+    await SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  it('is a clean no-op on a database that never had the legacy roles column', async () => {
+    expect(await runMigration()).toEqual({ backfilled: 0 });
+  }, 60000);
+
+  it('backfills, normalizes, preserves, and re-runs clean on a deployed-shape database', async () => {
+    // Simulate the deployed state: the legacy column exists beside the new schema.
+    await spannerDriver.runUpdateSchema(`ALTER TABLE ${tables.User.name} ADD COLUMN roles STRING(255)`);
+
+    await rawUserInsert('legacy-admin', 'admin');
+    await rawUserInsert('legacy-messy', ' admin, ops ,admin,, dev');
+    await rawUserInsert('legacy-empty', '');
+    await rawUserInsert('legacy-null', null);
+    // Already migrated / post-cutover grant: role_list set, stale legacy value beside it.
+    const db = getDbAsSystem();
+    const alreadyMigrated = await db.insert(tables.User, {
+      name: 'Already migrated',
+      email: 'already@test.local',
+      password: 'test',
+      emailVerified: false,
+      roles: ['ops'],
+    });
+    await spannerDriver.runDml(() => ({
+      sql: `UPDATE ${tables.User.name} SET roles = 'admin' WHERE id = '${alreadyMigrated.id}'`,
+    }));
+
+    expect(await runMigration()).toEqual({ backfilled: 2 });
+
+    // The ORM (the product's read path) sees typed arrays.
+    expect((await db.get(tables.User, { id: 'legacy-admin' })).roles).toEqual(['admin']);
+    expect((await db.get(tables.User, { id: 'legacy-messy' })).roles).toEqual(['admin', 'ops', 'dev']);
+    // No roles then, no roles now.
+    expect(await rawRoleList('legacy-empty')).toBeNull();
+    expect(await rawRoleList('legacy-null')).toBeNull();
+    // The post-cutover value wins over the stale legacy string.
+    expect((await db.get(tables.User, { id: alreadyMigrated.id })).roles).toEqual(['ops']);
+
+    // Re-run: nothing left to do, nothing clobbered.
+    expect(await runMigration()).toEqual({ backfilled: 0 });
+    expect((await db.get(tables.User, { id: 'legacy-admin' })).roles).toEqual(['admin']);
+  }, 120000);
+});

package/test/Roles.integration.test.ts

@@ -0,0 +1,163 @@
+import moment from 'moment';
+import { Db, Table, getDbAsSystem } from '@proteinjs/db';
+import { SpannerDriver } from '@proteinjs/db-driver-spanner';
+import { SpannerEmulatorProvisioner, getDropTestTable } from '@proteinjs/db-driver-spanner/test';
+import { SourceRepository } from '@proteinjs/reflection';
+import { Session, SessionData, SessionDataStorage } from '@proteinjs/server-api';
+import { RoleCatalogEntry, USER_PERMISSIONS, UserRepo, tables } from '@proteinjs/user';
+import { Roles } from '../src/services/Roles';
+
+/**
+ * The Roles service is the ONE write path for user roles: grants/revokes validated against the
+ * roles catalog, the role update and its `role_grant_event` audit row committed together.
+ * Outcomes asserted against a real Spanner emulator: the rows written, not the calls made.
+ *
+ * The service door itself (`{ permission: 'roles' }`) is resolved by ServiceAuth — covered in
+ * @proteinjs/service — so these tests call the implementation directly and pin the metadata.
+ */
+
+class TestSessionDataStorage implements SessionDataStorage {
+  environment = 'node' as 'node';
+  static SESSION_DATA: { [id: string]: SessionData } = {};
+
+  setData(data: SessionData) {
+    TestSessionDataStorage.SESSION_DATA['sessionData'] = data;
+  }
+
+  getData(): SessionData {
+    return TestSessionDataStorage.SESSION_DATA['sessionData'];
+  }
+}
+
+const spannerDriver = new SpannerDriver({
+  projectId: 'proteinjs-test',
+  instanceName: 'proteinjs-test',
+  databaseName: 'test',
+});
+
+class DbDriverFactory {
+  getDbDriver() {
+    return spannerDriver;
+  }
+}
+
+const actor = {
+  name: 'Role granter',
+  email: 'granter@test.local',
+  password: 'test',
+  emailVerified: true,
+  roles: ['admin'],
+  created: moment(),
+  updated: moment(),
+  id: 'actor-1',
+};
+
+const dropTable = getDropTestTable(spannerDriver);
+
+describe('Roles service — grant/revoke outcomes and audit trail', () => {
+  beforeAll(async () => {
+    (SourceRepository.get() as any).objectCache['@proteinjs/db/DefaultDbDriverFactory'] = [new DbDriverFactory()];
+    (SourceRepository.get() as any).objectCache['@proteinjs/server-api/SessionDataStorage'] = [
+      new TestSessionDataStorage(),
+    ];
+    (SourceRepository.get() as any).objectCache['@proteinjs/user/RoleCatalogEntry'] = [
+      { role: 'ops', description: 'Run the ops cockpit' } as RoleCatalogEntry,
+    ];
+    jest.spyOn(Db, 'getDefaultDbDriver').mockImplementation(() => spannerDriver);
+
+    await SpannerEmulatorProvisioner.ensureProvisioned({
+      projectId: 'proteinjs-test',
+      instanceName: 'proteinjs-test',
+      databaseName: 'test',
+    });
+    await dropTable(tables.User as Table<any>);
+    await dropTable(tables.RoleGrantEvent as Table<any>);
+    await spannerDriver.getTableManager().loadTable(tables.User);
+    await spannerDriver.getTableManager().loadTable(tables.RoleGrantEvent);
+
+    Session.setData({ sessionId: 'test-session', user: actor.email, data: {} });
+    new UserRepo().setUser(actor);
+  }, 120000);
+
+  afterAll(async () => {
+    await dropTable(tables.User as Table<any>);
+    await dropTable(tables.RoleGrantEvent as Table<any>);
+    await SpannerEmulatorProvisioner.release();
+  }, 60000);
+
+  let targetId: string;
+
+  beforeEach(async () => {
+    const db = getDbAsSystem();
+    await db.delete(tables.RoleGrantEvent, {});
+    await db.delete(tables.User, {});
+    await db.insert(tables.User, { ...actor });
+    const target = await db.insert(tables.User, {
+      name: 'Target user',
+      email: 'target@test.local',
+      password: 'test',
+      emailVerified: true,
+      roles: [],
+    });
+    targetId = target.id;
+  }, 60000);
+
+  const targetRoles = async () => (await getDbAsSystem().get(tables.User, { id: targetId }))!.roles;
+  const auditRows = async () => await getDbAsSystem().query(tables.RoleGrantEvent, {});
+
+  it('requires the roles permission on its service door', () => {
+    expect(new Roles().serviceMetadata?.auth?.permission).toBe(USER_PERMISSIONS.roles);
+  });
+
+  it('grant writes the role on the user row and one audit row', async () => {
+    await new Roles().grantRole(targetId, 'ops');
+
+    expect(await targetRoles()).toEqual(['ops']);
+    const events = await auditRows();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ actor: 'actor-1', target: targetId, role: 'ops', action: 'grant' });
+    expect(events[0].created).toBeDefined();
+  }, 60000);
+
+  it('granting an already-held role changes nothing and writes no audit row', async () => {
+    const roles = new Roles();
+    await roles.grantRole(targetId, 'ops');
+    await roles.grantRole(targetId, 'ops');
+
+    expect(await targetRoles()).toEqual(['ops']);
+    expect(await auditRows()).toHaveLength(1);
+  }, 60000);
+
+  it('revoke removes the role and audits the revoke', async () => {
+    const roles = new Roles();
+    await roles.grantRole(targetId, 'ops');
+    await roles.grantRole(targetId, 'admin');
+    await roles.revokeRole(targetId, 'ops');
+
+    expect(await targetRoles()).toEqual(['admin']);
+    const events = await auditRows();
+    expect(events).toHaveLength(3);
+    const revoke = events.find((event) => event.action === 'revoke');
+    expect(revoke).toMatchObject({ actor: 'actor-1', target: targetId, role: 'ops' });
+  }, 60000);
+
+  it('revoking a role the user does not hold changes nothing and writes no audit row', async () => {
+    await new Roles().revokeRole(targetId, 'ops');
+
+    expect(await targetRoles()).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+  }, 60000);
+
+  it('refuses a role the catalog does not know, and writes nothing', async () => {
+    await expect(new Roles().grantRole(targetId, 'made-up')).rejects.toThrow(
+      `'made-up' is not a known role. Pick one from the roles catalog.`
+    );
+    expect(await targetRoles()).toEqual([]);
+    expect(await auditRows()).toHaveLength(0);
+  }, 60000);
+
+  it('refuses a grant to a user that does not exist', async () => {
+    await expect(new Roles().grantRole('nobody-1', 'ops')).rejects.toThrow('No user found for id: nobody-1');
+    expect(await auditRows()).toHaveLength(0);
+  }, 60000);
+});

package/test/Signup.test.ts

@@ -14,7 +14,10 @@ import { Signup } from '../src/services/Signup';
  * (same pattern as @proteinjs/db's TableServiceAuth.test.ts).
  */
 
-type UserAuthInternals = { userRepo?: { getUser: () => { email: string; roles: string[] } } };
+type UserAuthInternals = {
+  userRepo?: { getUser: () => { email: string; roles: string[] } };
+  permissionRolesMapping?: { getRoles: (permission: string) => string[] | undefined };
+};
 
 const setUser = (roles: string[]) => {
   (UserAuth as unknown as UserAuthInternals).userRepo = {
@@ -22,6 +25,12 @@ const setUser = (roles: string[]) => {
   };
 };
 
+const setMapping = (mapping: { [permission: string]: string[] }) => {
+  (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = {
+    getRoles: (permission: string) => mapping[permission],
+  };
+};
+
 const canAccess = (methodName: string) => {
   const signup = new Signup();
   return signup.serviceMetadata.auth.canAccess(methodName, []);
@@ -30,20 +39,28 @@ const canAccess = (methodName: string) => {
 describe('Signup service auth', () => {
   afterEach(() => {
     (UserAuth as unknown as UserAuthInternals).userRepo = undefined;
+    (UserAuth as unknown as UserAuthInternals).permissionRolesMapping = undefined;
   });
 
-  it('denies sendInvite and revokeInvite to a non-admin', () => {
+  it('denies sendInvite and revokeInvite to a caller without the users permission', () => {
     setUser([]);
     expect(canAccess('sendInvite')).toBe(false);
     expect(canAccess('revokeInvite')).toBe(false);
   });
 
-  it('allows sendInvite and revokeInvite for an admin', () => {
+  it('allows sendInvite and revokeInvite for an admin (break-glass)', () => {
     setUser(['admin']);
     expect(canAccess('sendInvite')).toBe(true);
     expect(canAccess('revokeInvite')).toBe(true);
   });
 
+  it(`allows sendInvite and revokeInvite for a holder of the consumer's users-mapped role`, () => {
+    setUser(['support']);
+    setMapping({ users: ['support'] });
+    expect(canAccess('sendInvite')).toBe(true);
+    expect(canAccess('revokeInvite')).toBe(true);
+  });
+
   it('keeps the signup flow itself open (createUser / initializeSignup)', () => {
     setUser([]);
     expect(canAccess('createUser')).toBe(true);

package/test/setup.js

@@ -0,0 +1,2 @@
+process.env.SPANNER_EMULATOR_HOST = process.env.SPANNER_EMULATOR_HOST || 'localhost:9010';
+process.env.DB_LOG_LEVEL = 'error';