@tumbaland/backend-core 1.22.0 → 1.24.0

package/src/entitlements/usage.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Integration tests against a real MongoDB, not mocks.
+ *
+ * `tickerPriceHistory.service.test.ts` reports 100% line coverage while mocking
+ * Mongoose entirely, and a real upsert bug survived it. Quota code has the same
+ * failure mode with worse consequences: a mocked `$inc` always looks correct,
+ * and a broken one either gives the product away or bills people for capacity
+ * they cannot use. The concurrency tests below are meaningless without a real
+ * server — they are the whole reason the atomic reserve is written the way it is.
+ */
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+import logger from '../logging/logger';
+import { UsageMeter, currentPeriod } from './UsageMeter';
+import { checkQuota, consumeQuota, getUsage, getUsageSnapshot, releaseQuota, setUsage } from './usage';
+import { Entitlements } from './types';
+import { UNLIMITED, normalizeLimits } from './definitions';
+
+jest.setTimeout(120_000);
+
+let mongod: MongoMemoryServer;
+
+const ORIGINAL_ENV = process.env;
+
+function entitlements(overrides: Partial<Entitlements> = {}): Entitlements {
+  return {
+    email: 'user@example.com',
+    planCode: 'free',
+    status: null,
+    limits: normalizeLimits({ meters: { aiJobs: 5, storageBytes: 1000, trackedTickers: 3, seats: 1 } }, 'free'),
+    upgradeTo: 'personal',
+    ...overrides
+  };
+}
+
+beforeAll(async () => {
+  mongod = await MongoMemoryServer.create();
+  await mongoose.connect(mongod.getUri());
+});
+
+afterAll(async () => {
+  await mongoose.disconnect();
+  await mongod.stop();
+});
+
+beforeEach(async () => {
+  process.env = { ...ORIGINAL_ENV, ENTITLEMENTS_MODE: 'enforce' };
+  await UsageMeter.deleteMany({});
+  // The unique index is what makes the concurrent upserts below collapse onto
+  // one document instead of racing into duplicates.
+  await UsageMeter.syncIndexes();
+  (logger.info as jest.Mock).mockClear();
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('consumeQuota', () => {
+  it('records usage and allows a request that lands exactly on the limit', async () => {
+    await consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', amount: 5, entitlements: entitlements() });
+
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(5);
+  });
+
+  it('rejects with a 402 carrying everything the upgrade dialog renders', async () => {
+    await setUsage('user@example.com', 'aiJobs', 5);
+
+    await expect(
+      consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', amount: 1, entitlements: entitlements() })
+    ).rejects.toMatchObject({
+      statusCode: 402,
+      details: { code: 'QUOTA_EXCEEDED', meter: 'aiJobs', used: 5, limit: 5, planCode: 'free', upgradeTo: 'personal' }
+    });
+  });
+
+  it('rolls its own increment back when it rejects, so a refusal costs the user nothing', async () => {
+    await setUsage('user@example.com', 'aiJobs', 5);
+
+    await expect(
+      consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', entitlements: entitlements() })
+    ).rejects.toMatchObject({ statusCode: 402 });
+
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(5);
+  });
+
+  it('admits exactly the limit under concurrency and rejects the rest', async () => {
+    const results = await Promise.allSettled(
+      Array.from({ length: 12 }, () =>
+        consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', entitlements: entitlements() })
+      )
+    );
+
+    const admitted = results.filter(r => r.status === 'fulfilled');
+    expect(admitted).toHaveLength(5);
+    // The rejected requests all rolled back, so the counter reflects the
+    // admitted ones only — no permanent drift from the losers of the race.
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(5);
+  });
+
+  it('never blocks an unlimited meter', async () => {
+    const unlimited = entitlements({
+      planCode: 'family',
+      limits: normalizeLimits({ meters: { trackedTickers: UNLIMITED } }, 'family')
+    });
+
+    await consumeQuota({ subjectId: 'user@example.com', meter: 'trackedTickers', amount: 10_000, entitlements: unlimited });
+
+    expect(await getUsage('user@example.com', 'trackedTickers')).toBe(10_000);
+  });
+
+  it('counts monthly meters into the calendar month, so usage rolls over', async () => {
+    await consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', amount: 5, entitlements: entitlements() });
+
+    // A document written under a previous month's bucket must not count.
+    const previousMonth = await UsageMeter.findOne({ meter: 'aiJobs' });
+    expect(previousMonth?.period).toBe(currentPeriod('aiJobs'));
+
+    await UsageMeter.updateOne({ meter: 'aiJobs' }, { $set: { period: '2001-01' } });
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(0);
+    await expect(
+      consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', entitlements: entitlements() })
+    ).resolves.toBeUndefined();
+  });
+
+  it('bills the same subject regardless of email casing', async () => {
+    await consumeQuota({ subjectId: 'User@Example.com', meter: 'seats', entitlements: entitlements() });
+
+    expect(await getUsage('user@example.com', 'seats')).toBe(1);
+  });
+});
+
+describe('modes', () => {
+  it('records nothing and blocks nothing when off', async () => {
+    process.env.ENTITLEMENTS_MODE = 'off';
+    await setUsage('user@example.com', 'aiJobs', 5);
+
+    await expect(
+      consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', entitlements: entitlements() })
+    ).resolves.toBeUndefined();
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(5);
+  });
+
+  it('keeps the increment and logs would_block instead of rejecting when observing', async () => {
+    process.env.ENTITLEMENTS_MODE = 'observe';
+    await setUsage('user@example.com', 'aiJobs', 5);
+
+    await expect(
+      consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', entitlements: entitlements(), route: '/ai/dispatch' })
+    ).resolves.toBeUndefined();
+
+    // Observe mode exists to measure real demand — rolling the count back would
+    // under-report exactly the users the limits are being calibrated against.
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(6);
+    expect(logger.info).toHaveBeenCalledWith(
+      'entitlement.would_block',
+      expect.objectContaining({ meter: 'aiJobs', used: 5, limit: 5, route: '/ai/dispatch' })
+    );
+  });
+});
+
+describe('checkQuota', () => {
+  it('passes when the requested amount still fits and writes nothing', async () => {
+    await setUsage('user@example.com', 'storageBytes', 400);
+
+    await expect(
+      checkQuota({ subjectId: 'user@example.com', meter: 'storageBytes', amount: 600, entitlements: entitlements() })
+    ).resolves.toBeUndefined();
+    expect(await getUsage('user@example.com', 'storageBytes')).toBe(400);
+  });
+
+  it('logs would_block instead of rejecting when observing', async () => {
+    process.env.ENTITLEMENTS_MODE = 'observe';
+    await setUsage('user@example.com', 'storageBytes', 400);
+
+    await expect(
+      checkQuota({ subjectId: 'user@example.com', meter: 'storageBytes', amount: 601, entitlements: entitlements() })
+    ).resolves.toBeUndefined();
+    expect(logger.info).toHaveBeenCalledWith(
+      'entitlement.would_block',
+      expect.objectContaining({ meter: 'storageBytes', used: 400, limit: 1000 })
+    );
+  });
+
+  it('is inert when the mode is off, even over the limit', async () => {
+    process.env.ENTITLEMENTS_MODE = 'off';
+    await setUsage('user@example.com', 'storageBytes', 5000);
+
+    await expect(
+      checkQuota({ subjectId: 'user@example.com', meter: 'storageBytes', amount: 1, entitlements: entitlements() })
+    ).resolves.toBeUndefined();
+  });
+
+  it('skips the usage read entirely for an unlimited meter', async () => {
+    const unlimited = entitlements({ limits: normalizeLimits({ meters: { storageBytes: UNLIMITED } }, 'free') });
+
+    await expect(
+      checkQuota({ subjectId: 'user@example.com', meter: 'storageBytes', amount: 10 ** 12, entitlements: unlimited })
+    ).resolves.toBeUndefined();
+  });
+
+  it('rejects when the amount would overrun, reporting current usage', async () => {
+    await setUsage('user@example.com', 'storageBytes', 400);
+
+    await expect(
+      checkQuota({ subjectId: 'user@example.com', meter: 'storageBytes', amount: 601, entitlements: entitlements() })
+    ).rejects.toMatchObject({ statusCode: 402, details: { meter: 'storageBytes', used: 400, limit: 1000 } });
+  });
+});
+
+describe('releaseQuota', () => {
+  it('hands capacity back after a failure', async () => {
+    await consumeQuota({ subjectId: 'user@example.com', meter: 'aiJobs', amount: 3, entitlements: entitlements() });
+
+    await releaseQuota('user@example.com', 'aiJobs', 3);
+
+    expect(await getUsage('user@example.com', 'aiJobs')).toBe(0);
+  });
+
+  it('clamps at zero rather than going negative', async () => {
+    await setUsage('user@example.com', 'storageBytes', 100);
+
+    await releaseQuota('user@example.com', 'storageBytes', 500);
+
+    expect(await getUsage('user@example.com', 'storageBytes')).toBe(0);
+  });
+
+  it('does not lose concurrent releases', async () => {
+    await setUsage('user@example.com', 'storageBytes', 100);
+
+    await Promise.all(Array.from({ length: 10 }, () => releaseQuota('user@example.com', 'storageBytes', 10)));
+
+    expect(await getUsage('user@example.com', 'storageBytes')).toBe(0);
+  });
+
+  it('is a no-op when no counter exists', async () => {
+    await expect(releaseQuota('nobody@example.com', 'seats', 1)).resolves.toBeUndefined();
+    expect(await getUsage('nobody@example.com', 'seats')).toBe(0);
+  });
+});
+
+describe('getUsageSnapshot', () => {
+  it('reports every meter, defaulting the untouched ones to zero', async () => {
+    await setUsage('user@example.com', 'storageBytes', 42);
+    await setUsage('user@example.com', 'aiJobs', 7);
+    await setUsage('other@example.com', 'seats', 99);
+
+    expect(await getUsageSnapshot('user@example.com')).toEqual({
+      storageBytes: 42,
+      aiJobs: 7,
+      trackedTickers: 0,
+      seats: 0
+    });
+  });
+});
+
+describe('setUsage', () => {
+  it('overwrites for backfill and reconciliation, refusing negatives', async () => {
+    await setUsage('user@example.com', 'storageBytes', 5_000);
+    expect(await getUsage('user@example.com', 'storageBytes')).toBe(5_000);
+
+    await setUsage('user@example.com', 'storageBytes', -20);
+    expect(await getUsage('user@example.com', 'storageBytes')).toBe(0);
+  });
+});

package/src/entitlements/usage.ts

@@ -0,0 +1,189 @@
+import logger from '../logging/logger';
+import { PaymentRequiredError } from '../errors/HttpError';
+import { UsageMeter, currentPeriod } from './UsageMeter';
+import { MeterKey, METER_KEYS, UNLIMITED, fitsWithin } from './definitions';
+import { Entitlements } from './types';
+import { getEntitlementsMode } from './mode';
+
+export interface QuotaRequest {
+  /** Who the usage is billed to — see `IUsageMeter.subjectId`. */
+  subjectId: string;
+  meter: MeterKey;
+  /** How much this request wants. Bytes for `storageBytes`, otherwise a count. */
+  amount?: number;
+  entitlements: Entitlements;
+  /** Attached to the observe-mode log line so a would-block can be traced to a route. */
+  route?: string;
+}
+
+/** Current count for one meter in its live period. */
+export async function getUsage(subjectId: string, meter: MeterKey, now?: Date): Promise<number> {
+  const doc = await UsageMeter.findOne({
+    subjectId: subjectId.toLowerCase(),
+    meter,
+    period: currentPeriod(meter, now)
+  }).lean();
+  return doc?.count ?? 0;
+}
+
+/** Every meter at once, for the account page and the pricing table's live numbers. */
+export async function getUsageSnapshot(subjectId: string, now?: Date): Promise<Record<MeterKey, number>> {
+  const periods = METER_KEYS.map(meter => ({ meter, period: currentPeriod(meter, now) }));
+  const docs = await UsageMeter.find({
+    subjectId: subjectId.toLowerCase(),
+    $or: periods.map(p => ({ meter: p.meter, period: p.period }))
+  }).lean();
+
+  const snapshot = Object.fromEntries(METER_KEYS.map(k => [k, 0])) as Record<MeterKey, number>;
+  for (const doc of docs) {
+    if ((METER_KEYS as readonly string[]).includes(doc.meter)) snapshot[doc.meter as MeterKey] = doc.count;
+  }
+  return snapshot;
+}
+
+function quotaError(req: QuotaRequest, used: number, limit: number): PaymentRequiredError {
+  return new PaymentRequiredError(`Limit reached for ${req.meter}`, {
+    code: 'QUOTA_EXCEEDED',
+    meter: req.meter,
+    used,
+    limit,
+    planCode: req.entitlements.planCode,
+    upgradeTo: req.entitlements.upgradeTo
+  });
+}
+
+function logWouldBlock(req: QuotaRequest, used: number, limit: number): void {
+  logger.info('entitlement.would_block', {
+    event: 'entitlement.would_block',
+    meter: req.meter,
+    subjectId: req.subjectId,
+    amount: req.amount ?? 1,
+    used,
+    limit,
+    planCode: req.entitlements.planCode,
+    route: req.route,
+    stale: req.entitlements.stale === true
+  });
+}
+
+/**
+ * Read-only check for cumulative meters whose real increment happens later
+ * (storage is counted when the upload lands, not when it is authorized).
+ *
+ * Racy by construction — two concurrent requests can both pass — which is
+ * acceptable here precisely because the meters it guards are reconciled from
+ * the underlying data. Use `consumeQuota` where the count is the only record.
+ */
+export async function checkQuota(req: QuotaRequest): Promise<void> {
+  const mode = getEntitlementsMode();
+  if (mode === 'off') return;
+
+  const limit = req.entitlements.limits.meters[req.meter] ?? UNLIMITED;
+  if (limit === UNLIMITED) return;
+
+  const used = await getUsage(req.subjectId, req.meter);
+  if (fitsWithin(limit, used, req.amount ?? 1)) return;
+
+  if (mode === 'observe') {
+    logWouldBlock(req, used, limit);
+    return;
+  }
+  throw quotaError(req, used, limit);
+}
+
+/**
+ * Atomically reserve capacity, throwing when the reservation would overrun.
+ *
+ * The increment and the check are one `$inc` + read, not a read-then-write:
+ * two concurrent requests that both read "24 used" against a limit of 25 would
+ * both proceed and overrun. Incrementing first and rejecting on the
+ * *post-increment* value means the loser of that race is the one rejected.
+ *
+ * A rejected reservation rolls its own increment back before throwing — unlike
+ * the provider-quota version this generalizes, where an over-limit count just
+ * sits there until the day rolls over. A per-user cumulative meter never rolls
+ * over, so a leaked increment is permanent and shows up months later as a user
+ * who cannot upload despite being well under their limit.
+ */
+export async function consumeQuota(req: QuotaRequest): Promise<void> {
+  const mode = getEntitlementsMode();
+  if (mode === 'off') return;
+
+  const amount = req.amount ?? 1;
+  const limit = req.entitlements.limits.meters[req.meter] ?? UNLIMITED;
+  const period = currentPeriod(req.meter);
+  const subjectId = req.subjectId.toLowerCase();
+
+  const usage = await UsageMeter.findOneAndUpdate(
+    { subjectId, meter: req.meter, period },
+    { $inc: { count: amount } },
+    { upsert: true, returnDocument: 'after', setDefaultsOnInsert: true }
+  );
+
+  if (limit === UNLIMITED || usage.count <= limit) return;
+
+  const usedBefore = usage.count - amount;
+
+  if (mode === 'observe') {
+    // Keep the increment: observe mode exists to measure real demand, and a
+    // rolled-back count would under-report exactly the users who matter.
+    logWouldBlock(req, usedBefore, limit);
+    return;
+  }
+
+  await releaseQuota(subjectId, req.meter, amount);
+  throw quotaError(req, usedBefore, limit);
+}
+
+/**
+ * Hand back capacity after a failure that never consumed it (the upload errored,
+ * the AI service refused the job), and on deletes — a cumulative meter that only
+ * counts up is a bug that surfaces as an angry support email six months in.
+ *
+ * Never drops below zero, and never throws: a failed release must not turn a
+ * recoverable error into a 500 for the caller that was already unwinding.
+ */
+export async function releaseQuota(
+  subjectId: string,
+  meter: MeterKey,
+  amount = 1,
+  now?: Date
+): Promise<void> {
+  try {
+    const filter = { subjectId: subjectId.toLowerCase(), meter, period: currentPeriod(meter, now) };
+
+    // Conditional `$inc` rather than read-then-write: a read-modify-write here
+    // loses concurrent releases, which on a cumulative meter is permanent drift.
+    const result = await UsageMeter.updateOne({ ...filter, count: { $gte: amount } }, { $inc: { count: -amount } });
+    if (result.matchedCount === 0) {
+      // Either no counter exists, or it holds less than we are handing back
+      // (a reconciliation reset it in between). Clamp at zero, never negative.
+      await UsageMeter.updateOne({ ...filter, count: { $lt: amount } }, { $set: { count: 0 } });
+    }
+  } catch (err) {
+    logger.warn('Failed to release usage quota', {
+      subjectId,
+      meter,
+      amount,
+      error: (err as Error)?.message
+    });
+  }
+}
+
+/**
+ * Set a meter to a known value. For the backfill (existing storage has to be
+ * seeded or every current user starts at zero and silently exceeds later) and
+ * for periodic reconciliation against the source of truth.
+ */
+export async function setUsage(
+  subjectId: string,
+  meter: MeterKey,
+  count: number,
+  now?: Date
+): Promise<void> {
+  await UsageMeter.updateOne(
+    { subjectId: subjectId.toLowerCase(), meter, period: currentPeriod(meter, now) },
+    { $set: { count: Math.max(0, Math.floor(count)) } },
+    { upsert: true, setDefaultsOnInsert: true }
+  );
+}

package/src/errors/HttpError.test.ts

@@ -1,4 +1,4 @@
-import { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError } from './HttpError';
+import { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError, PaymentRequiredError } from './HttpError';
 
 describe('HttpError', () => {
   it('carries the given status code and message', () => {
@@ -11,6 +11,44 @@ describe('HttpError', () => {
   it('sets name to the concrete subclass name', () => {
     expect(new HttpError(400, 'x').name).toBe('HttpError');
   });
+
+  it('carries optional details for the error handler to serialize', () => {
+    expect(new HttpError(400, 'x').details).toBeUndefined();
+    expect(new HttpError(400, 'x', { field: 'title' }).details).toEqual({ field: 'title' });
+  });
+});
+
+describe('PaymentRequiredError', () => {
+  it('is a 402 — "you may, for money" — and never a 403', () => {
+    const error = new PaymentRequiredError('Storage limit reached', {
+      code: 'QUOTA_EXCEEDED',
+      meter: 'storageBytes',
+      used: 10,
+      limit: 10,
+      planCode: 'free',
+      upgradeTo: 'personal'
+    });
+
+    expect(error.statusCode).toBe(402);
+    expect(error).toBeInstanceOf(HttpError);
+    expect(error.details).toEqual({
+      code: 'QUOTA_EXCEEDED',
+      meter: 'storageBytes',
+      used: 10,
+      limit: 10,
+      planCode: 'free',
+      upgradeTo: 'personal'
+    });
+  });
+
+  it('copies the details, so a caller reusing its object cannot mutate the error', () => {
+    const details = { code: 'QUOTA_EXCEEDED', meter: 'seats' };
+    const error = new PaymentRequiredError('Seat limit reached', details);
+
+    details.meter = 'aiJobs';
+
+    expect(error.details?.meter).toBe('seats');
+  });
 });
 
 describe.each([

package/src/errors/HttpError.ts

@@ -9,11 +9,18 @@
  */
 export class HttpError extends Error {
   statusCode: number;
+  /**
+   * Extra fields merged into the JSON body by the shared errorHandler. Used by
+   * errors the client has to *act* on rather than just display — a 402 tells
+   * the upgrade dialog which meter blocked and which plan lifts it.
+   */
+  details?: Record<string, unknown>;
 
-  constructor(statusCode: number, message: string) {
+  constructor(statusCode: number, message: string, details?: Record<string, unknown>) {
     super(message);
     this.name = new.target.name;
     this.statusCode = statusCode;
+    this.details = details;
     // Restore the prototype chain (needed when compiling to ES2018 targets
     // where `extends Error` doesn't preserve instanceof checks correctly).
     Object.setPrototypeOf(this, new.target.prototype);
@@ -55,3 +62,30 @@ export class TooManyRequestsError extends HttpError {
     super(429, message);
   }
 }
+
+/**
+ * Fields the upgrade dialog renders. Every one of them comes from the response
+ * body, so the dialog needs no knowledge of which call failed.
+ */
+export interface PaymentRequiredDetails {
+  /** Machine-readable reason, e.g. `QUOTA_EXCEEDED` or `FEATURE_NOT_IN_PLAN`. */
+  code: string;
+  meter?: string;
+  feature?: string;
+  used?: number;
+  limit?: number;
+  planCode?: string;
+  /** The cheapest plan that lifts this particular limit, when one exists. */
+  upgradeTo?: string;
+}
+
+/**
+ * 402, never 403. 403 means "you may not"; 402 means "you may, for money" —
+ * and the frontend needs to tell those apart to choose between an error toast
+ * and an upgrade dialog.
+ */
+export class PaymentRequiredError extends HttpError {
+  constructor(message: string, details: PaymentRequiredDetails) {
+    super(402, message, { ...details });
+  }
+}

package/src/index.ts

@@ -21,10 +21,22 @@ export { connectDB, disconnectDB } from './database/connection';
 export { requireEnv } from './config/env';
 
 // Errors
-export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError } from './errors/HttpError';
+export { HttpError, BadRequestError, UnauthorizedError, ForbiddenError, NotFoundError, ConflictError, TooManyRequestsError, PaymentRequiredError } from './errors/HttpError';
+export type { PaymentRequiredDetails } from './errors/HttpError';
+
+// Entitlements (plan limits, usage meters, enforcement)
+export * from './entitlements';
 
 // Middleware
 export { authenticateToken } from './middleware/authMiddleware';
+export {
+  requireInternalServiceToken,
+  internalServiceTokenBypass,
+  allowUserOrInternalService,
+  verifyInternalToken,
+  INTERNAL_TOKEN_HEADER,
+  SERVICE_ID_HEADER
+} from './middleware/internalServiceAuth';
 export { createCorsMiddleware } from './middleware/corsMiddleware';
 export { errorHandler } from './middleware/errorHandler';
 export { requestLogger, requestLoggerWithMetrics, simpleRequestLogger } from './middleware/requestLogger';

package/src/middleware/corsMiddleware.test.ts

@@ -40,6 +40,44 @@ describe('createCorsMiddleware', () => {
     expect(res.headers['access-control-allow-origin']).toBeUndefined();
   });
 
+  describe('the preflight', () => {
+    const preflight = (method: string) =>
+      request(app)
+        .options('/ping')
+        .set('Origin', 'https://allowed.example')
+        .set('Access-Control-Request-Method', method);
+
+    // A method left out here is the worst kind of CORS failure: the preflight
+    // returns 204, so the network tab shows nothing failing, and the browser
+    // quietly refuses to send the request it just asked about.
+    it.each([['GET'], ['POST'], ['PUT'], ['PATCH'], ['DELETE']])('permits %s', async (method) => {
+      const res = await preflight(method);
+
+      expect(res.headers['access-control-allow-methods'].split(',')).toContain(method);
+    });
+
+    it('does not advertise a method the services do not serve', async () => {
+      const res = await preflight('GET');
+
+      expect(res.headers['access-control-allow-methods']).not.toContain('TRACE');
+    });
+  });
+
+  it('exposes only the response headers a caller asks for', async () => {
+    // Cross-origin JavaScript cannot read a header that is not exposed — the
+    // CSV export reads its filename out of Content-Disposition
+    const exposing = express();
+    exposing.use(createCorsMiddleware({
+      origins: 'https://allowed.example',
+      exposedHeaders: ['Content-Disposition']
+    }));
+    exposing.get('/ping', (_req, res) => res.json({ ok: true }));
+
+    const res = await request(exposing).get('/ping').set('Origin', 'https://allowed.example');
+
+    expect(res.headers['access-control-expose-headers']).toBe('Content-Disposition');
+  });
+
   it('falls back to process.env.CORS_ORIGIN when no origins option is given', async () => {
     const ORIGINAL_ENV = process.env;
     process.env = { ...ORIGINAL_ENV, CORS_ORIGIN: 'https://from-env.example' };

package/src/middleware/corsMiddleware.ts

@@ -29,7 +29,11 @@ export function createCorsMiddleware(options: CorsMiddlewareOptions = {}) {
       return callback(new Error('Not allowed by CORS: ' + origin));
     },
     credentials: true,
-    methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+    // PATCH belongs here as much as PUT: leaving it out lets the preflight
+    // succeed and then has the browser block the request it just approved,
+    // which surfaces in the UI as a bare "failed to save" with a 204 in the
+    // network tab and no failing request to point at.
+    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
     allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'x-correlation-id', 'x-session-id'],
     exposedHeaders: options.exposedHeaders
   });