@tumbaland/backend-core 1.37.0 → 1.39.0

package/src/apiKeys/types.ts

@@ -24,17 +24,69 @@ export const isApiKeyScope = (value: unknown): value is ApiKeyScope =>
   typeof value === 'string' && (API_KEY_SCOPES as readonly string[]).includes(value);
 
 /**
- * The tenant a key acts in, fixed when the key is created.
+ * A tenant a credential may act in: a group id, or the user's own data.
  *
- * The web app picks this per request from a tenant selector, but an agent has no
- * such UI and no way to know it guessed wrong — so the choice is made once, by a
- * person, and the key cannot escape it. `groupId: null` means the user's own
- * non-group data.
+ * Personal is a named sentinel rather than `null` so that a tenant is always a
+ * plain string — storable in an array, sendable in a JWT claim, comparable
+ * without a special case at every layer. It cannot collide with a real tenant:
+ * group ids are 24-character hex.
+ */
+export const PERSONAL_TENANT = 'personal';
+
+export type Tenant = string;
+
+/** The `groupId` a tenant corresponds to, as handlers have always read it. */
+export const groupIdOf = (tenant: Tenant): string | null =>
+  tenant === PERSONAL_TENANT ? null : tenant;
+
+/**
+ * Which tenants a credential may act in, and which one it acts in by default.
+ *
+ * The web app picks a tenant per request from a selector; an agent has no such
+ * UI. So the *set* is chosen once, by a person, and the credential cannot escape
+ * it — but within that set the caller may name one per request, which is what
+ * lets a single connection reach both a shared journal and a private photo
+ * library without reconnecting.
+ *
+ * `allowed` is never empty and always contains `default`. A credential granted
+ * exactly one tenant behaves precisely as a pinned one did: nothing to name,
+ * nothing to get wrong.
  */
 export interface ApiKeyTenant {
-  groupId: string | null;
+  allowed: Tenant[];
+  default: Tenant;
 }
 
+/** Just the groups, for the `req.userGroups` every handler already reads. */
+export const groupIdsOf = (tenants: Tenant[]): string[] =>
+  tenants.filter((tenant) => tenant !== PERSONAL_TENANT);
+
+/**
+ * Read a stored tenant grant, tolerating one written before tenants were a set.
+ *
+ * Keys and grants issued under the old single-tenant model carry `groupId`
+ * alone. Falling back to it here means they keep working across the deploy
+ * rather than every connected assistant breaking at once.
+ */
+export const readTenants = (stored: {
+  tenants?: Tenant[] | null;
+  defaultTenant?: Tenant | null;
+  groupId?: string | null;
+}): ApiKeyTenant => {
+  const allowed =
+    stored.tenants && stored.tenants.length > 0
+      ? stored.tenants
+      : [stored.groupId ?? PERSONAL_TENANT];
+
+  const fallbackDefault = allowed[0] as Tenant;
+  const preferred = stored.defaultTenant ?? fallbackDefault;
+
+  return {
+    allowed,
+    default: allowed.includes(preferred) ? preferred : fallbackDefault
+  };
+};
+
 /** A key as the API hands it back — never including the secret. */
 export interface ApiKeySummary {
   id: string;
@@ -42,7 +94,8 @@ export interface ApiKeySummary {
   /** the public half, shown in listings so a key is identifiable at a glance */
   prefix: string;
   scopes: ApiKeyScope[];
-  groupId: string | null;
+  tenants: Tenant[];
+  defaultTenant: Tenant;
   createdAt: string;
   lastUsedAt: string | null;
   expiresAt: string | null;
@@ -64,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[];
-  groupId?: string | null;
+  tenants?: ApiKeyTenant;
 }

package/src/audit/AuditEvent.ts

@@ -0,0 +1,79 @@
+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.
+ */
+export interface IAuditEvent extends Document {
+  at: Date;
+  /** which service handled it — 'relationship-service', 'album-service' */
+  service: string;
+  action: 'create' | 'update' | 'delete' | 'read';
+  /** 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;
+  createdAt: Date;
+}
+
+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'] },
+    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 }
+  },
+  { 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})`;

package/src/audit/context.test.ts

@@ -0,0 +1,91 @@
+import type { Request, Response } from 'express';
+
+jest.mock('./reads', () => ({ recordRead: jest.fn() }));
+
+import { recordRead } from './reads';
+import { beginAudit, currentAuditContext, withAuditContext } from './context';
+import { PERSONAL_TENANT } from '../apiKeys/types';
+
+const ORIGINAL_ENV = process.env;
+
+const req = (over: Partial<Request> = {}): Request =>
+  ({ method: 'GET', query: {}, body: {}, baseUrl: '', path: '/', ...over }) as unknown as Request;
+
+const res = () => ({ on: jest.fn(), locals: {} }) as unknown as Response;
+const user = { id: 'u1', email: 'tom@example.com', name: 'Tom' };
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV };
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+});
+
+describe('beginAudit', () => {
+  it('puts the actor in scope for everything after it', () => {
+    let seen: string | undefined;
+    beginAudit(req({ user }), res(), () => {
+      seen = currentAuditContext()?.actor.label;
+    });
+
+    expect(seen).toBe('Tom');
+  });
+
+  it('leaves no context behind once the request is done', () => {
+    beginAudit(req({ user }), res(), () => undefined);
+    // A leaked context would attribute the next request — or a background job —
+    // to whoever happened to come before it.
+    expect(currentAuditContext()).toBeUndefined();
+  });
+
+  it('continues without a context when nobody is authenticated', () => {
+    const next = jest.fn();
+    beginAudit(req(), res(), next);
+
+    expect(next).toHaveBeenCalled();
+    expect(recordRead).not.toHaveBeenCalled();
+  });
+
+  it('arms the read trail for the same request', () => {
+    beginAudit(req({ user }), res(), () => undefined);
+    expect(recordRead).toHaveBeenCalled();
+  });
+});
+
+describe('naming the service', () => {
+  it('uses SERVICE_NAME, as metrics and health already do', () => {
+    process.env.SERVICE_NAME = 'album-service';
+    let seen: string | undefined;
+
+    beginAudit(req({ user }), res(), () => {
+      seen = currentAuditContext()?.service;
+    });
+
+    expect(seen).toBe('album-service');
+  });
+
+  it('falls back to the package name, so local development is still labelled', () => {
+    // Nothing sets SERVICE_NAME in dev, and every row landing under one
+    // meaningless label makes the UI's area filter look broken.
+    delete process.env.SERVICE_NAME;
+    process.env.npm_package_name = 'finance-service';
+    let seen: string | undefined;
+
+    beginAudit(req({ user }), res(), () => {
+      seen = currentAuditContext()?.service;
+    });
+
+    expect(seen).toBe('finance-service');
+  });
+});
+
+describe('withAuditContext', () => {
+  it('runs work as an explicit actor, for jobs and tests', () => {
+    const actor = { kind: 'person' as const, userId: 'u1', label: 'Tom', tenant: PERSONAL_TENANT };
+    const seen = withAuditContext({ actor, service: 'test' }, () => currentAuditContext());
+
+    expect(seen?.actor.label).toBe('Tom');
+  });
+});

package/src/audit/context.ts

@@ -0,0 +1,83 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { actorOf, type Actor } from './actor';
+import { recordRead } from './reads';
+
+/**
+ * The actor, reachable from wherever the write actually happens.
+ *
+ * Attribution has to come from the request and be recorded at the data layer,
+ * and those are far apart: a Mongoose hook knows exactly which fields changed
+ * and nothing about who asked. Threading an actor through every service and
+ * controller signature to bridge that would touch every function between the
+ * two and be silently wrong the first time someone forgot.
+ *
+ * `AsyncLocalStorage` carries it instead, so the hook reads the actor without
+ * anything in between knowing it exists. A write outside a request — a script,
+ * a migration — simply finds no actor, which is the truth about it.
+ */
+export interface AuditContext {
+  actor: Actor;
+  service: string;
+}
+
+const storage = new AsyncLocalStorage<AuditContext>();
+
+export const currentAuditContext = (): AuditContext | undefined => storage.getStore();
+
+/**
+ * Run the rest of a request with its actor in scope.
+ *
+ * Mounted after authentication, since there is no actor before it.
+ */
+export const auditContext =
+  (service: string): RequestHandler =>
+  (req: Request, _res: Response, next: NextFunction): void => {
+    const actor = actorOf(req);
+    if (!actor) {
+      next();
+      return;
+    }
+
+    storage.run({ actor, service }, next);
+  };
+
+/** Run something with an explicit actor — for jobs and tests. */
+export const withAuditContext = <T>(context: AuditContext, fn: () => T): T =>
+  storage.run(context, fn);
+
+/**
+ * The service this process is, for a trail that spans several of them.
+ *
+ * `SERVICE_NAME` is already how metrics, health and the internal-service clients
+ * identify a process, so auditing uses the same one rather than introducing a
+ * second name for the same thing.
+ *
+ * The fallback to the package name matters more here than elsewhere: the trail
+ * is filtered by service in the UI, and in local development nothing sets
+ * `SERVICE_NAME`, so every row would land under one meaningless label and the
+ * filter would look broken. Every service's package is named after it.
+ */
+const serviceName = (): string =>
+  process.env.SERVICE_NAME || process.env.npm_package_name || 'unknown-service';
+
+/**
+ * Put a request's actor in scope, and arm the read trail, for everything after.
+ *
+ * Called from `authenticateAgent` rather than mounted as its own middleware. A
+ * separate mount only works on a router that authenticates with
+ * `router.use(...)`; routers that authenticate per route — album's photos,
+ * finance's tickers — have no actor yet when a router-level middleware runs, so
+ * the context would be silently empty for exactly the endpoints most worth
+ * auditing. Doing it where authentication happens makes the two inseparable.
+ */
+export function beginAudit(req: Request, res: Response, next: NextFunction): void {
+  const actor = actorOf(req);
+  if (!actor) {
+    next();
+    return;
+  }
+
+  recordRead(req, res, actor, serviceName());
+  storage.run({ actor, service: serviceName() }, next);
+}

package/src/audit/index.ts

@@ -0,0 +1,11 @@
+export { actorOf, describeActor } from './actor';
+export type { Actor, ActorKind } from './actor';
+export { AuditEvent } from './AuditEvent';
+export type { IAuditEvent } from './AuditEvent';
+export { auditContext, beginAudit, currentAuditContext, withAuditContext } from './context';
+export type { AuditContext } from './context';
+export { auditPlugin } from './plugin';
+export type { AuditPluginOptions } from './plugin';
+export { auditReads, countRead, resourceOf } from './reads';
+export { listAuditEvents } from './service';
+export type { AuditQuery, AuditEntry } from './service';