@lenne.tech/nest-server 11.32.4 → 11.33.1

package/src/server/modules/user/user.model.ts

@@ -6,6 +6,7 @@ import { Document, Schema } from 'mongoose';
 import { Restricted } from '../../../core/common/decorators/restricted.decorator';
 import { Translatable } from '../../../core/common/decorators/translatable.decorator';
 import { UnifiedField } from '../../../core/common/decorators/unified-field.decorator';
+import { ProcessType } from '../../../core/common/enums/process-type.enum';
 import { RoleEnum } from '../../../core/common/enums/role.enum';
 import { CoreUserModel } from '../../../core/modules/user/core-user.model';
 import { PersistenceModel } from '../../common/models/persistence.model';
@@ -24,13 +25,18 @@ export class User extends CoreUserModel implements PersistenceModel {
   // ===================================================================================================================
 
   /**
-   * URL to avatar file of the user
+   * ID of the user's avatar file, assigned by POST /avatar/upload
+   *
+   * Readable by everyone, writable by NO ONE through a generic update: it is a file id the
+   * server hands out, and the avatar endpoint deletes the file the previous value points at.
+   * While it was freely writable, a signed-in user could put someone else's file id here and
+   * have the next upload delete that file for them.
    */
   @UnifiedField({
-    description: 'URL to avatar file of the user',
+    description: "ID of the user's avatar file (set via POST /avatar/upload)",
     isOptional: true,
     mongoose: true,
-    roles: RoleEnum.S_EVERYONE,
+    roles: [{ processType: ProcessType.INPUT, roles: RoleEnum.S_NO_ONE }],
   })
   avatar: string = undefined;
 

package/src/server/modules/user/user.module.ts

@@ -1,8 +1,11 @@
-import { Module } from '@nestjs/common';
+import { forwardRef, Module } from '@nestjs/common';
 import { MongooseModule } from '@nestjs/mongoose';
 import { PubSub } from 'graphql-subscriptions';
 
 import { ConfigService } from '../../../core/common/services/config.service';
+import { CoreRedisPubSub } from '../../../core/common/services/core-redis-pubsub';
+import { CoreRedisService } from '../../../core/common/services/core-redis.service';
+import { FileModule } from '../file/file.module';
 import { AvatarController } from './avatar.controller';
 import { UserController } from './user.controller';
 import { User, UserSchema } from './user.model';
@@ -15,7 +18,9 @@ import { UserService } from './user.service';
 @Module({
   controllers: [AvatarController, UserController],
   exports: [MongooseModule, UserResolver, UserService, 'USER_CLASS'],
-  imports: [MongooseModule.forFeature([{ name: User.name, schema: UserSchema }])],
+  // forwardRef: FileModule already imports UserModule, and the avatar upload now
+  // needs FileService to reach the central storage — so the two reference each other.
+  imports: [MongooseModule.forFeature([{ name: User.name, schema: UserSchema }]), forwardRef(() => FileModule)],
   providers: [
     UserResolver,
     ConfigService,
@@ -25,8 +30,12 @@ import { UserService } from './user.service';
       useValue: User,
     },
     {
+      // Redis-backed when Redis is enabled (subscriptions reach all replicas),
+      // process-local in-memory PubSub otherwise
       provide: 'PUB_SUB',
-      useValue: new PubSub(),
+      useFactory: (redisService?: CoreRedisService) =>
+        redisService?.enabled ? new CoreRedisPubSub(redisService) : new PubSub(),
+      inject: [{ optional: true, token: CoreRedisService }],
     },
   ],
 })

package/src/server/modules/user/user.service.ts

@@ -1,6 +1,5 @@
 import { Inject, Injectable, Optional, UnauthorizedException, UnprocessableEntityException } from '@nestjs/common';
 import { InjectModel } from '@nestjs/mongoose';
-import fs = require('fs');
 import { PubSub } from 'graphql-subscriptions';
 import { Model } from 'mongoose';
 
@@ -94,10 +93,22 @@ export class UserService extends CoreUserService<User, UserInput, UserCreateInpu
   }
 
   /**
-   * Set avatar image
+   * Point the user's avatar at an already-stored file
+   *
+   * Takes the file ID rather than the upload itself: the bytes belong in the central
+   * file storage (GridFS/S3) so every replica can serve them, and putting that
+   * dependency here is not possible — `UserService` is instantiated by
+   * `CoreAuthModule`, which knows nothing about the project's `FileModule`.
+   * `AvatarController` therefore stores the file and calls this with the resulting id.
+   *
+   * @returns the PREVIOUS avatar id, so the caller can delete the orphaned file
    */
-  async setAvatar(file: Express.Multer.File, user: User): Promise<string> {
-    const dbUser = await this.mainDbModel.findOne({ id: user.id }).exec();
+  async setAvatar(avatarId: string, user: User): Promise<string> {
+    // `findById`, not `findOne({ id })`: `id` is a Mongoose virtual, so it exists on the
+    // document but not in MongoDB — a filter on it matches nothing and every call ended in
+    // "session user no longer exists". Broken since the Mongoose migration and never noticed,
+    // because no test covers the avatar endpoint.
+    const dbUser = await this.mainDbModel.findById(user.id).exec();
     // Check user: the token is valid but the account no longer exists, so the session really is
     // invalid — 401 is right here. (A permission error would have to be 403, see accessDeniedException.)
     if (!dbUser) {
@@ -105,25 +116,17 @@ export class UserService extends CoreUserService<User, UserInput, UserCreateInpu
     }
 
     // Check file
-    if (!file) {
+    if (!avatarId) {
       throw new UnprocessableEntityException('Missing avatar file');
     }
 
-    // Remove old avatar image
-    if (user.avatar) {
-      fs.unlink(`${this.configService.configFastButReadOnly.staticAssets.path}/avatars/${user.avatar}`, (err) => {
-        if (err) {
-          console.error(err);
-        }
-      });
-    }
+    const previousAvatar = dbUser.avatar;
 
-    // Update user
-    dbUser.avatar = file.filename;
+    // The avatar is referenced by file id and served via GET /files/id/:id
+    dbUser.avatar = avatarId;
 
     await dbUser.save();
 
-    // Return user
-    return file.filename;
+    return previousAvatar;
   }
 }

package/src/test/README.md

@@ -181,10 +181,15 @@ await testHelper.rest('/protected-endpoint', {
 Download a file and return the response with a `data` string property for content comparison.
 
 ```typescript
-// No authentication
-const res = await testHelper.download('/files/id/abc123');
+// The core download routes are gated by `file.downloadRoles` (default ADMIN),
+// so a request without credentials answers 401 — pass a token or a session cookie.
+const res = await testHelper.download('/files/id/abc123', { token: adminToken });
 expect(res.statusCode).toEqual(200);
 expect(res.data).toEqual('file content');
+
+// Without credentials:
+const anonymous = await testHelper.download('/files/id/abc123');
+expect(anonymous.statusCode).toEqual(401);
 ```
 
 ### `downloadBuffer(url, tokenOrOptions?)`

package/src/core/common/helpers/file.helper.spec.ts

@@ -1,145 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { IMAGE_UPLOAD_ALLOW_LIST, multerFileFilter, multerOptionsForImageUpload, UploadAllowList } from './file.helper';
-
-/**
- * The filter used to be ONE unanchored `RegExp`, `.test()`ed against the
- * mimetype AND the extension. `.test()` searches for a substring, so every
- * alternative matched anywhere inside either value — `te?xt` matched the "text"
- * in `text/html`, and a file named `x.txt` sent as `text/html` passed both
- * halves of a filter documented as "no html".
- *
- * Consumer projects hit this for real. The tests below therefore cover three
- * things: the exact-matching allow-list, that the legacy `RegExp` form still
- * works, and — the point of the fix — that scriptable types are rejected on
- * BOTH paths, so an expression that already exists in a consumer project is
- * safe without being rewritten.
- */
-
-/** Run a filter the way multer does and report its verdict. */
-function verdict(
-  filter: ReturnType<typeof multerFileFilter>,
-  mimetype: string,
-  originalname: string,
-): { accepted: boolean; error?: string } {
-  let accepted = false;
-  let error: string | undefined;
-  filter({}, { mimetype, originalname }, (err: any, result?: boolean) => {
-    if (err) {
-      error = err instanceof Error ? err.message : String(err);
-    }
-    accepted = result === true;
-  });
-  return { accepted, error };
-}
-
-const DOCUMENTS: UploadAllowList = {
-  extensions: ['.csv', '.pdf', '.txt'],
-  mimeTypes: ['application/pdf', 'text/csv', 'text/plain'],
-};
-
-describe('multerFileFilter', () => {
-  describe('allow-list form', () => {
-    it('accepts a mimetype and extension that are both on the list', () => {
-      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain', 'notes.txt').accepted).toBe(true);
-      expect(verdict(multerFileFilter(DOCUMENTS), 'application/pdf', 'report.pdf').accepted).toBe(true);
-    });
-
-    it('rejects as soon as one half is missing from the list', () => {
-      expect(verdict(multerFileFilter(DOCUMENTS), 'application/x-msdownload', 'setup.pdf').accepted).toBe(false);
-      expect(verdict(multerFileFilter(DOCUMENTS), 'application/pdf', 'setup.exe').accepted).toBe(false);
-    });
-
-    it('matches whole values, never substrings', () => {
-      // Only an unanchored matcher would let these through.
-      expect(verdict(multerFileFilter(DOCUMENTS), 'evil/text-plain', 'notes.txt').accepted).toBe(false);
-      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain', 'notes.txtx').accepted).toBe(false);
-    });
-
-    it('ignores mimetype parameters and casing', () => {
-      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain; charset=utf-8', 'notes.txt').accepted).toBe(true);
-      expect(verdict(multerFileFilter(IMAGE_UPLOAD_ALLOW_LIST), 'IMAGE/PNG', 'PHOTO.PNG').accepted).toBe(true);
-    });
-
-    it('rejects a file without an extension', () => {
-      expect(verdict(multerFileFilter(DOCUMENTS), 'text/plain', 'README').accepted).toBe(false);
-    });
-  });
-
-  describe('scriptable types are rejected on BOTH forms', () => {
-    // This is what makes an ALREADY EXISTING consumer expression safe.
-    const legacy = /jpeg|jpg|png|te?xt|csv/;
-
-    it('rejects text/html even when the expression matches it as a substring', () => {
-      const result = verdict(multerFileFilter(legacy), 'text/html', 'invoice.txt');
-      expect(result.accepted).toBe(false);
-      expect(result.error).toMatch(/may execute as script/);
-    });
-
-    it('rejects text/xml and application/xhtml+xml', () => {
-      expect(verdict(multerFileFilter(legacy), 'text/xml', 'notes.txt').accepted).toBe(false);
-      expect(verdict(multerFileFilter(legacy), 'application/xhtml+xml', 'notes.txt').accepted).toBe(false);
-    });
-
-    it('rejects SVG on the image default', () => {
-      expect(verdict(multerFileFilter(), 'image/svg+xml', 'logo.svg').accepted).toBe(false);
-    });
-
-    it('rejects a scriptable EXTENSION even under a harmless mimetype', () => {
-      expect(verdict(multerFileFilter(legacy), 'text/plain', 'payload.html').accepted).toBe(false);
-      expect(verdict(multerFileFilter(legacy), 'image/png', 'payload.svg').accepted).toBe(false);
-    });
-
-    it('allows them only when the caller opts in explicitly', () => {
-      const filter = multerFileFilter(
-        { extensions: ['.svg'], mimeTypes: ['image/svg+xml'] },
-        {
-          allowScriptableTypes: true,
-        },
-      );
-      expect(verdict(filter, 'image/svg+xml', 'logo.svg').accepted).toBe(true);
-    });
-  });
-
-  describe('legacy RegExp form stays usable', () => {
-    it('still accepts what it accepted before', () => {
-      const filter = multerFileFilter(/jpeg|jpg|png/);
-      expect(verdict(filter, 'image/jpeg', 'photo.jpg').accepted).toBe(true);
-      expect(verdict(filter, 'image/png', 'photo.png').accepted).toBe(true);
-      expect(verdict(filter, 'application/pdf', 'report.pdf').accepted).toBe(false);
-    });
-  });
-
-  describe('rejection reporting', () => {
-    it('reports a real Error, not a bare string', () => {
-      let received: unknown;
-      multerFileFilter(DOCUMENTS)({}, { mimetype: 'application/x-foo', originalname: 'x.foo' }, (err: unknown) => {
-        received = err;
-      });
-      // A bare string leaves multer with an "error" that has no `message`,
-      // which NestJS's transformException cannot map to a 4xx.
-      expect(received).toBeInstanceOf(Error);
-    });
-  });
-});
-
-describe('multerOptionsForImageUpload', () => {
-  it('applies the image allow-list by default', () => {
-    const filter = multerOptionsForImageUpload({}).fileFilter!;
-    expect(verdict(filter as any, 'image/png', 'a.png').accepted).toBe(true);
-    expect(verdict(filter as any, 'image/svg+xml', 'a.svg').accepted).toBe(false);
-  });
-
-  it('still installs a filter when fileTypeRegex is explicitly undefined', () => {
-    // Previously this disabled filtering entirely — on a helper named
-    // "ImageUpload". Safe-by-default instead; see the migration guide.
-    const filter = multerOptionsForImageUpload({ fileTypeRegex: undefined }).fileFilter;
-    expect(filter).toBeDefined();
-    expect(verdict(filter as any, 'text/html', 'a.txt').accepted).toBe(false);
-  });
-
-  it('honours an explicit allowList', () => {
-    const filter = multerOptionsForImageUpload({ allowList: DOCUMENTS }).fileFilter!;
-    expect(verdict(filter as any, 'application/pdf', 'report.pdf').accepted).toBe(true);
-  });
-});

package/src/core/common/helpers/logging.helper.spec.ts

@@ -1,61 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { redactSensitiveText } from './logging.helper';
-
-describe('redactSensitiveText', () => {
-  it('redacts JWTs appearing anywhere in a line', () => {
-    const jwt = 'eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U';
-    const out = redactSensitiveText(`token issued: ${jwt} done`);
-
-    expect(out).not.toContain(jwt);
-    expect(out).toContain('token issued:');
-    expect(out).toContain('done');
-  });
-
-  it('redacts Authorization Bearer values', () => {
-    const out = redactSensitiveText('Authorization: Bearer abcdef1234567890secret');
-
-    expect(out).not.toContain('abcdef1234567890secret');
-    expect(out.toLowerCase()).toContain('authorization');
-  });
-
-  it('redacts key/value secrets regardless of separator or quoting', () => {
-    expect(redactSensitiveText('password=SuperSecret123')).not.toContain('SuperSecret123');
-    expect(redactSensitiveText('token: "abcd1234efgh"')).not.toContain('abcd1234efgh');
-    expect(redactSensitiveText("apiKey='pk_live_9999'")).not.toContain('pk_live_9999');
-    expect(redactSensitiveText('client_secret=verySecretValue')).not.toContain('verySecretValue');
-  });
-
-  it('redacts cookie headers', () => {
-    const out = redactSensitiveText('cookie: session=abc123; other=xyz789');
-
-    expect(out).not.toContain('abc123');
-    expect(out).not.toContain('xyz789');
-  });
-
-  it('redacts reset/verification tokens carried as a URL PATH segment (not key=value)', () => {
-    const link = 'https://app.example.com/verify/AbCdEf0123456789XyZtoken please click';
-    const out = redactSensitiveText(link);
-    expect(out).not.toContain('AbCdEf0123456789XyZtoken');
-    expect(out).toContain('/verify/');
-    // also for reset / set-password style links
-    expect(redactSensitiveText('/reset/SUPERSECRETVALUE1234567890')).not.toContain('SUPERSECRETVALUE1234567890');
-    expect(redactSensitiveText('/set-password/ZZZ1112223334445556667')).not.toContain('ZZZ1112223334445556667');
-  });
-
-  it('leaves harmless short path segments untouched', () => {
-    // Only long token-like segments (>= 16 chars) are masked — normal routes stay readable.
-    const text = 'GET /verify/email done';
-    expect(redactSensitiveText(text)).toBe(text);
-  });
-
-  it('leaves harmless text untouched', () => {
-    const text = 'User signed in successfully with id 507f1f77bcf86cd799439011';
-    expect(redactSensitiveText(text)).toBe(text);
-  });
-
-  it('handles empty / non-secret input without throwing', () => {
-    expect(redactSensitiveText('')).toBe('');
-    expect(redactSensitiveText('plain message')).toBe('plain message');
-  });
-});

package/src/core/common/helpers/process-diagnostics.helper.spec.ts

@@ -1,310 +0,0 @@
-import { EventEmitter } from 'node:events';
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import { handleFatalBootstrapError, installProcessDiagnostics } from './process-diagnostics.helper';
-
-// `vi.spyOn(fs, 'writeSync')` cannot work here — an ESM module namespace is not configurable, so
-// the property cannot be redefined. Mocking the module is the only way to observe the default
-// sink, and the helper imports nothing else from `node:fs`.
-const { writeSyncMock } = vi.hoisted(() => ({ writeSyncMock: vi.fn<(fd: number, data: string) => number>() }));
-vi.mock('node:fs', () => ({ writeSync: writeSyncMock }));
-
-/**
- * Regression guard for the "silent exit" class of failures: a Node API under a ts-node dev
- * runner can die printing nothing but `app crashed` — no stacktrace, which reads like a
- * product bug and costs long, misdirected debugging sessions. The diagnostics helper makes
- * the exit reason visible — a rejected fire-and-forget promise no longer takes the server
- * down, an uncaught exception is logged with a clear marker before it exits, and an EXTERNAL
- * termination signal (another tool's pkill, `lt dev down`, an OS OOM SIGTERM, Ctrl-C) is
- * logged as such instead of masquerading as an in-process crash.
- *
- * The installer is tested against an injected EventEmitter so the real process (and the
- * Vitest runner it lives in) is never signalled or exited.
- *
- * Repo-wiring assertions (src/main.ts, src/index.ts, nodemon.json) deliberately live in
- * `tests/unit/process-diagnostics-wiring.spec.ts`, NOT here: this file ships inside `src/core/`
- * and is copied verbatim into vendor-mode consumer projects, where those repo-root paths do not
- * exist. Keeping this spec free of `process.cwd()` is what makes it portable.
- */
-function setup(
-  preRegister?: Partial<Record<string, () => void>>,
-  options?: Parameters<typeof installProcessDiagnostics>[0],
-) {
-  const target = new EventEmitter();
-  target.setMaxListeners(50);
-  const errors: string[] = [];
-  const warnings: string[] = [];
-  const logger = {
-    error: (message: string) => errors.push(message),
-    warn: (message: string) => warnings.push(message),
-  };
-  const exit = vi.fn();
-  const reraise = vi.fn();
-  if (preRegister) {
-    for (const [event, fn] of Object.entries(preRegister)) {
-      target.on(event, fn);
-    }
-  }
-  installProcessDiagnostics({ exit, logger, reraise, target, ...options });
-  return { errors, exit, reraise, target, warnings };
-}
-
-afterEach(() => {
-  vi.restoreAllMocks();
-  vi.useRealTimers();
-});
-
-describe('installProcessDiagnostics', () => {
-  it('logs an unhandled rejection but keeps the process alive', () => {
-    const { exit, target, warnings } = setup();
-    target.emit('unhandledRejection', new Error('SMTP down'));
-    expect(warnings.some((line) => line.includes('[unhandledRejection]') && line.includes('SMTP down'))).toBe(true);
-    expect(exit).not.toHaveBeenCalled();
-  });
-
-  it('routes an unhandled rejection to the NON-blocking sink', () => {
-    // An unhandled rejection can fire once per request while the server keeps serving. A
-    // synchronous write would block the whole event loop until stderr drains, so this path must
-    // use `warn` (async) and never `error` (sync). Nothing is terminating, so there is no
-    // last-gasp guarantee worth blocking for.
-    const { errors, target, warnings } = setup();
-    target.emit('unhandledRejection', new Error('per-request failure'));
-    expect(warnings).toHaveLength(1);
-    expect(errors).toHaveLength(0);
-  });
-
-  it('formats a non-Error rejection reason via String()', () => {
-    const { target, warnings } = setup();
-    target.emit('unhandledRejection', 'plain string reason');
-    expect(warnings.some((line) => line.includes('[unhandledRejection]') && line.includes('plain string reason'))).toBe(
-      true,
-    );
-  });
-
-  it('exits on an unhandled rejection when onUnhandledRejection is "exit"', () => {
-    // Restores Node >= 15's own `--unhandled-rejections=throw` default for deployments that
-    // prefer a clean restart over serving from an unknown state.
-    const { errors, exit, target } = setup(undefined, { onUnhandledRejection: 'exit' });
-    target.emit('unhandledRejection', new Error('inconsistent state'));
-    expect(errors.some((line) => line.includes('[unhandledRejection]'))).toBe(true);
-    expect(exit).toHaveBeenCalledWith(1);
-  });
-
-  it('logs an uncaught exception with a marker and exits with code 1', () => {
-    const { errors, exit, target } = setup();
-    target.emit('uncaughtException', new Error('boom'));
-    expect(errors.some((line) => line.includes('[uncaughtException]') && line.includes('boom'))).toBe(true);
-    expect(exit).toHaveBeenCalledWith(1);
-  });
-
-  it('does NOT print the error message twice', () => {
-    // `error.stack` already begins with `${name}: ${message}`. Prefixing the message again put the
-    // same line in the output twice, which reads like two distinct failures.
-    const { errors, target } = setup();
-    const error = new Error('duplicated');
-    target.emit('uncaughtException', error);
-    const occurrences = errors[0].split('duplicated').length - 1;
-    expect(occurrences).toBe(1);
-  });
-
-  it('falls back to name + message when an Error carries no stack', () => {
-    const { errors, target } = setup();
-    const error = new Error('no stack here');
-    error.stack = undefined;
-    target.emit('uncaughtException', error);
-    expect(errors[0]).toContain('Error: no stack here');
-  });
-
-  it('does NOT register a process warning handler', () => {
-    // Node prints process warnings to stderr itself and adding a listener does not replace that —
-    // it appends a second, strictly worse copy (Node's own line carries the warning `name` and the
-    // `--trace-warnings` hint). Duplicating it doubles the volume on a path that fires during
-    // normal operation.
-    const { target } = setup();
-    expect(target.listenerCount('warning')).toBe(0);
-  });
-
-  it('logs a non-zero exit code', () => {
-    const { errors, target } = setup();
-    target.emit('exit', 143);
-    expect(errors.some((line) => line.includes('[exit]') && line.includes('143'))).toBe(true);
-  });
-
-  it('stays silent on a clean exit', () => {
-    // A clean exit is not a diagnostic. Logging it under every CLI script and every graceful
-    // shutdown trains readers to ignore the marker.
-    const { errors, target } = setup();
-    target.emit('exit', 0);
-    expect(errors).toHaveLength(0);
-  });
-
-  it('logs SIGTERM as external termination and re-raises it when it is the only listener', () => {
-    const { errors, exit, reraise, target } = setup();
-    target.emit('SIGTERM', 'SIGTERM');
-    expect(errors.some((line) => line.includes('[signal]') && line.includes('SIGTERM'))).toBe(true);
-    expect(reraise).toHaveBeenCalledWith('SIGTERM');
-    expect(exit).not.toHaveBeenCalled();
-    // The handler MUST remove itself before re-raising — otherwise the re-raised signal
-    // re-enters the same handler forever (infinite log-and-re-raise loop, never terminates).
-    expect(target.listenerCount('SIGTERM')).toBe(0);
-  });
-
-  it('logs SIGINT and re-raises it when it is the only listener', () => {
-    const { errors, reraise, target } = setup();
-    target.emit('SIGINT', 'SIGINT');
-    expect(errors.some((line) => line.includes('[signal]') && line.includes('SIGINT'))).toBe(true);
-    expect(reraise).toHaveBeenCalledWith('SIGINT');
-    expect(target.listenerCount('SIGINT')).toBe(0);
-  });
-
-  it.each(['SIGHUP', 'SIGQUIT'] as const)('labels %s as an external termination too', (signal) => {
-    // A closed terminal (SIGHUP) or a SIGQUIT from an orchestrator used to terminate unannotated,
-    // producing exactly the stackless death this helper exists to explain.
-    const { errors, reraise, target } = setup();
-    target.emit(signal, signal);
-    expect(errors.some((line) => line.includes('[signal]') && line.includes(signal))).toBe(true);
-    expect(reraise).toHaveBeenCalledWith(signal);
-  });
-
-  it('does NOT touch SIGUSR2', () => {
-    // nodemon restarts the app with SIGUSR2. Attaching a listener overrides its disposition, and
-    // labelling a restart is not worth changing how restarts behave.
-    const { target } = setup();
-    expect(target.listenerCount('SIGUSR2')).toBe(0);
-  });
-
-  it('does NOT re-raise a signal when a graceful-shutdown handler is also registered', () => {
-    // `app.enableShutdownHooks()` registers its own SIGTERM/SIGINT listener. Re-raising on top of
-    // it would kill the process mid-shutdown and defeat the graceful teardown.
-    const other = vi.fn();
-    const { errors, reraise, target } = setup({ SIGTERM: other }, { shutdownTimeoutMs: 0 });
-    target.emit('SIGTERM', 'SIGTERM');
-    expect(errors.some((line) => line.includes('[signal]'))).toBe(true);
-    expect(errors.some((line) => line.includes('another handler owns the shutdown'))).toBe(true);
-    expect(reraise).not.toHaveBeenCalled();
-  });
-
-  it('forces an exit when the co-listener never finishes the shutdown', () => {
-    // Abdicating unconditionally means a co-listener that never terminates makes SIGTERM a
-    // permanent no-op while the log line claims the process is going down — only SIGKILL would
-    // still work. The watchdog bounds that.
-    vi.useFakeTimers();
-    const { errors, exit, target } = setup({ SIGTERM: vi.fn() }, { shutdownTimeoutMs: 30_000 });
-    target.emit('SIGTERM', 'SIGTERM');
-    expect(exit).not.toHaveBeenCalled();
-    vi.advanceTimersByTime(30_000);
-    expect(errors.some((line) => line.includes('shutdown watchdog expired'))).toBe(true);
-    expect(exit).toHaveBeenCalledWith(1);
-  });
-
-  it('does not arm the watchdog when shutdownTimeoutMs is 0', () => {
-    vi.useFakeTimers();
-    const { exit, target } = setup({ SIGTERM: vi.fn() }, { shutdownTimeoutMs: 0 });
-    target.emit('SIGTERM', 'SIGTERM');
-    vi.advanceTimersByTime(120_000);
-    expect(exit).not.toHaveBeenCalled();
-  });
-
-  it('is idempotent — installing twice does not stack duplicate handlers', () => {
-    const target = new EventEmitter();
-    const logger = { error: () => undefined };
-    const exit = vi.fn();
-    const reraise = vi.fn();
-    installProcessDiagnostics({ exit, logger, reraise, target });
-    installProcessDiagnostics({ exit, logger, reraise, target });
-    expect(target.listenerCount('uncaughtException')).toBe(1);
-    expect(target.listenerCount('unhandledRejection')).toBe(1);
-    expect(target.listenerCount('SIGTERM')).toBe(1);
-    expect(target.listenerCount('SIGINT')).toBe(1);
-  });
-
-  it('falls back to the error sink when a custom logger provides no warn', () => {
-    const target = new EventEmitter();
-    const errors: string[] = [];
-    installProcessDiagnostics({
-      exit: vi.fn(),
-      logger: { error: (message: string) => errors.push(message) },
-      reraise: vi.fn(),
-      target,
-    });
-    target.emit('unhandledRejection', new Error('no warn sink'));
-    expect(errors.some((line) => line.includes('[unhandledRejection]'))).toBe(true);
-  });
-});
-
-describe('redaction and truncation', () => {
-  it('masks a JWT and truncates an oversized line', () => {
-    const target = new EventEmitter();
-    const warnings: string[] = [];
-    installProcessDiagnostics({
-      exit: vi.fn(),
-      logger: { error: () => undefined, warn: (message: string) => warnings.push(message) },
-      reraise: vi.fn(),
-      target,
-    });
-    const jwt = `eyJhbGciOiJIUzI1NiJ9.${'a'.repeat(40)}.${'b'.repeat(20)}`;
-    const error = new Error(`token=${jwt} ${'x'.repeat(30_000)}`);
-    error.stack = `Error: token=${jwt} ${'x'.repeat(30_000)}`;
-    target.emit('unhandledRejection', error);
-
-    expect(warnings).toHaveLength(1);
-    expect(warnings[0]).not.toContain(jwt);
-    expect(warnings[0]).toContain('[truncated]');
-    expect(warnings[0].length).toBeLessThan(20_000);
-  });
-});
-
-describe('defaultDiagnosticsLogger', () => {
-  it('writes synchronously to fd 2 so a last-gasp line cannot be truncated', () => {
-    // console.error is asynchronous on a pipe, so a line written immediately before process.exit()
-    // can be dropped — silently losing the very line this helper exists to emit.
-    writeSyncMock.mockReset();
-    writeSyncMock.mockReturnValue(0);
-    const target = new EventEmitter();
-    installProcessDiagnostics({ exit: vi.fn(), reraise: vi.fn(), target });
-    target.emit('uncaughtException', new Error('sync sink'));
-
-    expect(writeSyncMock).toHaveBeenCalled();
-    const [fd, payload] = writeSyncMock.mock.calls[0];
-    expect(fd).toBe(2);
-    expect(String(payload)).toContain('[uncaughtException]');
-  });
-
-  it('survives a broken stderr instead of escalating', () => {
-    // EBADF (fd 2 closed), EPIPE (reader exited) and EAGAIN (non-blocking pipe) all make writeSync
-    // throw. A throw raised INSIDE the uncaughtException handler makes Node exit 7 and print its
-    // own "throw inside handler" message — losing the original error entirely.
-    writeSyncMock.mockReset();
-    writeSyncMock.mockImplementation(() => {
-      throw Object.assign(new Error('EBADF: bad file descriptor'), { code: 'EBADF' });
-    });
-    const exit = vi.fn();
-    const target = new EventEmitter();
-    installProcessDiagnostics({ exit, reraise: vi.fn(), target });
-
-    expect(() => target.emit('uncaughtException', new Error('original failure'))).not.toThrow();
-    expect(exit).toHaveBeenCalledWith(1);
-  });
-});
-
-describe('handleFatalBootstrapError', () => {
-  it('logs a failed bootstrap with a marker and exits with code 1', () => {
-    const errors: string[] = [];
-    const logger = { error: (message: string) => errors.push(message) };
-    const exit = vi.fn();
-    handleFatalBootstrapError(new Error('listen EADDRINUSE: address already in use'), { exit, logger });
-    expect(errors.some((line) => line.includes('[bootstrap]') && line.includes('EADDRINUSE'))).toBe(true);
-    expect(exit).toHaveBeenCalledWith(1);
-  });
-
-  it('redacts secrets out of a startup error before logging it', () => {
-    // The documented motivating failures ("DB unreachable") carry connection strings.
-    const errors: string[] = [];
-    const exit = vi.fn();
-    handleFatalBootstrapError(new Error('connect failed: password=hunter2'), {
-      exit,
-      logger: { error: (message: string) => errors.push(message) },
-    });
-    expect(errors[0]).not.toContain('hunter2');
-  });
-});