@tumbaland/backend-core 1.43.0 → 1.45.0

package/src/middleware/authMiddleware.ts

@@ -1,91 +0,0 @@
-import { Request, Response, NextFunction } from 'express';
-import jwt from 'jsonwebtoken';
-import { requireEnv } from '../config/env';
-import { isAccessTokenClaims } from '../oauth/tokens';
-import { UserPayload } from '../types/auth';
-import { isCurrentSession } from '../auth/session';
-import { currentGroupsOf } from '../groups/membership';
-
-/**
- * JWT authentication middleware
- * Verifies JWT token and attaches user info (and its embedded groups) to
- * the request — typed via the global `Express.Request` augmentation in
- * `../types/auth`, no `(req as any)` cast needed.
- *
- * OAuth access tokens are refused outright. They are signed with the same
- * secret, so they verify here, but they mean something this middleware has no
- * way to honour: an assistant acting within scopes, pinned to one tenant.
- * Routes that software may legitimately reach use `authenticateAgent`, which
- * enforces both — so anything still guarded by this one is a person's to do,
- * and letting a token through would be handing an assistant the account.
- */
-export async function authenticateToken(req: Request, res: Response, next: NextFunction): Promise<void> {
-  try {
-    const JWT_SECRET = requireEnv('JWT_SECRET');
-    const token = req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
-
-    if (!token) {
-      res.status(401).json({ success: false, message: 'Access token required' });
-      return;
-    }
-
-    const claims = jwt.verify(token, JWT_SECRET);
-    if (isAccessTokenClaims(claims)) {
-      res.status(403).json({
-        success: false,
-        message: 'This operation requires an interactive session, not a connected assistant'
-      });
-      return;
-    }
-
-    // A signed-out or revoked device keeps a validly signed token; only its
-    // session record says it has ended.
-    if (!(await isCurrentSession(claims))) {
-      res.status(401).json({ success: false, message: 'Session has ended' });
-      return;
-    }
-    // Membership is asked of group-service, not read from the token, so a
-    // change applies within seconds rather than at the next renewal.
-    const groups = await currentGroupsOf(claims as UserPayload);
-    req.user = { ...(claims as UserPayload), groups };
-    req.userGroups = groups;
-  } catch (error) {
-    res.status(401).json({ success: false, message: 'Invalid or expired token' });
-    return;
-  }
-  next();
-}
-/**
- * Attaches the user when a valid token is present, and never rejects.
- *
- * For routes whose response is public but *richer* when signed in — the plan
- * catalog is the case this exists for: a signed-out visitor on the landing
- * page must be able to read prices, while a signed-in one additionally gets
- * the hidden plan they are actually on.
- *
- * An invalid or expired token is treated as no token rather than as a 401. The
- * caller asked for public data; refusing it because a stale cookie is lying
- * around would break the landing page for exactly the people most likely to
- * have one.
- */
-export async function optionalAuth(req: Request, _res: Response, next: NextFunction): Promise<void> {
-  try {
-    const JWT_SECRET = requireEnv('JWT_SECRET');
-    const token = req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
-
-    if (token) {
-      const claims = jwt.verify(token, JWT_SECRET);
-      // An access token is not a session; treated as none, exactly like an
-      // expired cookie, so the route still answers with its public form.
-      // An ended session is treated as none, like an expired cookie.
-      if (!isAccessTokenClaims(claims) && (await isCurrentSession(claims))) {
-        const groups = await currentGroupsOf(claims as UserPayload);
-        req.user = { ...(claims as UserPayload), groups };
-        req.userGroups = groups;
-      }
-    }
-  } catch {
-    // Deliberately ignored — see above.
-  }
-  next();
-}

package/src/middleware/corsMiddleware.test.ts

@@ -1,135 +0,0 @@
-import express from 'express';
-import request from 'supertest';
-import { createCorsMiddleware } from './corsMiddleware';
-import { errorHandler } from './errorHandler';
-
-jest.mock('../logging/logger', () => ({
-  __esModule: true,
-  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
-}));
-
-function buildApp(origins: string) {
-  const app = express();
-  app.use(createCorsMiddleware({ origins }));
-  app.get('/ping', (_req, res) => res.json({ ok: true }));
-  app.use(errorHandler);
-  return app;
-}
-
-describe('createCorsMiddleware', () => {
-  const app = buildApp('https://allowed.example,https://also-allowed.example');
-
-  it('allows a request with no Origin header (server-to-server / health checks)', async () => {
-    const res = await request(app).get('/ping');
-    expect(res.status).toBe(200);
-    expect(res.body).toEqual({ ok: true });
-  });
-
-  it('allows a whitelisted origin and echoes it back with credentials', async () => {
-    const res = await request(app).get('/ping').set('Origin', 'https://allowed.example');
-
-    expect(res.status).toBe(200);
-    expect(res.headers['access-control-allow-origin']).toBe('https://allowed.example');
-    expect(res.headers['access-control-allow-credentials']).toBe('true');
-  });
-
-  it('rejects an origin not on the whitelist', async () => {
-    const res = await request(app).get('/ping').set('Origin', 'https://evil.example');
-
-    expect(res.status).toBe(500);
-    expect(res.headers['access-control-allow-origin']).toBeUndefined();
-  });
-
-  describe('the preflight', () => {
-    const preflight = (method: string) =>
-      request(app)
-        .options('/ping')
-        .set('Origin', 'https://allowed.example')
-        .set('Access-Control-Request-Method', method);
-
-    // A method left out here is the worst kind of CORS failure: the preflight
-    // returns 204, so the network tab shows nothing failing, and the browser
-    // quietly refuses to send the request it just asked about.
-    it.each([['GET'], ['POST'], ['PUT'], ['PATCH'], ['DELETE']])('permits %s', async (method) => {
-      const res = await preflight(method);
-
-      expect(res.headers['access-control-allow-methods'].split(',')).toContain(method);
-    });
-
-    it('does not advertise a method the services do not serve', async () => {
-      const res = await preflight('GET');
-
-      expect(res.headers['access-control-allow-methods']).not.toContain('TRACE');
-    });
-  });
-
-  it('exposes only the response headers a caller asks for', async () => {
-    // Cross-origin JavaScript cannot read a header that is not exposed — the
-    // CSV export reads its filename out of Content-Disposition
-    const exposing = express();
-    exposing.use(createCorsMiddleware({
-      origins: 'https://allowed.example',
-      exposedHeaders: ['Content-Disposition']
-    }));
-    exposing.get('/ping', (_req, res) => res.json({ ok: true }));
-
-    const res = await request(exposing).get('/ping').set('Origin', 'https://allowed.example');
-
-    expect(res.headers['access-control-expose-headers']).toBe('Content-Disposition');
-  });
-
-  it('falls back to process.env.CORS_ORIGIN when no origins option is given', async () => {
-    const ORIGINAL_ENV = process.env;
-    process.env = { ...ORIGINAL_ENV, CORS_ORIGIN: 'https://from-env.example' };
-
-    const envApp = express();
-    envApp.use(createCorsMiddleware());
-    envApp.get('/ping', (_req, res) => res.json({ ok: true }));
-    envApp.use(errorHandler);
-
-    const res = await request(envApp).get('/ping').set('Origin', 'https://from-env.example');
-    expect(res.status).toBe(200);
-    expect(res.headers['access-control-allow-origin']).toBe('https://from-env.example');
-
-    process.env = ORIGINAL_ENV;
-  });
-});
-
-describe('bypassPaths', () => {
-  const run = (middleware: ReturnType<typeof createCorsMiddleware>, path: string, origin?: string) => {
-    const req = { path, method: 'POST', headers: origin ? { origin } : {} } as never;
-    const res = { setHeader: jest.fn(), getHeader: jest.fn(), end: jest.fn() } as never;
-    const next = jest.fn();
-    middleware(req, res, next);
-    return next;
-  };
-
-  it('lets a bypassed path through with an origin that would otherwise be blocked', () => {
-    // Firefox sends a literal `Origin: null` on the consent form POST after the
-    // login redirect. It is truthy, matches no whitelist entry, and turned an
-    // approved consent into a 500.
-    const middleware = createCorsMiddleware({ origins: 'https://app.example', bypassPaths: ['/oauth'] });
-
-    const next = run(middleware, '/oauth/authorize', 'null');
-
-    expect(next).toHaveBeenCalledWith();
-  });
-
-  it('still checks the origin on every other path', () => {
-    const middleware = createCorsMiddleware({ origins: 'https://app.example', bypassPaths: ['/oauth'] });
-
-    const next = run(middleware, '/auth/profile', 'null');
-
-    expect(next).toHaveBeenCalledWith(expect.objectContaining({ message: expect.stringContaining('CORS') }));
-  });
-
-  it('matches by prefix, so nested oauth routes are covered too', () => {
-    const middleware = createCorsMiddleware({ origins: 'https://app.example', bypassPaths: ['/oauth'] });
-    expect(run(middleware, '/oauth/token', 'null')).toHaveBeenCalledWith();
-  });
-
-  it('changes nothing when no bypass is configured', () => {
-    const middleware = createCorsMiddleware({ origins: 'https://app.example' });
-    expect(run(middleware, '/oauth/authorize', 'null')).toHaveBeenCalledWith(expect.any(Error));
-  });
-});

package/src/middleware/corsMiddleware.ts

@@ -1,65 +0,0 @@
-import cors from 'cors';
-import type { RequestHandler } from 'express';
-import logger from '../logging/logger';
-
-export interface CorsMiddlewareOptions {
-  /**
-   * Comma-separated origin whitelist. Defaults to process.env.CORS_ORIGIN,
-   * read per-request so it works regardless of dotenv.config() timing.
-   */
-  origins?: string;
-  exposedHeaders?: string[];
-  /**
-   * Path prefixes that skip the origin check entirely.
-   *
-   * For endpoints the browser *navigates* to rather than fetches — an OAuth
-   * authorize page and the consent form it posts back. CORS governs
-   * script-initiated cross-origin reads and has nothing to say about a
-   * top-level form submission, but it still blocks one: Firefox sends a
-   * literal `Origin: null` after a cross-site redirect chain, which is truthy,
-   * matches no whitelist entry, and turns a legitimate consent into a 500.
-   *
-   * Nothing is weakened by skipping them. These routes carry no XHR-readable
-   * data, and what actually protects the consent POST is its signed consent
-   * token, not the origin header.
-   */
-  bypassPaths?: string[];
-}
-
-/**
- * Shared CORS middleware with an explicit origin whitelist.
- * Requests without an Origin header (server-to-server, curl, health checks)
- * are always allowed; browser requests must match the whitelist.
- */
-export function createCorsMiddleware(options: CorsMiddlewareOptions = {}): RequestHandler {
-  const bypassPaths = options.bypassPaths ?? [];
-
-  const corsHandler = cors({
-    origin: (origin, callback) => {
-      const allowedOrigins = (options.origins ?? process.env.CORS_ORIGIN ?? '')
-        .split(',')
-        .map(o => o.trim())
-        .filter(Boolean);
-      if (!origin || allowedOrigins.includes(origin)) {
-        return callback(null, true);
-      }
-      logger.warn('Blocked CORS origin', { origin });
-      return callback(new Error('Not allowed by CORS: ' + origin));
-    },
-    credentials: true,
-    // PATCH belongs here as much as PUT: leaving it out lets the preflight
-    // succeed and then has the browser block the request it just approved,
-    // which surfaces in the UI as a bare "failed to save" with a 204 in the
-    // network tab and no failing request to point at.
-    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
-    allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With', 'x-correlation-id', 'x-session-id'],
-    exposedHeaders: options.exposedHeaders
-  });
-
-  if (bypassPaths.length === 0) return corsHandler as RequestHandler;
-
-  return (req, res, next) => {
-    if (bypassPaths.some((prefix) => req.path.startsWith(prefix))) return next();
-    return (corsHandler as RequestHandler)(req, res, next);
-  };
-}

package/src/middleware/errorHandler.test.ts

@@ -1,188 +0,0 @@
-import express from 'express';
-import request from 'supertest';
-import { errorHandler } from './errorHandler';
-import { NotFoundError, ForbiddenError, PaymentRequiredError } from '../errors/HttpError';
-
-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';
-
-function namedError(name: string, message: string): Error {
-  const error = new Error(message);
-  error.name = name;
-  return error;
-}
-
-function buildApp() {
-  const app = express();
-  app.get('/boom', (_req, _res, next) => next(new Error('kaboom')));
-  app.get('/missing', (_req, _res, next) => next(new NotFoundError('Album not found')));
-  app.get('/forbidden', (_req, _res, next) => next(new ForbiddenError()));
-  app.get('/validation', (_req, _res, next) =>
-    next(namedError('ValidationError', 'CollageModel validation failed: title: Path `title` is required.'))
-  );
-  app.get('/cast', (_req, _res, next) => next(namedError('CastError', 'Cast to ObjectId failed for value "abc"')));
-  app.get('/over-quota', (_req, _res, next) =>
-    next(
-      new PaymentRequiredError('Storage limit reached', {
-        code: 'QUOTA_EXCEEDED',
-        meter: 'storageBytes',
-        used: 1073741824,
-        limit: 1073741824,
-        planCode: 'free',
-        upgradeTo: 'support'
-      })
-    )
-  );
-  app.use(errorHandler);
-  return app;
-}
-
-describe('errorHandler', () => {
-  const ORIGINAL_ENV = process.env;
-
-  beforeEach(() => {
-    process.env = { ...ORIGINAL_ENV };
-    (logger.error as jest.Mock).mockClear();
-    (logger.warn as jest.Mock).mockClear();
-  });
-
-  afterAll(() => {
-    process.env = ORIGINAL_ENV;
-  });
-
-  it('logs the error and responds 500 with a generic message in production', async () => {
-    process.env.NODE_ENV = 'production';
-    const app = buildApp();
-
-    const res = await request(app).get('/boom');
-
-    expect(res.status).toBe(500);
-    expect(res.body).toEqual({
-      success: false,
-      error: 'Internal server error',
-      message: 'Something went wrong'
-    });
-    expect(logger.error).toHaveBeenCalledWith('Unhandled error:', expect.objectContaining({ error: 'kaboom' }));
-  });
-
-  it('includes the real error message and stack in development', async () => {
-    process.env.NODE_ENV = 'development';
-    const app = buildApp();
-
-    const res = await request(app).get('/boom');
-
-    expect(res.status).toBe(500);
-    expect(res.body.message).toBe('kaboom');
-    expect(res.body.stack).toBeDefined();
-  });
-
-  it('adds CORS headers to the error response for an allowed origin', async () => {
-    process.env.NODE_ENV = 'production';
-    const app = buildApp();
-
-    const res = await request(app).get('/boom').set('Origin', 'http://localhost:3000');
-
-    expect(res.headers['access-control-allow-origin']).toBe('http://localhost:3000');
-    expect(res.headers['access-control-allow-credentials']).toBe('true');
-  });
-
-  it('does not add CORS headers for a disallowed origin', async () => {
-    process.env.NODE_ENV = 'production';
-    const app = buildApp();
-
-    const res = await request(app).get('/boom').set('Origin', 'https://evil.example');
-
-    expect(res.headers['access-control-allow-origin']).toBeUndefined();
-  });
-
-  describe('typed HttpError instances', () => {
-    it('uses the error’s own status code and message, in production too', async () => {
-      process.env.NODE_ENV = 'production';
-      const app = buildApp();
-
-      const res = await request(app).get('/missing');
-
-      expect(res.status).toBe(404);
-      expect(res.body).toEqual({ success: false, error: 'NotFoundError', message: 'Album not found' });
-    });
-
-    it('logs at warn level, not error, and without a stack trace', async () => {
-      const app = buildApp();
-
-      await request(app).get('/forbidden');
-
-      expect(logger.warn).toHaveBeenCalledWith(
-        'Request failed:',
-        expect.objectContaining({ error: 'Access denied', statusCode: 403 })
-      );
-      expect(logger.error).not.toHaveBeenCalled();
-    });
-
-    it('does not include a stack trace in the response body, even in development', async () => {
-      process.env.NODE_ENV = 'development';
-      const app = buildApp();
-
-      const res = await request(app).get('/missing');
-
-      expect(res.body.stack).toBeUndefined();
-    });
-  });
-
-  describe('Mongoose ValidationError / CastError', () => {
-    it('maps a ValidationError to 400, using its own message', async () => {
-      const app = buildApp();
-
-      const res = await request(app).get('/validation');
-
-      expect(res.status).toBe(400);
-      expect(res.body).toEqual({
-        success: false,
-        error: 'ValidationError',
-        message: 'CollageModel validation failed: title: Path `title` is required.'
-      });
-    });
-
-    it('maps a CastError (e.g. an invalid ObjectId) to 400', async () => {
-      const app = buildApp();
-
-      const res = await request(app).get('/cast');
-
-      expect(res.status).toBe(400);
-      expect(res.body.error).toBe('CastError');
-    });
-  });
-
-  describe('PaymentRequiredError', () => {
-    it('serializes the details the upgrade dialog needs alongside the envelope', async () => {
-      const app = buildApp();
-
-      const res = await request(app).get('/over-quota');
-
-      expect(res.status).toBe(402);
-      expect(res.body).toEqual({
-        success: false,
-        error: 'PaymentRequiredError',
-        message: 'Storage limit reached',
-        code: 'QUOTA_EXCEEDED',
-        meter: 'storageBytes',
-        used: 1073741824,
-        limit: 1073741824,
-        planCode: 'free',
-        upgradeTo: 'support'
-      });
-    });
-
-    it('logs a paywall hit as routine control flow, not as a server fault', async () => {
-      const app = buildApp();
-
-      await request(app).get('/over-quota');
-
-      expect(logger.error).not.toHaveBeenCalled();
-      expect(logger.warn).toHaveBeenCalledWith('Request failed:', expect.objectContaining({ statusCode: 402 }));
-    });
-  });
-});

package/src/middleware/errorHandler.ts

@@ -1,103 +0,0 @@
-import { Request, Response, NextFunction, ErrorRequestHandler } from 'express';
-import logger from '../logging/logger';
-import { HttpError } from '../errors/HttpError';
-
-interface KnownError {
-  statusCode: number;
-  name: string;
-  message: string;
-  /** Extra body fields carried by errors the client must act on (e.g. a 402's meter/limit/upgradeTo). */
-  details?: Record<string, unknown>;
-}
-
-/**
- * Recognizes error shapes that map to an obvious HTTP status without a
- * controller having to catch and re-throw them: our own typed HttpError
- * hierarchy, plus Mongoose's ValidationError (failed schema validation,
- * e.g. a missing required field) and CastError (e.g. an invalid ObjectId
- * string) — both of which are client mistakes, not server bugs, but throw
- * as plain Mongoose error classes rather than anything of ours.
- */
-function classifyError(error: Error): KnownError | null {
-  if (error instanceof HttpError) {
-    return { statusCode: error.statusCode, name: error.name, message: error.message, details: error.details };
-  }
-  if (error.name === 'ValidationError' || error.name === 'CastError') {
-    return { statusCode: 400, name: error.name, message: error.message };
-  }
-  return null;
-}
-
-/**
- * Global error handler middleware.
- *
- * Controllers throw a typed `HttpError` (BadRequestError, NotFoundError,
- * ForbiddenError, ...) instead of hand-rolling try/catch + string-matching
- * on `error.message` to pick a status code — Express 5 forwards rejected
- * promises from async route handlers here automatically. Anything that
- * isn't a recognized error type is treated as an unexpected bug: logged
- * with its full stack and returned as a generic 500 (no message leak
- * outside development), same as before this file knew about HttpError.
- */
-export const errorHandler: ErrorRequestHandler = (
-  error: Error,
-  req: Request,
-  res: Response,
-  _next: NextFunction
-): void => {
-  const known = classifyError(error);
-
-  if (known) {
-    // Client errors (4xx) are routine, expected control flow — log without
-    // a stack trace at warn level, not as if the service were broken.
-    logger.warn('Request failed:', {
-      error: known.message,
-      statusCode: known.statusCode,
-      url: req.url,
-      method: req.method,
-      correlationId: req.correlationId
-    });
-  } else {
-    logger.error('Unhandled error:', {
-      error: error.message,
-      stack: error.stack,
-      url: req.url,
-      method: req.method,
-      ip: req.ip,
-      userAgent: req.get('User-Agent'),
-      correlationId: req.correlationId
-    });
-  }
-
-  // Add CORS headers to error responses
-  const origin = req.headers.origin;
-  if (origin && (origin.includes('localhost') || origin.includes('tumbaland.eu'))) {
-    res.header('Access-Control-Allow-Origin', origin);
-    res.header('Access-Control-Allow-Credentials', 'true');
-    res.header('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
-    res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, X-Requested-With, x-correlation-id, x-session-id');
-  }
-
-  if (known) {
-    res.status(known.statusCode).json({
-      // Spread first so a stray details key can't shadow the envelope fields
-      // every client already relies on.
-      ...known.details,
-      success: false,
-      error: known.name,
-      message: known.message
-    });
-    return;
-  }
-
-  // Don't leak error details in production for unexpected errors
-  const isDevelopment = process.env.NODE_ENV === 'development';
-  const errorMessage = isDevelopment ? error.message : 'Something went wrong';
-
-  res.status(500).json({
-    success: false,
-    error: 'Internal server error',
-    message: errorMessage,
-    ...(isDevelopment && { stack: error.stack })
-  });
-};