@proteinjs/user-server 1.5.4 → 1.7.0

package/src/routes/devLogin.ts

@@ -1,29 +1,72 @@
 import { Route } from '@proteinjs/server-api';
 import { Logger } from '@proteinjs/logger';
+import { Signup } from '../services/Signup';
 
 const logger = new Logger({ name: 'devLogin' });
 
+/** Lowercased domain of an email address (the whole string when there is no `@`, which can never
+ *  equal a real env domain — so malformed params fall out at the domain rail). */
+const emailDomain = (address: string) => address.slice(address.lastIndexOf('@') + 1).toLowerCase();
+
 /**
- * DEV-ONLY session bootstrap: `GET /dev/login` establishes a session for the account named by
- * `DEV_AUTO_LOGIN_EMAIL` — no credentials involved — so automated dev-loop testing (agent-driven
- * browsers) can self-serve a session instead of stalling on the login form every time a cookie
- * is lost.
+ * DEV-ONLY session bootstrap: `GET /dev/login` establishes a session — no credentials involved —
+ * so automated dev-loop testing (agent-driven browsers) can self-serve a session instead of
+ * stalling on the login form. `?email=<addr>` selects the session's account so parallel
+ * verification can fan out over distinct users; absent, the `DEV_AUTO_LOGIN_EMAIL` account is
+ * used as before.
  *
  * Double-gated, acts only when BOTH hold; otherwise the path answers 404 as if unregistered:
  * 1. `process.env.DEVELOPMENT` — the dev-server switch, never set in prod images.
- * 2. `DEV_AUTO_LOGIN_EMAIL` — explicit per-launch opt-in naming exactly one account.
+ * 2. `DEV_AUTO_LOGIN_EMAIL` — explicit per-launch opt-in naming the default account.
+ *
+ * Domain rail: `?email` must share `DEV_AUTO_LOGIN_EMAIL`'s domain — even a dev server must not
+ * mint sessions (much less accounts) for arbitrary domains; anything else answers 400.
+ *
+ * A missing account is created through the normal signup creation path (`Signup.createAccount`)
+ * as a normal test user — password `test`, matching the seeded test-account convention, so
+ * interactive login works for the same identity. Composes with userCache's missing-account→guest
+ * seam: that covers sessions whose account was deleted AFTER minting; this ensures dev-minted
+ * sessions reference a real account from the start.
  */
 export const devLogin: Route = {
   path: '/dev/login',
   method: 'get',
   onRequest: async (request: any, response): Promise<void> => {
-    const email = (process.env.DEV_AUTO_LOGIN_EMAIL ?? '').trim();
-    if (!process.env.DEVELOPMENT || !email) {
+    const envEmail = (process.env.DEV_AUTO_LOGIN_EMAIL ?? '').trim();
+    if (!process.env.DEVELOPMENT || !envEmail) {
       response.status(404).send();
       return;
     }
 
+    let email = envEmail;
+    const emailParam = request.query?.email;
+    if (emailParam !== undefined) {
+      const requested = typeof emailParam === 'string' ? emailParam.trim() : '';
+      if (emailDomain(requested) !== emailDomain(envEmail)) {
+        response.status(400).send(`/dev/login only accepts accounts on the @${emailDomain(envEmail)} domain`);
+        return;
+      }
+      email = requested;
+    }
+    email = email.toLowerCase();
+
+    const creation = await new Signup().createAccount({
+      name: email.slice(0, email.indexOf('@')),
+      email,
+      password: 'test',
+      emailVerified: false, // same shape an inviteless signup produces
+      invitedBy: null,
+    });
+    if (creation === 'created') {
+      logger.info({ message: 'Dev auto-login created missing test account', obj: { email } });
+    }
+
     await new Promise((resolve) => request.login(email, resolve));
+    // Explicit save before redirecting: with a DB-backed session store, save-on-response-end
+    // races the redirected GET / — the follow-up request can read the session row before the
+    // write commits and render the login page (observed: first /dev/login load lands on /login,
+    // second succeeds). Awaiting the store write closes the race.
+    await new Promise((resolve) => request.session.save(resolve));
     logger.info({ message: 'Dev auto-login session established', obj: { email } });
     response.redirect('/');
   },

package/src/services/Signup.ts

@@ -8,6 +8,7 @@ import {
   InitializeSignupResponse,
   UserRepo,
   Invite,
+  User,
   UserSignup,
   USER_PERMISSIONS,
 } from '@proteinjs/user';
@@ -96,8 +97,14 @@ export class Signup implements SignupService {
     const config = defaultEmailConfigFactory.getConfig();
     const emailSender = new EmailSender();
 
-    const userRecord = await db.get(tables.User, { email });
-    if (userRecord) {
+    const creation = await this.createAccount({
+      name: user.name,
+      email,
+      password: user.password,
+      emailVerified: invite ? true : false, // because we retrieved the email from the invite record
+      invitedBy: invite ? invite.invitedBy : null,
+    });
+    if (creation === 'exists') {
       logger.error({ message: `User with this email already exists`, obj: { email } });
       if (config.getExistingUserEmailContent) {
         const { text, html } = config.getExistingUserEmailContent();
@@ -112,15 +119,6 @@ export class Signup implements SignupService {
       return;
     }
 
-    await db.insert(tables.User, {
-      name: user.name,
-      email,
-      password: sha256(user.password).toString(),
-      emailVerified: invite ? true : false, // because we retrieved the email from the invite record
-      roles: [],
-      invitedBy: invite ? invite.invitedBy : null,
-    });
-
     const { text, html } = config.getNewUserEmailContent();
     await emailSender.sendEmail({
       to: email,
@@ -257,6 +255,39 @@ export class Signup implements SignupService {
     }
   }
 
+  /**
+   * Single owner of account-record creation: case-normalized existence check + sha256-hashed
+   * insert. Both doors into a user row go through here — the signup flow (`createUser`, which
+   * layers invite validation and confirmation emails on top) and the dev-login bootstrap
+   * (`devLogin`, which auto-creates missing same-domain test accounts). Not exposed as an RPC:
+   * the service surface is the `SignupService` INTERFACE (ServiceRouter walks its declared
+   * methods), so extra class methods stay server-internal.
+   */
+  async createAccount(account: {
+    name: string;
+    email: string;
+    password: string;
+    emailVerified: boolean;
+    invitedBy: User['invitedBy'];
+  }): Promise<'created' | 'exists'> {
+    const db = getDbAsSystem();
+    const email = account.email.toLowerCase();
+    const existingUser = await db.get(tables.User, { email });
+    if (existingUser) {
+      return 'exists';
+    }
+
+    await db.insert(tables.User, {
+      name: account.name,
+      email,
+      password: sha256(account.password).toString(),
+      emailVerified: account.emailVerified,
+      roles: [],
+      invitedBy: account.invitedBy,
+    });
+    return 'created';
+  }
+
   /** Resolves an invite token, distinguishing "expired" from "never existed / already revoked". */
   private async lookupInvite(token: string): Promise<InviteLookup> {
     const db = getDbAsSystem();

package/src/services/UpdateUserInfo.ts

@@ -1,19 +1,36 @@
+import sharp from 'sharp';
+import heicDecode from 'heic-decode';
+import sha256 from 'crypto-js/sha256';
 import { getDbAsSystem } from '@proteinjs/db';
-import { tables, UserRepo, UpdatePasswordResponse, UpdateUserInfoService } from '@proteinjs/user';
+import { FileStorage } from '@proteinjs/db-file';
+import { tables, User, UserRepo, UpdatePasswordResponse, UpdatedUser, UpdateUserInfoService } from '@proteinjs/user';
 import { EmailSender, getDefaultPasswordUpdatedEmailConfigFactory } from '@proteinjs/email-server';
-import sha256 from 'crypto-js/sha256';
 
 export class UpdateUserInfo implements UpdateUserInfoService {
+  /** Stored avatar photos are exactly this: cover-cropped square JPEG. */
+  private static readonly AVATAR_SIZE = 512;
+  private static readonly AVATAR_JPEG_QUALITY = 85;
+  private static readonly MAX_AVATAR_PHOTO_BYTES = 10 * 1024 * 1024;
+  private static readonly ACCEPTED_AVATAR_MIME_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+    'image/heic',
+    'image/heif',
+  ];
+  /** One emoji (possibly a ZWJ/flag/keycap sequence) — a handful of code units, never a sentence. */
+  private static readonly MAX_AVATAR_EMOJI_LENGTH = 16;
+  /** Constructed (not a literal) because tsconfig targets es5; runs on Node, which supports `\p`. */
+  private static readonly EMOJI_PATTERN = new RegExp('[\\p{Extended_Pictographic}\\p{Regional_Indicator}\\u20E3]', 'u');
+
   public serviceMetadata = {
     auth: {
       allUsers: true,
     },
   };
 
-  async updateName(name: string): Promise<void> {
-    const db = getDbAsSystem();
-    const user = new UserRepo().getUser();
-    await db.update(tables.User, { name }, { id: user.id });
+  async updateName(name: string): Promise<UpdatedUser> {
+    return await this.saveUserInfo({ name });
   }
 
   async updatePassword(currentPassword: string, newPassword: string): Promise<UpdatePasswordResponse> {
@@ -54,13 +71,7 @@ export class UpdateUserInfo implements UpdateUserInfoService {
     // hash and store new password
     try {
       const hashedNewPassword = sha256(newPassword).toString();
-      await db.update(
-        tables.User,
-        {
-          password: hashedNewPassword,
-        },
-        { id: user.id }
-      );
+      await this.saveUserInfo({ password: hashedNewPassword });
     } catch (error: any) {
       return {
         updated: false,
@@ -72,4 +83,104 @@ export class UpdateUserInfo implements UpdateUserInfoService {
       updated: true,
     };
   }
+
+  async updateAvatarPhoto(fileData: string, mimeType: string): Promise<UpdatedUser> {
+    if (!UpdateUserInfo.ACCEPTED_AVATAR_MIME_TYPES.includes(mimeType)) {
+      throw new Error(
+        `Unsupported avatar image type '${mimeType}'. Accepted: ${UpdateUserInfo.ACCEPTED_AVATAR_MIME_TYPES.join(', ')}`
+      );
+    }
+
+    const imageBytes = Buffer.from(fileData, 'base64');
+    if (imageBytes.length > UpdateUserInfo.MAX_AVATAR_PHOTO_BYTES) {
+      throw new Error(`Avatar photo is too large (max 10MB)`);
+    }
+
+    const jpeg = await this.toAvatarJpeg(imageBytes, mimeType);
+    const file = await new FileStorage().createFile(
+      { name: 'avatar.jpg', type: 'image/jpeg', size: jpeg.length },
+      jpeg.toString('base64')
+    );
+    return await this.setAvatar({ avatarEmoji: null, avatarFileId: file.id });
+  }
+
+  async updateAvatarEmoji(emoji: string): Promise<UpdatedUser> {
+    const trimmed = emoji.trim();
+    if (
+      !trimmed ||
+      trimmed.length > UpdateUserInfo.MAX_AVATAR_EMOJI_LENGTH ||
+      /\s/.test(trimmed) ||
+      !UpdateUserInfo.EMOJI_PATTERN.test(trimmed)
+    ) {
+      throw new Error(`Avatar emoji must be a single short emoji`);
+    }
+
+    return await this.setAvatar({ avatarEmoji: trimmed, avatarFileId: null });
+  }
+
+  async clearAvatar(): Promise<UpdatedUser> {
+    return await this.setAvatar({ avatarEmoji: null, avatarFileId: null });
+  }
+
+  /**
+   * The single door to the avatar columns — every mutation assigns BOTH, which is what enforces
+   * 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.
+   */
+  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);
+    if (previousAvatarFileId && previousAvatarFileId !== avatar.avatarFileId) {
+      await new FileStorage().deleteFile(previousAvatarFileId);
+    }
+
+    return updated;
+  }
+
+  /**
+   * The one path every user-info mutation persists through: writes the changes AND refreshes the
+   * server session cache in the same stroke. userCache serializes the user into session data at
+   * request start; a bare DB write leaves every read through UserRepo in the same context — and
+   * 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.
+   */
+  private async saveUserInfo(changes: Partial<User>): Promise<UpdatedUser> {
+    const userRepo = new UserRepo();
+    const userId = userRepo.getUser().id;
+    const db = getDbAsSystem();
+    await db.update(tables.User, changes, { id: userId });
+    const updated = await db.get(tables.User, { id: userId });
+    delete (updated as Partial<User>).password; // the same password-less shape userCache caches
+    userRepo.setUser(updated);
+    return updated;
+  }
+
+  /**
+   * Minimal avatar pipeline: decode, auto-orient from EXIF, cover-crop square, re-encode JPEG.
+   * sharp drops metadata (EXIF orientation/GPS) on re-encode by default — the stored avatar
+   * carries no camera metadata. HEIC/HEIF (default iPhone camera format) is decoded with WASM
+   * libheif (`heic-decode`) because sharp's prebuilt libvips has no HEVC decoder. NOTE: this
+   * duplicates the HEIC-normalization approach of chat-server's FileTransformer, which this
+   * package cannot import (layering) — future extraction target: a shared image-transform seam.
+   */
+  private async toAvatarJpeg(imageBytes: Buffer, mimeType: string): Promise<Buffer> {
+    const pipeline =
+      mimeType === 'image/heic' || mimeType === 'image/heif'
+        ? await this.decodeHeic(imageBytes)
+        : sharp(imageBytes).rotate();
+    return await pipeline
+      .resize(UpdateUserInfo.AVATAR_SIZE, UpdateUserInfo.AVATAR_SIZE, { fit: 'cover' })
+      .jpeg({ quality: UpdateUserInfo.AVATAR_JPEG_QUALITY })
+      .toBuffer();
+  }
+
+  private async decodeHeic(imageBytes: Buffer): Promise<sharp.Sharp> {
+    const { width, height, data } = await heicDecode({ buffer: imageBytes });
+    return sharp(Buffer.from(data.buffer, data.byteOffset, data.byteLength), {
+      raw: { width, height, channels: 4 },
+    });
+  }
 }

package/test/DevLogin.test.ts

@@ -0,0 +1,159 @@
+import sha256 from 'crypto-js/sha256';
+import { getDbAsSystem } from '@proteinjs/db';
+import { tables } from '@proteinjs/user';
+import { devLogin } from '../src/routes/devLogin';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+
+const testEnv = new UserServerTestEnvironment();
+
+/**
+ * `GET /dev/login` multi-user dev bootstrap. The route mints a session for the account named by
+ * `?email=` (absent → `DEV_AUTO_LOGIN_EMAIL`), auto-creating a missing account through the normal
+ * signup creation path (`Signup.createAccount`) so parallel agent-driven verification can
+ * self-serve distinct users. Two rails under test:
+ * - 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.
+ */
+
+const ENV_EMAIL = 'dev@test.local';
+
+type RouteOutcome = {
+  loggedInAs?: string;
+  sessionSaved: boolean;
+  status?: number;
+  body?: unknown;
+  redirect?: string;
+};
+
+const invokeDevLogin = async (query?: Record<string, unknown>): Promise<RouteOutcome> => {
+  const outcome: RouteOutcome = { sessionSaved: false };
+  const request = {
+    query,
+    login: (email: string, done: () => void) => {
+      outcome.loggedInAs = email;
+      done();
+    },
+    session: {
+      save: (done: () => void) => {
+        outcome.sessionSaved = true;
+        done();
+      },
+    },
+  };
+  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);
+  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,
+  };
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  beforeEach(() => {
+    process.env.DEVELOPMENT = 'true';
+    process.env.DEV_AUTO_LOGIN_EMAIL = ENV_EMAIL;
+  });
+
+  afterEach(() => {
+    for (const [key, value] of Object.entries(originalEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it('pins the default path: no ?email → session for DEV_AUTO_LOGIN_EMAIL, redirect to /', async () => {
+    await testEnv.createUser({ name: 'Dev Default', email: ENV_EMAIL });
+
+    const outcome = await invokeDevLogin();
+
+    expect(outcome.loggedInAs).toBe(ENV_EMAIL);
+    expect(outcome.sessionSaved).toBe(true);
+    expect(outcome.redirect).toBe('/');
+    expect(outcome.status).toBeUndefined();
+  });
+
+  it('?email selects an existing same-domain account for the session', async () => {
+    await testEnv.createUser({ name: 'Agent Two', email: 'agent2@test.local' });
+
+    const outcome = await invokeDevLogin({ email: 'agent2@test.local' });
+
+    expect(outcome.loggedInAs).toBe('agent2@test.local');
+    expect(outcome.sessionSaved).toBe(true);
+    expect(outcome.redirect).toBe('/');
+  });
+
+  it('?email for a nonexistent same-domain account creates it as a normal test user, then logs in', async () => {
+    expect(await getUserRow('agent3@test.local')).toBeUndefined();
+
+    const outcome = await invokeDevLogin({ email: 'agent3@test.local' });
+
+    expect(outcome.loggedInAs).toBe('agent3@test.local');
+    expect(outcome.sessionSaved).toBe(true);
+    expect(outcome.redirect).toBe('/');
+
+    // Created through the normal signup creation path: sha256-hashed 'test' password (the seeded
+    // test-user convention — interactive login with password 'test' works too), no roles.
+    const created = await getUserRow('agent3@test.local');
+    expect(created).toBeDefined();
+    expect(created!.password).toBe(sha256('test').toString());
+    expect(created!.roles).toEqual([]);
+    expect(created!.name).toBeTruthy();
+  });
+
+  it('rejects a ?email outside the DEV_AUTO_LOGIN_EMAIL domain with 400 — no session, no account', async () => {
+    const outcome = await invokeDevLogin({ email: 'intruder@evil.example' });
+
+    expect(outcome.status).toBe(400);
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(outcome.sessionSaved).toBe(false);
+    expect(outcome.redirect).toBeUndefined();
+    expect(await getUserRow('intruder@evil.example')).toBeUndefined();
+  });
+
+  it('404s when DEVELOPMENT is unset, even with a ?email', async () => {
+    delete process.env.DEVELOPMENT;
+
+    const outcome = await invokeDevLogin({ email: 'agent4@test.local' });
+
+    expect(outcome.status).toBe(404);
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(await getUserRow('agent4@test.local')).toBeUndefined();
+  });
+
+  it('404s when DEV_AUTO_LOGIN_EMAIL is unset, even with a ?email', async () => {
+    delete process.env.DEV_AUTO_LOGIN_EMAIL;
+
+    const outcome = await invokeDevLogin({ email: 'agent5@test.local' });
+
+    expect(outcome.status).toBe(404);
+    expect(outcome.loggedInAs).toBeUndefined();
+    expect(await getUserRow('agent5@test.local')).toBeUndefined();
+  });
+});

package/test/UpdateUserInfoAvatar.test.ts

@@ -0,0 +1,174 @@
+import fs from 'fs';
+import path from 'path';
+import sharp from 'sharp';
+import { getDbAsSystem } from '@proteinjs/db';
+import { FileStorage, File, tables as fileTables } from '@proteinjs/db-file';
+import { tables, UserRepo, getScopedDbAsSystem } from '@proteinjs/user';
+import { UserServerTestEnvironment } from './UserServerTestEnvironment';
+import { UpdateUserInfo } from '../src/services/UpdateUserInfo';
+
+const testEnv = new UserServerTestEnvironment();
+
+/** JPEG magic bytes (SOI + marker prefix). */
+const isJpeg = (buffer: Buffer) => buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+
+const getFileRow = async (fileId: string) => await getScopedDbAsSystem<File>().get(fileTables.File, { id: fileId });
+
+/**
+ * Avatars are photo OR emoji — exactly one active — stored as 512x512 JPEG, previous photo file
+ * deleted on every change, and the server session cache refreshed in the same stroke (the same
+ * helper that fixes the updateName rename-staleness wart). All assertions are outcomes: rows,
+ * bytes, cache reads.
+ */
+describe('UpdateUserInfo avatar mutations', () => {
+  const service = new UpdateUserInfo();
+
+  beforeAll(async () => {
+    await testEnv.beforeAll();
+  });
+
+  afterAll(async () => {
+    await testEnv.afterAll();
+  });
+
+  it('updateAvatarPhoto stores a 512x512 JPEG file and points the user row at it', async () => {
+    const user = await testEnv.createUser({ name: 'Photo user', email: 'photo@test.local' });
+    testEnv.actAs(user);
+    const png = await sharp({
+      create: { width: 800, height: 600, channels: 3, background: { r: 200, g: 80, b: 40 } },
+    })
+      .png()
+      .toBuffer();
+
+    const updated = await service.updateAvatarPhoto(png.toString('base64'), 'image/png');
+
+    // Returned user: photo active, emoji null, no password hash.
+    expect(updated.avatarFileId).toBeTruthy();
+    expect(updated.avatarEmoji).toBeFalsy();
+    expect((updated as any).password).toBeUndefined();
+
+    // User row persisted with the exactly-one invariant.
+    const row = await getDbAsSystem().get(tables.User, { id: user.id });
+    expect(row.avatarFileId).toBe(updated.avatarFileId);
+    expect(row.avatarEmoji).toBeFalsy();
+
+    // File row + bytes written: a real 512x512 JPEG.
+    const file = await getFileRow(row.avatarFileId!);
+    expect(file).toBeTruthy();
+    expect(file.type).toBe('image/jpeg');
+    const bytes = Buffer.from(await new FileStorage().getFileData(file.id), 'base64');
+    expect(isJpeg(bytes)).toBe(true);
+    expect(file.size).toBe(bytes.length);
+    const metadata = await sharp(bytes).metadata();
+    expect(metadata.width).toBe(512);
+    expect(metadata.height).toBe(512);
+
+    // Session cache refreshed in the same stroke.
+    expect(new UserRepo().getUser().avatarFileId).toBe(row.avatarFileId);
+  });
+
+  it('a second updateAvatarPhoto deletes the previous avatar file', async () => {
+    const user = await testEnv.createUser({ name: 'Replacer', email: 'replace@test.local' });
+    testEnv.actAs(user);
+    const png = await sharp({ create: { width: 300, height: 300, channels: 3, background: { r: 0, g: 120, b: 200 } } })
+      .png()
+      .toBuffer();
+
+    const first = await service.updateAvatarPhoto(png.toString('base64'), 'image/png');
+    const second = await service.updateAvatarPhoto(png.toString('base64'), 'image/png');
+    expect(second.avatarFileId).not.toBe(first.avatarFileId);
+
+    // The prior file is gone — row and bytes.
+    expect(await getFileRow(first.avatarFileId!)).toBeFalsy();
+    expect(await new FileStorage().getFileData(first.avatarFileId!)).toBe('');
+    // The new one is intact.
+    expect(await getFileRow(second.avatarFileId!)).toBeTruthy();
+  });
+
+  it('updateAvatarPhoto normalizes HEIC (default iPhone camera format) to JPEG', async () => {
+    const user = await testEnv.createUser({ name: 'iPhone user', email: 'heic@test.local' });
+    testEnv.actAs(user);
+    const heic = fs.readFileSync(path.join(__dirname, 'fixtures', 'fixture.heic'));
+
+    const updated = await service.updateAvatarPhoto(heic.toString('base64'), 'image/heic');
+
+    const bytes = Buffer.from(await new FileStorage().getFileData(updated.avatarFileId!), 'base64');
+    expect(isJpeg(bytes)).toBe(true);
+    const metadata = await sharp(bytes).metadata();
+    expect(metadata.width).toBe(512);
+    expect(metadata.height).toBe(512);
+  });
+
+  it('updateAvatarEmoji sets the emoji, nulls the photo, and deletes the previous photo file', async () => {
+    const user = await testEnv.createUser({ name: 'Emoji user', email: 'emoji@test.local' });
+    testEnv.actAs(user);
+    const png = await sharp({ create: { width: 64, height: 64, channels: 3, background: { r: 9, g: 9, b: 9 } } })
+      .png()
+      .toBuffer();
+    const withPhoto = await service.updateAvatarPhoto(png.toString('base64'), 'image/png');
+
+    const updated = await service.updateAvatarEmoji('🦞');
+
+    // Exactly-one invariant, in the row and the returned user.
+    expect(updated.avatarEmoji).toBe('🦞');
+    expect(updated.avatarFileId).toBeFalsy();
+    const row = await getDbAsSystem().get(tables.User, { id: user.id });
+    expect(row.avatarEmoji).toBe('🦞');
+    expect(row.avatarFileId).toBeFalsy();
+
+    // Previous photo file deleted; session cache refreshed.
+    expect(await getFileRow(withPhoto.avatarFileId!)).toBeFalsy();
+    expect(new UserRepo().getUser().avatarEmoji).toBe('🦞');
+  });
+
+  it('accepts multi-codepoint emoji (ZWJ sequences)', async () => {
+    const user = await testEnv.createUser({ name: 'Astronaut', email: 'zwj@test.local' });
+    testEnv.actAs(user);
+    const updated = await service.updateAvatarEmoji('👩‍🚀');
+    expect(updated.avatarEmoji).toBe('👩‍🚀');
+  });
+
+  it('clearAvatar removes both representations and the stored photo file', async () => {
+    const user = await testEnv.createUser({ name: 'Clearer', email: 'clear@test.local' });
+    testEnv.actAs(user);
+    const png = await sharp({ create: { width: 64, height: 64, channels: 3, background: { r: 1, g: 2, b: 3 } } })
+      .png()
+      .toBuffer();
+    const withPhoto = await service.updateAvatarPhoto(png.toString('base64'), 'image/png');
+
+    const updated = await service.clearAvatar();
+
+    expect(updated.avatarEmoji).toBeFalsy();
+    expect(updated.avatarFileId).toBeFalsy();
+    const row = await getDbAsSystem().get(tables.User, { id: user.id });
+    expect(row.avatarEmoji).toBeFalsy();
+    expect(row.avatarFileId).toBeFalsy();
+    expect(await getFileRow(withPhoto.avatarFileId!)).toBeFalsy();
+    expect(new UserRepo().getUser().avatarFileId).toBeFalsy();
+  });
+
+  it('rejects oversized photos before transforming, and unsupported types', async () => {
+    const user = await testEnv.createUser({ name: 'Rejected', email: 'reject@test.local' });
+    testEnv.actAs(user);
+
+    const oversized = Buffer.alloc(10 * 1024 * 1024 + 1);
+    await expect(service.updateAvatarPhoto(oversized.toString('base64'), 'image/png')).rejects.toThrow(/too large/);
+    await expect(service.updateAvatarPhoto(Buffer.alloc(10).toString('base64'), 'image/gif')).rejects.toThrow(
+      /Unsupported avatar image type/
+    );
+
+    // Neither rejection touched the user row.
+    const row = await getDbAsSystem().get(tables.User, { id: user.id });
+    expect(row.avatarFileId).toBeFalsy();
+    expect(row.avatarEmoji).toBeFalsy();
+  });
+
+  it('rejects non-emoji strings as avatar emoji', async () => {
+    const user = await testEnv.createUser({ name: 'Wordy', email: 'wordy@test.local' });
+    testEnv.actAs(user);
+
+    await expect(service.updateAvatarEmoji('hello')).rejects.toThrow(/single short emoji/);
+    await expect(service.updateAvatarEmoji('')).rejects.toThrow(/single short emoji/);
+    await expect(service.updateAvatarEmoji('🦞🦞🦞🦞🦞🦞🦞🦞🦞')).rejects.toThrow(/single short emoji/);
+  });
+});