@tumbaland/backend-core 1.38.0 → 1.40.0

package/dist/oauth/models.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RefreshToken = exports.AuthorizationCode = exports.OAuthClient = void 0;
 const mongoose_1 = __importStar(require("mongoose"));
+const plugin_1 = require("../audit/plugin");
 const types_1 = require("../apiKeys/types");
 const OAuthClientSchema = new mongoose_1.Schema({
     clientId: { type: String, required: true, unique: true, index: true },
@@ -84,6 +85,15 @@ const RefreshTokenSchema = new mongoose_1.Schema({
     lastUsedAt: { type: Date }
 }, { timestamps: true, collection: 'oauth_refresh_tokens' });
 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(plugin_1.auditPlugin, { resource: 'connection', redact: ['tokenHash'] });
 exports.RefreshToken = mongoose_1.default.models.RefreshToken
     ? mongoose_1.default.models.RefreshToken
     : mongoose_1.default.model('RefreshToken', RefreshTokenSchema);

package/dist/oauth/models.js.map

@@ -1 +1 @@
-{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/oauth/models.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../../src/oauth/models.ts"],"names":[],"mappings":"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"}

package/dist/oauth/tokens.d.ts

@@ -34,6 +34,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;
@@ -52,6 +63,8 @@ export interface MintAccessTokenInput {
     tenants: Tenant[];
     defaultTenant: Tenant;
     tenantNames: Record<Tenant, string>;
+    clientId: string;
+    clientName: string;
 }
 export interface MintedAccessToken {
     accessToken: string;
@@ -68,6 +81,8 @@ export interface AccessTokenVerification {
     scopes?: ApiKeyScope[];
     tenants?: ApiKeyTenant;
     tenantNames?: Record<Tenant, string>;
+    clientId?: string;
+    clientName?: string;
 }
 /**
  * Check a bearer token presented to the MCP server.

package/dist/oauth/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/oauth/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;GASG;AAEH,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAK9C,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,iBAAiB,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,eAAe,GAAI,OAAO,oBAAoB,KAAG,iBAsB7D,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,gBAAgB,GAAG,YAAY,GAAG,eAAe,CAAC;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,EACb,kBAAkB,MAAM,KACvB,uBAsBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,OAAO,KAAG,MAAM,IAAI,iBAGP,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,WAAW,EACmB,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/oauth/tokens.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,MAAM,EACZ,MAAM,kBAAkB,CAAC;AAE1B;;;;;;;;;GASG;AAEH,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAK9C,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,OAAO,iBAAiB,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,eAAO,MAAM,eAAe,GAAI,OAAO,oBAAoB,KAAG,iBAwB7D,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,gBAAgB,GAAG,YAAY,GAAG,eAAe,CAAC;IACxF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAC5B,OAAO,MAAM,EACb,kBAAkB,MAAM,KACvB,uBAwBF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,QAAQ,OAAO,KAAG,MAAM,IAAI,iBAGP,CAAC;AAE1D,qFAAqF;AACrF,eAAO,MAAM,WAAW,GAAI,OAAO,OAAO,KAAG,WAAW,EACmB,CAAC"}

package/dist/oauth/tokens.js

@@ -32,6 +32,8 @@ const mintAccessToken = (input) => {
         tenants: input.tenants,
         defaultTenant: input.defaultTenant,
         tenantNames: input.tenantNames,
+        clientId: input.clientId,
+        clientName: input.clientName,
         email: input.email,
         name: input.name,
         typ: exports.ACCESS_TOKEN_TYPE,
@@ -72,7 +74,9 @@ const verifyAccessToken = (token, expectedAudience) => {
         name: claims.name ?? '',
         scopes: (claims.scope ?? '').split(' ').filter(types_1.isApiKeyScope),
         tenants: (0, types_1.readTenants)(claims),
-        tenantNames: claims.tenantNames ?? {}
+        tenantNames: claims.tenantNames ?? {},
+        clientId: claims.clientId,
+        clientName: claims.clientName
     };
 };
 exports.verifyAccessToken = verifyAccessToken;

package/dist/oauth/tokens.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/oauth/tokens.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/oauth/tokens.ts"],"names":[],"mappings":"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"}

package/package.json

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

package/src/apiKeys/ApiKey.test.ts

@@ -1,4 +1,4 @@
-import { ApiKey } from './ApiKey';
+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 = {
@@ -116,3 +116,27 @@ describe('model registration', () => {
     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,4 +1,5 @@
 import mongoose, { Document, Schema } from 'mongoose';
+import { auditPlugin } from '../audit/plugin';
 import { PERSONAL_TENANT, type ApiKeyScope, type Tenant } from './types';
 
 /**
@@ -82,6 +83,20 @@ const ApiKeySchema = new Schema<IApiKey>(
 // 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/middleware.test.ts

@@ -39,6 +39,7 @@ const okVerification = (over: Record<string, unknown> = {}) => ({
   keyId: 'k1',
   scopes: ['relationship:read', 'relationship:write'],
   tenants: grant(PERSONAL_TENANT),
+  label: 'Claude Code',
   ...over
 });
 
@@ -116,7 +117,11 @@ describe('authenticateAgent — API keys', () => {
       keyId: 'k1',
       scopes: ['relationship:read', 'relationship:write'],
       tenants: grant(PERSONAL_TENANT),
-      actingAs: PERSONAL_TENANT
+      actingAs: PERSONAL_TENANT,
+      kind: 'api_key',
+      // What the owner called it, so a trail reads "Claude Code" not an id.
+      label: 'Claude Code',
+      credentialId: 'k1'
     });
   });
 
@@ -341,7 +346,15 @@ describe('authenticateAgent — a multi-tenant grant', () => {
 describe('requireScope', () => {
   const keyReq = (scopes: string[]) =>
     req({
-      apiKey: { keyId: 'k1', scopes, tenants: grant(PERSONAL_TENANT), actingAs: PERSONAL_TENANT }
+      apiKey: {
+        keyId: 'k1',
+        scopes,
+        tenants: grant(PERSONAL_TENANT),
+        actingAs: PERSONAL_TENANT,
+        kind: 'api_key' as const,
+        label: 'A key',
+        credentialId: 'k1'
+      }
     } as Partial<Request>);
 
   it('lets a session through unconditionally', () => {
@@ -421,7 +434,15 @@ describe('denyApiKeys', () => {
 
     denyApiKeys(
       req({
-        apiKey: { keyId: 'k1', scopes: [], tenants: grant(PERSONAL_TENANT), actingAs: PERSONAL_TENANT }
+        apiKey: {
+          keyId: 'k1',
+          scopes: [],
+          tenants: grant(PERSONAL_TENANT),
+          actingAs: PERSONAL_TENANT,
+          kind: 'api_key' as const,
+          label: 'A key',
+          credentialId: 'k1'
+        }
       }) as Request,
       res,
       next
@@ -451,6 +472,8 @@ describe('authenticateAgent — OAuth access tokens', () => {
       tenants: [PERSONAL_TENANT],
       defaultTenant: PERSONAL_TENANT,
       tenantNames: { [PERSONAL_TENANT]: 'My own data' },
+      clientId: 'client-1',
+      clientName: 'Claude',
       ...over
     }).accessToken;
 

package/src/apiKeys/middleware.ts

@@ -2,6 +2,7 @@ import { NextFunction, Request, RequestHandler, Response } from 'express';
 import jwt from 'jsonwebtoken';
 import { requireEnv } from '../config/env';
 import logger from '../logging/logger';
+import { beginAudit } from '../audit/context';
 import { isAccessTokenClaims, type AccessTokenClaims } from '../oauth/tokens';
 import type { UserPayload } from '../types/auth';
 import { looksLikeApiKey } from './crypto';
@@ -28,6 +29,18 @@ export interface ApiKeyContext {
   tenants: ApiKeyTenant;
   /** the tenant this particular request resolved to */
   actingAs: Tenant;
+  /** which credential this is; they are revoked and audited differently */
+  kind: 'api_key' | 'oauth';
+  /** what the owner called it — a key's name, or the connected app's */
+  label: string;
+  /**
+   * The stable identity of the credential.
+   *
+   * A key's document id, or an OAuth client id — never the access token's
+   * `jti`, which rotates hourly and would make one connection look like a new
+   * actor every time it refreshed.
+   */
+  credentialId: string;
 }
 
 declare global {
@@ -113,8 +126,11 @@ const applyTenantGrant = (req: Request, tenants: ApiKeyTenant): Tenant | null =>
 
 /** A verified non-session credential, whichever kind it arrived as. */
 interface AgentCredential {
-  /** the key id or token id, for the request-scoped context */
+  /** the key's document id, or the OAuth client id */
   credentialId: string;
+  kind: 'api_key' | 'oauth';
+  /** what the owner called it, for a trail a person can read */
+  label: string;
   userId: string;
   email: string;
   name: string;
@@ -165,10 +181,16 @@ function admitAgent(
     keyId: credential.credentialId,
     scopes: credential.scopes,
     tenants: credential.tenants,
-    actingAs
+    actingAs,
+    kind: credential.kind,
+    label: credential.label,
+    credentialId: credential.credentialId
   };
 
-  next();
+  // Attribution comes from authentication, so it is established here rather
+  // than mounted separately — a router that authenticates per route would
+  // otherwise have no actor in scope when a router-level middleware ran.
+  beginAudit(req, res, next);
 }
 
 /**
@@ -204,7 +226,7 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
         const user = claims as UserPayload;
         req.user = user;
         req.userGroups = user.groups ?? [];
-        next();
+        beginAudit(req, res, next);
         return;
       }
 
@@ -219,7 +241,10 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
       // whose scope collapsed to nothing fell through to "no user context" and
       // answered from the whole collection.
       admitAgent(req, res, next, requiredScopes, {
-        credentialId: claims.jti,
+        // The client, not the token: `jti` is a new value every hour.
+        credentialId: claims.clientId ?? 'unknown-client',
+        kind: 'oauth',
+        label: claims.clientName || 'A connected app',
         userId: claims.sub,
         email: claims.email ?? '',
         name: claims.name ?? '',
@@ -240,6 +265,8 @@ export const authenticateAgent = (...requiredScopes: ApiKeyScope[]): RequestHand
 
     admitAgent(req, res, next, requiredScopes, {
       credentialId: result.keyId!,
+      kind: 'api_key',
+      label: result.label || 'An API key',
       userId: result.userId!,
       email: result.userEmail ?? '',
       name: result.userName ?? '',

package/src/apiKeys/service.test.ts

@@ -346,6 +346,8 @@ describe('verifyApiKey', () => {
       userName: 'Tester',
       keyId: 'k1',
       scopes: ['relationship:read', 'album:write'],
+      // The key's own name, so an audit trail reads "Claude" and not "k1".
+      label: 'Claude',
       tenants: { allowed: [PERSONAL_TENANT, 'g1'], default: 'g1' }
     });
   });

package/src/apiKeys/service.ts

@@ -161,6 +161,7 @@ export const verifyApiKey = async (token: unknown): Promise<ApiKeyVerification>
     userEmail: key.userEmail,
     userName: key.userName,
     keyId: String(key._id),
+    label: key.name,
     scopes: key.scopes,
     tenants: readTenants(key)
   };

package/src/apiKeys/types.ts

@@ -117,6 +117,8 @@ export interface ApiKeyVerification {
   userEmail?: string;
   userName?: string;
   keyId?: string;
+  /** what the owner called this key, for an audit trail a person can read */
+  label?: string;
   scopes?: ApiKeyScope[];
   tenants?: ApiKeyTenant;
 }

package/src/audit/AuditEvent.ts

@@ -0,0 +1,123 @@
+import mongoose, { Document, Schema } from 'mongoose';
+import type { ActorKind } from './actor';
+
+/**
+ * One thing that happened, and who did it.
+ *
+ * Lives in backend-core rather than any one service because the question it
+ * answers spans them: "what did Claude do yesterday" is not a relationship
+ * question or an album question. Every service writes into the same collection,
+ * and `service` says which one.
+ */
+/**
+ * What one MCP tool call cost.
+ *
+ * Kept beside the trail rather than in a metrics system because the question it
+ * answers is the same one the trail answers — what did the assistant do — with
+ * the part that turned out to matter added: how much text came back. A tool
+ * result is not a page a person closes. It stays in the conversation and is
+ * resent with every message after it, so a single answer of ten thousand tokens
+ * is paid for again on every turn that follows. Nothing in the product made
+ * that visible until a bill did.
+ */
+export interface ToolCall {
+  /** the tool as the model called it — 'get_net_worth', 'log_day' */
+  name: string;
+  /** how long the handler took, end to end, including the calls it made */
+  ms: number;
+  /** characters of text handed back to the model */
+  chars: number;
+  /**
+   * Roughly what those characters cost, at four to a token.
+   *
+   * An estimate on purpose: the real count depends on a tokeniser this server
+   * has no reason to carry, and the decision it informs — which tool is the
+   * expensive one — is nowhere near close enough for the difference to matter.
+   */
+  tokens: number;
+  /** the call came back as an error, so the size is a message rather than data */
+  failed?: boolean;
+}
+
+export interface IAuditEvent extends Document {
+  at: Date;
+  /** which service handled it — 'relationship-service', 'album-service' */
+  service: string;
+  action: 'create' | 'update' | 'delete' | 'read' | 'call';
+  /** what kind of thing — 'activity', 'activity_type', 'photo' */
+  resource: string;
+  resourceId?: string;
+  actorKind: ActorKind;
+  /** the account acted for; every listing is scoped to this */
+  userId: string;
+  actorLabel: string;
+  /** a key's id or an OAuth client id; absent when a person acted directly */
+  actorCredentialId?: string;
+  /** the journal it happened in */
+  tenant: string;
+  /**
+   * What changed, field by field.
+   *
+   * Present on updates. This is the difference between an audit log and a
+   * request log: "Claude edited an entry" is barely worth storing, "Claude
+   * changed hours from 3 to 2" is the thing someone actually wants to see.
+   */
+  changes?: Record<string, { from: unknown; to: unknown }>;
+  /** what a delete removed, so it can be read back or restored by hand */
+  snapshot?: Record<string, unknown>;
+  /** how many records a read returned — the size of what left the server */
+  count?: number;
+  /** present on 'call': the tool, and what it cost */
+  tool?: ToolCall;
+  createdAt: Date;
+}
+
+const ToolCallSchema = new Schema<ToolCall>(
+  {
+    name: { type: String, required: true },
+    ms: { type: Number, required: true },
+    chars: { type: Number, required: true },
+    tokens: { type: Number, required: true },
+    failed: { type: Boolean }
+  },
+  { _id: false }
+);
+
+const AuditEventSchema = new Schema<IAuditEvent>(
+  {
+    at: { type: Date, required: true, default: Date.now },
+    service: { type: String, required: true },
+    action: { type: String, required: true, enum: ['create', 'update', 'delete', 'read', 'call'] },
+    resource: { type: String, required: true },
+    resourceId: { type: String },
+    actorKind: { type: String, required: true, enum: ['person', 'key', 'assistant'] },
+    userId: { type: String, required: true, index: true },
+    actorLabel: { type: String, required: true },
+    actorCredentialId: { type: String },
+    tenant: { type: String, required: true },
+    changes: { type: Schema.Types.Mixed },
+    snapshot: { type: Schema.Types.Mixed },
+    count: { type: Number },
+    tool: { type: ToolCallSchema }
+  },
+  { timestamps: { createdAt: true, updatedAt: false }, collection: 'audit_events' }
+);
+
+// Every listing is one account's trail, newest first.
+AuditEventSchema.index({ userId: 1, at: -1 });
+
+/**
+ * Rows expire on their own.
+ *
+ * They carry journal content — the old value of a description, a deleted
+ * entry — so keeping them indefinitely would quietly build a second copy of the
+ * journal that nothing in the product ever deletes from. A year is long enough
+ * to answer "what happened" and short enough that the copy does not outlive the
+ * question.
+ */
+const RETENTION_DAYS = 365;
+AuditEventSchema.index({ at: 1 }, { expireAfterSeconds: RETENTION_DAYS * 24 * 60 * 60 });
+
+export const AuditEvent = mongoose.models.AuditEvent
+  ? (mongoose.models.AuditEvent as mongoose.Model<IAuditEvent>)
+  : mongoose.model<IAuditEvent>('AuditEvent', AuditEventSchema);

package/src/audit/actor.test.ts

@@ -0,0 +1,95 @@
+import type { Request } from 'express';
+import { actorOf, describeActor } from './actor';
+import { PERSONAL_TENANT } from '../apiKeys/types';
+
+const req = (over: Partial<Request> = {}): Request =>
+  ({ query: {}, body: {}, headers: {}, ...over }) as unknown as Request;
+
+const grant = { allowed: [PERSONAL_TENANT], default: PERSONAL_TENANT };
+
+describe('actorOf', () => {
+  it('reads a session as the person themselves', () => {
+    const actor = actorOf(req({ user: { id: 'u1', email: 'tom@example.com', name: 'Tom' } }));
+
+    expect(actor).toMatchObject({ kind: 'person', userId: 'u1', label: 'Tom' });
+    // Nothing to revoke and nothing that rotates: a person is not a credential.
+    expect(actor?.credentialId).toBeUndefined();
+  });
+
+  it('falls back to the email when a session carries no name', () => {
+    // An unlabelled row is the one nobody can act on.
+    const actor = actorOf(req({ user: { id: 'u1', email: 'tom@example.com', name: '' } }));
+    expect(actor?.label).toBe('tom@example.com');
+  });
+
+  it('names an API key by what its owner called it', () => {
+    const actor = actorOf(
+      req({
+        user: { id: 'u1', email: 'tom@example.com', name: 'Tom' },
+        apiKey: {
+          keyId: 'k1',
+          scopes: [],
+          tenants: grant,
+          actingAs: PERSONAL_TENANT,
+          kind: 'api_key',
+          label: 'Claude Code',
+          credentialId: 'k1'
+        }
+      })
+    );
+
+    expect(actor).toMatchObject({ kind: 'key', label: 'Claude Code', credentialId: 'k1' });
+  });
+
+  it('names a connected assistant by its client, not its token', () => {
+    const actor = actorOf(
+      req({
+        user: { id: 'u1', email: 'tom@example.com', name: 'Tom' },
+        apiKey: {
+          keyId: 'client-1',
+          scopes: [],
+          tenants: { allowed: ['g1'], default: 'g1' },
+          actingAs: 'g1',
+          kind: 'oauth',
+          label: 'Claude',
+          credentialId: 'client-1'
+        }
+      })
+    );
+
+    // An access token's `jti` rotates hourly; a trail built on it would show a
+    // different actor after every refresh.
+    expect(actor).toMatchObject({ kind: 'assistant', label: 'Claude', credentialId: 'client-1' });
+  });
+
+  it('records the journal the request is acting in', () => {
+    const actor = actorOf(
+      req({
+        user: { id: 'u1', email: 'a@b.c', name: 'Tom' },
+        apiKey: {
+          keyId: 'c1',
+          scopes: [],
+          tenants: { allowed: [PERSONAL_TENANT, 'g1'], default: 'g1' },
+          actingAs: 'g1',
+          kind: 'oauth',
+          label: 'Claude',
+          credentialId: 'c1'
+        }
+      })
+    );
+
+    expect(actor?.tenant).toBe('g1');
+  });
+
+  it('has nothing to attribute when nobody is authenticated', () => {
+    // A row about the transport is not a row about anyone.
+    expect(actorOf(req())).toBeNull();
+  });
+
+  it('describes software so it is not mistaken for a person', () => {
+    expect(describeActor({ kind: 'person', userId: 'u1', label: 'Tom', tenant: PERSONAL_TENANT })).toBe('Tom');
+    expect(
+      describeActor({ kind: 'assistant', userId: 'u1', label: 'Claude', tenant: 'g1' })
+    ).toBe('Claude (assistant)');
+  });
+});

package/src/audit/actor.ts

@@ -0,0 +1,68 @@
+import type { Request } from 'express';
+import { PERSONAL_TENANT, type Tenant } from '../apiKeys/types';
+
+/**
+ * Who is acting, in the only three ways anything reaches this system.
+ *
+ * The distinction that matters is `person` against everything else. A person is
+ * at a keyboard and can see what they are doing; a key or an assistant is
+ * software acting on their behalf, and is the thing an audit trail exists to
+ * make legible. Splitting `key` from `assistant` is worth the extra case because
+ * they fail differently: a key is a secret someone pasted somewhere and may have
+ * lost, an assistant is a consent screen someone approved and can withdraw.
+ */
+export type ActorKind = 'person' | 'key' | 'assistant';
+
+export interface Actor {
+  kind: ActorKind;
+  /** the account being acted for — the same whichever kind of actor it is */
+  userId: string;
+  /** what to show in a trail: the person's name, the key's name, the app's name */
+  label: string;
+  /**
+   * The credential, for software.
+   *
+   * A key's document id, or an OAuth client id. Deliberately not the access
+   * token's `jti`, which rotates hourly and would show a different actor after
+   * every refresh.
+   */
+  credentialId?: string;
+  /** the journal this request is acting in */
+  tenant: Tenant;
+}
+
+/**
+ * Read the actor off a request that has already been authenticated.
+ *
+ * Returns null for an unauthenticated request rather than inventing an
+ * anonymous actor: there is nothing to attribute, and a row saying so would be
+ * a row about the transport, not about anyone.
+ */
+export function actorOf(req: Request): Actor | null {
+  const user = req.user;
+  if (!user?.id) return null;
+
+  const credential = req.apiKey;
+  if (!credential) {
+    return {
+      kind: 'person',
+      userId: user.id,
+      // Falling back to the email because a name is optional on a session and an
+      // unlabelled row is the one nobody can act on.
+      label: user.name || user.email || user.id,
+      tenant: (req.query?.groupId as string) || PERSONAL_TENANT
+    };
+  }
+
+  return {
+    kind: credential.kind === 'oauth' ? 'assistant' : 'key',
+    userId: user.id,
+    label: credential.label,
+    credentialId: credential.credentialId,
+    tenant: credential.actingAs
+  };
+}
+
+/** One line naming an actor, for a log message or an error. */
+export const describeActor = (actor: Actor): string =>
+  actor.kind === 'person' ? actor.label : `${actor.label} (${actor.kind})`;