@tumbaland/backend-core 1.23.0 → 1.25.0

package/src/app/createBaseApp.ts

@@ -25,6 +25,12 @@ export interface CreateBaseAppOptions {
   tracing?: boolean;
   /** Use requestLoggerWithMetrics (adds Prometheus histograms) instead of the plain requestLogger. Default true. */
   metrics?: boolean;
+  /**
+   * Value for Express's `trust proxy`. Defaults to trusting private/loopback
+   * addresses — see the note on tumbaland-proxy below. Pass `false` for a
+   * service exposed directly to clients with no proxy in front of it.
+   */
+  trustProxy?: Parameters<Express['set']>[1];
 }
 
 /**
@@ -47,6 +53,24 @@ export interface CreateBaseAppOptions {
  * Services with non-standard body parsing (a webhook needing the raw body,
  * or conditional parsing per-route) should pass `parseJson`/`parseCookies:
  * false` and mount those themselves at the exact point they need to.
+ *
+ * `trust proxy` is on by default because nothing here is reached directly:
+ * every service sits behind tumbaland-proxy, which sets `X-Forwarded-For`.
+ * Left at Express's default (`false`) that header is ignored, which
+ * express-rate-limit reports as `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR` — and
+ * it is right to: the limiter would then key every request in the cluster on
+ * the proxy's own container IP, so one busy client could exhaust the window
+ * for everyone.
+ *
+ * The value is `loopback, linklocal, uniquelocal` (private ranges) rather
+ * than a hop count, because the chain length differs per ingress path: a
+ * direct hit arrives as `client` + the proxy's own socket address, while
+ * traffic through the Cloudflare tunnel arrives as `client, 127.0.0.1` (the
+ * local cloudflared) + that same socket address. Express walks the chain
+ * right-to-left and stops at the first address it does not trust, so both
+ * paths land on the real client; a fixed number would be wrong for one of
+ * them. All the intermediaries are private addresses and the client is not,
+ * which is exactly the split this preset encodes.
  */
 export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
   const {
@@ -55,11 +79,14 @@ export function createBaseApp(options: CreateBaseAppOptions = {}): Express {
     parseJson = true,
     parseCookies = true,
     tracing = true,
-    metrics = true
+    metrics = true,
+    trustProxy = 'loopback, linklocal, uniquelocal'
   } = options;
 
   const app = express();
 
+  app.set('trust proxy', trustProxy);
+
   app.get('/health/live', healthLive);
 
   app.use(securityHeaders);

package/src/entitlements/UsageMeter.ts

@@ -0,0 +1,49 @@
+import { Schema, model, models, Document, Model } from 'mongoose';
+import { MeterKey, MeterPeriod, meterPeriod } from './definitions';
+
+/**
+ * One counter per (subject, meter, period). Lives in the shared database, so
+ * album-service can write `storageBytes` while payment-service reads it back
+ * for the pricing page without another round trip.
+ *
+ * `subjectId` is whoever the usage is billed to — an email for personal
+ * meters, the group owner's email for pooled ones. It is deliberately not a
+ * user ObjectId: every service already has the email on the JWT, and none of
+ * them share a users collection.
+ */
+export interface IUsageMeter extends Document {
+  subjectId: string;
+  meter: MeterKey;
+  /** `ALL` for cumulative meters, `YYYY-MM` for monthly ones. */
+  period: string;
+  count: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const UsageMeterSchema = new Schema<IUsageMeter>(
+  {
+    subjectId: { type: String, required: true, lowercase: true, trim: true },
+    meter: { type: String, required: true },
+    period: { type: String, required: true, default: 'ALL' },
+    count: { type: Number, required: true, default: 0 }
+  },
+  { timestamps: true }
+);
+
+UsageMeterSchema.index({ subjectId: 1, meter: 1, period: 1 }, { unique: true });
+
+/**
+ * Registered through `models` first: several services import this module into
+ * the same mongoose singleton during tests, and a second `model()` call with
+ * the same name throws `OverwriteModelError`.
+ */
+export const UsageMeter: Model<IUsageMeter> =
+  (models.UsageMeter as Model<IUsageMeter>) || model<IUsageMeter>('UsageMeter', UsageMeterSchema);
+
+/** The period bucket a meter counts into right now. Monthly meters roll over at 00:00 UTC on the 1st. */
+export function currentPeriod(meter: MeterKey, now: Date = new Date()): string {
+  const period: MeterPeriod = meterPeriod(meter);
+  if (period === 'ALL') return 'ALL';
+  return now.toISOString().slice(0, 7); // YYYY-MM
+}

package/src/entitlements/client.test.ts

@@ -0,0 +1,170 @@
+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 { clearEntitlementsCache, getEntitlements, invalidateEntitlements } from './client';
+import { DEFAULT_PLAN_LIMITS } from './definitions';
+
+const ORIGINAL_ENV = process.env;
+const ORIGINAL_FETCH = global.fetch;
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return { ok: status >= 200 && status < 300, status, json: async () => body } as Response;
+}
+
+function paidResponse() {
+  return jsonResponse({
+    success: true,
+    planCode: 'personal',
+    status: 'active',
+    limits: { meters: { storageBytes: 12345 } },
+    upgradeTo: 'family'
+  });
+}
+
+beforeEach(() => {
+  process.env = {
+    ...ORIGINAL_ENV,
+    PAYMENT_API_URL: 'http://payment-service:5005',
+    INTERNAL_SERVICE_TOKEN: 'test-internal-token',
+    SERVICE_NAME: 'album-service'
+  };
+  clearEntitlementsCache();
+  global.fetch = jest.fn();
+  (logger.error as jest.Mock).mockClear();
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+  global.fetch = ORIGINAL_FETCH;
+});
+
+describe('getEntitlements', () => {
+  it('calls the internal endpoint with the service token and normalizes the answer', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    const result = await getEntitlements('User@Example.com');
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'http://payment-service:5005/internal/entitlements?email=user%40example.com',
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'x-internal-token': 'test-internal-token', 'x-service-id': 'album-service' })
+      })
+    );
+    expect(result.planCode).toBe('personal');
+    expect(result.upgradeTo).toBe('family');
+    expect(result.limits.meters.storageBytes).toBe(12345);
+    // Keys the payload omitted are filled from that plan's defaults rather than
+    // arriving undefined and comparing as NaN inside a quota check.
+    expect(result.limits.meters.seats).toBe(DEFAULT_PLAN_LIMITS.personal.meters.seats);
+    expect(result.stale).toBeUndefined();
+  });
+
+  it('serves the cached answer within the TTL and refetches after it', async () => {
+    jest.useFakeTimers();
+    try {
+      (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+      await getEntitlements('user@example.com');
+      await getEntitlements('user@example.com');
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(60_001);
+      await getEntitlements('user@example.com');
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('treats casing and surrounding whitespace as the same user', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    await getEntitlements('user@example.com');
+    await getEntitlements('  User@Example.COM ');
+
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('collapses a concurrent burst for one user into a single request', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    await Promise.all(Array.from({ length: 10 }, () => getEntitlements('user@example.com')));
+
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('drops the cached answer on invalidate', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    await getEntitlements('user@example.com');
+    invalidateEntitlements('User@example.com');
+    await getEntitlements('user@example.com');
+
+    expect(global.fetch).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('when payment-service cannot be reached', () => {
+  it('fails closed to free limits rather than handing out the product', async () => {
+    (global.fetch as jest.Mock).mockRejectedValue(new Error('ECONNREFUSED'));
+
+    const result = await getEntitlements('user@example.com');
+
+    expect(result.planCode).toBe('free');
+    expect(result.limits).toEqual(DEFAULT_PLAN_LIMITS.free);
+    expect(result.stale).toBe(true);
+    expect(logger.error).toHaveBeenCalled();
+  });
+
+  it('fails closed on a non-2xx answer too', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(jsonResponse({ success: false }, 500));
+
+    const result = await getEntitlements('user@example.com');
+
+    expect(result.planCode).toBe('free');
+    expect(result.stale).toBe(true);
+  });
+
+  it('never caches a fallback, so recovery is immediate rather than a minute later', async () => {
+    (global.fetch as jest.Mock).mockRejectedValueOnce(new Error('ECONNREFUSED')).mockResolvedValue(paidResponse());
+
+    const failed = await getEntitlements('user@example.com');
+    const recovered = await getEntitlements('user@example.com');
+
+    expect(failed.stale).toBe(true);
+    expect(recovered.planCode).toBe('personal');
+  });
+
+  it('fails closed without calling out at all when the channel is unconfigured', async () => {
+    delete process.env.PAYMENT_API_URL;
+
+    const result = await getEntitlements('user@example.com');
+
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(result.planCode).toBe('free');
+    expect(result.stale).toBe(true);
+    expect(logger.error).toHaveBeenCalledWith('Entitlement lookup not configured', expect.anything());
+  });
+});
+
+describe('cache bounds', () => {
+  it('evicts the oldest entries instead of growing without limit', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(paidResponse());
+
+    for (let i = 0; i < 5_001; i++) {
+      await getEntitlements(`user${i}@example.com`);
+    }
+    const callsAfterFill = (global.fetch as jest.Mock).mock.calls.length;
+
+    // The very first user was evicted by the 5001st, so this is a refetch.
+    await getEntitlements('user0@example.com');
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
+
+    // The most recent user is still cached.
+    await getEntitlements('user5000@example.com');
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
+  });
+});

package/src/entitlements/client.ts

@@ -0,0 +1,162 @@
+import logger from '../logging/logger';
+import { FALLBACK_PLAN, normalizeLimits, resolveLimits } from './definitions';
+import { Entitlements } from './types';
+
+/**
+ * Entitlements are read over the internal-service channel, not carried on the
+ * JWT.
+ *
+ * The JWT is signed for 24h and no service outside auth-service checks
+ * `tokenVersion`, so a plan embedded in it would be stale in both directions:
+ * a user who upgrades waits up to a day for what they just paid for, and a user
+ * who cancels keeps paid features for up to a day. A 60-second cache in front
+ * of a live lookup bounds that to a minute, and the enforcement points are
+ * writes and dispatches — low frequency — so the network cost is negligible.
+ */
+const CACHE_TTL_MS = 60_000;
+
+/** Bounded so a service under enumeration can't grow the cache without limit. */
+const MAX_CACHE_ENTRIES = 5_000;
+
+const REQUEST_TIMEOUT_MS = 3_000;
+
+interface CacheEntry {
+  value: Entitlements;
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Concurrent callers for the same email share one request. Without this, a
+ * burst of uploads from one user on a cold cache fans out into one
+ * payment-service call each.
+ */
+const inFlight = new Map<string, Promise<Entitlements>>();
+
+function cacheKey(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+function putInCache(key: string, value: Entitlements): void {
+  if (cache.size >= MAX_CACHE_ENTRIES) {
+    // Map iterates in insertion order, so the first key is the oldest write.
+    const oldest = cache.keys().next();
+    if (!oldest.done) cache.delete(oldest.value);
+  }
+  cache.set(key, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+/**
+ * Fail closed: an unreachable payment-service degrades everyone to free limits
+ * rather than handing the product out for the length of the outage. The blast
+ * radius is bounded by design — reads are never gated, only writes and
+ * dispatches — so the worst case is "cannot upload for a minute", not
+ * "cannot use the app".
+ */
+function fallbackEntitlements(email: string): Entitlements {
+  return {
+    email,
+    planCode: FALLBACK_PLAN,
+    status: null,
+    limits: resolveLimits(FALLBACK_PLAN),
+    stale: true
+  };
+}
+
+interface EntitlementResponse {
+  success?: boolean;
+  planCode?: string;
+  status?: string | null;
+  limits?: Parameters<typeof normalizeLimits>[0];
+  upgradeTo?: string;
+}
+
+async function fetchEntitlements(email: string): Promise<Entitlements> {
+  const baseUrl = process.env.PAYMENT_API_URL;
+  const token = process.env.INTERNAL_SERVICE_TOKEN;
+  const serviceId = process.env.SERVICE_NAME || 'unknown-service';
+
+  if (!baseUrl || !token) {
+    logger.error('Entitlement lookup not configured', {
+      hasPaymentApiUrl: Boolean(baseUrl),
+      hasInternalToken: Boolean(token)
+    });
+    return fallbackEntitlements(email);
+  }
+
+  try {
+    const response = await fetch(`${baseUrl}/internal/entitlements?email=${encodeURIComponent(email)}`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-internal-token': token,
+        'x-service-id': serviceId
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+
+    if (!response.ok) {
+      logger.error('Entitlement lookup failed', { email, status: response.status });
+      return fallbackEntitlements(email);
+    }
+
+    const body = (await response.json()) as EntitlementResponse;
+    const planCode = body.planCode || FALLBACK_PLAN;
+    return {
+      email,
+      planCode,
+      status: body.status ?? null,
+      // Re-normalized on this side too: the payload crossed a network boundary
+      // and a partially-configured plan must not leave a meter undefined.
+      limits: normalizeLimits(body.limits, planCode),
+      upgradeTo: body.upgradeTo
+    };
+  } catch (err) {
+    logger.error('Entitlement lookup errored', { email, error: (err as Error)?.message });
+    return fallbackEntitlements(email);
+  }
+}
+
+/**
+ * The user's current plan and limits, cached for {@link CACHE_TTL_MS}.
+ *
+ * Failures are never cached — a fallback result would otherwise pin a paying
+ * user to free limits for a full minute after the outage ended.
+ */
+export async function getEntitlements(email: string): Promise<Entitlements> {
+  const key = cacheKey(email);
+
+  const cached = cache.get(key);
+  if (cached && cached.expiresAt > Date.now()) return cached.value;
+
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+
+  const request = fetchEntitlements(key)
+    .then(value => {
+      if (!value.stale) putInCache(key, value);
+      return value;
+    })
+    .finally(() => {
+      inFlight.delete(key);
+    });
+
+  inFlight.set(key, request);
+  return request;
+}
+
+/**
+ * Drop a user's cached entitlements. Call after anything that changes their
+ * plan (checkout completed, subscription canceled) to collapse the staleness
+ * window from 60s to zero for the user who is watching.
+ */
+export function invalidateEntitlements(email: string): void {
+  cache.delete(cacheKey(email));
+}
+
+/** Empties the whole cache. Test seam, and a usable lever after a bulk plan edit. */
+export function clearEntitlementsCache(): void {
+  cache.clear();
+  inFlight.clear();
+}

package/src/entitlements/definitions.test.ts

@@ -0,0 +1,161 @@
+import {
+  DEFAULT_PLAN_LIMITS,
+  FALLBACK_PLAN,
+  FEATURE_KEYS,
+  METER_KEYS,
+  STAFF_PLAN,
+  UNLIMITED,
+  applyLimits,
+  fitsWithin,
+  isFeatureKey,
+  isMeterKey,
+  meterPeriod,
+  normalizeLimits,
+  resolveLimits
+} from './definitions';
+
+describe('resolveLimits', () => {
+  it('returns the defaults for a known plan code', () => {
+    expect(resolveLimits('personal')).toEqual(DEFAULT_PLAN_LIMITS.personal);
+  });
+
+  it('falls back to free for an unknown code, never to unlimited', () => {
+    expect(resolveLimits('enterprise-typo')).toEqual(DEFAULT_PLAN_LIMITS.free);
+    expect(resolveLimits(undefined)).toEqual(DEFAULT_PLAN_LIMITS[FALLBACK_PLAN]);
+  });
+
+  it('returns a copy, so a caller mutating limits cannot poison the defaults', () => {
+    const limits = resolveLimits('free');
+    limits.meters.storageBytes = 999;
+    limits.features.cleanExport = true;
+
+    expect(resolveLimits('free').meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
+    expect(resolveLimits('free').features.cleanExport).toBe(false);
+  });
+});
+
+describe('normalizeLimits', () => {
+  it('applies stored values over the plan defaults', () => {
+    const limits = normalizeLimits({ meters: { storageBytes: 123 }, retentionDays: 30 }, 'personal');
+
+    expect(limits.meters.storageBytes).toBe(123);
+    expect(limits.retentionDays).toBe(30);
+    // Untouched keys keep the plan's defaults rather than resetting to free.
+    expect(limits.meters.trackedTickers).toBe(DEFAULT_PLAN_LIMITS.personal.meters.trackedTickers);
+  });
+
+  it('drops keys that no code enforces', () => {
+    const limits = normalizeLimits(
+      { meters: { storageBytes: 5, wormholes: 1000 }, features: { cleanExport: true, teleport: true } },
+      'free'
+    );
+
+    expect(limits.meters).not.toHaveProperty('wormholes');
+    expect(limits.features).not.toHaveProperty('teleport');
+    expect(Object.keys(limits.meters).sort()).toEqual([...METER_KEYS].sort());
+  });
+
+  it('normalizes any negative ceiling to UNLIMITED and floors fractions', () => {
+    const limits = normalizeLimits({ meters: { aiJobs: -5, trackedTickers: 7.9 }, retentionDays: -2 }, 'free');
+
+    expect(limits.meters.aiJobs).toBe(UNLIMITED);
+    expect(limits.meters.trackedTickers).toBe(7);
+    expect(limits.retentionDays).toBe(UNLIMITED);
+  });
+
+  it('ignores non-numeric and non-boolean junk instead of producing NaN limits', () => {
+    const limits = normalizeLimits(
+      { meters: { seats: 'lots' as unknown as number }, features: { cleanExport: 'yes' as unknown as boolean } },
+      'family'
+    );
+
+    expect(limits.meters.seats).toBe(DEFAULT_PLAN_LIMITS.family.meters.seats);
+    expect(limits.features.cleanExport).toBe(true);
+  });
+
+  it('returns the plan defaults for an empty or missing payload', () => {
+    expect(normalizeLimits(undefined, 'family')).toEqual(DEFAULT_PLAN_LIMITS.family);
+    expect(normalizeLimits(null, 'family')).toEqual(DEFAULT_PLAN_LIMITS.family);
+    expect(normalizeLimits({}, 'family')).toEqual(DEFAULT_PLAN_LIMITS.family);
+  });
+
+  it('resolves an unknown plan code to free even when limits are stored', () => {
+    const limits = normalizeLimits({ meters: { seats: 3 } }, 'gold-tier-that-never-shipped');
+
+    expect(limits.meters.seats).toBe(3);
+    expect(limits.meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
+    expect(limits.features.cleanExport).toBe(false);
+  });
+});
+
+describe('applyLimits', () => {
+  it('layers a partial set over a complete one without mutating the base', () => {
+    const base = resolveLimits('free');
+
+    const layered = applyLimits(base, { meters: { storageBytes: 500 } });
+
+    expect(layered.meters.storageBytes).toBe(500);
+    expect(base.meters.storageBytes).toBe(DEFAULT_PLAN_LIMITS.free.meters.storageBytes);
+  });
+
+  it('stacks: defaults, then plan, then a per-user override', () => {
+    const planLimits = normalizeLimits({ meters: { storageBytes: 100, seats: 2 } }, 'free');
+
+    const withOverride = applyLimits(planLimits, { meters: { storageBytes: 5000 }, features: { cleanExport: true } });
+
+    expect(withOverride.meters.storageBytes).toBe(5000); // override wins
+    expect(withOverride.meters.seats).toBe(2); // plan wins where the override is silent
+    expect(withOverride.meters.aiJobs).toBe(DEFAULT_PLAN_LIMITS.free.meters.aiJobs); // default underneath both
+    expect(withOverride.features.cleanExport).toBe(true);
+  });
+});
+
+describe('the staff plan', () => {
+  it('grants every meter and feature without limit', () => {
+    const limits = resolveLimits(STAFF_PLAN);
+
+    for (const meter of METER_KEYS) {
+      expect(limits.meters[meter]).toBe(UNLIMITED);
+    }
+    expect(limits.retentionDays).toBe(UNLIMITED);
+    expect(limits.features.cleanExport).toBe(true);
+  });
+});
+
+describe('fitsWithin', () => {
+  it('treats UNLIMITED as always fitting', () => {
+    expect(fitsWithin(UNLIMITED, Number.MAX_SAFE_INTEGER, 1)).toBe(true);
+  });
+
+  it('allows landing exactly on the limit but not passing it', () => {
+    expect(fitsWithin(10, 9, 1)).toBe(true);
+    expect(fitsWithin(10, 10, 1)).toBe(false);
+  });
+});
+
+describe('key registry', () => {
+  it('recognizes only registered keys', () => {
+    expect(isMeterKey('storageBytes')).toBe(true);
+    expect(isMeterKey('storagebytes')).toBe(false);
+    expect(isFeatureKey('cleanExport')).toBe(true);
+    expect(isFeatureKey('planner')).toBe(false);
+  });
+
+  it('assigns every meter a period', () => {
+    expect(meterPeriod('aiJobs')).toBe('MONTH');
+    expect(meterPeriod('storageBytes')).toBe('ALL');
+  });
+
+  it('gives every registered plan a value for every registered key', () => {
+    for (const [code, limits] of Object.entries(DEFAULT_PLAN_LIMITS)) {
+      for (const meter of METER_KEYS) {
+        expect(typeof limits.meters[meter]).toBe(`number`);
+      }
+      for (const feature of FEATURE_KEYS) {
+        expect(typeof limits.features[feature]).toBe('boolean');
+      }
+      expect(typeof limits.retentionDays).toBe(`number`);
+      expect(code).toBeTruthy();
+    }
+  });
+});