@tumbaland/backend-core 1.43.0 → 1.45.0

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.43.0",
+  "version": "1.45.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "testing.js"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",

package/.versionrc.json

@@ -1,7 +0,0 @@
-{
-  "skip": {
-    "changelog": true,
-    "commit": true,
-    "tag": true
-  }
-}

package/__mocks__/uuid.js

@@ -1,8 +0,0 @@
-// Jest's CJS module loader can't require the real `uuid` package (ESM-only
-// since v9) — Node itself supports require(esm) at runtime, but Jest doesn't.
-// Swap in Node's built-in UUID generator for tests only.
-const crypto = require('crypto');
-
-module.exports = {
-  v4: () => crypto.randomUUID()
-};

package/jest.config.js

@@ -1,24 +0,0 @@
-/** @type {import('jest').Config} */
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testMatch: ['<rootDir>/src/**/*.test.ts'],
-  clearMocks: true,
-  transform: {
-    '^.+\\.ts$': ['ts-jest', { tsconfig: { types: ['jest', 'node'] } }]
-  },
-  coverageProvider: 'v8',
-  // Barrels are excluded, not just the root one: a file of `export { x } from
-  // './y'` has no logic to test, but Jest counts every re-exported function as
-  // an uncovered one — which is what held global function coverage at ~78%
-  // while every module underneath was thoroughly tested.
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.test.ts',
-    '!src/index.ts',
-    '!src/**/index.ts',
-    '!src/types/**'
-  ],
-  coverageReporters: ['text', 'json-summary'],
-  coverageThreshold: { global: { statements: 90, branches: 80, functions: 90, lines: 90 } }
-};

package/src/apiKeys/ApiKey.test.ts

@@ -1,142 +0,0 @@
-import { ApiKey, API_KEY_SECRET_FIELDS } from './ApiKey';
-
-/** The fields the schema insists on, so each test only varies what it is about. */
-const complete = {
-  userId: 'u1',
-  userEmail: 'u1@example.com',
-  userName: 'Tester',
-  name: 'Claude Code',
-  keyId: 'abcdef123456',
-  hash: 'a'.repeat(64),
-  sealedCiphertext: 'ct',
-  sealedIv: 'iv',
-  sealedTag: 'tag'
-};
-
-describe('required fields', () => {
-  it('accepts a complete document', () => {
-    expect(new ApiKey(complete).validateSync()).toBeUndefined();
-  });
-
-  it.each([
-    'userId',
-    'userEmail',
-    'name',
-    'keyId',
-    'hash',
-    'sealedCiphertext',
-    'sealedIv',
-    'sealedTag'
-  ])('refuses a document with no %s', (field) => {
-    const doc = new ApiKey({ ...complete, [field]: undefined });
-    expect(doc.validateSync()?.errors[field]).toBeDefined();
-  });
-
-  it('will not store a key without the material needed to verify it', () => {
-    // A record missing its digest could never authenticate anything, and one
-    // missing the sealed copy could never be revealed — both are corruption,
-    // not a valid state.
-    const doc = new ApiKey({ ...complete, hash: undefined, sealedCiphertext: undefined });
-    const err = doc.validateSync();
-
-    expect(err?.errors.hash).toBeDefined();
-    expect(err?.errors.sealedCiphertext).toBeDefined();
-  });
-});
-
-describe('defaults', () => {
-  it('treats an unpinned key as personal rather than as unset', () => {
-    // `null` and "nobody set this" must not be distinguishable downstream: the
-    // middleware reads a null groupId as the owner's personal scope.
-    expect(new ApiKey(complete).groupId).toBeNull();
-  });
-
-  it('starts with no scopes, so a key grants nothing until asked', () => {
-    expect(new ApiKey(complete).scopes).toEqual([]);
-  });
-
-  it('starts the reveal counter at zero', () => {
-    expect(new ApiKey(complete).revealCount).toBe(0);
-  });
-
-  it('leaves the lifecycle timestamps unset', () => {
-    const doc = new ApiKey(complete);
-
-    expect(doc.lastUsedAt).toBeUndefined();
-    expect(doc.expiresAt).toBeUndefined();
-    expect(doc.revokedAt).toBeUndefined();
-    expect(doc.lastRevealedAt).toBeUndefined();
-  });
-});
-
-describe('name', () => {
-  it('trims surrounding whitespace', () => {
-    expect(new ApiKey({ ...complete, name: '  Claude  ' }).name).toBe('Claude');
-  });
-
-  it('caps the length so a listing stays readable', () => {
-    const doc = new ApiKey({ ...complete, name: 'x'.repeat(61) });
-    expect(doc.validateSync()?.errors.name).toBeDefined();
-  });
-
-  it('accepts a name at the cap', () => {
-    const doc = new ApiKey({ ...complete, name: 'x'.repeat(60) });
-    expect(doc.validateSync()?.errors.name).toBeUndefined();
-  });
-});
-
-describe('indexes', () => {
-  const indexes = ApiKey.schema.indexes().map(([fields]) => fields);
-
-  it('indexes keyId, which every verification looks a key up by', () => {
-    const path = ApiKey.schema.path('keyId') as unknown as { options: Record<string, unknown> };
-    expect(path.options.index).toBe(true);
-    expect(path.options.unique).toBe(true);
-  });
-
-  it('indexes a user’s keys newest first, matching how the listing reads them', () => {
-    expect(indexes).toContainEqual({ userId: 1, createdAt: -1 });
-  });
-});
-
-describe('collection', () => {
-  it('lives in api_keys', () => {
-    // Named explicitly rather than pluralised by Mongoose, so the collection a
-    // migration or a manual query targets is not a guess.
-    expect(ApiKey.collection.collectionName).toBe('api_keys');
-  });
-});
-
-describe('model registration', () => {
-  it('reuses the compiled model instead of redefining it', () => {
-    // backend-core is imported by every service, and some import it more than
-    // once through different paths; recompiling would throw OverwriteModelError.
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const again = require('./ApiKey').ApiKey;
-    expect(again).toBe(ApiKey);
-  });
-});
-
-describe('what a key’s audit trail may carry', () => {
-  /**
-   * The trail is readable by the account owner and kept for a year. A snapshot
-   * carrying the hash or the sealed ciphertext would copy credential material
-   * into a second collection with a different lifetime — which is exactly what
-   * the encryption exists to prevent.
-   */
-  it('redacts every field on the schema that holds a secret', () => {
-    const secretish = Object.keys(ApiKey.schema.paths).filter((path) =>
-      /hash|sealed|secret/i.test(path)
-    );
-
-    // Compared against the schema rather than a hand-written list, so a secret
-    // field added later fails here instead of quietly reaching the trail.
-    expect(secretish.sort()).toEqual([...API_KEY_SECRET_FIELDS].sort());
-  });
-
-  it('keeps the fields that make a row worth reading', () => {
-    for (const field of ['name', 'scopes', 'tenants', 'revokedAt']) {
-      expect(API_KEY_SECRET_FIELDS).not.toContain(field);
-    }
-  });
-});

package/src/apiKeys/ApiKey.ts

@@ -1,102 +0,0 @@
-import mongoose, { Document, Schema } from 'mongoose';
-import { auditPlugin } from '../audit/plugin';
-import { PERSONAL_TENANT, type ApiKeyScope, type Tenant } from './types';
-
-/**
- * One API key. Lives in backend-core rather than auth-service because both
- * halves need it: auth-service issues and revokes keys, and every other service
- * verifies them on the way in. All services share one database, so the model is
- * shared rather than the lookup going over HTTP on every request.
- */
-export interface IApiKey extends Document {
-  userId: string;
-  /**
-   * The owner's identity as it stood when the key was issued.
-   *
-   * Snapshotted so verifying a key stays a single indexed read. Every
-   * authenticated request would otherwise need a second query into the users
-   * collection to fill in a `UserPayload`, to serve fields almost no handler
-   * reads. The cost is that a later rename shows the old name on requests made
-   * with this key, which is a fair price and easy to reason about.
-   */
-  userEmail: string;
-  userName: string;
-  /** what the user called it — "Claude Code", "home assistant" */
-  name: string;
-  /** the public half of the token; unique, and what a presented key is looked up by */
-  keyId: string;
-  /** SHA-256 of the secret half — what verification actually compares against */
-  hash: string;
-  /** the whole token, encrypted, so the owner can read it back later */
-  sealedCiphertext: string;
-  sealedIv: string;
-  sealedTag: string;
-  scopes: ApiKeyScope[];
-  /** every tenant this key may act in; see `Tenant` */
-  tenants: Tenant[];
-  /** the one it acts in when a request names none; always a member of `tenants` */
-  defaultTenant: Tenant;
-  /**
-   * The single tenant this key was pinned to, before tenants were a set.
-   *
-   * Kept so keys issued under the old model keep working; `readTenants` falls
-   * back to it. Nothing writes it any more.
-   */
-  groupId?: string | null;
-  lastUsedAt?: Date;
-  expiresAt?: Date;
-  revokedAt?: Date;
-  /** reveals are counted and timestamped — reading back a key is worth an audit trail */
-  revealCount: number;
-  lastRevealedAt?: Date;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-const ApiKeySchema = new Schema<IApiKey>(
-  {
-    userId: { type: String, required: true, index: true },
-    userEmail: { type: String, required: true },
-    userName: { type: String, required: true, default: '' },
-    name: { type: String, required: true, trim: true, maxlength: 60 },
-    keyId: { type: String, required: true, unique: true, index: true },
-    hash: { type: String, required: true },
-    sealedCiphertext: { type: String, required: true },
-    sealedIv: { type: String, required: true },
-    sealedTag: { type: String, required: true },
-    scopes: { type: [String], default: [] },
-    // Defaulted rather than optional: which data a key reaches is a decision the
-    // creator made, and it must not be indistinguishable from a field nobody set.
-    tenants: { type: [String], default: () => [PERSONAL_TENANT] },
-    defaultTenant: { type: String, default: PERSONAL_TENANT },
-    // Written by the single-tenant model this replaced; read-only now.
-    groupId: { type: String, default: null },
-    lastUsedAt: { type: Date },
-    expiresAt: { type: Date },
-    revokedAt: { type: Date },
-    revealCount: { type: Number, default: 0 },
-    lastRevealedAt: { type: Date }
-  },
-  { timestamps: true, collection: 'api_keys' }
-);
-
-// Every listing is one user's keys, newest first.
-ApiKeySchema.index({ userId: 1, createdAt: -1 });
-
-/**
- * Issuing and revoking a key is worth a record — arguably more than anything a
- * key goes on to do, since a credential nobody remembers creating is the one
- * that matters.
- *
- * Every secret-bearing field is redacted. The trail is readable by the account
- * owner and kept for a year; a snapshot carrying `hash` or the sealed
- * ciphertext would put credential material into a second collection with a
- * different lifetime, which is precisely the thing the encryption is for.
- */
-export const API_KEY_SECRET_FIELDS = ['hash', 'sealedCiphertext', 'sealedIv', 'sealedTag'];
-
-ApiKeySchema.plugin(auditPlugin, { resource: 'api_key', redact: API_KEY_SECRET_FIELDS });
-
-export const ApiKey = mongoose.models.ApiKey
-  ? (mongoose.models.ApiKey as mongoose.Model<IApiKey>)
-  : mongoose.model<IApiKey>('ApiKey', ApiKeySchema);

package/src/apiKeys/crypto.test.ts

@@ -1,161 +0,0 @@
-const ORIGINAL_ENV = process.env;
-
-import {
-  generateKey,
-  parseKey,
-  looksLikeApiKey,
-  secretMatches,
-  encryptSecret,
-  decryptSecret,
-  displayPrefix,
-  sha256,
-  resetEncryptionKeyCache
-} from './crypto';
-
-beforeEach(() => {
-  process.env = { ...ORIGINAL_ENV, API_KEY_ENCRYPTION_SECRET: 'test-encryption-secret' };
-  resetEncryptionKeyCache();
-});
-
-afterEach(() => {
-  process.env = ORIGINAL_ENV;
-  resetEncryptionKeyCache();
-});
-
-describe('generateKey', () => {
-  it('produces a prefixed token whose parts round-trip through parseKey', () => {
-    const { token, id, hash } = generateKey();
-    const parsed = parseKey(token);
-
-    expect(token.startsWith('tmb_live_')).toBe(true);
-    expect(parsed).not.toBeNull();
-    expect(parsed!.id).toBe(id);
-    expect(sha256(parsed!.secret)).toBe(hash);
-  });
-
-  it('never repeats a key', () => {
-    const tokens = new Set(Array.from({ length: 50 }, () => generateKey().token));
-    expect(tokens.size).toBe(50);
-  });
-
-  it('does not store the secret in recoverable form in the hash', () => {
-    const { token, hash } = generateKey();
-    expect(hash).not.toContain(token);
-    expect(hash).toMatch(/^[0-9a-f]{64}$/);
-  });
-});
-
-describe('parseKey', () => {
-  it.each([
-    ['a non-string', 12345],
-    ['an empty string', ''],
-    ['a foreign prefix', 'sk_live_abcdef123456_secretsecretsecret'],
-    ['too few parts', 'tmb_live_abcdef123456'],
-    ['a missing secret', 'tmb_live_abcdef123456_'],
-    ['a non-hex id', 'tmb_live_ZZZZZZZZZZZZ_secretsecretsecret'],
-    ['a short id', 'tmb_live_abc_secretsecretsecret'],
-    ['a truncated secret', 'tmb_live_abcdef123456_short']
-  ])('rejects %s', (_label, token) => {
-    expect(parseKey(token)).toBeNull();
-  });
-
-  it('accepts a secret containing underscores, which base64url produces', () => {
-    // The alphabet is A-Za-z0-9-_, so roughly a third of real keys carry an
-    // underscore in the secret. Splitting the token on '_' rejected those.
-    expect(parseKey('tmb_live_abcdef123456_aa_bb_cc-dd_eeffgghhiijj')).toEqual({
-      id: 'abcdef123456',
-      secret: 'aa_bb_cc-dd_eeffgghhiijj'
-    });
-  });
-
-  it('round-trips every generated key, underscores and all', () => {
-    for (let i = 0; i < 200; i++) {
-      const { token, id } = generateKey();
-      expect(parseKey(token)?.id).toBe(id);
-    }
-  });
-
-  it('accepts a well-formed key', () => {
-    expect(parseKey('tmb_live_abcdef123456_aaaaaaaaaaaaaaaaaaaa')).toEqual({
-      id: 'abcdef123456',
-      secret: 'aaaaaaaaaaaaaaaaaaaa'
-    });
-  });
-});
-
-describe('looksLikeApiKey', () => {
-  it('separates our keys from JWTs so the caller can skip a pointless verify', () => {
-    expect(looksLikeApiKey(generateKey().token)).toBe(true);
-    expect(looksLikeApiKey('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.abc.def')).toBe(false);
-    expect(looksLikeApiKey(undefined)).toBe(false);
-  });
-});
-
-describe('secretMatches', () => {
-  it('accepts the right secret and rejects a wrong one', () => {
-    const { token, hash } = generateKey();
-    const { secret } = parseKey(token)!;
-
-    expect(secretMatches(secret, hash)).toBe(true);
-    expect(secretMatches(`${secret}x`, hash)).toBe(false);
-  });
-
-  it('returns false rather than throwing on a malformed stored hash', () => {
-    // timingSafeEqual throws on a length mismatch, which would turn a corrupt
-    // record into a 500 instead of a failed authentication.
-    expect(secretMatches('anything', 'not-a-sha256')).toBe(false);
-  });
-});
-
-describe('encryptSecret / decryptSecret', () => {
-  it('round-trips a token', () => {
-    const { token } = generateKey();
-    expect(decryptSecret(encryptSecret(token))).toBe(token);
-  });
-
-  it('produces different ciphertext each time, so equal keys are not detectable', () => {
-    const { token } = generateKey();
-    const a = encryptSecret(token);
-    const b = encryptSecret(token);
-
-    expect(a.ciphertext).not.toBe(b.ciphertext);
-    expect(a.iv).not.toBe(b.iv);
-  });
-
-  it('refuses to decrypt tampered ciphertext rather than returning rubbish', () => {
-    const sealed = encryptSecret(generateKey().token);
-    const flipped = Buffer.from(sealed.ciphertext, 'base64');
-    flipped[0] ^= 0xff;
-
-    expect(() =>
-      decryptSecret({ ...sealed, ciphertext: flipped.toString('base64') })
-    ).toThrow();
-  });
-
-  it('cannot be decrypted with a different encryption secret', () => {
-    const sealed = encryptSecret(generateKey().token);
-
-    process.env.API_KEY_ENCRYPTION_SECRET = 'a-completely-different-secret';
-    resetEncryptionKeyCache();
-
-    expect(() => decryptSecret(sealed)).toThrow();
-  });
-
-  it('requires the encryption secret to be configured at all', () => {
-    delete process.env.API_KEY_ENCRYPTION_SECRET;
-    resetEncryptionKeyCache();
-
-    expect(() => encryptSecret('tmb_live_x')).toThrow(/API_KEY_ENCRYPTION_SECRET/);
-  });
-});
-
-describe('displayPrefix', () => {
-  it('identifies a key without exposing enough to use it', () => {
-    const { token, id } = generateKey();
-    const prefix = displayPrefix(id);
-
-    expect(prefix).toBe(`tmb_live_${id}`);
-    expect(token.startsWith(prefix)).toBe(true);
-    expect(prefix.length).toBeLessThan(token.length);
-  });
-});

package/src/apiKeys/crypto.ts

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