@tumbaland/backend-core 1.31.0 → 1.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tumbaland/backend-core",
-  "version": "1.31.0",
+  "version": "1.33.0",
   "description": "Core shared functionality for Tumbaland backend services",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/apiKeys/ApiKey.test.ts

@@ -0,0 +1,118 @@
+import { ApiKey } 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);
+  });
+});

package/src/apiKeys/index.test.ts

@@ -0,0 +1,72 @@
+import * as core from '../index';
+import * as apiKeys from './index';
+
+/**
+ * The package's public surface, as the services actually consume it.
+ *
+ * Services install this lib from npm, so an export dropped in a refactor does
+ * not fail here — it fails inside a Docker build as "has no exported member X",
+ * against a registry that genuinely has the code. That is a slow and confusing
+ * loop, and it is entirely preventable by naming the surface once.
+ */
+const PUBLIC_SURFACE = [
+  // middleware the services mount
+  'authenticateAgent',
+  'requireScope',
+  'denyApiKeys',
+  // key lifecycle, used by auth-service
+  'createApiKey',
+  'listApiKeys',
+  'revealApiKey',
+  'revokeApiKey',
+  'deleteApiKey',
+  'verifyApiKey',
+  // configuration and vocabulary
+  'isEncryptionConfigured',
+  'API_KEY_SCOPES',
+  'isApiKeyScope',
+  'ApiKey',
+  // helpers
+  'looksLikeApiKey',
+  'displayPrefix',
+  'resetEncryptionKeyCache'
+] as const;
+
+describe('the apiKeys barrel', () => {
+  it.each(PUBLIC_SURFACE)('exports %s', (name) => {
+    expect(apiKeys).toHaveProperty(name);
+    expect((apiKeys as Record<string, unknown>)[name]).toBeDefined();
+  });
+});
+
+describe('the package root', () => {
+  it.each(PUBLIC_SURFACE)('re-exports %s, which is how services import it', (name) => {
+    expect((core as Record<string, unknown>)[name]).toBeDefined();
+  });
+
+  it('exposes the same binding through both paths', () => {
+    for (const name of PUBLIC_SURFACE) {
+      expect((core as Record<string, unknown>)[name]).toBe((apiKeys as Record<string, unknown>)[name]);
+    }
+  });
+
+  it('still exports the session middleware the key work sits alongside', () => {
+    // `authenticateToken` stays JWT-only and is what auth-service and
+    // payment-service rely on to refuse keys outright.
+    expect(core.authenticateToken).toBeDefined();
+    expect(core.optionalAuth).toBeDefined();
+  });
+});
+
+describe('the scope vocabulary', () => {
+  it('is the same list the services and the UI are written against', () => {
+    expect([...core.API_KEY_SCOPES]).toEqual([
+      'relationship:read',
+      'relationship:write',
+      'album:read',
+      'album:write',
+      'finance:read',
+      'finance:write'
+    ]);
+  });
+});

package/src/apiKeys/middleware.test.ts

@@ -8,7 +8,7 @@ jest.mock('../logging/logger', () => ({
 
 import jwt from 'jsonwebtoken';
 import { verifyApiKey } from './service';
-import { authenticateAgent, denyApiKeys } from './middleware';
+import { authenticateAgent, requireScope, denyApiKeys } from './middleware';
 
 const mockedVerify = verifyApiKey as jest.Mock;
 const ORIGINAL_ENV = process.env;
@@ -157,6 +157,37 @@ describe('authenticateAgent — API keys', () => {
   });
 });
 
+it('authenticates a key stored before the owner snapshot existed', async () => {
+  // Records written by an earlier version carry no userEmail/userName. Such a
+  // key must still work — the id is what every handler actually reads — rather
+  // than 500 on a missing field.
+  mockedVerify.mockResolvedValue({
+    ok: true,
+    userId: 'u1',
+    keyId: 'k1',
+    scopes: ['relationship:read'],
+    groupId: null
+  });
+  const request = withKey();
+  const next = jest.fn();
+
+  await authenticateAgent('relationship:read')(request, mockRes(), next);
+
+  expect(next).toHaveBeenCalled();
+  expect(request.user).toEqual({ id: 'u1', email: '', name: '' });
+});
+
+it('treats a verification result with no scopes as granting nothing', async () => {
+  mockedVerify.mockResolvedValue({ ok: true, userId: 'u1', keyId: 'k1', groupId: null });
+  const res = mockRes();
+  const next = jest.fn();
+
+  await authenticateAgent('relationship:read')(withKey(), res, next);
+
+  expect(res.status).toHaveBeenCalledWith(403);
+  expect(next).not.toHaveBeenCalled();
+});
+
 describe('authenticateAgent — tenant pinning', () => {
   it('grants a personal key no groups at all', async () => {
     mockedVerify.mockResolvedValue(okVerification({ groupId: null }));
@@ -231,6 +262,74 @@ describe('authenticateAgent — tenant pinning', () => {
   });
 });
 
+describe('requireScope', () => {
+  const keyReq = (scopes: string[]) =>
+    req({ apiKey: { keyId: 'k1', scopes, groupId: null } } as Partial<Request>);
+
+  it('lets a session through unconditionally', () => {
+    // Scopes narrow what software may do on a person's behalf, not what the
+    // person may do themselves — a session carries no apiKey context at all.
+    const next = jest.fn();
+    requireScope('relationship:write')(req(), mockRes(), next);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('lets a key with the required scope through', () => {
+    const next = jest.fn();
+    requireScope('relationship:read')(keyReq(['relationship:read']), mockRes(), next);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('refuses a key without it, naming what is missing', () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    requireScope('relationship:write')(keyReq(['relationship:read']), res, next);
+
+    expect(res.status).toHaveBeenCalledWith(403);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ message: expect.stringContaining('relationship:write') })
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('does not let a read scope stand in for a write', () => {
+    const next = jest.fn();
+    requireScope('album:write')(keyReq(['album:read']), mockRes(), next);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('does not let one area’s scope stand in for another’s', () => {
+    const next = jest.fn();
+    requireScope('finance:read')(keyReq(['relationship:read', 'album:read']), mockRes(), next);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('requires every named scope, not just one of them', () => {
+    const res = mockRes();
+    const next = jest.fn();
+
+    requireScope('relationship:read', 'album:write')(keyReq(['relationship:read']), res, next);
+
+    expect(next).not.toHaveBeenCalled();
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ message: expect.stringContaining('album:write') })
+    );
+  });
+
+  it('refuses a key with no scopes at all', () => {
+    const next = jest.fn();
+    requireScope('relationship:read')(keyReq([]), mockRes(), next);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it('lets any authenticated caller through when no scope is named', () => {
+    const next = jest.fn();
+    requireScope()(keyReq([]), mockRes(), next);
+    expect(next).toHaveBeenCalled();
+  });
+});
+
 describe('denyApiKeys', () => {
   it('lets a session through', () => {
     const next = jest.fn();

package/src/apiKeys/service.test.ts

@@ -0,0 +1,352 @@
+const ORIGINAL_ENV = process.env;
+
+jest.mock('./ApiKey', () => ({
+  ApiKey: {
+    create: jest.fn(),
+    find: jest.fn(),
+    findOne: jest.fn(),
+    updateOne: jest.fn(),
+    deleteOne: jest.fn()
+  }
+}));
+
+import { ApiKey } from './ApiKey';
+import {
+  createApiKey,
+  listApiKeys,
+  revealApiKey,
+  revokeApiKey,
+  deleteApiKey,
+  verifyApiKey
+} from './service';
+import { encryptSecret, generateKey, parseKey, resetEncryptionKeyCache, sha256 } from './crypto';
+
+const mockedCreate = ApiKey.create as unknown as jest.Mock;
+const mockedFind = ApiKey.find as unknown as jest.Mock;
+const mockedFindOne = ApiKey.findOne as unknown as jest.Mock;
+const mockedUpdateOne = ApiKey.updateOne as unknown as jest.Mock;
+const mockedDeleteOne = ApiKey.deleteOne as unknown as jest.Mock;
+
+const CREATED_AT = new Date('2026-09-01T00:00:00.000Z');
+
+/** A stored key document, with the save()/field mutation the service relies on. */
+function storedKey(over: Record<string, unknown> = {}) {
+  return {
+    _id: 'k1',
+    userId: 'u1',
+    userEmail: 'u1@example.com',
+    userName: 'Tester',
+    name: 'Claude',
+    keyId: 'abcdef123456',
+    hash: sha256('a-secret-value-long-enough'),
+    sealedCiphertext: 'ct',
+    sealedIv: 'iv',
+    sealedTag: 'tag',
+    scopes: ['relationship:read'],
+    groupId: null,
+    revealCount: 0,
+    lastRevealedAt: undefined as Date | undefined,
+    createdAt: CREATED_AT,
+    lastUsedAt: undefined,
+    expiresAt: undefined,
+    revokedAt: undefined,
+    save: jest.fn().mockResolvedValue(undefined),
+    ...over
+  };
+}
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV, API_KEY_ENCRYPTION_SECRET: 'test-encryption-secret' };
+  resetEncryptionKeyCache();
+  mockedUpdateOne.mockResolvedValue({});
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+  resetEncryptionKeyCache();
+});
+
+describe('createApiKey', () => {
+  beforeEach(() => mockedCreate.mockImplementation(async (doc) => ({ ...doc, _id: 'k1', createdAt: CREATED_AT })));
+
+  const input = {
+    userId: 'u1',
+    userEmail: 'u1@example.com',
+    userName: 'Tester',
+    name: 'Claude',
+    scopes: ['relationship:read' as const]
+  };
+
+  it('returns a usable token and stores only its digest', async () => {
+    const { token } = await createApiKey(input);
+    const [stored] = mockedCreate.mock.calls[0];
+
+    // The plaintext must never reach the hash column — that is the whole point
+    // of keeping a digest alongside the reversible copy.
+    expect(stored.hash).not.toContain(token);
+    expect(stored.hash).toBe(sha256(parseKey(token)!.secret));
+    expect(stored.keyId).toBe(parseKey(token)!.id);
+  });
+
+  it('stores the token encrypted, recoverable only with the secret', async () => {
+    const { token } = await createApiKey(input);
+    const [stored] = mockedCreate.mock.calls[0];
+
+    expect(stored.sealedCiphertext).not.toContain(token);
+    expect(stored.sealedIv).toBeTruthy();
+    expect(stored.sealedTag).toBeTruthy();
+  });
+
+  it('defaults an unpinned key to the owner’s personal scope', async () => {
+    await createApiKey(input);
+    expect(mockedCreate.mock.calls[0][0].groupId).toBeNull();
+  });
+
+  it('pins a key to the group it was issued for', async () => {
+    await createApiKey({ ...input, groupId: 'g1' });
+    expect(mockedCreate.mock.calls[0][0].groupId).toBe('g1');
+  });
+
+  it('snapshots the owner so verification needs no second query', async () => {
+    await createApiKey(input);
+    expect(mockedCreate.mock.calls[0][0]).toMatchObject({
+      userEmail: 'u1@example.com',
+      userName: 'Tester'
+    });
+  });
+
+  it('never returns the secret material in the summary', async () => {
+    const { summary } = await createApiKey(input);
+    expect(summary).not.toHaveProperty('hash');
+    expect(summary).not.toHaveProperty('sealedCiphertext');
+    expect(summary.prefix).toBe(`tmb_live_${mockedCreate.mock.calls[0][0].keyId}`);
+  });
+});
+
+describe('listApiKeys', () => {
+  it('lists the owner’s keys newest first, carrying no secrets', async () => {
+    const sort = jest.fn().mockResolvedValue([storedKey(), storedKey({ _id: 'k2', name: 'Other' })]);
+    mockedFind.mockReturnValue({ sort });
+
+    const keys = await listApiKeys('u1');
+
+    expect(mockedFind).toHaveBeenCalledWith({ userId: 'u1' });
+    expect(sort).toHaveBeenCalledWith({ createdAt: -1 });
+    for (const key of keys) {
+      expect(key).not.toHaveProperty('hash');
+      expect(key).not.toHaveProperty('sealedCiphertext');
+      expect(JSON.stringify(key)).not.toContain('ct');
+    }
+  });
+
+  it('renders absent timestamps as null rather than undefined', async () => {
+    mockedFind.mockReturnValue({ sort: jest.fn().mockResolvedValue([storedKey()]) });
+    const [key] = await listApiKeys('u1');
+
+    expect(key.lastUsedAt).toBeNull();
+    expect(key.expiresAt).toBeNull();
+    expect(key.revokedAt).toBeNull();
+  });
+});
+
+describe('revealApiKey', () => {
+  it('decrypts the stored token for its owner', async () => {
+    const { token } = generateKey();
+    const sealed = encryptSecret(token);
+    const key = storedKey({
+      sealedCiphertext: sealed.ciphertext,
+      sealedIv: sealed.iv,
+      sealedTag: sealed.tag
+    });
+    mockedFindOne.mockResolvedValue(key);
+
+    await expect(revealApiKey('u1', 'k1')).resolves.toBe(token);
+  });
+
+  it('scopes the lookup to the owner, so another user’s key is simply not found', async () => {
+    mockedFindOne.mockResolvedValue(null);
+
+    await expect(revealApiKey('someone-else', 'k1')).resolves.toBeNull();
+    // Ownership is part of the query rather than a check afterwards — there is
+    // no path where a mismatched user still reaches the decrypt.
+    expect(mockedFindOne).toHaveBeenCalledWith({ _id: 'k1', userId: 'someone-else' });
+  });
+
+  it('counts and timestamps every reveal', async () => {
+    const sealed = encryptSecret(generateKey().token);
+    const key = storedKey({
+      sealedCiphertext: sealed.ciphertext,
+      sealedIv: sealed.iv,
+      sealedTag: sealed.tag,
+      revealCount: 2
+    });
+    mockedFindOne.mockResolvedValue(key);
+
+    await revealApiKey('u1', 'k1');
+
+    expect(key.revealCount).toBe(3);
+    expect(key.lastRevealedAt).toBeInstanceOf(Date);
+    expect(key.save).toHaveBeenCalled();
+  });
+
+  it('still reveals a revoked key, so the owner can see what they turned off', async () => {
+    const { token } = generateKey();
+    const sealed = encryptSecret(token);
+    mockedFindOne.mockResolvedValue(
+      storedKey({
+        sealedCiphertext: sealed.ciphertext,
+        sealedIv: sealed.iv,
+        sealedTag: sealed.tag,
+        revokedAt: new Date()
+      })
+    );
+
+    await expect(revealApiKey('u1', 'k1')).resolves.toBe(token);
+  });
+});
+
+describe('revokeApiKey', () => {
+  it('stamps the key revoked', async () => {
+    const key = storedKey();
+    mockedFindOne.mockResolvedValue(key);
+
+    const summary = await revokeApiKey('u1', 'k1');
+
+    expect(key.revokedAt).toBeInstanceOf(Date);
+    expect(key.save).toHaveBeenCalled();
+    expect(summary?.revokedAt).not.toBeNull();
+  });
+
+  it('leaves an already-revoked key’s original timestamp alone', async () => {
+    const revokedAt = new Date('2026-01-01T00:00:00.000Z');
+    const key = storedKey({ revokedAt });
+    mockedFindOne.mockResolvedValue(key);
+
+    await revokeApiKey('u1', 'k1');
+
+    expect(key.revokedAt).toBe(revokedAt);
+    expect(key.save).not.toHaveBeenCalled();
+  });
+
+  it('returns null for a key that is not the caller’s', async () => {
+    mockedFindOne.mockResolvedValue(null);
+    await expect(revokeApiKey('u2', 'k1')).resolves.toBeNull();
+  });
+});
+
+describe('deleteApiKey', () => {
+  it('deletes only within the owner’s keys', async () => {
+    mockedDeleteOne.mockResolvedValue({ deletedCount: 1 });
+
+    await expect(deleteApiKey('u1', 'k1')).resolves.toBe(true);
+    expect(mockedDeleteOne).toHaveBeenCalledWith({ _id: 'k1', userId: 'u1' });
+  });
+
+  it('reports false when nothing matched', async () => {
+    mockedDeleteOne.mockResolvedValue({ deletedCount: 0 });
+    await expect(deleteApiKey('u2', 'k1')).resolves.toBe(false);
+  });
+});
+
+describe('verifyApiKey', () => {
+  /** A stored record that will actually accept `token`. */
+  const acceptingKey = (token: string, over: Record<string, unknown> = {}) =>
+    storedKey({
+      keyId: parseKey(token)!.id,
+      hash: sha256(parseKey(token)!.secret),
+      ...over
+    });
+
+  it('rejects a malformed token without touching the database', async () => {
+    await expect(verifyApiKey('not-a-key')).resolves.toEqual({ ok: false, rejection: 'malformed' });
+    expect(mockedFindOne).not.toHaveBeenCalled();
+  });
+
+  it('rejects a token for a key that does not exist', async () => {
+    mockedFindOne.mockResolvedValue(null);
+    const { token } = generateKey();
+
+    await expect(verifyApiKey(token)).resolves.toEqual({ ok: false, rejection: 'unknown' });
+  });
+
+  it('rejects a revoked key', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(acceptingKey(token, { revokedAt: new Date() }));
+
+    await expect(verifyApiKey(token)).resolves.toEqual({ ok: false, rejection: 'revoked' });
+  });
+
+  it('rejects a key whose expiry has passed', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(acceptingKey(token, { expiresAt: new Date(Date.now() - 1000) }));
+
+    await expect(verifyApiKey(token)).resolves.toEqual({ ok: false, rejection: 'expired' });
+  });
+
+  it('accepts a key whose expiry is still ahead', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(acceptingKey(token, { expiresAt: new Date(Date.now() + 60_000) }));
+
+    await expect(verifyApiKey(token)).resolves.toMatchObject({ ok: true });
+  });
+
+  it('rejects a right-shaped token whose secret is wrong', async () => {
+    const { token } = generateKey();
+    const other = generateKey();
+    // Same public id, a different secret's digest — the id half is not a credential.
+    mockedFindOne.mockResolvedValue(
+      storedKey({ keyId: parseKey(token)!.id, hash: sha256(parseKey(other.token)!.secret) })
+    );
+
+    await expect(verifyApiKey(token)).resolves.toEqual({ ok: false, rejection: 'bad-secret' });
+  });
+
+  it('looks a key up by its public id alone', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(acceptingKey(token));
+
+    await verifyApiKey(token);
+
+    expect(mockedFindOne).toHaveBeenCalledWith({ keyId: parseKey(token)!.id });
+  });
+
+  it('returns the identity, scopes and tenant a valid key carries', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(
+      acceptingKey(token, { scopes: ['relationship:read', 'album:write'], groupId: 'g1' })
+    );
+
+    await expect(verifyApiKey(token)).resolves.toEqual({
+      ok: true,
+      userId: 'u1',
+      userEmail: 'u1@example.com',
+      userName: 'Tester',
+      keyId: 'k1',
+      scopes: ['relationship:read', 'album:write'],
+      groupId: 'g1'
+    });
+  });
+
+  it('records that the key was used', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(acceptingKey(token));
+
+    await verifyApiKey(token);
+
+    expect(mockedUpdateOne).toHaveBeenCalledWith(
+      { _id: 'k1' },
+      { $set: { lastUsedAt: expect.any(Date) } }
+    );
+  });
+
+  it('still authenticates when recording the usage timestamp fails', async () => {
+    const { token } = generateKey();
+    mockedFindOne.mockResolvedValue(acceptingKey(token));
+    mockedUpdateOne.mockRejectedValue(new Error('write concern failed'));
+
+    // The timestamp is a convenience for the listing UI; losing it must never
+    // cost an otherwise valid request.
+    await expect(verifyApiKey(token)).resolves.toMatchObject({ ok: true });
+  });
+});

package/src/apiKeys/types.test.ts

@@ -0,0 +1,41 @@
+import { API_KEY_SCOPES, isApiKeyScope } from './types';
+
+describe('API_KEY_SCOPES', () => {
+  it('has no duplicates', () => {
+    expect(new Set(API_KEY_SCOPES).size).toBe(API_KEY_SCOPES.length);
+  });
+
+  it('offers a read and a write for every area it covers', () => {
+    for (const area of ['relationship', 'album', 'finance']) {
+      expect(API_KEY_SCOPES).toContain(`${area}:read`);
+      expect(API_KEY_SCOPES).toContain(`${area}:write`);
+    }
+  });
+
+  it('grants nothing over auth or payment, which stay a person’s to do', () => {
+    // A key that could mint keys could not be revoked, and one that could change
+    // a subscription has no ceiling on what it can cost.
+    for (const scope of API_KEY_SCOPES) {
+      expect(scope.startsWith('auth:')).toBe(false);
+      expect(scope.startsWith('payment:')).toBe(false);
+    }
+  });
+});
+
+describe('isApiKeyScope', () => {
+  it.each([...API_KEY_SCOPES])('accepts %s', (scope) => {
+    expect(isApiKeyScope(scope)).toBe(true);
+  });
+
+  it.each([
+    ['an invented area', 'admin:everything'],
+    ['an invented verb', 'relationship:delete'],
+    ['a bare area', 'relationship'],
+    ['an empty string', ''],
+    ['a non-string', 42],
+    ['null', null],
+    ['undefined', undefined]
+  ])('rejects %s', (_label, value) => {
+    expect(isApiKeyScope(value)).toBe(false);
+  });
+});