@tumbaland/backend-core 1.25.0 → 1.26.0

package/src/groups/client.test.ts

@@ -0,0 +1,215 @@
+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 { clearGroupOwnerCache, getGroupOwner, invalidateGroupOwner } from './client';
+
+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 ownerResponse(overrides: Record<string, unknown> = {}) {
+  return jsonResponse({
+    success: true,
+    groupId: 'group-1',
+    ownerEmail: 'Owner@Example.com',
+    memberCount: 3,
+    deleted: false,
+    ...overrides
+  });
+}
+
+beforeEach(() => {
+  process.env = {
+    ...ORIGINAL_ENV,
+    GROUP_API_URL: 'http://group-service:5006',
+    INTERNAL_SERVICE_TOKEN: 'test-internal-token',
+    SERVICE_NAME: 'album-service'
+  };
+  clearGroupOwnerCache();
+  global.fetch = jest.fn();
+  (logger.error as jest.Mock).mockClear();
+  (logger.warn as jest.Mock).mockClear();
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+  global.fetch = ORIGINAL_FETCH;
+});
+
+describe('getGroupOwner', () => {
+  it('calls the internal endpoint with the service token and normalizes the owner', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    const result = await getGroupOwner('group-1');
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'http://group-service:5006/internal/groups/group-1/owner',
+      expect.objectContaining({
+        headers: expect.objectContaining({ 'x-internal-token': 'test-internal-token', 'x-service-id': 'album-service' })
+      })
+    );
+    // Lowercased on arrival: it becomes a UsageMeter subjectId, which is
+    // lowercase, so an owner recorded with capitals would open a second meter.
+    expect(result?.ownerEmail).toBe('owner@example.com');
+    expect(result?.memberCount).toBe(3);
+    expect(result?.deleted).toBe(false);
+  });
+
+  it('resolves a soft-deleted group rather than dropping its storage', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse({ deleted: true }));
+
+    const result = await getGroupOwner('group-1');
+
+    expect(result?.ownerEmail).toBe('owner@example.com');
+    expect(result?.deleted).toBe(true);
+  });
+
+  it('serves the cached answer within the TTL and refetches after it', async () => {
+    jest.useFakeTimers();
+    try {
+      (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+      await getGroupOwner('group-1');
+      await getGroupOwner('group-1');
+      expect(global.fetch).toHaveBeenCalledTimes(1);
+
+      jest.advanceTimersByTime(60_001);
+      await getGroupOwner('group-1');
+      expect(global.fetch).toHaveBeenCalledTimes(2);
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('collapses a concurrent burst for one group into a single request', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    await Promise.all(Array.from({ length: 10 }, () => getGroupOwner('group-1')));
+
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('drops the cached owner on invalidate, so a transferred group rebills at once', async () => {
+    (global.fetch as jest.Mock)
+      .mockResolvedValueOnce(ownerResponse())
+      .mockResolvedValue(ownerResponse({ ownerEmail: 'new-owner@example.com' }));
+
+    const before = await getGroupOwner('group-1');
+    invalidateGroupOwner('group-1');
+    const after = await getGroupOwner('group-1');
+
+    expect(before?.ownerEmail).toBe('owner@example.com');
+    expect(after?.ownerEmail).toBe('new-owner@example.com');
+  });
+
+  it('returns null without calling out on a blank group id', async () => {
+    expect(await getGroupOwner('   ')).toBeNull();
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+});
+
+describe('when the group cannot be resolved', () => {
+  it('returns null on a 404 and warns rather than erroring', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(jsonResponse({ success: false }, 404));
+
+    expect(await getGroupOwner('missing')).toBeNull();
+    expect(logger.warn).toHaveBeenCalled();
+    expect(logger.error).not.toHaveBeenCalled();
+  });
+
+  it('returns null and errors when group-service is unreachable', async () => {
+    (global.fetch as jest.Mock).mockRejectedValue(new Error('ECONNREFUSED'));
+
+    expect(await getGroupOwner('group-1')).toBeNull();
+    expect(logger.error).toHaveBeenCalled();
+  });
+
+  it('returns null when the answer carries no owner', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse({ ownerEmail: undefined }));
+
+    expect(await getGroupOwner('group-1')).toBeNull();
+    expect(logger.error).toHaveBeenCalled();
+  });
+
+  it('returns null without calling out at all when the channel is unconfigured', async () => {
+    delete process.env.GROUP_API_URL;
+
+    expect(await getGroupOwner('group-1')).toBeNull();
+    expect(global.fetch).not.toHaveBeenCalled();
+    expect(logger.error).toHaveBeenCalledWith('Group owner lookup not configured', expect.anything());
+  });
+});
+
+describe('base URL selection', () => {
+  it('prefers the container-network address over the public hostname', async () => {
+    process.env.GROUP_INTERNAL_URL = 'http://group-service:5006';
+    process.env.GROUP_API_URL = 'https://group-api.tumbaland.eu';
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    await getGroupOwner('group-1');
+
+    // The public variable is what the frontends hand to the browser, so it can
+    // never be pointed inward — this is the server-side half of that split.
+    expect(global.fetch).toHaveBeenCalledWith(
+      'http://group-service:5006/internal/groups/group-1/owner',
+      expect.anything()
+    );
+  });
+
+  it('falls back to the public URL, so local dev and un-migrated deploys still work', async () => {
+    delete process.env.GROUP_INTERNAL_URL;
+    process.env.GROUP_API_URL = 'https://group-api.tumbaland.eu';
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    await getGroupOwner('group-1');
+
+    expect(global.fetch).toHaveBeenCalledWith(
+      'https://group-api.tumbaland.eu/internal/groups/group-1/owner',
+      expect.anything()
+    );
+  });
+
+  it('never caches a failure, so recovery is immediate rather than a minute later', async () => {
+    (global.fetch as jest.Mock).mockRejectedValueOnce(new Error('ECONNREFUSED')).mockResolvedValue(ownerResponse());
+
+    const failed = await getGroupOwner('group-1');
+    const recovered = await getGroupOwner('group-1');
+
+    expect(failed).toBeNull();
+    expect(recovered?.ownerEmail).toBe('owner@example.com');
+  });
+
+  it('never caches a 404 either — a bad id must not spend a cache slot', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(jsonResponse({ success: false }, 404));
+
+    await getGroupOwner('missing');
+    await getGroupOwner('missing');
+
+    expect(global.fetch).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('cache bounds', () => {
+  it('evicts the oldest entries instead of growing without limit', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    for (let i = 0; i < 5_001; i++) {
+      await getGroupOwner(`group-${i}`);
+    }
+    const callsAfterFill = (global.fetch as jest.Mock).mock.calls.length;
+
+    // The very first group was evicted by the 5001st, so this is a refetch.
+    await getGroupOwner('group-0');
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
+
+    // The most recent group is still cached.
+    await getGroupOwner('group-5000');
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(callsAfterFill + 1);
+  });
+});

package/src/groups/client.ts

@@ -0,0 +1,182 @@
+import logger from '../logging/logger';
+
+/**
+ * Who a group's pooled usage bills to, read over the internal-service channel.
+ *
+ * The JWT carries `groups` — the ids a user belongs to — but never says who
+ * owns them, and no service outside group-service has the collection. So a
+ * chokepoint that needs the *quota subject* for a group album or a group ticker
+ * has to ask. See MONETIZATION.md's note on why that subject is the owner and
+ * not the uploader.
+ *
+ * Same 60s TTL as the entitlement client, for a weaker reason: ownership moves
+ * far more rarely than a plan does, so the cache could be much longer, but a
+ * stale owner bills the wrong person and one shared number is one fewer thing
+ * to reason about. The enforcement points are writes, so the traffic is low
+ * either way.
+ */
+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;
+
+export interface GroupOwner {
+  groupId: string;
+  ownerEmail: string;
+  memberCount: number;
+  /** Soft-deleted groups still resolve: their photos still occupy storage. */
+  deleted: boolean;
+  /** True when group-service could not be reached and nothing was resolved. */
+  stale?: boolean;
+}
+
+interface CacheEntry {
+  value: GroupOwner;
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+/**
+ * Concurrent callers for one group share a request — a burst of uploads into
+ * the same shared album is the expected shape of this traffic.
+ */
+const inFlight = new Map<string, Promise<GroupOwner | null>>();
+
+function putInCache(groupId: string, value: GroupOwner): 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(groupId, { value, expiresAt: Date.now() + CACHE_TTL_MS });
+}
+
+interface GroupOwnerResponse {
+  success?: boolean;
+  groupId?: string;
+  ownerEmail?: string;
+  memberCount?: number;
+  deleted?: boolean;
+}
+
+/**
+ * Prefers the container-network address over the public hostname.
+ *
+ * `GROUP_API_URL` cannot simply be pointed inward: the frontend containers
+ * template that same variable into the `config.json` the *browser* downloads,
+ * so a Docker-internal value there breaks every group call in the UI. One
+ * variable genuinely has two consumers with incompatible needs, so this is the
+ * server-side half of it.
+ *
+ * Falling back to the public URL keeps local dev (where only `GROUP_API_URL` is
+ * set) and any un-migrated deployment working — it just takes the long way
+ * round, out through the proxy and back, carrying the internal token across the
+ * public edge.
+ */
+function internalGroupUrl(): string | undefined {
+  return process.env.GROUP_INTERNAL_URL || process.env.GROUP_API_URL;
+}
+
+async function fetchGroupOwner(groupId: string): Promise<GroupOwner | null> {
+  const baseUrl = internalGroupUrl();
+  const token = process.env.INTERNAL_SERVICE_TOKEN;
+  const serviceId = process.env.SERVICE_NAME || 'unknown-service';
+
+  if (!baseUrl || !token) {
+    logger.error('Group owner lookup not configured', {
+      hasGroupApiUrl: Boolean(baseUrl),
+      hasInternalToken: Boolean(token)
+    });
+    return null;
+  }
+
+  try {
+    const response = await fetch(`${baseUrl}/internal/groups/${encodeURIComponent(groupId)}/owner`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-internal-token': token,
+        'x-service-id': serviceId
+      },
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+
+    // A 404 is an answer, not an outage: the group is gone. Distinguished from
+    // an unreachable service because the two want opposite handling — one is
+    // permanent and cacheable, the other must be retried on the next request.
+    if (response.status === 404) {
+      logger.warn('Group owner lookup found no such group', { groupId });
+      return null;
+    }
+
+    if (!response.ok) {
+      logger.error('Group owner lookup failed', { groupId, status: response.status });
+      return null;
+    }
+
+    const body = (await response.json()) as GroupOwnerResponse;
+    if (!body.ownerEmail) {
+      logger.error('Group owner lookup returned no owner', { groupId });
+      return null;
+    }
+
+    return {
+      groupId: body.groupId ?? groupId,
+      ownerEmail: body.ownerEmail.trim().toLowerCase(),
+      memberCount: body.memberCount ?? 0,
+      deleted: body.deleted === true
+    };
+  } catch (err) {
+    logger.error('Group owner lookup errored', { groupId, error: (err as Error)?.message });
+    return null;
+  }
+}
+
+/**
+ * The group's owner, cached for {@link CACHE_TTL_MS}, or `null` when the group
+ * does not exist or group-service could not answer.
+ *
+ * Nothing negative is cached — neither a missing group nor a failure. A group
+ * that 404s is nearly always a caller passing a bad id, so caching it would
+ * spend memory on garbage, and caching a failure would keep billing the wrong
+ * subject for a minute after the outage ended.
+ */
+export async function getGroupOwner(groupId: string): Promise<GroupOwner | null> {
+  const key = String(groupId).trim();
+  if (!key) return null;
+
+  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 = fetchGroupOwner(key)
+    .then(value => {
+      if (value) putInCache(key, value);
+      return value;
+    })
+    .finally(() => {
+      inFlight.delete(key);
+    });
+
+  inFlight.set(key, request);
+  return request;
+}
+
+/**
+ * Drop a group's cached owner. Call after anything that moves the `owner` role,
+ * to collapse the window in which usage bills to the previous owner.
+ */
+export function invalidateGroupOwner(groupId: string): void {
+  cache.delete(String(groupId).trim());
+}
+
+/** Empties the whole cache. Test seam, and a lever after a bulk ownership edit. */
+export function clearGroupOwnerCache(): void {
+  cache.clear();
+  inFlight.clear();
+}

package/src/groups/index.ts

@@ -0,0 +1,5 @@
+export { getGroupOwner, invalidateGroupOwner, clearGroupOwnerCache } from './client';
+export type { GroupOwner } from './client';
+
+export { groupOwnerSubject } from './subject';
+export type { GroupIdResolver } from './subject';

package/src/groups/subject.test.ts

@@ -0,0 +1,85 @@
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+import { Request } from 'express';
+import logger from '../logging/logger';
+import { clearGroupOwnerCache } from './client';
+import { groupOwnerSubject } from './subject';
+
+const ORIGINAL_ENV = process.env;
+const ORIGINAL_FETCH = global.fetch;
+
+function ownerResponse(ownerEmail = 'owner@example.com'): Response {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => ({ success: true, groupId: 'group-1', ownerEmail, memberCount: 2, deleted: false })
+  } as Response;
+}
+
+const request = (overrides: Partial<Request> = {}) =>
+  ({ user: { id: '1', email: 'member@example.com', name: 'Member' }, originalUrl: '/api/photos', ...overrides }) as Request;
+
+beforeEach(() => {
+  process.env = {
+    ...ORIGINAL_ENV,
+    GROUP_API_URL: 'http://group-service:5006',
+    INTERNAL_SERVICE_TOKEN: 'test-internal-token'
+  };
+  clearGroupOwnerCache();
+  global.fetch = jest.fn();
+  (logger.error as jest.Mock).mockClear();
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+  global.fetch = ORIGINAL_FETCH;
+});
+
+describe('groupOwnerSubject', () => {
+  it('bills a group resource to the group owner, not the uploader', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    const subject = groupOwnerSubject(() => 'group-1');
+
+    expect(await subject(request())).toBe('owner@example.com');
+  });
+
+  it('bills a personal resource to the caller and never asks group-service', async () => {
+    const subject = groupOwnerSubject(() => undefined);
+
+    expect(await subject(request())).toBe('member@example.com');
+    expect(global.fetch).not.toHaveBeenCalled();
+  });
+
+  it('accepts an async group-id resolver', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue(ownerResponse());
+
+    const subject = groupOwnerSubject(async () => 'group-1');
+
+    expect(await subject(request())).toBe('owner@example.com');
+  });
+
+  it('falls back to the caller and logs when the owner cannot be resolved', async () => {
+    (global.fetch as jest.Mock).mockRejectedValue(new Error('ECONNREFUSED'));
+
+    const subject = groupOwnerSubject(() => 'group-1');
+
+    // Billing the caller checks the write against their own — typically
+    // smaller — allowance rather than refusing it outright, matching how the
+    // entitlement client degrades for the same class of outage.
+    expect(await subject(request())).toBe('member@example.com');
+    expect(logger.error).toHaveBeenCalledWith(
+      'Group owner unresolved; billing usage to the caller instead',
+      expect.objectContaining({ groupId: 'group-1', caller: 'member@example.com' })
+    );
+  });
+
+  it('returns undefined when there is no caller and no resolvable group, so the middleware 401s', async () => {
+    const subject = groupOwnerSubject(() => undefined);
+
+    expect(await subject(request({ user: undefined }))).toBeUndefined();
+  });
+});

package/src/groups/subject.ts

@@ -0,0 +1,50 @@
+import { Request } from 'express';
+import logger from '../logging/logger';
+import { SubjectResolver } from '../entitlements/middleware';
+import { getGroupOwner } from './client';
+
+export type GroupIdResolver = (req: Request) => string | undefined | Promise<string | undefined>;
+
+/**
+ * Builds the `subject` resolver that `requireQuota` / `requireEntitlement`
+ * already accept, for the meters whose resource can live in a group.
+ *
+ * ```ts
+ * requireQuota('storageBytes', {
+ *   subject: groupOwnerSubject(req => req.body.groupId),
+ *   amount: req => req.body.sizeBytes
+ * })
+ * ```
+ *
+ * Personal rows keep billing to the caller; group rows bill to the group's
+ * owner, because Family sells *pooled* storage and seats and the uploader's own
+ * free tier is not the pool.
+ *
+ * **When the owner cannot be resolved, it bills the caller and says so.** The
+ * alternative — refusing the write — is harsher than what the entitlement
+ * client itself does for the same class of outage (it degrades to free limits
+ * rather than denying), and the error direction here is bounded in the shape
+ * that matters: the common case is a member on a cheap personal plan uploading
+ * into a group owned by someone on Family, so falling back to the caller checks
+ * against the *smaller* allowance. It can over-grant when the caller happens to
+ * hold the richer plan, which is why it logs at `error` — a run of these means
+ * group-service is down, not that a limit is wrong.
+ */
+export function groupOwnerSubject(resolveGroupId: GroupIdResolver): SubjectResolver {
+  return async (req: Request) => {
+    const caller = req.user?.email;
+    const groupId = await resolveGroupId(req);
+    if (!groupId) return caller;
+
+    const owner = await getGroupOwner(String(groupId));
+    if (owner) return owner.ownerEmail;
+
+    logger.error('Group owner unresolved; billing usage to the caller instead', {
+      event: 'entitlement.subject_fallback',
+      groupId: String(groupId),
+      caller,
+      route: req.originalUrl
+    });
+    return caller;
+  };
+}

package/src/index.ts

@@ -27,6 +27,9 @@ export type { PaymentRequiredDetails } from './errors/HttpError';
 // Entitlements (plan limits, usage meters, enforcement)
 export * from './entitlements';
 
+// Group ownership (the quota subject for anything pooled)
+export * from './groups';
+
 // Middleware
 export { authenticateToken } from './middleware/authMiddleware';
 export {

package/dist/entitlements/mode.d.ts

@@ -1,10 +0,0 @@
-import { EntitlementsMode } from './types';
-/**
- * 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 declare function getEntitlementsMode(): EntitlementsMode;
-/** Test seam — the "already warned" latch would otherwise leak between cases. */
-export declare function resetEntitlementsModeWarning(): void;
-//# sourceMappingURL=mode.d.ts.map

package/dist/entitlements/mode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/entitlements/mode.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAM3C;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAUtD;AAED,iFAAiF;AACjF,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/dist/entitlements/mode.js

@@ -1,32 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getEntitlementsMode = getEntitlementsMode;
-exports.resetEntitlementsModeWarning = resetEntitlementsModeWarning;
-const logger_1 = __importDefault(require("../logging/logger"));
-const VALID_MODES = ['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.
- */
-function getEntitlementsMode() {
-    const raw = (process.env.ENTITLEMENTS_MODE || '').trim().toLowerCase();
-    if (!raw)
-        return 'observe';
-    if (VALID_MODES.includes(raw))
-        return raw;
-    if (!warnedAboutInvalidMode) {
-        warnedAboutInvalidMode = true;
-        logger_1.default.warn('Invalid ENTITLEMENTS_MODE, falling back to observe', { value: raw });
-    }
-    return 'observe';
-}
-/** Test seam — the "already warned" latch would otherwise leak between cases. */
-function resetEntitlementsModeWarning() {
-    warnedAboutInvalidMode = false;
-}
-//# sourceMappingURL=mode.js.map

package/dist/entitlements/mode.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"mode.js","sourceRoot":"","sources":["../../src/entitlements/mode.ts"],"names":[],"mappings":";;;;;AAYA,kDAUC;AAGD,oEAEC;AA3BD,+DAAuC;AAGvC,MAAM,WAAW,GAAgC,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;AAE/E,IAAI,sBAAsB,GAAG,KAAK,CAAC;AAEnC;;;;GAIG;AACH,SAAgB,mBAAmB;IACjC,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACvE,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAK,WAAiC,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,GAAuB,CAAC;IAErF,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAC5B,sBAAsB,GAAG,IAAI,CAAC;QAC9B,gBAAM,CAAC,IAAI,CAAC,oDAAoD,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,iFAAiF;AACjF,SAAgB,4BAA4B;IAC1C,sBAAsB,GAAG,KAAK,CAAC;AACjC,CAAC"}

package/src/entitlements/mode.test.ts

@@ -1,50 +0,0 @@
-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

@@ -1,28 +0,0 @@
-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;
-}