@proteinjs/user-server 1.16.1 → 1.18.0

package/src/services/UpdateUserInfo.ts

@@ -1,15 +1,18 @@
 import sharp from 'sharp';
 import heicDecode from 'heic-decode';
 import { getDbAsSystem } from '@proteinjs/db';
-import { FileStorage } from '@proteinjs/db-file';
+import { File, FileStorage, tables as fileTables } from '@proteinjs/db-file';
 import {
   tables,
   User,
+  UserAuth,
   UserRepo,
+  USER_PERMISSIONS,
   UpdatePasswordResponse,
   UpdatedUser,
   UpdateUserInfoService,
   AvatarCrop,
+  getScopedDbAsSystem,
 } from '@proteinjs/user';
 import { EmailSender, getDefaultPasswordUpdatedEmailConfigFactory } from '@proteinjs/email-server';
 import { PasswordHasher } from '../authentication/PasswordHasher';
@@ -131,8 +134,22 @@ export class UpdateUserInfo implements UpdateUserInfoService {
     return await this.setAvatar({ avatarEmoji: trimmed, avatarFileId: null });
   }
 
-  async clearAvatar(): Promise<UpdatedUser> {
-    return await this.setAvatar({ avatarEmoji: null, avatarFileId: null });
+  async clearAvatar(userId?: string): Promise<UpdatedUser> {
+    return await this.setAvatar({ avatarEmoji: null, avatarFileId: null }, userId);
+  }
+
+  /**
+   * The read-only half of `saveUserInfo`: no write, just the stored row pulled back into the
+   * session cache. Every mutation through this service already refreshes the cache, so this is
+   * for changes made ELSEWHERE — another device, another tab, a user manager — which the cached
+   * user would otherwise keep hiding until the next sign-in.
+   */
+  async refresh(): Promise<UpdatedUser> {
+    const userRepo = new UserRepo();
+    const updated = await getDbAsSystem().get(tables.User, { id: userRepo.getUser().id });
+    delete (updated as Partial<User>).password; // the same password-less shape userCache caches
+    userRepo.setUser(updated);
+    return updated;
   }
 
   /**
@@ -140,13 +157,25 @@ export class UpdateUserInfo implements UpdateUserInfoService {
    * the exactly-one-active invariant (photo OR emoji, never both). Also the previous photo's
    * cleanup point: an avatar file the user row no longer points to is unreachable (the /avatar
    * route serves only the id on the user row), so it is deleted here, after the row moves off it.
+   *
+   * `userId` names ANOTHER person (see {@link resolveTarget} for the permission that admits it);
+   * everything below then applies to that person's row and their previous photo.
    */
-  private async setAvatar(avatar: { avatarEmoji: string | null; avatarFileId: string | null }): Promise<UpdatedUser> {
-    const userId = new UserRepo().getUser().id;
-    const previousAvatarFileId = (await getDbAsSystem().get(tables.User, { id: userId })).avatarFileId;
-    const updated = await this.saveUserInfo(avatar);
+  private async setAvatar(
+    avatar: { avatarEmoji: string | null; avatarFileId: string | null },
+    userId?: string
+  ): Promise<UpdatedUser> {
+    const { targetUserId } = this.resolveTarget(userId);
+    const previousAvatarFileId = (await getDbAsSystem().get(tables.User, { id: targetUserId })).avatarFileId;
+    const updated = await this.saveUserInfo(avatar, userId);
     if (previousAvatarFileId && previousAvatarFileId !== avatar.avatarFileId) {
-      await new FileStorage().deleteFile(previousAvatarFileId);
+      // Deleted as SYSTEM, like the user-row write it accompanies: the file lives in the TARGET's
+      // scope, and a caller-scoped delete (`FileStorage.deleteFile`) would silently match nothing
+      // when a user manager clears someone else's photo, orphaning the bytes. This door has
+      // already made its own access decision, the same shape as the /avatar route's system read.
+      // The bytes still die with the row — `FileStorageTableWatcher` fires for every file-row
+      // delete path, system sweeps included.
+      await getScopedDbAsSystem<File>().delete(fileTables.File, { id: previousAvatarFileId });
     }
 
     return updated;
@@ -159,18 +188,44 @@ export class UpdateUserInfo implements UpdateUserInfoService {
    * long-lived contexts that keep their session data (sockets) — serving the STALE user until
    * re-login (the rename wart). Fusing persist + refresh here means no future mutation can
    * reintroduce that class of staleness.
+   *
+   * The refresh is the CALLER's own cache, so it happens only when the caller is the target. A
+   * user manager changing someone else writes the row and stops there: refreshing would hand the
+   * admin the target's row as their own identity, and there is no way to reach the target's
+   * session from here anyway — their next sign-in reads the row.
    */
-  private async saveUserInfo(changes: Partial<User>): Promise<UpdatedUser> {
+  private async saveUserInfo(changes: Partial<User>, userId?: string): Promise<UpdatedUser> {
     const userRepo = new UserRepo();
-    const userId = userRepo.getUser().id;
+    const { targetUserId, targetIsCaller } = this.resolveTarget(userId);
     const db = getDbAsSystem();
-    await db.update(tables.User, changes, { id: userId });
-    const updated = await db.get(tables.User, { id: userId });
+    await db.update(tables.User, changes, { id: targetUserId });
+    const updated = await db.get(tables.User, { id: targetUserId });
     delete (updated as Partial<User>).password; // the same password-less shape userCache caches
-    userRepo.setUser(updated);
+    if (targetIsCaller) {
+      userRepo.setUser(updated);
+    }
+
     return updated;
   }
 
+  /**
+   * The user a mutation targets, and whether that is the caller.
+   *
+   * The service door is `allUsers` — it has to be, every signed-in user manages their own
+   * profile through it — so naming ANOTHER person's id is authorized here, in-body and
+   * fail-closed: only a `users` permission holder may do it.
+   */
+  private resolveTarget(userId?: string): { targetUserId: string; targetIsCaller: boolean } {
+    const callerId = new UserRepo().getUser().id;
+    const targetUserId = userId ?? callerId;
+    const targetIsCaller = targetUserId === callerId;
+    if (!targetIsCaller && !UserAuth.hasPermission(USER_PERMISSIONS.users)) {
+      throw new Error(`Only a user manager can change another person's avatar.`);
+    }
+
+    return { targetUserId, targetIsCaller };
+  }
+
   /**
    * THE avatar image pipeline — the only place avatar pixels are ever resampled: decode,
    * auto-orient from EXIF, extract the crop frame (client-framed, or the centered square),

package/test/DevLogin.test.ts

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

package/test/DevLoginBootstrapAdmin.test.ts

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

package/test/Roles.integration.test.ts

@@ -214,6 +214,47 @@ describe('Roles service — grant/revoke outcomes and audit trail', () => {
     expect(events[0]).toMatchObject({ actor: 'actor-1', target: targetId, role: 'data-access', action: 'grant' });
   }, 60000);
 
+  /**
+   * Nobody edits their own roles. Self-service escalation is the whole reason the 'roles'
+   * permission is separated from 'users', and a self-REVOKE is the mirror hazard: the last
+   * holder locking themselves out of the door they were meant to keep. Both are refused before
+   * the no-change early return, so a self-target is always an error and never a silent no-op,
+   * and before the transaction, so nothing lands in the audit ledger.
+   */
+  describe('self-targeted role changes', () => {
+    const selfEvents = async () =>
+      (await auditRows()).filter((event) => event.actor === actor.id && event.target === actor.id);
+
+    it('refuses a self GRANT — the actor keeps their roles and nothing is audited', async () => {
+      await expect(new Roles().grantRole(actor.id, 'ops')).rejects.toThrow(
+        `You can't grant your own roles — ask another user manager.`
+      );
+
+      const actorRow = await getDbAsSystem().get(tables.User, { id: actor.id });
+      expect(actorRow.roles).toEqual(['admin']);
+      expect(await selfEvents()).toHaveLength(0);
+    }, 60000);
+
+    it('refuses a self REVOKE of a role the actor holds — the role stays, nothing is audited', async () => {
+      await getDbAsSystem().update(tables.User, { id: actor.id, roles: ['admin', 'ops'] });
+
+      await expect(new Roles().revokeRole(actor.id, 'ops')).rejects.toThrow(
+        `You can't revoke your own roles — ask another user manager.`
+      );
+
+      const actorRow = await getDbAsSystem().get(tables.User, { id: actor.id });
+      expect(actorRow.roles).toEqual(['admin', 'ops']);
+      expect(await selfEvents()).toHaveLength(0);
+    }, 60000);
+
+    it('refuses a self target the catalog would otherwise no-op — a self-target is never silent', async () => {
+      // The actor does NOT hold 'ops', so a revoke would have hit the no-change early return and
+      // returned quietly. The refusal comes first: the caller always learns the act was refused.
+      await expect(new Roles().revokeRole(actor.id, 'ops')).rejects.toThrow(/your own roles/);
+      expect(await selfEvents()).toHaveLength(0);
+    }, 60000);
+  });
+
   it('a roles-holder can still REVOKE an admin-grant-only role — de-escalation stays open (the break-glass precedent)', async () => {
     await new Roles().grantRole(targetId, 'data-access');
     new UserRepo().setUser({ ...actor, roles: ['roles'] });

package/test/UpdateUserInfoClearAvatarByAdmin.test.ts

@@ -0,0 +1,109 @@
+import sharp from 'sharp';
+import { getDbAsSystem } from '@proteinjs/db';
+import { File, tables as fileTables } from '@proteinjs/db-file';
+import { SourceRepository } from '@proteinjs/reflection';
+import { tables, UpdateUserInfoService, User, UserRepo, getScopedDbAsSystem } from '@proteinjs/user';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+import { UpdateUserInfo } from '../src/services/UpdateUserInfo';
+
+const testEnv = new UserServerTestEnvironment();
+
+const getFileRow = async (fileId: string) => await getScopedDbAsSystem<File>().get(fileTables.File, { id: fileId });
+const userRow = async (id: string) => await getDbAsSystem().get(tables.User, { id });
+
+/**
+ * Clearing SOMEONE ELSE'S avatar — the user-manager act behind the admin user surface.
+ *
+ * The service door is `allUsers` (every signed-in user manages their own profile through it), so
+ * the cross-user authorization is in-body and fail-closed: naming another person's id requires
+ * the `users` permission. Two invariants beyond the row write:
+ *  - the ACTOR's session cache is never overwritten with the target's row (the mutation path
+ *    refreshes the caller's cached user, and doing that for another person's row would leave the
+ *    admin browsing as their target);
+ *  - the target's own session cache is NOT refreshed — the write is to their row, and their next
+ *    sign-in reads it.
+ * Outcomes asserted against a real Spanner emulator: rows, files, cached identity.
+ */
+describe('UpdateUserInfo — clearing another person avatar', () => {
+  const service: UpdateUserInfoService = new UpdateUserInfo();
+  let admin: User;
+  let kevin: User;
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+    // The in-body permission check resolves the CALLER through UserAuth — the same session-backed
+    // repo the services use (the environment seeds session storage but not this registration).
+    (SourceRepository.get() as any).objectCache['@proteinjs/user-auth/AuthenticatedUserRepo'] = [new UserRepo()];
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(async () => {
+    admin = await testEnv.createUser({ name: 'Ada Admin', email: `admin-${Date.now()}@test.local`, roles: ['admin'] });
+    kevin = await testEnv.createUser({ name: 'Kevin', email: `kevin-${Date.now()}@test.local` });
+    testEnv.actAs(admin);
+  });
+
+  it("clears the target's avatar, returns the target's row, and leaves the actor's session alone", async () => {
+    await getDbAsSystem().update(tables.User, { id: kevin.id, avatarEmoji: '🦊' });
+
+    const updated = await service.clearAvatar(kevin.id);
+
+    // The TARGET's row moved.
+    const kevinRow = await userRow(kevin.id);
+    expect(kevinRow.avatarEmoji).toBeFalsy();
+    expect(kevinRow.avatarFileId).toBeFalsy();
+
+    // The returned user is the target's row, password-less.
+    expect(updated.id).toBe(kevin.id);
+    expect(updated.name).toBe('Kevin');
+    expect((updated as any).password).toBeUndefined();
+
+    // The actor is still signed in as themselves — the session cache was not handed the target.
+    expect(new UserRepo().getUser().id).toBe(admin.id);
+    expect(new UserRepo().getUser().name).toBe('Ada Admin');
+  });
+
+  it("deletes the target's stored avatar photo", async () => {
+    testEnv.actAs(kevin);
+    const png = await sharp({ create: { width: 64, height: 64, channels: 3, background: { r: 4, g: 5, b: 6 } } })
+      .png()
+      .toBuffer();
+    const withPhoto = await service.updateAvatarPhoto(png.toString('base64'), 'image/png');
+    expect(await getFileRow(withPhoto.avatarFileId!)).toBeTruthy();
+    testEnv.actAs(admin);
+
+    await service.clearAvatar(kevin.id);
+
+    expect(await getFileRow(withPhoto.avatarFileId!)).toBeFalsy();
+    expect((await userRow(kevin.id)).avatarFileId).toBeFalsy();
+  });
+
+  it("refuses an actor without the users permission, and the target's avatar is untouched", async () => {
+    const bystander = await testEnv.createUser({ name: 'Bystander', email: `bystander-${Date.now()}@test.local` });
+    await getDbAsSystem().update(tables.User, { id: kevin.id, avatarEmoji: '🦊' });
+    testEnv.actAs(bystander);
+
+    await expect(service.clearAvatar(kevin.id)).rejects.toThrow(
+      `Only a user manager can change another person's avatar.`
+    );
+
+    expect((await userRow(kevin.id)).avatarEmoji).toBe('🦊');
+  });
+
+  it('with no id it still clears the CALLER own avatar and refreshes their session (the existing contract)', async () => {
+    testEnv.actAs(kevin);
+    await service.updateAvatarEmoji('🦞');
+    expect(new UserRepo().getUser().avatarEmoji).toBe('🦞');
+
+    const updated = await service.clearAvatar();
+
+    expect(updated.id).toBe(kevin.id);
+    expect(updated.avatarEmoji).toBeFalsy();
+    expect((await userRow(kevin.id)).avatarEmoji).toBeFalsy();
+    // Self path: the session cache is refreshed in the same stroke.
+    expect(new UserRepo().getUser().avatarEmoji).toBeFalsy();
+  });
+});

package/test/UpdateUserInfoRefresh.test.ts

@@ -0,0 +1,40 @@
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables, UserRepo } from '@proteinjs/user';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+import { UpdateUserInfo } from '../src/services/UpdateUserInfo';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `refresh()` is the read-only half of the persist-and-refresh helper: no write, just the stored
+ * row pulled back into the session cache. It exists for changes this session did not make — an
+ * avatar set on the phone, a rename from another tab, an admin clearing an avatar — which
+ * otherwise stay invisible here until the next sign-in, because the cached user is only ever
+ * rewritten by this session's OWN mutations.
+ */
+describe('UpdateUserInfo.refresh — re-reads the stored row into the session cache', () => {
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  it('picks up a change made outside this session, and returns the row password-less', async () => {
+    const user = await testEnv.createUser({ name: 'Two Devices', email: 'refresh@test.local' });
+    testEnv.actAs(user);
+
+    // The other device's write: the row moves, this session's cached user does not.
+    await getDbAsSystem().update(tables.User, { avatarEmoji: '🦊' }, { id: user.id });
+    expect(new UserRepo().getUser().avatarEmoji).toBeFalsy();
+
+    const updated = await new UpdateUserInfo().refresh();
+
+    expect(updated.id).toBe(user.id);
+    expect(updated.avatarEmoji).toBe('🦊');
+    expect((updated as any).password).toBeUndefined();
+    // The point of the call: the cached user carries it now, with no re-login.
+    expect(new UserRepo().getUser().avatarEmoji).toBe('🦊');
+  });
+});

package/test/devLoginHarness.ts

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