@tumbaland/backend-core 1.38.0 → 1.39.0

package/src/audit/reads.test.ts

@@ -0,0 +1,164 @@
+import type { Request, Response } from 'express';
+
+jest.mock('./AuditEvent', () => ({ AuditEvent: { create: jest.fn().mockResolvedValue({}) } }));
+jest.mock('../logging/logger', () => ({
+  __esModule: true,
+  default: { warn: jest.fn(), info: jest.fn(), error: jest.fn(), debug: jest.fn() }
+}));
+
+import { AuditEvent } from './AuditEvent';
+import { auditReads, countRead, resourceOf } from './reads';
+import { PERSONAL_TENANT } from '../apiKeys/types';
+
+const created = AuditEvent.create as jest.Mock;
+
+/** A response that runs its finish listeners when told to. */
+function mockRes(statusCode = 200) {
+  const listeners: (() => void)[] = [];
+  const res = {
+    statusCode,
+    locals: {} as Record<string, unknown>,
+    on: (event: string, fn: () => void) => {
+      if (event === 'finish') listeners.push(fn);
+      return res;
+    },
+    finish: () => listeners.forEach((fn) => fn())
+  };
+  return res as unknown as Response & { finish: () => void };
+}
+
+const req = (over: Partial<Request> = {}): Request =>
+  ({ method: 'GET', baseUrl: '/api/activities', path: '/', query: {}, ...over }) as unknown as Request;
+
+const assistant = {
+  keyId: 'client-1',
+  scopes: [],
+  tenants: { allowed: ['g1'], default: 'g1' },
+  actingAs: 'g1',
+  kind: 'oauth' as const,
+  label: 'Claude',
+  credentialId: 'client-1'
+};
+
+const user = { id: 'u1', email: 'tom@example.com', name: 'Tom' };
+
+beforeEach(() => jest.clearAllMocks());
+
+describe('auditReads', () => {
+  it('records what an assistant read', async () => {
+    const res = mockRes();
+    const request = req({ user, apiKey: assistant });
+
+    auditReads('relationship-service')(request, res, jest.fn());
+    countRead(res, 47);
+    res.finish();
+
+    expect(created).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: 'read',
+        resource: 'activities',
+        actorKind: 'assistant',
+        actorLabel: 'Claude',
+        tenant: 'g1',
+        // The size of what left the server is most of what makes a read worth
+        // keeping: "read the journal" and "read 47 entries" are different events.
+        count: 47
+      })
+    );
+  });
+
+  it('records nothing for a person browsing their own journal', async () => {
+    // One dashboard load hits half a dozen endpoints. Logging those would bury
+    // the interesting rows and put a database write behind every page view.
+    const res = mockRes();
+
+    auditReads('relationship-service')(req({ user }), res, jest.fn());
+    res.finish();
+
+    expect(created).not.toHaveBeenCalled();
+  });
+
+  it('records nothing for a write, which the model plugin already covers', () => {
+    const res = mockRes();
+    auditReads('relationship-service')(req({ user, apiKey: assistant, method: 'POST' }), res, jest.fn());
+    res.finish();
+
+    expect(created).not.toHaveBeenCalled();
+  });
+
+  it('records nothing for a refused request', () => {
+    // A 403 is not a read: nothing left the server.
+    const res = mockRes(403);
+    auditReads('relationship-service')(req({ user, apiKey: assistant }), res, jest.fn());
+    res.finish();
+
+    expect(created).not.toHaveBeenCalled();
+  });
+
+  it('always continues the request, whether or not it recorded anything', () => {
+    const next = jest.fn();
+    auditReads('relationship-service')(req(), mockRes(), next);
+    expect(next).toHaveBeenCalled();
+  });
+
+  it('does not fail the request when the trail cannot be written', async () => {
+    created.mockRejectedValueOnce(new Error('audit db down'));
+    const res = mockRes();
+
+    auditReads('relationship-service')(req({ user, apiKey: assistant }), res, jest.fn());
+    expect(() => res.finish()).not.toThrow();
+  });
+
+  it('survives a handler that never counted anything', () => {
+    const res = mockRes();
+    auditReads('relationship-service')(req({ user, apiKey: assistant }), res, jest.fn());
+    res.finish();
+
+    expect(created).toHaveBeenCalledWith(expect.objectContaining({ count: undefined }));
+  });
+});
+
+describe('resourceOf', () => {
+  it.each([
+    ['/api/activities/', 'activities'],
+    ['/api/activities/68d6d7edfb26c947ecaa057a', 'activities'],
+    ['/api/activity-types/', 'activity_types'],
+    ['/api/statistics/trends', 'statistics']
+  ])('reads %s as %s', (path, expected) => {
+    // Deliberately crude: a trail naming the resource is readable, and one
+    // naming the full path with ids in it is a request log in disguise.
+    expect(resourceOf(path)).toBe(expected);
+  });
+
+  it('names something rather than nothing for an unrecognisable path', () => {
+    expect(resourceOf('/')).toBe('unknown');
+  });
+});
+
+describe('countRead', () => {
+  it('cannot break the request it is instrumenting', () => {
+    // Express always provides `locals`; a handler called directly does not.
+    expect(() => countRead({} as Response, 3)).not.toThrow();
+    expect(() => countRead(undefined as unknown as Response, 3)).not.toThrow();
+  });
+
+  it('leaves the count where the middleware will find it', () => {
+    const res = { locals: {} } as Response;
+    countRead(res, 12);
+    expect(res.locals.auditCount).toBe(12);
+  });
+});
+
+describe('PERSONAL_TENANT', () => {
+  it('is what a personal-tenant read is recorded against', () => {
+    const res = mockRes();
+    auditReads('relationship-service')(
+      req({ user, apiKey: { ...assistant, actingAs: PERSONAL_TENANT } }),
+      res,
+      jest.fn()
+    );
+    res.finish();
+
+    expect(created).toHaveBeenCalledWith(expect.objectContaining({ tenant: PERSONAL_TENANT }));
+  });
+});

package/src/audit/reads.ts

@@ -0,0 +1,88 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { AuditEvent } from './AuditEvent';
+import { actorOf, type Actor } from './actor';
+import logger from '../logging/logger';
+
+/**
+ * Record what software read, and only what software read.
+ *
+ * A person browsing their own journal generates nothing here. That is not a
+ * shortcut: one dashboard load hits half a dozen endpoints, so logging it would
+ * bury the interesting rows under thousands of uninteresting ones and put a
+ * database write behind every page view.
+ *
+ * What an assistant read is the part worth keeping, because it is the part that
+ * left the server. A created entry leaves a record behind either way; a read
+ * leaves nothing at all, and it is exactly what the privacy page warns about —
+ * ask an assistant what you did last month and those entries go to whoever runs
+ * it. This is the only place that becomes visible.
+ */
+/**
+ * Arm the read trail for one request, if it is one worth recording.
+ *
+ * Nothing is written here — the listener fires when the response finishes, so a
+ * refused request is not recorded as a read and the count reflects what was
+ * actually sent.
+ */
+export function recordRead(req: Request, res: Response, actor: Actor, service: string): void {
+  if (req.method !== 'GET' || actor.kind === 'person') return;
+
+  res.on('finish', () => {
+    if (res.statusCode >= 400) return;
+
+    void AuditEvent.create({
+      at: new Date(),
+      service,
+      action: 'read',
+      resource: resourceOf(req.baseUrl + req.path),
+      actorKind: actor.kind,
+      userId: actor.userId,
+      actorLabel: actor.label,
+      actorCredentialId: actor.credentialId,
+      tenant: actor.tenant,
+      count: res.locals.auditCount as number | undefined
+    }).catch((error) => {
+      logger.warn('Could not record a read', { error: (error as Error)?.message });
+    });
+  });
+}
+
+/**
+ * The same thing as standalone middleware, for anything that authenticates its
+ * own way rather than through `authenticateAgent`.
+ */
+export const auditReads =
+  (service: string): RequestHandler =>
+  (req: Request, res: Response, next: NextFunction): void => {
+    const actor = actorOf(req);
+    if (actor) recordRead(req, res, actor, service);
+    next();
+  };
+
+/**
+ * What a path was asking for, in one word.
+ *
+ * The first path segment, which is the collection on every route here —
+ * `/api/activities/68d6…` is about activities. Deliberately crude: a trail
+ * naming the resource is readable, and one naming the full path with ids in it
+ * is a request log wearing an audit log's clothes.
+ */
+export function resourceOf(path: string): string {
+  const segments = path.split('/').filter((segment) => segment && segment !== 'api');
+  return segments[0]?.replace(/-/g, '_') ?? 'unknown';
+}
+
+/**
+ * How many records a response carried.
+ *
+ * Set by a handler that knows; absent otherwise. The size of what left the
+ * server is most of what makes a read worth recording — "read the journal" and
+ * "read four hundred entries of the journal" are different events.
+ */
+export const countRead = (res: Response, count: number): void => {
+  // Guarded for the same reason recording is fire-and-forget: instrumentation
+  // must not be able to fail the thing it instruments. Express always provides
+  // `locals`, but a handler called directly does not have to.
+  if (!res?.locals) return;
+  res.locals.auditCount = count;
+};

package/src/audit/service.test.ts

@@ -0,0 +1,115 @@
+import mongoose from 'mongoose';
+import { MongoMemoryServer } from 'mongodb-memory-server';
+
+import { AuditEvent } from './AuditEvent';
+import { listAuditEvents } from './service';
+
+let mongo: MongoMemoryServer;
+
+const event = (over: Record<string, unknown> = {}) => ({
+  at: new Date('2026-09-05T10:00:00Z'),
+  service: 'relationship-service',
+  action: 'create' as const,
+  resource: 'activity',
+  actorKind: 'assistant' as const,
+  userId: 'u1',
+  actorLabel: 'Claude',
+  actorCredentialId: 'client-1',
+  tenant: 'g1',
+  ...over
+});
+
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  await mongoose.connect(mongo.getUri());
+});
+
+afterAll(async () => {
+  await mongoose.disconnect();
+  await mongo.stop();
+});
+
+beforeEach(() => AuditEvent.deleteMany({}));
+
+describe('listAuditEvents', () => {
+  it('returns one account’s trail and never anyone else’s', async () => {
+    await AuditEvent.insertMany([event(), event({ userId: 'u2', actorLabel: 'Someone else' })]);
+
+    const { events, total } = await listAuditEvents({ userId: 'u1' });
+
+    // Scoped by the query rather than filtered afterwards: the trail carries old
+    // values of journal entries, so a wider read must not be one forgotten
+    // condition away.
+    expect(total).toBe(1);
+    expect(events[0].actorLabel).toBe('Claude');
+  });
+
+  it('returns newest first, which is the only order anyone reads a trail in', async () => {
+    await AuditEvent.insertMany([
+      event({ at: new Date('2026-09-01T10:00:00Z'), resource: 'older' }),
+      event({ at: new Date('2026-09-05T10:00:00Z'), resource: 'newer' })
+    ]);
+
+    const { events } = await listAuditEvents({ userId: 'u1' });
+    expect(events.map((e) => e.resource)).toEqual(['newer', 'older']);
+  });
+
+  it('narrows to one assistant, which is the question people actually ask', async () => {
+    await AuditEvent.insertMany([
+      event({ actorCredentialId: 'client-1', actorLabel: 'Claude' }),
+      event({ actorCredentialId: 'client-2', actorLabel: 'ChatGPT' })
+    ]);
+
+    const { events } = await listAuditEvents({ userId: 'u1', credentialId: 'client-1' });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].actorLabel).toBe('Claude');
+  });
+
+  it('separates what software did from what a person did', async () => {
+    await AuditEvent.insertMany([
+      event({ actorKind: 'assistant' }),
+      event({ actorKind: 'person', actorLabel: 'Tom' })
+    ]);
+
+    const { events } = await listAuditEvents({ userId: 'u1', actorKind: 'person' });
+    expect(events.map((e) => e.actorLabel)).toEqual(['Tom']);
+  });
+
+  it('narrows by action and by date range', async () => {
+    await AuditEvent.insertMany([
+      event({ action: 'delete', at: new Date('2026-09-01T10:00:00Z') }),
+      event({ action: 'delete', at: new Date('2026-09-05T10:00:00Z') }),
+      event({ action: 'read', at: new Date('2026-09-05T11:00:00Z') })
+    ]);
+
+    const { events } = await listAuditEvents({
+      userId: 'u1',
+      action: 'delete',
+      from: new Date('2026-09-03T00:00:00Z')
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0].at).toBe('2026-09-05T10:00:00.000Z');
+  });
+
+  it('hands back the change detail, which is the reason to look', async () => {
+    await AuditEvent.insertMany([event({ action: 'update', changes: { hours: { from: 3, to: 2 } } })]);
+
+    const { events } = await listAuditEvents({ userId: 'u1' });
+    expect(events[0].changes).toEqual({ hours: { from: 3, to: 2 } });
+  });
+
+  it('pages, and caps a caller asking for everything at once', async () => {
+    await AuditEvent.insertMany(Array.from({ length: 5 }, (_, i) => event({ resource: `r${i}` })));
+
+    const { events, total, totalPages } = await listAuditEvents({ userId: 'u1', limit: 2, page: 2 });
+
+    expect(events).toHaveLength(2);
+    expect(total).toBe(5);
+    expect(totalPages).toBe(3);
+
+    const capped = await listAuditEvents({ userId: 'u1', limit: 5000 });
+    expect(capped.events.length).toBeLessThanOrEqual(200);
+  });
+});

package/src/audit/service.ts

@@ -0,0 +1,92 @@
+import { AuditEvent, type IAuditEvent } from './AuditEvent';
+import type { ActorKind } from './actor';
+
+export interface AuditQuery {
+  userId: string;
+  /** narrow to one actor — a key's id or an OAuth client id */
+  credentialId?: string;
+  actorKind?: ActorKind;
+  action?: IAuditEvent['action'];
+  resource?: string;
+  /** narrow to one area — 'relationship-service', 'album-service' */
+  service?: string;
+  from?: Date;
+  to?: Date;
+  limit?: number;
+  page?: number;
+}
+
+export interface AuditEntry {
+  id: string;
+  at: string;
+  service: string;
+  action: IAuditEvent['action'];
+  resource: string;
+  resourceId?: string;
+  actorKind: ActorKind;
+  actorLabel: string;
+  actorCredentialId?: string;
+  tenant: string;
+  changes?: Record<string, { from: unknown; to: unknown }>;
+  snapshot?: Record<string, unknown>;
+  count?: number;
+}
+
+const toEntry = (event: IAuditEvent): AuditEntry => ({
+  id: String(event._id),
+  at: event.at.toISOString(),
+  service: event.service,
+  action: event.action,
+  resource: event.resource,
+  resourceId: event.resourceId,
+  actorKind: event.actorKind,
+  actorLabel: event.actorLabel,
+  actorCredentialId: event.actorCredentialId,
+  tenant: event.tenant,
+  changes: event.changes,
+  snapshot: event.snapshot,
+  count: event.count
+});
+
+/**
+ * One account's trail, newest first.
+ *
+ * Always scoped to `userId` by the query rather than filtered afterwards, so
+ * there is no path where a wider read is one forgotten condition away. The trail
+ * carries old values of journal entries, which makes it as sensitive as the
+ * journal itself.
+ */
+export const listAuditEvents = async (
+  query: AuditQuery
+): Promise<{ events: AuditEntry[]; total: number; page: number; totalPages: number }> => {
+  const limit = Math.min(query.limit ?? 50, 200);
+  const page = Math.max(query.page ?? 1, 1);
+
+  const filter: Record<string, unknown> = { userId: query.userId };
+  if (query.credentialId) filter.actorCredentialId = query.credentialId;
+  if (query.actorKind) filter.actorKind = query.actorKind;
+  if (query.action) filter.action = query.action;
+  if (query.resource) filter.resource = query.resource;
+  if (query.service) filter.service = query.service;
+  if (query.from || query.to) {
+    const at: Record<string, Date> = {};
+    if (query.from) at.$gte = query.from;
+    if (query.to) at.$lte = query.to;
+    filter.at = at;
+  }
+
+  const [events, total] = await Promise.all([
+    AuditEvent.find(filter)
+      .sort({ at: -1 })
+      .skip((page - 1) * limit)
+      .limit(limit),
+    AuditEvent.countDocuments(filter)
+  ]);
+
+  return {
+    events: events.map(toEntry),
+    total,
+    page,
+    totalPages: Math.ceil(total / limit)
+  };
+};

package/src/index.ts

@@ -35,6 +35,7 @@ export * from './apiKeys';
 
 // OAuth 2.1 authorization server, for assistants connecting over MCP
 export * from './oauth';
+export * from './audit';
 
 // Middleware
 export { authenticateToken, optionalAuth } from './middleware/authMiddleware';

package/src/middleware/authMiddleware.test.ts

@@ -195,7 +195,9 @@ describe('OAuth access tokens are not sessions', () => {
       scopes: ['relationship:read'],
       tenants: [PERSONAL_TENANT],
       defaultTenant: PERSONAL_TENANT,
-      tenantNames: {}
+      tenantNames: {},
+      clientId: 'client-1',
+      clientName: 'Claude'
     }).accessToken;
 
   it('refuses one on a session-only route', () => {

package/src/oauth/models.ts

@@ -1,4 +1,5 @@
 import mongoose, { Document, Schema } from 'mongoose';
+import { auditPlugin } from '../audit/plugin';
 import { PERSONAL_TENANT, type Tenant } from '../apiKeys/types';
 
 /**
@@ -148,6 +149,16 @@ const RefreshTokenSchema = new Schema<IRefreshToken>(
 
 RefreshTokenSchema.index({ userId: 1, createdAt: -1 });
 
+/**
+ * A grant appearing and being revoked is the shape of "who connected Claude,
+ * and when did it stop" — the question the connections page answers for the
+ * present and this answers for the past.
+ *
+ * `tokenHash` is redacted: it is the only thing standing between a copy of this
+ * collection and a working refresh token.
+ */
+RefreshTokenSchema.plugin(auditPlugin, { resource: 'connection', redact: ['tokenHash'] });
+
 export const RefreshToken = mongoose.models.RefreshToken
   ? (mongoose.models.RefreshToken as mongoose.Model<IRefreshToken>)
   : mongoose.model<IRefreshToken>('RefreshToken', RefreshTokenSchema);

package/src/oauth/tokens.test.ts

@@ -18,6 +18,8 @@ const mint = (over: Partial<Parameters<typeof mintAccessToken>[0]> = {}) =>
     tenants: [PERSONAL_TENANT],
     defaultTenant: PERSONAL_TENANT,
     tenantNames: { [PERSONAL_TENANT]: 'My own data' },
+    clientId: 'client-1',
+    clientName: 'Claude',
     ...over
   });
 

package/src/oauth/tokens.ts

@@ -49,6 +49,17 @@ export interface AccessTokenClaims {
   tenantNames: Record<Tenant, string>;
   /** the single tenant an older token was pinned to; read by `readTenants` */
   groupId?: string | null;
+  /**
+   * Which app this token was issued to.
+   *
+   * `jti` identifies the token and rotates every hour, so it cannot stand in for
+   * the connection — an audit trail built on it would show a different actor
+   * each time the assistant refreshed. The client id is stable for the life of
+   * the grant, and the name is snapshotted alongside it for the same reason the
+   * tenant names are: nothing downstream can look it up.
+   */
+  clientId: string;
+  clientName: string;
   email: string;
   name: string;
   typ: typeof ACCESS_TOKEN_TYPE;
@@ -68,6 +79,8 @@ export interface MintAccessTokenInput {
   tenants: Tenant[];
   defaultTenant: Tenant;
   tenantNames: Record<Tenant, string>;
+  clientId: string;
+  clientName: string;
 }
 
 export interface MintedAccessToken {
@@ -88,6 +101,8 @@ export const mintAccessToken = (input: MintAccessTokenInput): MintedAccessToken
       tenants: input.tenants,
       defaultTenant: input.defaultTenant,
       tenantNames: input.tenantNames,
+      clientId: input.clientId,
+      clientName: input.clientName,
       email: input.email,
       name: input.name,
       typ: ACCESS_TOKEN_TYPE,
@@ -109,6 +124,8 @@ export interface AccessTokenVerification {
   scopes?: ApiKeyScope[];
   tenants?: ApiKeyTenant;
   tenantNames?: Record<Tenant, string>;
+  clientId?: string;
+  clientName?: string;
 }
 
 /**
@@ -144,7 +161,9 @@ export const verifyAccessToken = (
     name: claims.name ?? '',
     scopes: (claims.scope ?? '').split(' ').filter(isApiKeyScope),
     tenants: readTenants(claims),
-    tenantNames: claims.tenantNames ?? {}
+    tenantNames: claims.tenantNames ?? {},
+    clientId: claims.clientId,
+    clientName: claims.clientName
   };
 };