@tumbaland/backend-core 1.29.0 → 1.31.0

package/src/apiKeys/crypto.ts

@@ -0,0 +1,163 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+  scryptSync,
+  timingSafeEqual
+} from 'crypto';
+import { requireEnv } from '../config/env';
+
+/**
+ * Key material and the two different things we do with it.
+ *
+ * A presented key is checked against a SHA-256 digest — fast, because it runs on
+ * every authenticated request. Plain SHA-256 rather than bcrypt is right here
+ * and wrong for passwords: the secret is 32 bytes from a CSPRNG, so there is no
+ * dictionary to attack and nothing for a slow hash to buy.
+ *
+ * Separately, the key is stored encrypted so the owner can look it up again
+ * later. That is a deliberate trade — see `encryptSecret` — and the reason the
+ * digest is kept as well: verification never touches the reversible copy.
+ */
+
+/** `tmb_live_<id>_<secret>` — the prefix makes a leaked key greppable in logs. */
+const KEY_PREFIX = 'tmb_live';
+const ID_BYTES = 6; // 12 hex chars, the public half
+const SECRET_BYTES = 32;
+
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12;
+/** Fixed: the input is a high-entropy env secret, not a password, so a per-record salt buys nothing. */
+const KDF_SALT = 'tumbaland/api-key/v1';
+
+export interface GeneratedKey {
+  /** the whole key, shown to the user and never stored in this form */
+  token: string;
+  /** the public half, indexed for lookup */
+  id: string;
+  /** SHA-256 of the secret half, for verification */
+  hash: string;
+}
+
+/** Derive the AES key once per process; scrypt is deliberately slow. */
+let cachedKey: Buffer | null = null;
+function encryptionKey(): Buffer {
+  if (!cachedKey) {
+    cachedKey = scryptSync(requireEnv('API_KEY_ENCRYPTION_SECRET'), KDF_SALT, 32);
+  }
+  return cachedKey;
+}
+
+/** Test seam: the derived key is cached for the life of the process. */
+export const resetEncryptionKeyCache = (): void => {
+  cachedKey = null;
+};
+
+/**
+ * Whether keys can be issued and revealed at all.
+ *
+ * Only the reversible copy needs the secret — verification runs off the digest —
+ * so a service that merely accepts keys works without it. That asymmetry is easy
+ * to get wrong in a deployment, so callers can ask rather than discovering it
+ * through a 500 on someone's first key.
+ */
+export const isEncryptionConfigured = (): boolean =>
+  Boolean(process.env.API_KEY_ENCRYPTION_SECRET);
+
+export const sha256 = (value: string): string =>
+  createHash('sha256').update(value, 'utf8').digest('hex');
+
+export const generateKey = (): GeneratedKey => {
+  const id = randomBytes(ID_BYTES).toString('hex');
+  const secret = randomBytes(SECRET_BYTES).toString('base64url');
+
+  return {
+    token: `${KEY_PREFIX}_${id}_${secret}`,
+    id,
+    hash: sha256(secret)
+  };
+};
+
+export interface ParsedKey {
+  id: string;
+  secret: string;
+}
+
+/**
+ * Split a presented key into its public id and its secret half.
+ *
+ * Returns null rather than throwing: an unparseable token is an ordinary failed
+ * authentication, not an exceptional condition, and the caller answers both the
+ * same way.
+ */
+export const parseKey = (token: unknown): ParsedKey | null => {
+  if (typeof token !== 'string') return null;
+
+  // Matched positionally rather than split on '_': the base64url alphabet
+  // includes '_', so a secret can contain any number of them and splitting
+  // would reject roughly a third of otherwise valid keys. The id is
+  // fixed-width, so everything after it is the secret.
+  const match = token.match(/^tmb_live_([0-9a-f]{12})_(.+)$/);
+  if (!match) return null;
+  if (match[2].length < 16) return null;
+
+  return { id: match[1], secret: match[2] };
+};
+
+/** True when a token even looks like one of ours — lets the caller skip a JWT parse. */
+export const looksLikeApiKey = (token: unknown): boolean =>
+  typeof token === 'string' && token.startsWith(`${KEY_PREFIX}_`);
+
+/** Constant-time digest comparison, so a wrong key leaks nothing through timing. */
+export const secretMatches = (secret: string, expectedHash: string): boolean => {
+  const presented = Buffer.from(sha256(secret), 'hex');
+  const expected = Buffer.from(expectedHash, 'hex');
+  if (presented.length !== expected.length) return false;
+  return timingSafeEqual(presented, expected);
+};
+
+export interface SealedSecret {
+  ciphertext: string;
+  iv: string;
+  tag: string;
+}
+
+/**
+ * Encrypt the key so it can be shown again later.
+ *
+ * Storing a recoverable copy is weaker than hashing alone: whoever holds both
+ * the database and `API_KEY_ENCRYPTION_SECRET` can mint the plaintext. It buys
+ * the ability to re-read a key you have lost, which the product wants. The
+ * secret lives outside the database precisely so that a dump, a backup, or a
+ * read-only replica is not on its own enough.
+ */
+export const encryptSecret = (token: string): SealedSecret => {
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv(ALGORITHM, encryptionKey(), iv);
+  const ciphertext = Buffer.concat([cipher.update(token, 'utf8'), cipher.final()]);
+
+  return {
+    ciphertext: ciphertext.toString('base64'),
+    iv: iv.toString('base64'),
+    tag: cipher.getAuthTag().toString('base64')
+  };
+};
+
+/**
+ * Recover a stored key. Throws when the ciphertext has been tampered with —
+ * GCM authenticates, so a modified record fails loudly instead of returning
+ * plausible rubbish.
+ */
+export const decryptSecret = (sealed: SealedSecret): string => {
+  const decipher = createDecipheriv(ALGORITHM, encryptionKey(), Buffer.from(sealed.iv, 'base64'));
+  decipher.setAuthTag(Buffer.from(sealed.tag, 'base64'));
+
+  return Buffer.concat([
+    decipher.update(Buffer.from(sealed.ciphertext, 'base64')),
+    decipher.final()
+  ]).toString('utf8');
+};
+
+/** What the UI shows in a list: enough to tell two keys apart, not enough to use one. */
+export const displayPrefix = (id: string): string => `${KEY_PREFIX}_${id}`;

package/src/apiKeys/index.ts

@@ -0,0 +1,21 @@
+export { ApiKey } from './ApiKey';
+export type { IApiKey } from './ApiKey';
+export {
+  createApiKey,
+  listApiKeys,
+  revealApiKey,
+  revokeApiKey,
+  deleteApiKey,
+  verifyApiKey
+} from './service';
+export type { CreateApiKeyInput, CreatedApiKey } from './service';
+export { authenticateAgent, requireScope, denyApiKeys } from './middleware';
+export type { ApiKeyContext } from './middleware';
+export { API_KEY_SCOPES, isApiKeyScope } from './types';
+export type { ApiKeyScope, ApiKeySummary, ApiKeyVerification, ApiKeyRejection } from './types';
+export {
+  looksLikeApiKey,
+  displayPrefix,
+  isEncryptionConfigured,
+  resetEncryptionKeyCache
+} from './crypto';

package/src/apiKeys/middleware.test.ts

@@ -0,0 +1,254 @@
+import { Request, Response } from 'express';
+
+jest.mock('./service', () => ({ verifyApiKey: jest.fn() }));
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() }
+}));
+
+import jwt from 'jsonwebtoken';
+import { verifyApiKey } from './service';
+import { authenticateAgent, denyApiKeys } from './middleware';
+
+const mockedVerify = verifyApiKey as jest.Mock;
+const ORIGINAL_ENV = process.env;
+
+function mockRes(): Response {
+  const res: Partial<Response> = {};
+  res.status = jest.fn().mockReturnValue(res);
+  res.json = jest.fn().mockReturnValue(res);
+  return res as Response;
+}
+
+const req = (over: Partial<Request> = {}): Request =>
+  ({ query: {}, body: {}, headers: {}, path: '/activities', ...over }) as unknown as Request;
+
+const withKey = (token = 'tmb_live_abcdef123456_secretsecretsecret', over: Partial<Request> = {}) =>
+  req({ headers: { authorization: `Bearer ${token}` }, ...over });
+
+const okVerification = (over: Record<string, unknown> = {}) => ({
+  ok: true,
+  userId: 'u1',
+  userEmail: 'u1@example.com',
+  userName: 'Tester',
+  keyId: 'k1',
+  scopes: ['relationship:read', 'relationship:write'],
+  groupId: null,
+  ...over
+});
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV, JWT_SECRET: 'test-jwt-secret' };
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('authenticateAgent — no credentials', () => {
+  it('rejects a request with no token', async () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(req(), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe('authenticateAgent — session tokens', () => {
+  it('accepts a valid JWT and grants the full session, with no apiKey context', async () => {
+    const token = jwt.sign({ id: 'u1', email: 'a@b.c', name: 'A', groups: ['g1', 'g2'] }, 'test-jwt-secret');
+    const request = req({ headers: { authorization: `Bearer ${token}` } });
+    const next = jest.fn();
+
+    await authenticateAgent('relationship:write')(request, mockRes(), next);
+
+    expect(next).toHaveBeenCalled();
+    expect(request.user?.id).toBe('u1');
+    // A person keeps every group they belong to — scopes constrain keys, not sessions.
+    expect(request.userGroups).toEqual(['g1', 'g2']);
+    expect(request.apiKey).toBeUndefined();
+    expect(mockedVerify).not.toHaveBeenCalled();
+  });
+
+  it('reads the token from a cookie as well as the header', async () => {
+    const token = jwt.sign({ id: 'u1', email: 'a@b.c', name: 'A' }, 'test-jwt-secret');
+    const request = req({ cookies: { access_token: token } } as Partial<Request>);
+    const next = jest.fn();
+
+    await authenticateAgent()(request, mockRes(), next);
+
+    expect(next).toHaveBeenCalled();
+    expect(request.user?.id).toBe('u1');
+  });
+
+  it('rejects a JWT signed with the wrong secret', async () => {
+    const token = jwt.sign({ id: 'u1' }, 'not-the-secret');
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(req({ headers: { authorization: `Bearer ${token}` } }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe('authenticateAgent — API keys', () => {
+  it('accepts a valid key and populates the request as a session would', async () => {
+    mockedVerify.mockResolvedValue(okVerification());
+    const request = withKey();
+    const next = jest.fn();
+
+    await authenticateAgent('relationship:read')(request, mockRes(), next);
+
+    expect(next).toHaveBeenCalled();
+    expect(request.user).toEqual({ id: 'u1', email: 'u1@example.com', name: 'Tester' });
+    expect(request.apiKey).toEqual({
+      keyId: 'k1',
+      scopes: ['relationship:read', 'relationship:write'],
+      groupId: null
+    });
+  });
+
+  it.each([
+    ['unknown'], ['revoked'], ['expired'], ['bad-secret'], ['malformed']
+  ])('answers a %s key with the same opaque 401', async (rejection) => {
+    mockedVerify.mockResolvedValue({ ok: false, rejection });
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(withKey(), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    // Nothing in the body distinguishes the five cases — that difference would
+    // tell someone guessing which half of the guess was right.
+    expect(res.json).toHaveBeenCalledWith({
+      success: false,
+      message: 'Invalid or expired credentials'
+    });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('refuses a key missing a required scope, and names what is missing', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ scopes: ['relationship:read'] }));
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent('relationship:write')(withKey(), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ message: expect.stringContaining('relationship:write') })
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('requires every listed scope, not just one of them', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ scopes: ['relationship:read'] }));
+    const next = jest.fn();
+
+    await authenticateAgent('relationship:read', 'album:write')(withKey(), mockRes(), next);
+
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe('authenticateAgent — tenant pinning', () => {
+  it('grants a personal key no groups at all', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: null }));
+    const request = withKey();
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    expect(request.userGroups).toEqual([]);
+  });
+
+  it('grants a group key exactly its own group, not the owner’s whole membership', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    const request = withKey();
+
+    await authenticateAgent()(request, mockRes(), jest.fn());
+
+    expect(request.userGroups).toEqual(['g1']);
+  });
+
+  it('fills in the pinned group so the caller never has to know it', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    const request = withKey();
+    const next = jest.fn();
+
+    await authenticateAgent()(request, mockRes(), next);
+
+    expect(next).toHaveBeenCalled();
+    expect(request.query.groupId).toBe('g1');
+    expect((request.body as Record<string, unknown>).groupId).toBe('g1');
+  });
+
+  it('refuses a query that names a different group', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(withKey(undefined, { query: { groupId: 'g2' } }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('refuses a body that names a different group', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(withKey(undefined, { body: { groupId: 'g2' } }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('refuses a personal key that tries to reach into a group', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: null }));
+    const res = mockRes();
+    const next = jest.fn();
+
+    await authenticateAgent()(withKey(undefined, { query: { groupId: 'g1' } }), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('allows a request that names the pinned group explicitly', async () => {
+    mockedVerify.mockResolvedValue(okVerification({ groupId: 'g1' }));
+    const next = jest.fn();
+
+    await authenticateAgent()(withKey(undefined, { query: { groupId: 'g1' } }), mockRes(), next);
+
+    expect(next).toHaveBeenCalled();
+  });
+});
+
+describe('denyApiKeys', () => {
+  it('lets a session through', () => {
+    const next = jest.fn();
+    denyApiKeys(req(), mockRes(), next);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('blocks a request that arrived on a key', () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    denyApiKeys(
+      req({ apiKey: { keyId: 'k1', scopes: [], groupId: null } }) as Request,
+      res,
+      next
+    );
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(next).not.toHaveBeenCalled();
+  });
+});

package/src/apiKeys/middleware.ts

@@ -0,0 +1,206 @@
+import { NextFunction, Request, RequestHandler, Response } from 'express';
+import jwt from 'jsonwebtoken';
+import { requireEnv } from '../config/env';
+import logger from '../logging/logger';
+import type { UserPayload } from '../types/auth';
+import { looksLikeApiKey } from './crypto';
+import { verifyApiKey } from './service';
+import type { ApiKeyScope } from './types';
+
+/**
+ * Request-scoped facts about the key a request arrived on. Absent on ordinary
+ * session requests, which is itself the signal a handler needs: `req.apiKey`
+ * being set means software is acting, not a person.
+ */
+export interface ApiKeyContext {
+  keyId: string;
+  scopes: ApiKeyScope[];
+  /** the tenant this key is pinned to; null means the owner's personal data */
+  groupId: string | null;
+}
+
+declare global {
+  namespace Express {
+    interface Request {
+      apiKey?: ApiKeyContext;
+    }
+  }
+}
+
+/** Both auth paths read the token from the same two places. */
+const extractToken = (req: Request): string | undefined =>
+  req.cookies?.access_token || req.headers.authorization?.replace('Bearer ', '');
+
+const unauthorized = (res: Response): void => {
+  res.status(401).json({ success: false, message: 'Invalid or expired credentials' });
+};
+
+/**
+ * The tenant a request is asking to act in, wherever it named one.
+ *
+ * Handlers read `groupId` from either the query string or the body depending on
+ * the verb, so both are checked — a pin that only covered one of them would be
+ * no pin at all.
+ */
+const requestedGroupId = (req: Request): string | undefined => {
+  const fromQuery = req.query?.groupId;
+  if (typeof fromQuery === 'string' && fromQuery.length > 0) return fromQuery;
+
+  const fromBody = (req.body as Record<string, unknown> | undefined)?.groupId;
+  if (typeof fromBody === 'string' && fromBody.length > 0) return fromBody;
+
+  return undefined;
+};
+
+/**
+ * Hold a key to the tenant it was issued for.
+ *
+ * Two things happen here, and the second is the one that makes keys pleasant to
+ * use. A request that names a *different* tenant is refused outright — the pin
+ * is the whole reason a key is safe to hand to an agent. A request that names
+ * none has the pinned tenant written in for it, so the agent never has to know a
+ * group id exists, and a handler's `if (groupId) ... else personal` branch lands
+ * where the key's owner intended.
+ */
+const applyTenantPin = (req: Request, groupId: string | null): boolean => {
+  const requested = requestedGroupId(req);
+
+  if (requested !== undefined && requested !== groupId) return false;
+
+  if (groupId !== null && requested === undefined) {
+    // Express 5 makes req.query a getter, so it is redefined rather than assigned.
+    Object.defineProperty(req, 'query', {
+      value: { ...req.query, groupId },
+      writable: true,
+      configurable: true,
+      enumerable: true
+    });
+    if (req.body && typeof req.body === 'object') {
+      (req.body as Record<string, unknown>).groupId = groupId;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Authenticate a request that software may legitimately be making.
+ *
+ * Accepts either an ordinary session — a person at a keyboard, who keeps the
+ * full run of their own account — or an API key carrying every one of
+ * `requiredScopes`.
+ *
+ * This is deliberately *not* what `authenticateToken` became. Keys stay refused
+ * everywhere by default, and a route opts in by naming the scopes it needs; the
+ * alternative, teaching the existing middleware about keys, would have silently
+ * opened every route in every service at once, account deletion included.
+ */
+export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHandler =>
+  async function authenticateAgentHandler(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const token = extractToken(req);
+    if (!token) {
+      res.status(401).json({ success: false, message: 'Access token required' });
+      return;
+    }
+
+    if (!looksLikeApiKey(token)) {
+      try {
+        const user = jwt.verify(token, requireEnv('JWT_SECRET')) as UserPayload;
+        req.user = user;
+        req.userGroups = user.groups ?? [];
+        next();
+      } catch {
+        unauthorized(res);
+      }
+      return;
+    }
+
+    const result = await verifyApiKey(token);
+    if (!result.ok) {
+      // The client is told only that the credentials failed; which of the five
+      // ways it failed is a detail that would help someone guessing.
+      logger.warn('API key rejected', { rejection: result.rejection, path: req.path });
+      unauthorized(res);
+      return;
+    }
+
+    const scopes = result.scopes ?? [];
+    const missing = requiredScopes.filter((scope) => !scopes.includes(scope));
+    if (missing.length > 0) {
+      res.status(403).json({
+        success: false,
+        message: `API key is missing required scope: ${missing.join(', ')}`
+      });
+      return;
+    }
+
+    const groupId = result.groupId ?? null;
+    if (!applyTenantPin(req, groupId)) {
+      res.status(403).json({
+        success: false,
+        message: 'API key is not permitted to act in the requested group'
+      });
+      return;
+    }
+
+    req.user = {
+      id: result.userId!,
+      email: result.userEmail ?? '',
+      name: result.userName ?? ''
+    };
+    // Only the pinned group, never the owner's full membership: this is what
+    // stops a key reaching a group it was not issued for through any handler
+    // that consults `userGroups` instead of the `groupId` parameter.
+    req.userGroups = groupId ? [groupId] : [];
+    req.apiKey = { keyId: result.keyId!, scopes, groupId };
+
+    next();
+  };
+
+/**
+ * Require a scope on a route already behind `authenticateAgent`.
+ *
+ * Splitting authentication from authorization lets one `router.use` cover a
+ * whole router while each route still states what it needs — so a read-only key
+ * reaches the GETs and stops at the POSTs, instead of being turned away at the
+ * door for lacking a scope half the router never uses.
+ *
+ * A session passes unconditionally: scopes narrow what software may do on a
+ * person's behalf, not what the person may do themselves.
+ */
+export const requireScope = (...requiredScopes: ApiKeyScope[]): RequestHandler =>
+  function requireScopeHandler(req, res, next) {
+    if (!req.apiKey) {
+      next();
+      return;
+    }
+
+    const missing = requiredScopes.filter((scope) => !req.apiKey!.scopes.includes(scope));
+    if (missing.length > 0) {
+      res.status(403).json({
+        success: false,
+        message: `API key is missing required scope: ${missing.join(', ')}`
+      });
+      return;
+    }
+
+    next();
+  };
+
+/**
+ * Refuse API keys on a route that a session may still use.
+ *
+ * For the handful of operations that should stay a person's to perform — key
+ * management itself, most obviously, since a key that can mint keys is a key
+ * that cannot be revoked.
+ */
+export const denyApiKeys: RequestHandler = (req, res, next) => {
+  if (req.apiKey) {
+    res.status(403).json({
+      success: false,
+      message: 'This operation requires an interactive session, not an API key'
+    });
+    return;
+  }
+  next();
+};