@tumbaland/backend-core 1.22.0 → 1.24.0

package/src/middleware/errorHandler.test.ts

@@ -1,7 +1,7 @@
 import express from 'express';
 import request from 'supertest';
 import { errorHandler } from './errorHandler';
-import { NotFoundError, ForbiddenError } from '../errors/HttpError';
+import { NotFoundError, ForbiddenError, PaymentRequiredError } from '../errors/HttpError';
 
 jest.mock('../logging/logger', () => ({
   __esModule: true,
@@ -25,6 +25,18 @@ function buildApp() {
     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: 'personal'
+      })
+    )
+  );
   app.use(errorHandler);
   return app;
 }
@@ -143,4 +155,34 @@ describe('errorHandler', () => {
       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: 'personal'
+      });
+    });
+
+    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

@@ -6,6 +6,8 @@ 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>;
 }
 
 /**
@@ -18,7 +20,7 @@ interface KnownError {
  */
 function classifyError(error: Error): KnownError | null {
   if (error instanceof HttpError) {
-    return { statusCode: error.statusCode, name: error.name, message: error.message };
+    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 };
@@ -78,6 +80,9 @@ export const errorHandler: ErrorRequestHandler = (
 
   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

package/src/middleware/internalServiceAuth.test.ts

@@ -0,0 +1,173 @@
+import { Request, Response } from 'express';
+
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn(), http: jest.fn() }
+}));
+
+import {
+  allowUserOrInternalService,
+  internalServiceTokenBypass,
+  requireInternalServiceToken,
+  verifyInternalToken
+} from './internalServiceAuth';
+
+function mockRes(): Response {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+}
+
+function mockReq(headers: Record<string, string> = {}): Request {
+  return { headers, originalUrl: '/internal/entitlements' } as unknown as Request;
+}
+
+const ORIGINAL_ENV = process.env;
+
+beforeEach(() => {
+  process.env = { ...ORIGINAL_ENV, INTERNAL_SERVICE_TOKEN: 'test-internal-token' };
+});
+
+afterAll(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('verifyInternalToken', () => {
+  it('accepts only an exact match', () => {
+    expect(verifyInternalToken('test-internal-token')).toBe(true);
+    expect(verifyInternalToken('test-internal-tokeN')).toBe(false);
+  });
+
+  it('rejects a prefix or an extension without throwing on the length mismatch', () => {
+    expect(verifyInternalToken('test')).toBe(false);
+    expect(verifyInternalToken('test-internal-token-and-more')).toBe(false);
+  });
+
+  it('rejects anything that is not a non-empty string', () => {
+    expect(verifyInternalToken(undefined)).toBe(false);
+    expect(verifyInternalToken('')).toBe(false);
+    expect(verifyInternalToken(['test-internal-token'])).toBe(false);
+  });
+
+  it('rejects everything when no token is configured', () => {
+    delete process.env.INTERNAL_SERVICE_TOKEN;
+
+    expect(verifyInternalToken('test-internal-token')).toBe(false);
+  });
+});
+
+describe('requireInternalServiceToken', () => {
+  it('marks the request internal and continues on a valid token', () => {
+    const req = mockReq({ 'x-internal-token': 'test-internal-token', 'x-service-id': 'album-service' });
+    const next = jest.fn();
+
+    requireInternalServiceToken(req, mockRes(), next);
+
+    expect(req.isInternalService).toBe(true);
+    expect(req.serviceIdentifier).toBe('album-service');
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('defaults the service identifier when the header is absent', () => {
+    const req = mockReq({ 'x-internal-token': 'test-internal-token' });
+
+    requireInternalServiceToken(req, mockRes(), jest.fn());
+
+    expect(req.serviceIdentifier).toBe('unknown');
+  });
+
+  it('rejects a missing token with 401', () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    requireInternalServiceToken(mockReq(), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('rejects a wrong token with 401', () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    requireInternalServiceToken(mockReq({ 'x-internal-token': 'wrong' }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('fails with 500 rather than open when the deployment has no token configured', () => {
+    delete process.env.INTERNAL_SERVICE_TOKEN;
+    const res = mockRes();
+    const next = jest.fn();
+
+    requireInternalServiceToken(mockReq({ 'x-internal-token': 'anything' }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(500);
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe('internalServiceTokenBypass', () => {
+  it('passes a request with no internal header through untouched, for normal user auth', () => {
+    const req = mockReq();
+    const next = jest.fn();
+
+    internalServiceTokenBypass(req, mockRes(), next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(req.isInternalService).toBeUndefined();
+  });
+
+  it('rejects a bogus token instead of letting it stand in for authentication', () => {
+    // The bug this replaces: the header's mere presence used to skip JWT
+    // verification, so `x-internal-token: anything` reached the controller
+    // unauthenticated on any route that did not mount a second middleware.
+    const res = mockRes();
+    const next = jest.fn();
+
+    internalServiceTokenBypass(mockReq({ 'x-internal-token': 'anything' }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('marks a valid internal call and continues', () => {
+    const req = mockReq({ 'x-internal-token': 'test-internal-token' });
+    const next = jest.fn();
+
+    internalServiceTokenBypass(req, mockRes(), next);
+
+    expect(req.isInternalService).toBe(true);
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('allowUserOrInternalService', () => {
+  it('allows an internal service', () => {
+    const next = jest.fn();
+
+    allowUserOrInternalService({ isInternalService: true } as Request, mockRes(), next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows an authenticated user', () => {
+    const next = jest.fn();
+
+    allowUserOrInternalService({ user: { email: 'u@example.com' } } as Request, mockRes(), next);
+
+    expect(next).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects anyone else with 401', () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    allowUserOrInternalService({} as Request, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+});

package/src/middleware/internalServiceAuth.ts

@@ -0,0 +1,96 @@
+import { Request, RequestHandler } from 'express';
+import { timingSafeEqual } from 'crypto';
+import logger from '../logging/logger';
+
+/**
+ * Fields set by the internal-service middlewares below. Declared globally so
+ * routers and controllers read `req.isInternalService` off the same `Request`
+ * type Express itself uses, with no cast at the call site.
+ */
+declare global {
+  namespace Express {
+    interface Request {
+      isInternalService?: boolean;
+      serviceIdentifier?: string;
+    }
+  }
+}
+
+export const INTERNAL_TOKEN_HEADER = 'x-internal-token';
+export const SERVICE_ID_HEADER = 'x-service-id';
+
+/**
+ * Constant-time comparison of the presented token against the configured one.
+ *
+ * `===` on secrets leaks their prefix through timing, and `timingSafeEqual`
+ * throws on a length mismatch (which is itself a leak), so length is compared
+ * first and both buffers are hashed to a fixed width — a token of the wrong
+ * length takes the same path as one of the right length with wrong bytes.
+ */
+export function verifyInternalToken(presented: unknown): boolean {
+  const expected = process.env.INTERNAL_SERVICE_TOKEN;
+  if (!expected) return false;
+  if (typeof presented !== 'string' || presented.length === 0) return false;
+
+  const a = Buffer.from(presented, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+
+function markInternal(req: Request): void {
+  req.isInternalService = true;
+  req.serviceIdentifier = (req.headers[SERVICE_ID_HEADER] as string) || 'unknown';
+}
+
+/**
+ * Hard gate for endpoints that are only ever called service-to-service.
+ * No user-JWT fallback: a missing or wrong token is always a 401.
+ */
+export const requireInternalServiceToken: RequestHandler = (req, res, next) => {
+  if (!process.env.INTERNAL_SERVICE_TOKEN) {
+    logger.error('INTERNAL_SERVICE_TOKEN not configured');
+    res.status(500).json({ success: false, message: 'Internal service authentication not configured' });
+    return;
+  }
+
+  if (!verifyInternalToken(req.headers[INTERNAL_TOKEN_HEADER])) {
+    logger.warn('Rejected internal service request', {
+      serviceId: (req.headers[SERVICE_ID_HEADER] as string) || 'unknown',
+      path: req.originalUrl
+    });
+    res.status(401).json({ success: false, message: 'Invalid or missing internal service token' });
+    return;
+  }
+
+  markInternal(req);
+  next();
+};
+
+/**
+ * For routers that serve both browsers and services: when the internal-token
+ * header is present it is *verified here*, and a bad token is rejected rather
+ * than passed along.
+ *
+ * The bug this replaces: treating the mere presence of the header as grounds to
+ * skip JWT verification, leaving the real check to a second middleware mounted
+ * per-router — so any route that forgot to mount the second one was reachable
+ * by sending `x-internal-token: anything`.
+ */
+export const internalServiceTokenBypass: RequestHandler = (req, res, next) => {
+  const presented = req.headers[INTERNAL_TOKEN_HEADER];
+  if (presented === undefined) {
+    next();
+    return;
+  }
+  requireInternalServiceToken(req, res, next);
+};
+
+/** Allows a request that authenticated as either a user or an internal service. */
+export const allowUserOrInternalService: RequestHandler = (req, res, next) => {
+  if (req.isInternalService || req.user) {
+    next();
+    return;
+  }
+  res.status(401).json({ success: false, message: 'Authentication required' });
+};