@proteinjs/user-server 1.7.0 → 1.8.0

package/test/MachineAccounts.integration.test.ts

@@ -0,0 +1,312 @@
+import sha256 from 'crypto-js/sha256';
+import { SourceRecordSyncRunner, getDbAsSystem } from '@proteinjs/db';
+import { SourceRepository } from '@proteinjs/reflection';
+// Deep import (test-only): ServiceAuth is the real RPC door but is not index-exported by
+// @proteinjs/service — the door test below runs the actual gate rather than pinning metadata.
+import { ServiceAuth } from '@proteinjs/service/dist/src/ServiceAuth';
+import { MachineAccount, RoleCatalogEntry, User, UserRepo, tables } from '@proteinjs/user';
+import { authenticate } from '../src/authentication/authenticate';
+import { UserStatusTableWatcher } from '../src/authentication/UserStatusTableWatcher';
+import { MachineCredentials } from '../src/services/MachineCredentials';
+import { Roles } from '../src/services/Roles';
+import { SetUserStatus } from '../src/services/SetUserStatus';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/** The consumer-mapped role machine declarations grant (registered into the catalog below). */
+class OpsRole implements RoleCatalogEntry {
+  role = 'ops';
+  description = 'Operational machinery';
+}
+
+class TestOpsMachineAccount extends MachineAccount {
+  id = 'machine-test-ops';
+  email = 'machine-ops@test.local';
+  accountName = 'Test ops machine';
+  roles = ['ops'];
+  secretName = 'test-ops-secret';
+}
+
+type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+
+/**
+ * Reset `TableWatcherRunner`'s static watcher map so the NEXT Db construction recomputes it from
+ * the (just-changed) discovery seam. The class is internal to @proteinjs/db (its exports map
+ * blocks deep imports), so it's reached through a Db instance — the test-harness cast convention.
+ */
+const resetTableWatcherMap = () => {
+  const runner = (getDbAsSystem() as unknown as { tableWatcherRunner: object }).tableWatcherRunner;
+  (runner.constructor as { tableWatcherMap?: unknown }).tableWatcherMap = undefined;
+};
+
+/**
+ * Machine accounts as source records, at the user layer: declare-only on the REAL mixed user
+ * table, adopt-in-place by email (id + password survive — the old credential still logs in),
+ * removed-from-source auto-deactivation with session kill through the categorical
+ * UserStatusTableWatcher, the machine/human ledger split (Roles refuses machine targets),
+ * declaration validation, and credential minting (hash-only at rest, plaintext shown once).
+ */
+describe('Machine accounts as source records', () => {
+  const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+
+  /** One boot of Db.init's source-record leg with these MachineAccount declarations. */
+  const boot = async (declarations: MachineAccount[]) => {
+    objectCache()['@proteinjs/db/SourceRecordLoader'] = declarations;
+    await new SourceRecordSyncRunner().load();
+  };
+
+  const machineRow = async () => await getDbAsSystem().get(tables.User, { email: 'machine-ops@test.local' });
+
+  const insertSession = async (sessionId: string, userEmail: string) =>
+    await getDbAsSystem().insert(tables.Session, {
+      sessionId,
+      session: '{}',
+      expires: new Date(Date.now() + 60 * 60 * 1000),
+      userEmail,
+    });
+
+  const sessionEmails = async () =>
+    (await getDbAsSystem().query(tables.Session, {})).map((session) => session.userEmail);
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache[
+      '@proteinjs/user-auth/AuthenticatedUserRepo'
+    ] = [new UserRepo()];
+    objectCache()['@proteinjs/user/RoleCatalogEntry'] = [new OpsRole()];
+    // Exactly the deactivation watcher observes this run, rebuilt from the seeded cache.
+    objectCache()['@proteinjs/db/TableWatcher'] = [new UserStatusTableWatcher()];
+    resetTableWatcherMap();
+  }, 120000);
+
+  afterAll(async () => {
+    delete objectCache()['@proteinjs/db/SourceRecordLoader'];
+    delete objectCache()['@proteinjs/db/TableWatcher'];
+    delete objectCache()['@proteinjs/user/RoleCatalogEntry'];
+    resetTableWatcherMap();
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    const db = getDbAsSystem();
+    await db.delete(tables.Session, {});
+    await db.delete(tables.UserStatusEvent, {});
+    await db.delete(tables.RoleGrantEvent, {});
+    await db.delete(tables.User, {});
+  });
+
+  it('declare-only on the mixed user table: the declaration lands source-owned; human rows are untouched', async () => {
+    const human = await testEnv.createUser({ name: 'A human', email: 'human@test.local', roles: ['ops'] });
+    await boot([new TestOpsMachineAccount()]);
+
+    const machine = await machineRow();
+    expect(machine).toMatchObject({
+      id: 'machine-test-ops',
+      name: 'Test ops machine',
+      roles: ['ops'],
+      emailVerified: true,
+      status: 'active',
+      isLoadedFromSource: true,
+    });
+    // No declarable password: the fresh row carries none, so authenticate's email+hash match
+    // can never admit it until a credential is minted.
+    expect(machine.password).toBeFalsy();
+
+    const humanAfter = await getDbAsSystem().get(tables.User, { id: human.id });
+    expect(humanAfter.isLoadedFromSource).toBeFalsy();
+    expect(humanAfter).toMatchObject({ name: 'A human', roles: ['ops'] });
+  });
+
+  it('adopt-in-place by email: the hand-made row keeps its id and password; declared fields revert', async () => {
+    // The deployed-env shape: a hand-made machine row with an env-random id, a provisioned
+    // credential, and runtime-granted roles that have drifted from the declaration.
+    const handMade = await testEnv.createUser({
+      name: 'Hand-made bridge',
+      email: 'machine-ops@test.local',
+      roles: ['ops', 'stale-role'],
+    });
+
+    await boot([new TestOpsMachineAccount()]);
+
+    const adopted = await machineRow();
+    expect(adopted.id).toBe(handMade.id);
+    expect(adopted).toMatchObject({
+      name: 'Test ops machine',
+      roles: ['ops'],
+      status: 'active',
+      isLoadedFromSource: true,
+    });
+    // The credential survived adoption: the account still authenticates with its old password
+    // (createUser stores sha256('test')... it stores the raw string; assert equality instead).
+    expect(adopted.password).toBe(handMade.password);
+    expect((await getDbAsSystem().query(tables.User, { email: 'machine-ops@test.local' })).length).toBe(1);
+  });
+
+  it('removed from source: deactivated (never deleted), sessions killed, login refused; re-declaring reactivates', async () => {
+    const human = await testEnv.createUser({ name: 'A human', email: 'human@test.local' });
+    await boot([new TestOpsMachineAccount()]);
+    await insertSession('machine-session', 'machine-ops@test.local');
+    await insertSession('human-session', human.email);
+
+    await boot([]);
+
+    const removed = await machineRow();
+    expect(removed).toBeDefined();
+    expect(removed.status).toBe('deactivated');
+    // The categorical watcher killed the machine sessions; the human session is untouched.
+    expect(await sessionEmails()).toEqual([human.email]);
+    // The one login door refuses a deactivated account even with matching credentials.
+    await getDbAsSystem().update(tables.User, { id: removed.id, password: sha256('bridge-pw').toString() });
+    expect(await authenticate('machine-ops@test.local', 'bridge-pw')).toBe('This account has been deactivated');
+
+    // Decommission is reversible in code: re-declaring reverts status via drift reversion.
+    await boot([new TestOpsMachineAccount()]);
+    expect((await machineRow()).status).toBe('active');
+    expect(await authenticate('machine-ops@test.local', 'bridge-pw')).toBe(true);
+  });
+
+  it(`the staff toggle rides the same watcher: SetUserStatus deactivation kills the target's sessions`, async () => {
+    const admin = await testEnv.createUser({ name: 'Admin', email: 'admin@test.local', roles: ['admin'] });
+    const target = await testEnv.createUser({ name: 'Target', email: 'target@test.local' });
+    await insertSession('target-session', target.email);
+    await insertSession('admin-session', admin.email);
+
+    testEnv.actAs(admin);
+    await new SetUserStatus().setUserStatus(target.id, 'deactivated');
+
+    expect(await sessionEmails()).toEqual([admin.email]);
+  });
+
+  it('the Roles service refuses machine-account targets (git is the machine audit); human grants still work', async () => {
+    const admin = await testEnv.createUser({ name: 'Admin', email: 'admin@test.local', roles: ['admin'] });
+    const human = await testEnv.createUser({ name: 'A human', email: 'human@test.local' });
+    await boot([new TestOpsMachineAccount()]);
+    testEnv.actAs(admin);
+
+    const machine = await machineRow();
+    await expect(new Roles().grantRole(machine.id, 'ops')).rejects.toThrow(
+      /machine account: its roles are declared in code/
+    );
+    await expect(new Roles().revokeRole(machine.id, 'ops')).rejects.toThrow(
+      /machine account: its roles are declared in code/
+    );
+    // No machine rows in the human ledger.
+    expect(await getDbAsSystem().query(tables.RoleGrantEvent, { target: machine.id })).toHaveLength(0);
+
+    await new Roles().grantRole(human.id, 'ops');
+    expect((await getDbAsSystem().get(tables.User, { id: human.id })).roles).toEqual(['ops']);
+  });
+
+  it('declaration validation fails boot loudly: non-lowercase email, unknown role, break-glass role', async () => {
+    class UppercaseEmail extends TestOpsMachineAccount {
+      email = 'Machine-Ops@test.local';
+    }
+    await expect(boot([new UppercaseEmail()])).rejects.toThrow(/emails must be lowercase/);
+
+    class UnknownRole extends TestOpsMachineAccount {
+      roles = ['not-a-role'];
+    }
+    await expect(boot([new UnknownRole()])).rejects.toThrow(/unknown role 'not-a-role'/);
+
+    class BreakGlass extends TestOpsMachineAccount {
+      roles = ['admin'];
+    }
+    await expect(boot([new BreakGlass()])).rejects.toThrow(/break-glass role 'admin'/);
+  });
+
+  describe('credential minting', () => {
+    beforeEach(async () => {
+      await boot([new TestOpsMachineAccount()]);
+    });
+
+    it('mints a generated credential: hash-only at rest, sessions rotated, plaintext + paste note returned once', async () => {
+      await insertSession('old-credential-session', 'machine-ops@test.local');
+
+      const minted = await new MachineCredentials().mintCredential('machine-ops@test.local');
+
+      expect(minted.email).toBe('machine-ops@test.local');
+      expect(minted.password).toMatch(/^[0-9a-f]{64}$/); // 256 bits, generated — never human-chosen
+      expect(minted.secretName).toBe('test-ops-secret');
+      expect(minted.note).toMatch(/test-ops-secret/);
+      expect(minted.note).toMatch(/restart/i);
+
+      // Only the hash is stored, and it is the hash of the returned plaintext.
+      const row = await machineRow();
+      expect(row.password).toBe(sha256(minted.password).toString());
+      // The old credential's sessions died with the rotation...
+      expect(await sessionEmails()).toEqual([]);
+      // ...and the minted credential is immediately loggable.
+      expect(await authenticate('machine-ops@test.local', minted.password)).toBe(true);
+    });
+
+    it('lists declared accounts with row state for the admin surface', async () => {
+      class NotBooted extends TestOpsMachineAccount {
+        id = 'machine-not-booted';
+        email = 'machine-not-booted@test.local';
+        secretName = 'not-booted-secret';
+      }
+      objectCache()['@proteinjs/db/SourceRecordLoader'] = [new TestOpsMachineAccount(), new NotBooted()];
+
+      const before = await new MachineCredentials().listMachineAccounts();
+      expect(before).toEqual([
+        {
+          email: 'machine-ops@test.local',
+          accountName: 'Test ops machine',
+          roles: ['ops'],
+          secretName: 'test-ops-secret',
+          status: 'active',
+          hasCredential: false,
+        },
+        {
+          email: 'machine-not-booted@test.local',
+          accountName: 'Test ops machine',
+          roles: ['ops'],
+          secretName: 'not-booted-secret',
+          status: 'pending first boot',
+          hasCredential: false,
+        },
+      ]);
+
+      await new MachineCredentials().mintCredential('machine-ops@test.local');
+      const after = await new MachineCredentials().listMachineAccounts();
+      expect(after[0]).toMatchObject({ email: 'machine-ops@test.local', hasCredential: true });
+    });
+
+    it('refuses non-machine targets: undeclared emails and human accounts', async () => {
+      await testEnv.createUser({ name: 'A human', email: 'human@test.local' });
+      await expect(new MachineCredentials().mintCredential('human@test.local')).rejects.toThrow(
+        /No machine account is declared/
+      );
+      await expect(new MachineCredentials().mintCredential('nobody@test.local')).rejects.toThrow(
+        /No machine account is declared/
+      );
+    });
+
+    it('refuses a declared account whose row has not been loaded from source yet', async () => {
+      class NotBooted extends TestOpsMachineAccount {
+        id = 'machine-not-booted';
+        email = 'machine-not-booted@test.local';
+      }
+      // Declared (discoverable) but never booted: no source-owned row exists.
+      objectCache()['@proteinjs/db/SourceRecordLoader'] = [new TestOpsMachineAccount(), new NotBooted()];
+      await expect(new MachineCredentials().mintCredential('machine-not-booted@test.local')).rejects.toThrow(
+        /has not been loaded from source yet/
+      );
+    });
+
+    it(`the door is the 'users' permission (admin passes as break-glass)`, async () => {
+      const admin = await testEnv.createUser({ name: 'Admin', email: 'admin@test.local', roles: ['admin'] });
+      const plain = await testEnv.createUser({ name: 'Plain', email: 'plain@test.local', roles: ['ops'] });
+      const canRun = () =>
+        ServiceAuth.canRunService(new MachineCredentials(), { name: 'mintCredential' } as any, [
+          'machine-ops@test.local',
+        ]);
+
+      testEnv.actAs(plain);
+      expect(canRun()).toBe(false);
+      testEnv.actAs(admin);
+      expect(canRun()).toBe(true);
+    });
+  });
+});

package/test/PasswordMigration.integration.test.ts

@@ -0,0 +1,132 @@
+import sha256 from 'crypto-js/sha256';
+import * as argon2 from 'argon2';
+import moment from 'moment';
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables, User } from '@proteinjs/user';
+import { authenticate } from '../src/authentication/authenticate';
+import { PasswordHasher } from '../src/authentication/PasswordHasher';
+import { Signup } from '../src/services/Signup';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+const ARGON2ID_PREFIX = '$argon2id$';
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * The sha256→argon2id migration: authentication queries by EMAIL ONLY and compares in code
+ * (query-by-hash is dead), legacy sha256 rows upgrade in place on their next successful login
+ * (verify-then-rehash), every password write produces only the new self-describing format, and
+ * machine rows (generated 256-bit secrets) stay sha256 by design — cheap per-poll verifies.
+ */
+describe('Password KDF migration', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  }, 120000);
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    await getDbAsSystem().delete(tables.User, {});
+  });
+
+  const insertUser = async (fields: Partial<User> & { email: string; password: string }) =>
+    await getDbAsSystem().insert(tables.User, {
+      name: 'Test user',
+      emailVerified: true,
+      roles: [],
+      ...fields,
+    });
+
+  const userRow = async (email: string) => await getDbAsSystem().get(tables.User, { email });
+
+  it('legacy sha256 row: login succeeds and the row is upgraded in place to argon2id', async () => {
+    const legacyHash = sha256('hunter2 was fine in 2004').toString();
+    await insertUser({ email: 'legacy@test.local', password: legacyHash });
+
+    expect(await authenticate('legacy@test.local', 'hunter2 was fine in 2004')).toBe(true);
+
+    // Outcome: the stored value CHANGED, to the self-describing argon2id format, and still
+    // matches the same credential (the encoded string carries its own per-user salt).
+    const upgraded = (await userRow('legacy@test.local')).password;
+    expect(upgraded).not.toBe(legacyHash);
+    expect(upgraded.startsWith(ARGON2ID_PREFIX)).toBe(true);
+    await expect(argon2.verify(upgraded, 'hunter2 was fine in 2004')).resolves.toBe(true);
+
+    // The migrated row logs in through the argon2 leg — and is NOT rehashed again.
+    expect(await authenticate('legacy@test.local', 'hunter2 was fine in 2004')).toBe(true);
+    expect((await userRow('legacy@test.local')).password).toBe(upgraded);
+  });
+
+  it('new-format row: login verifies against the stored encoded hash', async () => {
+    const encoded = await new PasswordHasher().hash('correct horse battery staple');
+    await insertUser({ email: 'modern@test.local', password: encoded });
+
+    expect(await authenticate('modern@test.local', 'correct horse battery staple')).toBe(true);
+    expect((await userRow('modern@test.local')).password).toBe(encoded);
+  });
+
+  it('wrong password fails for both stored formats, and never mutates the row', async () => {
+    const legacyHash = sha256('right password').toString();
+    await insertUser({ email: 'legacy@test.local', password: legacyHash });
+    await insertUser({ email: 'modern@test.local', password: await new PasswordHasher().hash('right password') });
+
+    expect(await authenticate('legacy@test.local', 'wrong password')).toBe('User name or password incorrect');
+    expect(await authenticate('modern@test.local', 'wrong password')).toBe('User name or password incorrect');
+
+    // A failed attempt is not a migration event: the legacy row still holds its sha256.
+    expect((await userRow('legacy@test.local')).password).toBe(legacyHash);
+  });
+
+  it('unknown email fails the same way (no query-by-hash oracle)', async () => {
+    expect(await authenticate('nobody@test.local', 'anything')).toBe('User name or password incorrect');
+  });
+
+  it('new registrations write only the new format', async () => {
+    await new Signup().createAccount({
+      name: 'New user',
+      email: 'new@test.local',
+      password: 'first password',
+      emailVerified: false,
+      invitedBy: null,
+    });
+
+    const row = await userRow('new@test.local');
+    expect(row.password.startsWith(ARGON2ID_PREFIX)).toBe(true);
+    expect(row.password).not.toBe(sha256('first password').toString());
+    expect(await authenticate('new@test.local', 'first password')).toBe(true);
+  });
+
+  it('deactivated and pending-deletion gates are unchanged across both formats', async () => {
+    // Staff-deactivated account: correct credentials are still refused a session.
+    await insertUser({ email: 'off@test.local', password: sha256('pw').toString(), status: 'deactivated' });
+    expect(await authenticate('off@test.local', 'pw')).toBe('This account has been deactivated');
+
+    // Pending-deletion account (deactivated + deleteRequestedAt): login IS the cancel signal —
+    // authenticate admits it, for migrated rows too.
+    await insertUser({
+      email: 'pending@test.local',
+      password: await new PasswordHasher().hash('pw'),
+      status: 'deactivated',
+      deleteRequestedAt: moment(),
+    });
+    expect(await authenticate('pending@test.local', 'pw')).toBe(true);
+  });
+
+  it('machine rows authenticate through the same owner but never leave sha256', async () => {
+    // The minted-credential shape: a generated 256-bit hex secret, sha256 at rest (stretching a
+    // random 256-bit secret buys nothing, and the bridge logs in fresh per poll — see
+    // PasswordHasher's machine mode).
+    const secret = '9f'.repeat(32);
+    const machineHash = sha256(secret).toString();
+    await insertUser({ email: 'machine@test.local', password: machineHash, isLoadedFromSource: true });
+
+    expect(await authenticate('machine@test.local', secret)).toBe(true);
+
+    const row = await userRow('machine@test.local');
+    expect(row.password).toBe(machineHash);
+    expect(row.password).toMatch(SHA256_HEX);
+  });
+});

package/test/SetUserStatus.integration.test.ts

@@ -0,0 +1,120 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { SourceRepository } from '@proteinjs/reflection';
+// Deep import (test-only): ServiceAuth is the real RPC door but is not index-exported by
+// @proteinjs/service — the door test below runs the actual gate rather than pinning metadata.
+import { ServiceAuth } from '@proteinjs/service/dist/src/ServiceAuth';
+import { User, UserRepo, tables } from '@proteinjs/user';
+import { SetUserStatus } from '../src/services/SetUserStatus';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * The SetUserStatus service is the ONE write path for account standing: the status update and
+ * its `user_status_event` audit row commit together. Outcomes asserted against the emulator:
+ * the rows written, not the calls made.
+ *
+ * The service door is exercised through ServiceAuth itself (the same gate the RPC path runs):
+ * the explicit `roles: ['admin']` block refuses everyone but admins.
+ */
+describe('SetUserStatus service — admin door, standing writes, audit trail', () => {
+  let admin: User;
+  let nonAdmin: User;
+  let target: User;
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    // ServiceAuth funnels through UserAuth, which resolves the current user from the
+    // source-graph-registered AuthenticatedUserRepo — seed it the way the env seeds session
+    // storage (tests do not load the generated source graph).
+    (SourceRepository.get() as unknown as { objectCache: Record<string, unknown[]> }).objectCache[
+      '@proteinjs/user-auth/AuthenticatedUserRepo'
+    ] = [new UserRepo()];
+  }, 120000);
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    const db = getDbAsSystem();
+    await db.delete(tables.UserStatusEvent, {});
+    await db.delete(tables.User, {});
+    admin = await testEnv.createUser({ name: 'Admin actor', email: 'status-admin@test.local', roles: ['admin'] });
+    nonAdmin = await testEnv.createUser({ name: 'Plain actor', email: 'status-plain@test.local', roles: ['ops'] });
+    target = await testEnv.createUser({ name: 'Target user', email: 'status-target@test.local' });
+  });
+
+  const targetStatus = async () => (await getDbAsSystem().get(tables.User, { id: target.id }))!.status;
+  const auditRows = async () => await getDbAsSystem().query(tables.UserStatusEvent, {});
+  const canRun = () =>
+    ServiceAuth.canRunService(new SetUserStatus(), { name: 'setUserStatus' } as any, [target.id, 'deactivated']);
+
+  it('refuses the door for a non-admin and admits an admin', () => {
+    testEnv.actAs(nonAdmin);
+    expect(canRun()).toBe(false);
+
+    testEnv.actAs(admin);
+    expect(canRun()).toBe(true);
+  });
+
+  it('deactivate writes the standing on the user row and one audit row', async () => {
+    testEnv.actAs(admin);
+    await new SetUserStatus().setUserStatus(target.id, 'deactivated');
+
+    expect(await targetStatus()).toBe('deactivated');
+    const events = await auditRows();
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ actor: admin.id, target: target.id, status: 'deactivated' });
+    expect(events[0].created).toBeDefined();
+  });
+
+  it('setting the standing the user already holds changes nothing and writes no audit row', async () => {
+    testEnv.actAs(admin);
+    const service = new SetUserStatus();
+    await service.setUserStatus(target.id, 'deactivated');
+    await service.setUserStatus(target.id, 'deactivated');
+
+    expect(await targetStatus()).toBe('deactivated');
+    expect(await auditRows()).toHaveLength(1);
+  });
+
+  it('treats a null standing (row predating the column) as active — no write, no audit row', async () => {
+    await getDbAsSystem().update(tables.User, { id: target.id, status: null });
+
+    testEnv.actAs(admin);
+    await new SetUserStatus().setUserStatus(target.id, 'active');
+
+    expect(await targetStatus()).toBeFalsy();
+    expect(await auditRows()).toHaveLength(0);
+  });
+
+  it('reactivate flips the standing back and audits it', async () => {
+    testEnv.actAs(admin);
+    const service = new SetUserStatus();
+    await service.setUserStatus(target.id, 'deactivated');
+    await service.setUserStatus(target.id, 'active');
+
+    expect(await targetStatus()).toBe('active');
+    const events = await auditRows();
+    expect(events).toHaveLength(2);
+    expect(events.map((event) => event.status).sort()).toEqual(['active', 'deactivated']);
+  });
+
+  it('refuses a standing the vocabulary does not know, and writes nothing', async () => {
+    testEnv.actAs(admin);
+    await expect(new SetUserStatus().setUserStatus(target.id, 'suspended' as any)).rejects.toThrow(
+      `'suspended' is not a known user status. Pick one of: active, deactivated.`
+    );
+    expect(await targetStatus()).toBe('active');
+    expect(await auditRows()).toHaveLength(0);
+  });
+
+  it('refuses a change for a user that does not exist', async () => {
+    testEnv.actAs(admin);
+    await expect(new SetUserStatus().setUserStatus('nobody-1', 'deactivated')).rejects.toThrow(
+      'No user found for id: nobody-1'
+    );
+    expect(await auditRows()).toHaveLength(0);
+  });
+});

package/test/UserStatusGate.integration.test.ts

@@ -0,0 +1,68 @@
+import sha256 from 'crypto-js/sha256';
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables } from '@proteinjs/user';
+import { authenticate } from '../src/authentication/authenticate';
+import { userCache } from '../src/authorization/userCache';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * The deactivation gate, both halves, asserted on outcomes against the emulator:
+ * - login half (authenticate): correct credentials on a deactivated account are refused;
+ * - session half (userCache): the session cache is rebuilt per request, so a live session stops
+ *   resolving the moment its account is deactivated — requests run as the unauthenticated guest.
+ */
+describe('user status gate — login refusal and session resolution', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  }, 120000);
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  /** Insert an account the way the product stores it: lowercased email, sha256 password. */
+  const createAccount = async (email: string, password: string, status?: 'active' | 'deactivated') => {
+    return await getDbAsSystem().insert(tables.User, {
+      name: 'Gate test user',
+      email,
+      password: sha256(password).toString(),
+      emailVerified: true,
+      roles: [],
+      ...(status ? { status } : {}),
+    });
+  };
+
+  it('refuses login for a deactivated account even with correct credentials', async () => {
+    await createAccount('deactivated-login@test.local', 'correct-password', 'deactivated');
+
+    const result = await authenticate('deactivated-login@test.local', 'correct-password');
+
+    expect(result).toBe('This account has been deactivated');
+  });
+
+  it('logs an active account in unaffected', async () => {
+    await createAccount('active-login@test.local', 'correct-password');
+
+    expect(await authenticate('active-login@test.local', 'correct-password')).toBe(true);
+    expect(await authenticate('active-login@test.local', 'wrong-password')).toBe('User name or password incorrect');
+  });
+
+  it('stops resolving a live session once its user is deactivated, and resumes on reactivation', async () => {
+    const account = await createAccount('live-session@test.local', 'correct-password');
+
+    const before = await userCache.create('live-session', 'live-session@test.local');
+    expect(before.id).toBe(account.id);
+    expect(before.email).toBe('live-session@test.local');
+
+    await getDbAsSystem().update(tables.User, { id: account.id, status: 'deactivated' });
+    const during = await userCache.create('live-session', 'live-session@test.local');
+    expect(during.id).toBe('guest');
+    expect(during.roles).toEqual([]);
+
+    await getDbAsSystem().update(tables.User, { id: account.id, status: 'active' });
+    const after = await userCache.create('live-session', 'live-session@test.local');
+    expect(after.id).toBe(account.id);
+  });
+});