@proteinjs/user-server 1.9.1 → 1.10.1

package/src/services/UpdateUserInfo.ts

@@ -2,13 +2,27 @@ import sharp from 'sharp';
 import heicDecode from 'heic-decode';
 import { getDbAsSystem } from '@proteinjs/db';
 import { FileStorage } from '@proteinjs/db-file';
-import { tables, User, UserRepo, UpdatePasswordResponse, UpdatedUser, UpdateUserInfoService } from '@proteinjs/user';
+import {
+  tables,
+  User,
+  UserRepo,
+  UpdatePasswordResponse,
+  UpdatedUser,
+  UpdateUserInfoService,
+  AvatarCrop,
+} from '@proteinjs/user';
 import { EmailSender, getDefaultPasswordUpdatedEmailConfigFactory } from '@proteinjs/email-server';
 import { PasswordHasher } from '../authentication/PasswordHasher';
 
 export class UpdateUserInfo implements UpdateUserInfoService {
-  /** Stored avatar photos are exactly this: cover-cropped square JPEG. */
-  private static readonly AVATAR_SIZE = 512;
+  /**
+   * Stored avatar photos are square JPEGs capped at this edge — and never ENLARGED to it: a
+   * source (or crop) smaller than the cap keeps its honest pixel count. Upscaling a small photo
+   * to a fixed 512 invents pixels that read as permanent blur on every chip that renders it
+   * (the founder's fuzzy-avatar defect); the display layer downscales crisply from whatever
+   * honest size is stored.
+   */
+  private static readonly AVATAR_MAX_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 = [
@@ -83,7 +97,7 @@ export class UpdateUserInfo implements UpdateUserInfoService {
     };
   }
 
-  async updateAvatarPhoto(fileData: string, mimeType: string): Promise<UpdatedUser> {
+  async updateAvatarPhoto(fileData: string, mimeType: string, crop?: AvatarCrop): 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(', ')}`
@@ -95,7 +109,7 @@ export class UpdateUserInfo implements UpdateUserInfoService {
       throw new Error(`Avatar photo is too large (max 10MB)`);
     }
 
-    const jpeg = await this.toAvatarJpeg(imageBytes, mimeType);
+    const jpeg = await this.toAvatarJpeg(imageBytes, mimeType, crop);
     const file = await new FileStorage().createFile(
       { name: 'avatar.jpg', type: 'image/jpeg', size: jpeg.length },
       jpeg.toString('base64')
@@ -158,24 +172,74 @@ export class UpdateUserInfo implements UpdateUserInfoService {
   }
 
   /**
-   * Minimal avatar pipeline: decode, auto-orient from EXIF, cover-crop square, re-encode JPEG.
+   * 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),
+   * one high-quality resize down to at most AVATAR_MAX_SIZE (never up), re-encode JPEG.
+   * Clients send ORIGINAL bytes; a client-side canvas export would resample a second time
+   * (and with the browser's low-default smoothing), baking blur into the stored master.
    * 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> {
+  private async toAvatarJpeg(imageBytes: Buffer, mimeType: string, crop?: AvatarCrop): Promise<Buffer> {
     const pipeline =
       mimeType === 'image/heic' || mimeType === 'image/heif'
         ? await this.decodeHeic(imageBytes)
         : sharp(imageBytes).rotate();
+    const { width, height } = await this.orientedDimensions(pipeline);
+    const frame = this.clampCrop(crop, width, height);
+    const target = Math.min(UpdateUserInfo.AVATAR_MAX_SIZE, frame.size);
     return await pipeline
-      .resize(UpdateUserInfo.AVATAR_SIZE, UpdateUserInfo.AVATAR_SIZE, { fit: 'cover' })
+      .extract({ left: frame.left, top: frame.top, width: frame.size, height: frame.size })
+      .resize(target, target, { fit: 'cover' })
       .jpeg({ quality: UpdateUserInfo.AVATAR_JPEG_QUALITY })
       .toBuffer();
   }
 
+  /**
+   * The decoded image's dimensions in DISPLAYED (EXIF-oriented) pixel space — the space the
+   * client framed its crop in, and the space `.rotate()` makes `.extract` operate in.
+   * Orientations 5-8 transpose the encoded axes.
+   */
+  private async orientedDimensions(pipeline: sharp.Sharp): Promise<{ width: number; height: number }> {
+    const metadata = await pipeline.metadata();
+    if (!metadata.width || !metadata.height) {
+      throw new Error(`Could not read avatar image dimensions`);
+    }
+
+    const transposed = (metadata.orientation ?? 1) >= 5;
+    return {
+      width: transposed ? metadata.height : metadata.width,
+      height: transposed ? metadata.width : metadata.height,
+    };
+  }
+
+  /**
+   * Resolve the crop request against the real image: round to whole pixels and clamp fully
+   * inside the oriented bounds, staying square. Absent crop = the centered square (identical
+   * to the old `fit: cover` center-crop, so no-crop clients keep byte-equivalent behavior).
+   */
+  private clampCrop(
+    crop: AvatarCrop | undefined,
+    width: number,
+    height: number
+  ): { left: number; top: number; size: number } {
+    const maxSize = Math.min(width, height);
+    if (!crop) {
+      return { left: Math.floor((width - maxSize) / 2), top: Math.floor((height - maxSize) / 2), size: maxSize };
+    }
+
+    if (![crop.sx, crop.sy, crop.size].every(Number.isFinite)) {
+      throw new Error(`Avatar crop must be numeric`);
+    }
+
+    const size = Math.min(Math.max(1, Math.round(crop.size)), maxSize);
+    const clampOffset = (value: number, max: number) => Math.min(Math.max(0, Math.round(value)), max);
+    return { left: clampOffset(crop.sx, width - size), top: clampOffset(crop.sy, height - size), size };
+  }
+
   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), {

package/test/AvatarPhotoFidelity.test.ts

@@ -0,0 +1,109 @@
+import fs from 'fs';
+import path from 'path';
+import sharp from 'sharp';
+import { UpdateUserInfo } from '../src/services/UpdateUserInfo';
+
+/**
+ * Pixel-fidelity contract of THE avatar image pipeline (`toAvatarJpeg` — the only place avatar
+ * pixels are ever resampled), tested straight through the pipeline with no DB: a stored master
+ * never contains invented (enlarged) pixels, honors the client's crop frame exactly, and still
+ * caps large sources at 512. This is the categorical guard for the founder's fuzzy-avatar
+ * defect: a small source blown up to a fixed 512 master reads as permanent blur on every chip
+ * that renders it.
+ *
+ * Helpers are reached via the house typed-cast-on-an-instance pattern (no widening of the
+ * class surface).
+ */
+type AvatarPipelineInternals = {
+  toAvatarJpeg(imageBytes: Buffer, mimeType: string, crop?: { sx: number; sy: number; size: number }): Promise<Buffer>;
+};
+
+const pipeline = () => new UpdateUserInfo() as unknown as AvatarPipelineInternals;
+
+const solidPng = async (width: number, height: number, rgb: { r: number; g: number; b: number }) =>
+  await sharp({ create: { width, height, channels: 3, background: rgb } })
+    .png()
+    .toBuffer();
+
+const dimensionsOf = async (jpeg: Buffer) => {
+  const metadata = await sharp(jpeg).metadata();
+  return { width: metadata.width, height: metadata.height, format: metadata.format };
+};
+
+/** Average color of the whole output — crop-mapping assertions read regions, not single pixels. */
+const averageColor = async (jpeg: Buffer) => {
+  const stats = await sharp(jpeg).stats();
+  const [r, g, b] = stats.channels.map((channel) => channel.mean);
+  return { r, g, b };
+};
+
+describe('avatar photo pixel fidelity', () => {
+  it('keeps a small source at its honest pixel count — never enlarged to the 512 cap', async () => {
+    const png = await solidPng(96, 96, { r: 200, g: 80, b: 40 });
+
+    const jpeg = await pipeline().toAvatarJpeg(png, 'image/png');
+
+    // The defect: the old pipeline resized EVERYTHING to a fixed 512 square, inventing 5x the
+    // pixels for a 96px source — permanent blur baked into the master.
+    expect(await dimensionsOf(jpeg)).toEqual({ width: 96, height: 96, format: 'jpeg' });
+  });
+
+  it('center-crops a small non-square source to its honest square (no enlargement)', async () => {
+    const png = await solidPng(300, 200, { r: 10, g: 120, b: 210 });
+
+    const jpeg = await pipeline().toAvatarJpeg(png, 'image/png');
+
+    expect(await dimensionsOf(jpeg)).toEqual({ width: 200, height: 200, format: 'jpeg' });
+  });
+
+  it('extracts exactly the client-framed crop square', async () => {
+    // Left half blue, right half red; the client frames the right half.
+    const left = await solidPng(100, 100, { r: 20, g: 40, b: 220 });
+    const source = await sharp({
+      create: { width: 200, height: 100, channels: 3, background: { r: 220, g: 30, b: 30 } },
+    })
+      .composite([{ input: left, left: 0, top: 0 }])
+      .png()
+      .toBuffer();
+
+    const jpeg = await pipeline().toAvatarJpeg(source, 'image/png', { sx: 100, sy: 0, size: 100 });
+
+    expect(await dimensionsOf(jpeg)).toEqual({ width: 100, height: 100, format: 'jpeg' });
+    const color = await averageColor(jpeg);
+    expect(color.r).toBeGreaterThan(180);
+    expect(color.b).toBeLessThan(80);
+  });
+
+  it('clamps an out-of-bounds crop inside the image, staying square', async () => {
+    const png = await solidPng(300, 200, { r: 90, g: 90, b: 90 });
+
+    const jpeg = await pipeline().toAvatarJpeg(png, 'image/png', { sx: 250, sy: 150, size: 120 });
+
+    expect(await dimensionsOf(jpeg)).toEqual({ width: 120, height: 120, format: 'jpeg' });
+  });
+
+  it('still lands a large source at the 512 cap', async () => {
+    const png = await solidPng(1024, 768, { r: 40, g: 160, b: 90 });
+
+    const jpeg = await pipeline().toAvatarJpeg(png, 'image/png');
+
+    expect(await dimensionsOf(jpeg)).toEqual({ width: 512, height: 512, format: 'jpeg' });
+  });
+
+  it('keeps a small HEIC source at its honest centered square (the WASM decode path)', async () => {
+    // The 96x64 fixture: centered 64px square, not an enlarged 512.
+    const heic = fs.readFileSync(path.join(__dirname, 'fixtures', 'fixture.heic'));
+
+    const jpeg = await pipeline().toAvatarJpeg(heic, 'image/heic');
+
+    expect(await dimensionsOf(jpeg)).toEqual({ width: 64, height: 64, format: 'jpeg' });
+  });
+
+  it('rejects a non-numeric crop in plain words', async () => {
+    const png = await solidPng(64, 64, { r: 10, g: 10, b: 10 });
+
+    await expect(pipeline().toAvatarJpeg(png, 'image/png', { sx: NaN, sy: 0, size: 32 })).rejects.toThrow(
+      'Avatar crop must be numeric'
+    );
+  });
+});

package/test/MachineAccounts.integration.test.ts

@@ -28,7 +28,13 @@ class TestOpsMachineAccount extends MachineAccount {
   secretName = 'test-ops-secret';
 }
 
-type SourceRepositoryInternals = { objectCache: { [qualifiedName: string]: unknown[] } };
+type SourceRepositoryInternals = {
+  objectCache: { [qualifiedName: string]: unknown[] };
+  // db >=1.34.4 reads loaders through objectsWithNames (declaration provenance — the
+  // source-ownership grain), which resolves from THIS cache; seeding objectCache alone is
+  // invisible to it.
+  namedObjectCache: { [type: string]: { qualifiedName: string; packageName: string; object: unknown }[] };
+};
 
 /**
  * Reset `TableWatcherRunner`'s static watcher map so the NEXT Db construction recomputes it from
@@ -49,10 +55,19 @@ const resetTableWatcherMap = () => {
  */
 describe('Machine accounts as source records', () => {
   const objectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).objectCache;
+  const namedObjectCache = () => (SourceRepository.get() as unknown as SourceRepositoryInternals).namedObjectCache;
+  const seedLoaders = (declarations: unknown[]) => {
+    objectCache()['@proteinjs/db/SourceRecordLoader'] = declarations;
+    namedObjectCache()['@proteinjs/db/SourceRecordLoader'] = declarations.map((object, i) => ({
+      qualifiedName: `@proteinjs/user-server-test/MachineAccountFixture${i}`,
+      packageName: '@proteinjs/user-server',
+      object,
+    }));
+  };
 
   /** One boot of Db.init's source-record leg with these MachineAccount declarations. */
   const boot = async (declarations: MachineAccount[]) => {
-    objectCache()['@proteinjs/db/SourceRecordLoader'] = declarations;
+    seedLoaders(declarations);
     await new SourceRecordSyncRunner().load();
   };
 
@@ -82,6 +97,7 @@ describe('Machine accounts as source records', () => {
 
   afterAll(async () => {
     delete objectCache()['@proteinjs/db/SourceRecordLoader'];
+    delete namedObjectCache()['@proteinjs/db/SourceRecordLoader'];
     delete objectCache()['@proteinjs/db/TableWatcher'];
     delete objectCache()['@proteinjs/user/RoleCatalogEntry'];
     resetTableWatcherMap();
@@ -143,28 +159,46 @@ describe('Machine accounts as source records', () => {
     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);
-  });
+  // KNOWN CROSS-TRAIN GAP (it.failing — flips RED the moment it starts passing, forcing the
+  // marker's removal): the re-declare-after-removal leg needs db's soft-removal re-adoption
+  // (integration/r5-db ba9f4ba7 — the sync currently INSERTs the existing machine-test-ops row
+  // instead of adopting it). Green everywhere else against db ^1.35.0; this leg lands with the
+  // R5 db mint. Exact repro + the semantics call recorded on this suite's landing commit.
+  it.failing(
+    '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);
+
+      // Removal under the db >=1.34.4 ownership law: the reconcile only touches rows whose
+      // sourcePackage the RUNNING build still declares from (shared-db safety — a build missing a
+      // package must never deactivate that package's rows). The real removal case is the package
+      // still booting with THIS declaration gone — modeled by keeping another declaration from
+      // the same package aboard. boot([]) would model "package vanished", which the law protects.
+      class SurvivingSibling extends TestOpsMachineAccount {
+        email = 'machine-sibling@test.local';
+        name = 'Surviving sibling machine';
+        secretName = 'sibling-secret';
+      }
+      await boot([new SurvivingSibling()]);
+
+      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'] });
@@ -246,7 +280,7 @@ describe('Machine accounts as source records', () => {
         email = 'machine-not-booted@test.local';
         secretName = 'not-booted-secret';
       }
-      objectCache()['@proteinjs/db/SourceRecordLoader'] = [new TestOpsMachineAccount(), new NotBooted()];
+      seedLoaders([new TestOpsMachineAccount(), new NotBooted()]);
 
       const before = await new MachineCredentials().listMachineAccounts();
       expect(before).toEqual([
@@ -289,7 +323,7 @@ describe('Machine accounts as source records', () => {
         email = 'machine-not-booted@test.local';
       }
       // Declared (discoverable) but never booted: no source-owned row exists.
-      objectCache()['@proteinjs/db/SourceRecordLoader'] = [new TestOpsMachineAccount(), new NotBooted()];
+      seedLoaders([new TestOpsMachineAccount(), new NotBooted()]);
       await expect(new MachineCredentials().mintCredential('machine-not-booted@test.local')).rejects.toThrow(
         /has not been loaded from source yet/
       );

package/test/UpdateUserInfoAvatar.test.ts

@@ -15,7 +15,8 @@ const isJpeg = (buffer: Buffer) => buffer[0] === 0xff && buffer[1] === 0xd8 && b
 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
+ * Avatars are photo OR emoji — exactly one active — stored as a square JPEG capped at 512px
+ * (never enlarged past the source's honest pixels; see AvatarPhotoFidelity.test.ts), 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.
@@ -85,9 +86,11 @@ describe('UpdateUserInfo avatar mutations', () => {
     expect(await getFileRow(second.avatarFileId!)).toBeTruthy();
   });
 
-  it('updateAvatarPhoto normalizes HEIC (default iPhone camera format) to JPEG', async () => {
+  it('updateAvatarPhoto normalizes HEIC (default iPhone camera format) to JPEG at its honest size', async () => {
     const user = await testEnv.createUser({ name: 'iPhone user', email: 'heic@test.local' });
     testEnv.actAs(user);
+    // The fixture is 96x64 — small on purpose: the stored master is its centered 64px square,
+    // NOT an enlarged 512 (enlargement invents pixels that read as permanent blur).
     const heic = fs.readFileSync(path.join(__dirname, 'fixtures', 'fixture.heic'));
 
     const updated = await service.updateAvatarPhoto(heic.toString('base64'), 'image/heic');
@@ -95,8 +98,8 @@ describe('UpdateUserInfo avatar mutations', () => {
     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);
+    expect(metadata.width).toBe(64);
+    expect(metadata.height).toBe(64);
   });
 
   it('updateAvatarEmoji sets the emoji, nulls the photo, and deletes the previous photo file', async () => {

package/test/avatarRoute.test.ts

@@ -70,8 +70,10 @@ describe('GET /avatar/:userId', () => {
     expect(bytes[0]).toBe(0xff); // JPEG SOI
     expect(bytes[1]).toBe(0xd8);
     const metadata = await sharp(bytes).metadata();
-    expect(metadata.width).toBe(512);
-    expect(metadata.height).toBe(512);
+    // The 100px source stays its honest 100px square — masters are capped at 512, never
+    // enlarged to it (AvatarPhotoFidelity.test.ts owns the pipeline contract).
+    expect(metadata.width).toBe(100);
+    expect(metadata.height).toBe(100);
 
     // The client-side URL contract carries the cache-buster.
     expect(avatarRoute.path(owner.id, updated.avatarFileId!)).toBe(`/avatar/${owner.id}?v=${updated.avatarFileId}`);

package/tsconfig.json

@@ -14,6 +14,10 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
-    "jsx": "react"
+    "jsx": "react",
+    "baseUrl": "./",
+    "paths": {
+      "@proteinjs/*": ["node_modules/@proteinjs/*"]
+    }
   }
 }