@tumbaland/backend-core 1.44.0 → 1.46.0

package/src/audit/service.ts

@@ -1,95 +0,0 @@
-import { AuditEvent, type IAuditEvent, type ToolCall } from './AuditEvent';
-import type { ActorKind } from './actor';
-
-export interface AuditQuery {
-  userId: string;
-  /** narrow to one actor — a key's id or an OAuth client id */
-  credentialId?: string;
-  actorKind?: ActorKind;
-  action?: IAuditEvent['action'];
-  resource?: string;
-  /** narrow to one area — 'relationship-service', 'album-service' */
-  service?: string;
-  from?: Date;
-  to?: Date;
-  limit?: number;
-  page?: number;
-}
-
-export interface AuditEntry {
-  id: string;
-  at: string;
-  service: string;
-  action: IAuditEvent['action'];
-  resource: string;
-  resourceId?: string;
-  actorKind: ActorKind;
-  actorLabel: string;
-  actorCredentialId?: string;
-  tenant: string;
-  changes?: Record<string, { from: unknown; to: unknown }>;
-  snapshot?: Record<string, unknown>;
-  count?: number;
-  /** present on 'call': which tool ran, how long it took, and what it cost */
-  tool?: ToolCall;
-}
-
-const toEntry = (event: IAuditEvent): AuditEntry => ({
-  id: String(event._id),
-  at: event.at.toISOString(),
-  service: event.service,
-  action: event.action,
-  resource: event.resource,
-  resourceId: event.resourceId,
-  actorKind: event.actorKind,
-  actorLabel: event.actorLabel,
-  actorCredentialId: event.actorCredentialId,
-  tenant: event.tenant,
-  changes: event.changes,
-  snapshot: event.snapshot,
-  count: event.count,
-  tool: event.tool
-});
-
-/**
- * One account's trail, newest first.
- *
- * Always scoped to `userId` by the query rather than filtered afterwards, so
- * there is no path where a wider read is one forgotten condition away. The trail
- * carries old values of journal entries, which makes it as sensitive as the
- * journal itself.
- */
-export const listAuditEvents = async (
-  query: AuditQuery
-): Promise<{ events: AuditEntry[]; total: number; page: number; totalPages: number }> => {
-  const limit = Math.min(query.limit ?? 50, 200);
-  const page = Math.max(query.page ?? 1, 1);
-
-  const filter: Record<string, unknown> = { userId: query.userId };
-  if (query.credentialId) filter.actorCredentialId = query.credentialId;
-  if (query.actorKind) filter.actorKind = query.actorKind;
-  if (query.action) filter.action = query.action;
-  if (query.resource) filter.resource = query.resource;
-  if (query.service) filter.service = query.service;
-  if (query.from || query.to) {
-    const at: Record<string, Date> = {};
-    if (query.from) at.$gte = query.from;
-    if (query.to) at.$lte = query.to;
-    filter.at = at;
-  }
-
-  const [events, total] = await Promise.all([
-    AuditEvent.find(filter)
-      .sort({ at: -1 })
-      .skip((page - 1) * limit)
-      .limit(limit),
-    AuditEvent.countDocuments(filter)
-  ]);
-
-  return {
-    events: events.map(toEntry),
-    total,
-    page,
-    totalPages: Math.ceil(total / limit)
-  };
-};

package/src/auth/session.test.ts

@@ -1,89 +0,0 @@
-const connection = { readyState: 1, collection: jest.fn() };
-
-jest.mock('mongoose', () => {
-  const actual = jest.requireActual('mongoose');
-  return { __esModule: true, default: { connection, Types: actual.Types } };
-});
-
-import mongoose from 'mongoose';
-import {
-  USER_SESSIONS_COLLECTION,
-  isCurrentSession,
-  isLegacySessionlessToken,
-  overrideSessionCheckForTests
-} from './session';
-
-const USER_ID = 'b'.repeat(24);
-const SESSION_ID = 'a'.repeat(24);
-const now = Math.floor(Date.now() / 1000);
-
-describe('isLegacySessionlessToken', () => {
-  it('accepts a pre-sessions token that lived 24 hours at most', () => {
-    expect(isLegacySessionlessToken({ iat: now, exp: now + 24 * 60 * 60 })).toBe(true);
-  });
-
-  it('refuses a session-less token that lives longer, or has no expiry', () => {
-    expect(isLegacySessionlessToken({ iat: now, exp: now + 24 * 60 * 60 + 1 })).toBe(false);
-    expect(isLegacySessionlessToken({ iat: now })).toBe(false);
-  });
-
-  it('is never true for a token that names a session', () => {
-    expect(isLegacySessionlessToken({ sid: SESSION_ID, iat: now, exp: now + 60 })).toBe(false);
-  });
-});
-
-describe('isCurrentSession', () => {
-  const findOne = jest.fn();
-
-  beforeEach(() => {
-    overrideSessionCheckForTests();
-    findOne.mockReset();
-    connection.readyState = 1;
-    connection.collection.mockReset().mockReturnValue({ findOne });
-  });
-
-  it('accepts a live session that belongs to the token user', async () => {
-    findOne.mockResolvedValue({ _id: SESSION_ID });
-
-    await expect(isCurrentSession({ id: USER_ID, sid: SESSION_ID })).resolves.toBe(true);
-
-    expect(mongoose.connection.collection).toHaveBeenCalledWith(USER_SESSIONS_COLLECTION);
-    const [query, options] = findOne.mock.calls[0];
-    expect(query._id.toString()).toBe(SESSION_ID);
-    expect(query.userId.toString()).toBe(USER_ID);
-    expect(query.expiresAt.$gt).toBeInstanceOf(Date);
-    expect(options).toMatchObject({ readPreference: 'primary' });
-  });
-
-  it('refuses a revoked or expired session', async () => {
-    findOne.mockResolvedValue(null);
-
-    await expect(isCurrentSession({ id: USER_ID, sid: SESSION_ID })).resolves.toBe(false);
-  });
-
-  it('refuses while the database is unavailable rather than letting the token through', async () => {
-    connection.readyState = 0;
-
-    await expect(isCurrentSession({ id: USER_ID, sid: SESSION_ID })).resolves.toBe(false);
-    expect(findOne).not.toHaveBeenCalled();
-  });
-
-  it.each([
-    [{ id: USER_ID, sid: 'not-an-id' }],
-    [{ id: 'not-an-id', sid: SESSION_ID }],
-    [{ id: USER_ID, sid: 42 }],
-    [null]
-  ])('refuses malformed claims %j without a lookup', async (claims) => {
-    await expect(isCurrentSession(claims)).resolves.toBe(false);
-    expect(findOne).not.toHaveBeenCalled();
-  });
-
-  it('accepts a short-lived pre-sessions token without a lookup', async () => {
-    await expect(isCurrentSession({ id: USER_ID, iat: now, exp: now + 60 })).resolves.toBe(true);
-    expect(findOne).not.toHaveBeenCalled();
-  });
-
-  it('refuses a long-lived token with no session', async () => {
-    await expect(isCurrentSession({ id: USER_ID, iat: now, exp: now + 90 * 24 * 60 * 60 })).resolves.toBe(false);
-  });
-});

package/src/auth/session.ts

@@ -1,75 +0,0 @@
-import mongoose from 'mongoose';
-
-/**
- * One document per signed-in device, owned and written by auth-service; every
- * other service only reads it here. A session token names its document in the
- * `sid` claim, and the token is only as good as that document: deleting it
- * (sign-out, "sign out this device") ends the session on its next request, in
- * every service, and its `expiresAt` (slid forward by auth-service while the
- * device is in use, never past a hard cap from sign-in) is what idle expiry
- * actually means.
- */
-export const USER_SESSIONS_COLLECTION = 'user_sessions';
-
-/**
- * Tokens minted before sessions existed carry no `sid` and lived 24 hours.
- * auth-service upgrades one to a session the next time `/auth/verify` sees it,
- * so this window closes by itself a day after the sessions release; the branch
- * accepting them can be deleted after that.
- */
-const LEGACY_TOKEN_MAX_LIFETIME_SECONDS = 24 * 60 * 60;
-
-const OBJECT_ID = /^[a-f\d]{24}$/i;
-
-/** True for a pre-sessions token: no `sid`, and the old 24-hour lifetime at most. */
-export function isLegacySessionlessToken(claims: unknown): boolean {
-  if (!claims || typeof claims !== 'object') return false;
-  const { sid, iat, exp } = claims as { sid?: unknown; iat?: unknown; exp?: unknown };
-  return (
-    sid === undefined &&
-    Number.isSafeInteger(iat) &&
-    Number.isSafeInteger(exp) &&
-    (exp as number) - (iat as number) <= LEGACY_TOKEN_MAX_LIFETIME_SECONDS
-  );
-}
-
-type SessionCheck = (claims: unknown) => Promise<boolean>;
-
-/**
- * Whether a verified session token still stands: for a token with a `sid`,
- * its session belongs to the token's user and has neither been revoked nor
- * expired. Read on the primary, uncached, so a revocation holds from the next
- * request.
- */
-const checkSessionInDatabase: SessionCheck = async (claims) => {
-  if (!claims || typeof claims !== 'object') return false;
-  const { id, sid } = claims as { id?: unknown; sid?: unknown };
-  if (sid === undefined) return isLegacySessionlessToken(claims);
-  if (typeof sid !== 'string' || !OBJECT_ID.test(sid)) return false;
-  if (typeof id !== 'string' || !OBJECT_ID.test(id)) return false;
-  // Refuse rather than queue an authentication query while the database is down.
-  if (mongoose.connection.readyState !== 1) return false;
-
-  const session = await mongoose.connection.collection(USER_SESSIONS_COLLECTION).findOne(
-    {
-      _id: new mongoose.Types.ObjectId(sid),
-      userId: new mongoose.Types.ObjectId(id),
-      expiresAt: { $gt: new Date() }
-    },
-    { projection: { _id: 1 }, readPreference: 'primary', maxTimeMS: 3000 }
-  );
-  return session !== null;
-};
-
-let sessionCheck: SessionCheck = checkSessionInDatabase;
-
-export const isCurrentSession = (claims: unknown): Promise<boolean> => sessionCheck(claims);
-
-/**
- * Replaces the check, for tests only; pass nothing to restore the real one.
- * Not exported from the package index: service suites reach it through the
- * `@tumbaland/backend-core/testing` entry point (see testing.js).
- */
-export function overrideSessionCheckForTests(check?: SessionCheck): void {
-  sessionCheck = check ?? checkSessionInDatabase;
-}

package/src/config/env.test.ts

@@ -1,28 +0,0 @@
-import { requireEnv } from './env';
-
-describe('requireEnv', () => {
-  const ORIGINAL_ENV = process.env;
-
-  beforeEach(() => {
-    process.env = { ...ORIGINAL_ENV };
-  });
-
-  afterAll(() => {
-    process.env = ORIGINAL_ENV;
-  });
-
-  it('returns the value when the variable is set', () => {
-    process.env.MY_VAR = 'hello';
-    expect(requireEnv('MY_VAR')).toBe('hello');
-  });
-
-  it('throws when the variable is missing', () => {
-    delete process.env.MY_VAR;
-    expect(() => requireEnv('MY_VAR')).toThrow('Missing required environment variable: MY_VAR');
-  });
-
-  it('throws when the variable is an empty string', () => {
-    process.env.MY_VAR = '';
-    expect(() => requireEnv('MY_VAR')).toThrow('Missing required environment variable: MY_VAR');
-  });
-});

package/src/config/env.ts

@@ -1,13 +0,0 @@
-/**
- * Returns the value of a required environment variable.
- * Throws if the variable is missing or empty — call at service startup
- * (after dotenv.config()) so misconfigured services fail fast instead of
- * running with insecure defaults.
- */
-export function requireEnv(name: string): string {
-  const value = process.env[name];
-  if (!value) {
-    throw new Error(`Missing required environment variable: ${name}`);
-  }
-  return value;
-}

package/src/database/connection.test.ts

@@ -1,188 +0,0 @@
-jest.mock('../logging/logger', () => ({
-  __esModule: true,
-  default: { info: jest.fn(), error: jest.fn(), warn: jest.fn(), debug: jest.fn(), http: jest.fn() }
-}));
-
-const connectionHandlers: Record<string, (...args: any[]) => void> = {};
-
-jest.mock('mongoose', () => ({
-  __esModule: true,
-  default: {
-    connect: jest.fn(),
-    connection: {
-      on: jest.fn((event: string, handler: (...args: any[]) => void) => {
-        connectionHandlers[event] = handler;
-      }),
-      close: jest.fn()
-    }
-  }
-}));
-
-import mongoose from 'mongoose';
-import logger from '../logging/logger';
-import { disconnectDB } from './connection';
-
-/**
- * `connection.ts` keeps module-level `connected`/`pending` flags, so each
- * connectDB scenario needs its own fresh copy of the module —
- * isolateModulesAsync sandboxes that without leaking into other tests in this
- * file the way a blanket jest.resetModules() would.
- *
- * Note that this does NOT re-create the mongoose/logger mocks: a jest.mock
- * factory result is shared across isolated registries, so the objects returned
- * here are the same instances every time. Resetting their implementations is
- * beforeEach's job — see the comment there.
- */
-async function freshConnectDB() {
-  let connectDBFn!: typeof import('./connection').connectDB;
-  let mongooseMock!: typeof mongoose;
-  let loggerMock!: typeof logger;
-
-  await jest.isolateModulesAsync(async () => {
-    mongooseMock = (await import('mongoose')).default as unknown as typeof mongoose;
-    loggerMock = (await import('../logging/logger')).default as unknown as typeof logger;
-    connectDBFn = (await import('./connection')).connectDB;
-  });
-
-  return { connectDB: connectDBFn, mongoose: mongooseMock, logger: loggerMock };
-}
-
-describe('connectDB', () => {
-  const ORIGINAL_ENV = process.env;
-
-  beforeEach(() => {
-    process.env = { ...ORIGINAL_ENV };
-    delete process.env.MONGODB_URI;
-    for (const key of Object.keys(connectionHandlers)) delete connectionHandlers[key];
-
-    // `clearMocks: true` only clears recorded calls, not implementations, so a
-    // mockRejectedValue set by one test stays installed for every test after
-    // it. Reset connect explicitly — but not connection.on, whose factory
-    // implementation is what records into connectionHandlers.
-    (mongoose.connect as jest.Mock).mockReset();
-  });
-
-  afterAll(() => {
-    process.env = ORIGINAL_ENV;
-  });
-
-  it('throws when no MongoDB URI is available', async () => {
-    const { connectDB } = await freshConnectDB();
-    await expect(connectDB('my-service')).rejects.toThrow('MONGODB_URI environment variable is not set');
-  });
-
-  it('connects using the explicit uri argument over the env var', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose, logger } = await freshConnectDB();
-
-    await connectDB('my-service', 'mongodb://explicit-uri');
-
-    expect(mongoose.connect).toHaveBeenCalledWith('mongodb://explicit-uri');
-    expect(logger.info).toHaveBeenCalledWith('MongoDB connected', { service: 'my-service' });
-  });
-
-  it('falls back to MONGODB_URI when no explicit uri is given', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose } = await freshConnectDB();
-
-    await connectDB('my-service');
-
-    expect(mongoose.connect).toHaveBeenCalledWith('mongodb://env-uri');
-  });
-
-  it('is a no-op on a second call once already connected', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose } = await freshConnectDB();
-
-    await connectDB('my-service');
-    await connectDB('my-service');
-
-    expect(mongoose.connect).toHaveBeenCalledTimes(1);
-  });
-
-  it('logs and rethrows when mongoose.connect fails', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose, logger } = await freshConnectDB();
-    (mongoose.connect as jest.Mock).mockRejectedValueOnce(new Error('ECONNREFUSED'));
-
-    await expect(connectDB('my-service')).rejects.toThrow('ECONNREFUSED');
-    expect(logger.error).toHaveBeenCalledWith('Failed to connect to MongoDB', {
-      service: 'my-service',
-      error: 'ECONNREFUSED'
-    });
-  });
-
-  /**
-   * The driver retries internally for serverSelectionTimeoutMS; anything that
-   * reaches us is a real fault, so one failure is one rejection. Callers exit
-   * non-zero and the container restart policy takes it from there.
-   */
-  it('does not retry a failed connection', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose } = await freshConnectDB();
-    (mongoose.connect as jest.Mock).mockRejectedValue(new Error('auth failed'));
-
-    await expect(connectDB('my-service')).rejects.toThrow('auth failed');
-
-    expect(mongoose.connect).toHaveBeenCalledTimes(1);
-  });
-
-  it('clears the in-flight promise so a later call can retry', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose } = await freshConnectDB();
-    (mongoose.connect as jest.Mock).mockRejectedValueOnce(new Error('not ready'));
-
-    await expect(connectDB('my-service')).rejects.toThrow('not ready');
-    await connectDB('my-service');
-
-    expect(mongoose.connect).toHaveBeenCalledTimes(2);
-  });
-
-  it('lets concurrent callers share one connection attempt', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, mongoose } = await freshConnectDB();
-
-    await Promise.all([connectDB('my-service'), connectDB('my-service')]);
-
-    expect(mongoose.connect).toHaveBeenCalledTimes(1);
-  });
-
-  it('registers error/disconnected/reconnected handlers that log through the shared logger', async () => {
-    process.env.MONGODB_URI = 'mongodb://env-uri';
-    const { connectDB, logger } = await freshConnectDB();
-
-    await connectDB('my-service');
-
-    connectionHandlers.error(new Error('boom'));
-    expect(logger.error).toHaveBeenCalledWith('MongoDB connection error', { service: 'my-service', error: 'boom' });
-
-    connectionHandlers.disconnected();
-    expect(logger.warn).toHaveBeenCalledWith('MongoDB disconnected', { service: 'my-service' });
-
-    connectionHandlers.reconnected();
-    expect(logger.info).toHaveBeenCalledWith('MongoDB reconnected', { service: 'my-service' });
-  });
-});
-
-describe('disconnectDB', () => {
-  beforeEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it('closes the connection and logs success', async () => {
-    await disconnectDB('my-service');
-
-    expect(mongoose.connection.close).toHaveBeenCalled();
-    expect(logger.info).toHaveBeenCalledWith('MongoDB connection closed', { service: 'my-service' });
-  });
-
-  it('logs and rethrows when closing fails', async () => {
-    (mongoose.connection.close as jest.Mock).mockRejectedValueOnce(new Error('close failed'));
-
-    await expect(disconnectDB('my-service')).rejects.toThrow('close failed');
-    expect(logger.error).toHaveBeenCalledWith('Error closing MongoDB connection', {
-      service: 'my-service',
-      error: 'close failed'
-    });
-  });
-});

package/src/database/connection.ts

@@ -1,90 +0,0 @@
-import mongoose from 'mongoose';
-import logger from '../logging/logger';
-
-let connected = false;
-/**
- * Set while a connection attempt is in flight so concurrent callers await that
- * attempt instead of opening a second one against the same mongoose singleton.
- */
-let pending: Promise<void> | null = null;
-let listenersRegistered = false;
-
-/**
- * Connects once and throws on failure. There is deliberately no retry loop here.
- *
- * MongoDB is Atlas (`mongodb+srv://`), not a sidecar container, so there is no
- * boot race to ride out — and the driver already retries for us: `connect()`
- * keeps doing server selection for `serverSelectionTimeoutMS` (30s by default)
- * before it rejects, so a transient DNS or network blip is absorbed there.
- * Anything that survives that is a real fault — bad credentials, an IP missing
- * from the Atlas allowlist, a dead cluster — and no amount of retrying fixes it.
- *
- * Callers exit non-zero when this throws, which hands the problem to the
- * container restart policy (`restart: unless-stopped`) that already supervises
- * every service. One supervisor, and a service that can't reach its database
- * shows up as a restarting container instead of a healthy one serving errors.
- */
-export const connectDB = async (serviceName?: string, uri?: string): Promise<void> => {
-  if (connected) return;
-  if (pending) return pending;
-
-  const mongoUri = uri || process.env.MONGODB_URI;
-  if (!mongoUri) {
-    throw new Error('MONGODB_URI environment variable is not set');
-  }
-
-  pending = connectOnce(mongoUri, serviceName).finally(() => {
-    pending = null;
-  });
-
-  return pending;
-};
-
-async function connectOnce(mongoUri: string, serviceName: string | undefined): Promise<void> {
-  try {
-    await mongoose.connect(mongoUri);
-    connected = true;
-
-    registerConnectionListeners(serviceName);
-    logger.info('MongoDB connected', { service: serviceName });
-  } catch (error) {
-    logger.error('Failed to connect to MongoDB', {
-      service: serviceName,
-      error: (error as Error).message
-    });
-    throw error;
-  }
-}
-
-/**
- * Mongoose reconnects on its own once an initial connection has succeeded, so
- * these only report state — but without them a drop is silent and the only
- * symptom is the health endpoint flipping to "disconnected".
- */
-function registerConnectionListeners(serviceName?: string): void {
-  if (listenersRegistered) return;
-  listenersRegistered = true;
-
-  mongoose.connection.on('error', (err: Error) => {
-    logger.error('MongoDB connection error', { service: serviceName, error: err.message });
-  });
-
-  mongoose.connection.on('disconnected', () => {
-    logger.warn('MongoDB disconnected', { service: serviceName });
-  });
-
-  mongoose.connection.on('reconnected', () => {
-    logger.info('MongoDB reconnected', { service: serviceName });
-  });
-}
-
-export const disconnectDB = async (serviceName?: string): Promise<void> => {
-  try {
-    await mongoose.connection.close();
-    connected = false;
-    logger.info('MongoDB connection closed', { service: serviceName });
-  } catch (error) {
-    logger.error('Error closing MongoDB connection', { service: serviceName, error: (error as Error).message });
-    throw error;
-  }
-};

package/src/entitlements/UsageMeter.ts

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