@tumbaland/backend-core 1.23.0 → 1.24.0

package/src/entitlements/middleware.test.ts

@@ -0,0 +1,179 @@
+import { Request, Response } from 'express';
+
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+jest.mock('./client', () => ({ getEntitlements: jest.fn() }));
+jest.mock('./usage', () => ({ checkQuota: jest.fn() }));
+
+import logger from '../logging/logger';
+import { getEntitlements } from './client';
+import { checkQuota } from './usage';
+import { loadEntitlements, requireEntitlement, requireQuota, retentionFloor } from './middleware';
+import { Entitlements } from './types';
+import { UNLIMITED, normalizeLimits } from './definitions';
+
+const mockGetEntitlements = getEntitlements as jest.MockedFunction<typeof getEntitlements>;
+const mockCheckQuota = checkQuota as jest.MockedFunction<typeof checkQuota>;
+
+const ORIGINAL_ENV = process.env;
+
+function entitlements(overrides: Partial<Entitlements> = {}): Entitlements {
+  return {
+    email: 'user@example.com',
+    planCode: 'free',
+    status: null,
+    limits: normalizeLimits(undefined, 'free'),
+    upgradeTo: 'personal',
+    ...overrides
+  };
+}
+
+function mockReq(overrides: Partial<Request> = {}): Request {
+  return { user: { email: 'user@example.com' }, originalUrl: '/api/photos', ...overrides } as Request;
+}
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV, ENTITLEMENTS_MODE: 'enforce' };
+  jest.clearAllMocks();
+  mockGetEntitlements.mockResolvedValue(entitlements());
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('loadEntitlements', () => {
+  it('resolves once per request even across several checks', async () => {
+    const req = mockReq();
+
+    await loadEntitlements(req);
+    await loadEntitlements(req);
+
+    expect(mockGetEntitlements).toHaveBeenCalledTimes(1);
+    expect(req.entitlements?.planCode).toBe('free');
+  });
+
+  it('rejects when there is no subject to bill', async () => {
+    await expect(loadEntitlements(mockReq({ user: undefined }))).rejects.toMatchObject({ statusCode: 401 });
+  });
+
+  it('bills the subject a resolver names, not the caller', async () => {
+    await loadEntitlements(mockReq(), () => 'owner@example.com');
+
+    expect(mockGetEntitlements).toHaveBeenCalledWith('owner@example.com');
+  });
+});
+
+describe('requireEntitlement', () => {
+  it('passes a plan that includes the feature', async () => {
+    mockGetEntitlements.mockResolvedValue(entitlements({ planCode: 'personal', limits: normalizeLimits(undefined, 'personal') }));
+    const next = jest.fn();
+
+    await requireEntitlement('cleanExport')(mockReq(), {} as Response, next);
+
+    expect(next).toHaveBeenCalledWith();
+  });
+
+  it('rejects with a 402 naming the feature and the upgrade target', async () => {
+    const next = jest.fn();
+
+    await requireEntitlement('cleanExport')(mockReq(), {} as Response, next);
+
+    expect(next).toHaveBeenCalledWith(
+      expect.objectContaining({
+        statusCode: 402,
+        details: { code: 'FEATURE_NOT_IN_PLAN', feature: 'cleanExport', planCode: 'free', upgradeTo: 'personal' }
+      })
+    );
+  });
+
+  it('logs instead of blocking in observe mode', async () => {
+    process.env.ENTITLEMENTS_MODE = 'observe';
+    const next = jest.fn();
+
+    await requireEntitlement('cleanExport')(mockReq(), {} as Response, next);
+
+    expect(next).toHaveBeenCalledWith();
+    expect(logger.info).toHaveBeenCalledWith('entitlement.would_block', expect.objectContaining({ feature: 'cleanExport' }));
+  });
+
+  it('does not even look entitlements up when the mode is off', async () => {
+    process.env.ENTITLEMENTS_MODE = 'off';
+    const next = jest.fn();
+
+    await requireEntitlement('cleanExport')(mockReq(), {} as Response, next);
+
+    expect(next).toHaveBeenCalledWith();
+    expect(mockGetEntitlements).not.toHaveBeenCalled();
+  });
+});
+
+describe('requireQuota', () => {
+  it('checks the meter for the amount the request costs', async () => {
+    const next = jest.fn();
+    const req = mockReq({ body: { sizeBytes: 2048 } } as Partial<Request>);
+
+    await requireQuota('storageBytes', { amount: r => (r.body as { sizeBytes: number }).sizeBytes })(
+      req,
+      {} as Response,
+      next
+    );
+
+    expect(mockCheckQuota).toHaveBeenCalledWith(
+      expect.objectContaining({ subjectId: 'user@example.com', meter: 'storageBytes', amount: 2048, route: '/api/photos' })
+    );
+    expect(next).toHaveBeenCalledWith();
+  });
+
+  it('defaults the amount to one', async () => {
+    await requireQuota('trackedTickers')(mockReq(), {} as Response, jest.fn());
+
+    expect(mockCheckQuota).toHaveBeenCalledWith(expect.objectContaining({ amount: 1 }));
+  });
+
+  it('forwards a quota rejection to the error handler', async () => {
+    const denial = Object.assign(new Error('nope'), { statusCode: 402 });
+    mockCheckQuota.mockRejectedValue(denial);
+    const next = jest.fn();
+
+    await requireQuota('storageBytes')(mockReq(), {} as Response, next);
+
+    expect(next).toHaveBeenCalledWith(denial);
+  });
+
+  it('is inert when the mode is off', async () => {
+    process.env.ENTITLEMENTS_MODE = 'off';
+    const next = jest.fn();
+
+    await requireQuota('storageBytes')(mockReq(), {} as Response, next);
+
+    expect(mockCheckQuota).not.toHaveBeenCalled();
+    expect(next).toHaveBeenCalledWith();
+  });
+});
+
+describe('retentionFloor', () => {
+  const now = new Date('2026-08-09T00:00:00.000Z');
+
+  it('returns the cutoff date for a capped plan', async () => {
+    const floor = await retentionFloor('user@example.com', now);
+
+    expect(floor).toEqual(new Date('2026-05-11T00:00:00.000Z')); // 90 days back
+  });
+
+  it('returns null for an unlimited plan, so no $match is added', async () => {
+    mockGetEntitlements.mockResolvedValue(
+      entitlements({ planCode: 'family', limits: normalizeLimits({ retentionDays: UNLIMITED }, 'family') })
+    );
+
+    expect(await retentionFloor('user@example.com', now)).toBeNull();
+  });
+
+  it('never truncates history outside enforce mode', async () => {
+    process.env.ENTITLEMENTS_MODE = 'observe';
+
+    expect(await retentionFloor('user@example.com', now)).toBeNull();
+  });
+});

package/src/entitlements/middleware.ts

@@ -0,0 +1,136 @@
+import { Request, RequestHandler } from 'express';
+import logger from '../logging/logger';
+import { PaymentRequiredError, UnauthorizedError } from '../errors/HttpError';
+import { FeatureKey, MeterKey, UNLIMITED } from './definitions';
+import { getEntitlements } from './client';
+import { checkQuota } from './usage';
+import { getEntitlementsMode } from './mode';
+import { Entitlements } from './types';
+
+declare global {
+  namespace Express {
+    interface Request {
+      /** Populated by the entitlement middlewares so controllers can read limits without a second lookup. */
+      entitlements?: Entitlements;
+    }
+  }
+}
+
+/**
+ * Who the check is billed to. Defaults to the authenticated user; group
+ * chokepoints override it with the group owner, since pooled quota belongs to
+ * whoever pays for the group.
+ */
+export type SubjectResolver = (req: Request) => string | undefined | Promise<string | undefined>;
+
+export interface EntitlementOptions {
+  subject?: SubjectResolver;
+}
+
+const defaultSubject: SubjectResolver = req => req.user?.email;
+
+/**
+ * Resolves and caches entitlements on the request. Two checks on one route
+ * (a feature gate plus a quota gate) therefore cost one lookup, not two.
+ */
+export async function loadEntitlements(req: Request, resolve: SubjectResolver = defaultSubject): Promise<Entitlements> {
+  if (req.entitlements) return req.entitlements;
+
+  const subject = await resolve(req);
+  if (!subject) throw new UnauthorizedError('Authentication required');
+
+  const entitlements = await getEntitlements(subject);
+  req.entitlements = entitlements;
+  return entitlements;
+}
+
+/**
+ * Gate a feature flag. Reads are never gated by design — use this on writes,
+ * dispatches and exports only.
+ */
+export function requireEntitlement(feature: FeatureKey, options: EntitlementOptions = {}): RequestHandler {
+  return async (req, _res, next) => {
+    try {
+      const mode = getEntitlementsMode();
+      if (mode === 'off') return next();
+
+      const entitlements = await loadEntitlements(req, options.subject);
+      if (entitlements.limits.features[feature]) return next();
+
+      if (mode === 'observe') {
+        logger.info('entitlement.would_block', {
+          event: 'entitlement.would_block',
+          feature,
+          subjectId: entitlements.email,
+          planCode: entitlements.planCode,
+          route: req.originalUrl,
+          stale: entitlements.stale === true
+        });
+        return next();
+      }
+
+      throw new PaymentRequiredError(`Your plan does not include ${feature}`, {
+        code: 'FEATURE_NOT_IN_PLAN',
+        feature,
+        planCode: entitlements.planCode,
+        upgradeTo: entitlements.upgradeTo
+      });
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+export interface QuotaOptions extends EntitlementOptions {
+  /**
+   * How much this request costs. A function when the amount is in the payload
+   * — an upload's `sizeBytes`, say — which is also why the storage gate sits on
+   * the signed-URL request: it is the only point where the size is known
+   * *before* the bytes are written.
+   */
+  amount?: number | ((req: Request) => number);
+}
+
+/**
+ * Read-only quota gate. Records nothing — the increment belongs at the point
+ * the resource actually comes into existence, via `consumeQuota`.
+ */
+export function requireQuota(meter: MeterKey, options: QuotaOptions = {}): RequestHandler {
+  return async (req, _res, next) => {
+    try {
+      if (getEntitlementsMode() === 'off') return next();
+
+      const entitlements = await loadEntitlements(req, options.subject);
+      const amount = typeof options.amount === 'function' ? options.amount(req) : (options.amount ?? 1);
+
+      await checkQuota({
+        subjectId: entitlements.email,
+        meter,
+        amount,
+        entitlements,
+        route: req.originalUrl
+      });
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+}
+
+/**
+ * The oldest timestamp a user may read, or `null` for unlimited history.
+ *
+ * Meant to be dropped straight into an aggregation `$match` — this is what
+ * gates the portfolio planner, since the planner runs entirely client-side and
+ * any `<PaywallGate>` around it is bypassable from devtools. Truncating the
+ * price history it depends on is not.
+ */
+export async function retentionFloor(email: string, now: Date = new Date()): Promise<Date | null> {
+  if (getEntitlementsMode() !== 'enforce') return null;
+
+  const { limits } = await getEntitlements(email);
+  const days = limits.retentionDays;
+  if (days === UNLIMITED || days < 0) return null;
+
+  return new Date(now.getTime() - days * 24 * 60 * 60 * 1000);
+}

package/src/entitlements/mode.test.ts

@@ -0,0 +1,50 @@
+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 { getEntitlementsMode, resetEntitlementsModeWarning } from './mode';
+
+const ORIGINAL_ENV = process.env;
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV };
+  delete process.env.ENTITLEMENTS_MODE;
+  resetEntitlementsModeWarning();
+  (logger.warn as jest.Mock).mockClear();
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('getEntitlementsMode', () => {
+  it('defaults to observe when unset', () => {
+    expect(getEntitlementsMode()).toBe('observe');
+  });
+
+  it('reads each valid mode, case- and whitespace-insensitively', () => {
+    process.env.ENTITLEMENTS_MODE = 'enforce';
+    expect(getEntitlementsMode()).toBe('enforce');
+
+    process.env.ENTITLEMENTS_MODE = ' Off ';
+    expect(getEntitlementsMode()).toBe('off');
+  });
+
+  it('falls back to observe and warns once on an invalid value', () => {
+    process.env.ENTITLEMENTS_MODE = 'enforcce';
+
+    expect(getEntitlementsMode()).toBe('observe');
+    expect(getEntitlementsMode()).toBe('observe');
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+  });
+
+  it('picks up a change without a restart of the module', () => {
+    process.env.ENTITLEMENTS_MODE = 'observe';
+    expect(getEntitlementsMode()).toBe('observe');
+
+    process.env.ENTITLEMENTS_MODE = 'enforce';
+    expect(getEntitlementsMode()).toBe('enforce');
+  });
+});

package/src/entitlements/mode.ts

@@ -0,0 +1,28 @@
+import logger from '../logging/logger';
+import { EntitlementsMode } from './types';
+
+const VALID_MODES: readonly EntitlementsMode[] = ['off', 'observe', 'enforce'];
+
+let warnedAboutInvalidMode = false;
+
+/**
+ * Read per call rather than cached at import time: a service can be flipped to
+ * `enforce` by restarting it with a new env value, and tests set the variable
+ * between cases. The cost is one `process.env` lookup per check.
+ */
+export function getEntitlementsMode(): EntitlementsMode {
+  const raw = (process.env.ENTITLEMENTS_MODE || '').trim().toLowerCase();
+  if (!raw) return 'observe';
+  if ((VALID_MODES as readonly string[]).includes(raw)) return raw as EntitlementsMode;
+
+  if (!warnedAboutInvalidMode) {
+    warnedAboutInvalidMode = true;
+    logger.warn('Invalid ENTITLEMENTS_MODE, falling back to observe', { value: raw });
+  }
+  return 'observe';
+}
+
+/** Test seam — the "already warned" latch would otherwise leak between cases. */
+export function resetEntitlementsModeWarning(): void {
+  warnedAboutInvalidMode = false;
+}

package/src/entitlements/types.ts

@@ -0,0 +1,30 @@
+import { PlanLimits } from './definitions';
+
+/**
+ * What payment-service answers for a user, and what the client caches.
+ * `limits` is already normalized — consumers never merge defaults themselves.
+ */
+export interface Entitlements {
+  email: string;
+  planCode: string;
+  /** Subscription status backing the plan; `null` for users on the implicit free plan. */
+  status: string | null;
+  limits: PlanLimits;
+  /** Cheapest active plan priced above the current one, for the upgrade dialog's CTA. */
+  upgradeTo?: string;
+  /**
+   * Set when payment-service could not be reached and these are fallback
+   * limits rather than the user's real ones. Enforcement still applies (fail
+   * closed), but the value lets callers log the difference.
+   */
+  stale?: boolean;
+}
+
+/**
+ * `off` — no metering, no blocking. `observe` — record usage and log what
+ * would have been blocked, block nothing. `enforce` — block.
+ *
+ * Observe is the default because the configured limits start as guesses; two
+ * weeks of `entitlement.would_block` volume is what turns them into numbers.
+ */
+export type EntitlementsMode = 'off' | 'observe' | 'enforce';