@tumbaland/backend-core 1.23.0 → 1.25.0

package/src/entitlements/definitions.ts

@@ -0,0 +1,261 @@
+/**
+ * The entitlement *vocabulary*: which meters and features exist, what they
+ * mean, and what a plan gets when nothing else says otherwise.
+ *
+ * The actual per-plan numbers are NOT here — they live on the `Plan` document
+ * in Mongo and are editable by an admin at runtime (see payment-service's
+ * `Plan.limits` and `PUT /api/plans/:code/limits`). Shipping a code change to
+ * move a limit from 50 GB to 75 GB would be absurd, and a hardcoded table
+ * would immediately drift from what the pricing page renders.
+ *
+ * What code still owns:
+ *   - the set of valid keys, so a typo in an admin form can't invent a meter
+ *     that nothing enforces (`normalizeLimits` drops unknown keys);
+ *   - `DEFAULT_PLAN_LIMITS`, the values used when a Plan document has no
+ *     `limits` yet (fresh install, newly created plan) or when payment-service
+ *     is unreachable and the client has to fail closed;
+ *   - `ENTITLEMENT_CATALOG`, the metadata an admin UI renders its form from,
+ *     so adding a meter needs no frontend change.
+ */
+
+export type MeterKey = 'storageBytes' | 'aiJobs' | 'trackedTickers' | 'seats';
+
+/**
+ * Deliberately small. The portfolio planner is NOT a feature flag — it is gated
+ * by `retentionDays` via the price-history range, because the planner runs
+ * entirely client-side and a boolean flag would be bypassable from devtools.
+ */
+export type FeatureKey = 'cleanExport';
+
+/** `ALL` = counts up forever (storage, seats). `MONTH` = resets each calendar month (UTC). */
+export type MeterPeriod = 'ALL' | 'MONTH';
+
+/** Sentinel for "no ceiling". Chosen over `Infinity` because it survives JSON and BSON. */
+export const UNLIMITED = -1;
+
+export interface MeterDefinition {
+  key: MeterKey;
+  label: string;
+  /** Drives formatting in the admin form and in `<UsageMeter>`: bytes get humanized, counts don't. */
+  unit: 'bytes' | 'count';
+  period: MeterPeriod;
+  description: string;
+}
+
+export interface FeatureDefinition {
+  key: FeatureKey;
+  label: string;
+  description: string;
+}
+
+export const METER_DEFINITIONS: readonly MeterDefinition[] = [
+  {
+    key: 'storageBytes',
+    label: 'Storage',
+    unit: 'bytes',
+    period: 'ALL',
+    description: 'Total bytes of uploaded photos and files held for the user.'
+  },
+  {
+    key: 'aiJobs',
+    label: 'AI analyses',
+    unit: 'count',
+    period: 'MONTH',
+    description: 'Segmentation and object-detection jobs dispatched per calendar month.'
+  },
+  {
+    key: 'trackedTickers',
+    label: 'Tracked tickers',
+    unit: 'count',
+    period: 'ALL',
+    description: 'Instruments followed for price history. Each one spends the deployment-wide market-data budget.'
+  },
+  {
+    key: 'seats',
+    label: 'Group seats',
+    unit: 'count',
+    period: 'ALL',
+    description: 'Members that may join groups owned by the user, including the owner.'
+  }
+] as const;
+
+export const FEATURE_DEFINITIONS: readonly FeatureDefinition[] = [
+  {
+    key: 'cleanExport',
+    label: 'Clean export',
+    description: 'Exports and downloads without a watermark.'
+  }
+] as const;
+
+export const METER_KEYS: readonly MeterKey[] = METER_DEFINITIONS.map(m => m.key);
+export const FEATURE_KEYS: readonly FeatureKey[] = FEATURE_DEFINITIONS.map(f => f.key);
+
+const METER_PERIODS = Object.fromEntries(
+  METER_DEFINITIONS.map(m => [m.key, m.period])
+) as Record<MeterKey, MeterPeriod>;
+
+export function meterPeriod(meter: MeterKey): MeterPeriod {
+  return METER_PERIODS[meter] ?? 'ALL';
+}
+
+export function isMeterKey(value: string): value is MeterKey {
+  return (METER_KEYS as readonly string[]).includes(value);
+}
+
+export function isFeatureKey(value: string): value is FeatureKey {
+  return (FEATURE_KEYS as readonly string[]).includes(value);
+}
+
+export interface PlanLimits {
+  /** `-1` (UNLIMITED) means no ceiling. */
+  meters: Record<MeterKey, number>;
+  features: Record<FeatureKey, boolean>;
+  /** How far back reads may reach. `-1` (UNLIMITED) means the full history. */
+  retentionDays: number;
+}
+
+/** What an admin form or an API caller may send: any subset, in any order. */
+export interface PartialPlanLimits {
+  meters?: Partial<Record<string, number>>;
+  features?: Partial<Record<string, boolean>>;
+  retentionDays?: number;
+}
+
+const GB = 1024 * 1024 * 1024;
+
+/**
+ * Bootstrap values only — a Plan document's own `limits` wins over anything
+ * here. These are what a plan gets before an admin has ever touched it, and
+ * what the entitlement client falls back to when payment-service is down.
+ *
+ * Keep `free` conservative for exactly that reason: an outage degrades paying
+ * users to these numbers, and the alternative (fail-open) gives the product
+ * away for the length of the outage.
+ */
+export const DEFAULT_PLAN_LIMITS: Readonly<Record<string, PlanLimits>> = {
+  free: {
+    meters: { storageBytes: 1 * GB, aiJobs: 25, trackedTickers: 3, seats: 1 },
+    features: { cleanExport: false },
+    retentionDays: 90
+  },
+  personal: {
+    meters: { storageBytes: 50 * GB, aiJobs: 200, trackedTickers: 25, seats: 1 },
+    features: { cleanExport: true },
+    retentionDays: UNLIMITED
+  },
+  family: {
+    meters: { storageBytes: 250 * GB, aiJobs: 600, trackedTickers: 100, seats: 5 },
+    features: { cleanExport: true },
+    retentionDays: UNLIMITED
+  },
+  /**
+   * Everything unlimited, for the maintainers and for comped friends. Held as a
+   * real plan with a real subscription rather than an exemption branch in the
+   * code, so the people running the product go through the identical
+   * enforcement path as a paying customer — an `if (isStaff) skipEverything`
+   * flag would mean the paywall is never exercised by anyone who could notice
+   * it was broken.
+   *
+   * Kept off the public catalog through `Plan.isPublic = false`.
+   */
+  staff: {
+    meters: { storageBytes: UNLIMITED, aiJobs: UNLIMITED, trackedTickers: UNLIMITED, seats: UNLIMITED },
+    features: { cleanExport: true },
+    retentionDays: UNLIMITED
+  }
+};
+
+/** Plan code the seeded staff/comp plan uses. */
+export const STAFF_PLAN = 'staff';
+
+export const FALLBACK_PLAN = 'free';
+
+/**
+ * Code defaults for a plan code, with unknown codes resolving to free.
+ *
+ * That fallback is deliberate: a typo'd or newly-added plan code must never
+ * silently grant unlimited. Callers that want the admin-configured numbers
+ * read them from the Plan document and pass them through `normalizeLimits`;
+ * this function is the floor underneath that.
+ */
+export function resolveLimits(planCode?: string): PlanLimits {
+  const limits = DEFAULT_PLAN_LIMITS[planCode ?? FALLBACK_PLAN] ?? DEFAULT_PLAN_LIMITS[FALLBACK_PLAN];
+  return cloneLimits(limits);
+}
+
+function cloneLimits(limits: PlanLimits): PlanLimits {
+  return {
+    meters: { ...limits.meters },
+    features: { ...limits.features },
+    retentionDays: limits.retentionDays
+  };
+}
+
+function normalizeCeiling(value: unknown, fallback: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  // Anything negative means "unlimited"; nothing else is a meaningful ceiling.
+  if (value < 0) return UNLIMITED;
+  return Math.floor(value);
+}
+
+/**
+ * Layers a partial set of limits over a complete one.
+ *
+ * Entitlements resolve through three layers, each one partial and each one
+ * overriding the last: code defaults → the Plan document's `limits` → a
+ * per-user `EntitlementOverride`. This is the single step all three share.
+ *
+ * - unknown meter/feature keys are dropped — no store can invent enforcement;
+ * - missing keys keep the base value, so adding a new meter in code works
+ *   everywhere before any stored document mentions it;
+ * - negative numbers normalize to `UNLIMITED`, fractions floor.
+ */
+export function applyLimits(base: PlanLimits, input?: PartialPlanLimits | null): PlanLimits {
+  const result = cloneLimits(base);
+  if (!input) return result;
+
+  for (const key of METER_KEYS) {
+    result.meters[key] = normalizeCeiling(input.meters?.[key], result.meters[key]);
+  }
+  for (const key of FEATURE_KEYS) {
+    const value = input.features?.[key];
+    result.features[key] = typeof value === 'boolean' ? value : result.features[key];
+  }
+  result.retentionDays = normalizeCeiling(input.retentionDays, result.retentionDays);
+
+  return result;
+}
+
+/**
+ * Turns whatever is stored on a Plan document (or arrived from an admin form)
+ * into a complete, valid `PlanLimits`, filling the gaps from that plan code's
+ * code defaults.
+ */
+export function normalizeLimits(input?: PartialPlanLimits | null, planCode?: string): PlanLimits {
+  return applyLimits(resolveLimits(planCode), input);
+}
+
+/** True when `used + amount` fits under `limit`. `UNLIMITED` always fits. */
+export function fitsWithin(limit: number, used: number, amount = 0): boolean {
+  if (limit === UNLIMITED || limit < 0) return true;
+  return used + amount <= limit;
+}
+
+/**
+ * Everything an admin UI needs to render a limits editor without hardcoding a
+ * single meter name — new keys appear in the form as soon as they exist here.
+ */
+export const ENTITLEMENT_CATALOG = {
+  unlimited: UNLIMITED,
+  meters: METER_DEFINITIONS,
+  features: FEATURE_DEFINITIONS,
+  retentionDays: {
+    key: 'retentionDays' as const,
+    label: 'History retention (days)',
+    unit: 'days' as const,
+    description:
+      'How far back reads may reach. Gates relationship history and, through the price-history range, the portfolio planner.'
+  },
+  defaults: DEFAULT_PLAN_LIMITS,
+  fallbackPlan: FALLBACK_PLAN
+};

package/src/entitlements/index.ts

@@ -0,0 +1,40 @@
+export {
+  UNLIMITED,
+  FALLBACK_PLAN,
+  STAFF_PLAN,
+  applyLimits,
+  METER_KEYS,
+  FEATURE_KEYS,
+  METER_DEFINITIONS,
+  FEATURE_DEFINITIONS,
+  DEFAULT_PLAN_LIMITS,
+  ENTITLEMENT_CATALOG,
+  resolveLimits,
+  normalizeLimits,
+  meterPeriod,
+  isMeterKey,
+  isFeatureKey,
+  fitsWithin
+} from './definitions';
+export type {
+  MeterKey,
+  FeatureKey,
+  MeterPeriod,
+  MeterDefinition,
+  FeatureDefinition,
+  PlanLimits,
+  PartialPlanLimits
+} from './definitions';
+
+export type { Entitlements, EntitlementsMode } from './types';
+export { getEntitlementsMode, resetEntitlementsModeWarning } from './mode';
+
+export { UsageMeter, currentPeriod } from './UsageMeter';
+export type { IUsageMeter } from './UsageMeter';
+export { getUsage, getUsageSnapshot, checkQuota, consumeQuota, releaseQuota, setUsage } from './usage';
+export type { QuotaRequest } from './usage';
+
+export { getEntitlements, invalidateEntitlements, clearEntitlementsCache } from './client';
+
+export { loadEntitlements, requireEntitlement, requireQuota, retentionFloor } from './middleware';
+export type { EntitlementOptions, QuotaOptions, SubjectResolver } from './middleware';

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;
+}