@tumbaland/backend-core 1.37.0 → 1.39.0

package/dist/apiKeys/types.js

@@ -9,7 +9,7 @@
  * it writes to rather than choosing one per request the way the UI does.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isApiKeyScope = exports.API_KEY_SCOPES = void 0;
+exports.readTenants = exports.groupIdsOf = exports.groupIdOf = exports.PERSONAL_TENANT = exports.isApiKeyScope = exports.API_KEY_SCOPES = void 0;
 /** Everything a key may be granted. Read and write are separate on purpose. */
 exports.API_KEY_SCOPES = [
     'relationship:read',
@@ -21,4 +21,38 @@ exports.API_KEY_SCOPES = [
 ];
 const isApiKeyScope = (value) => typeof value === 'string' && exports.API_KEY_SCOPES.includes(value);
 exports.isApiKeyScope = isApiKeyScope;
+/**
+ * A tenant a credential may act in: a group id, or the user's own 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.
+ */
+exports.PERSONAL_TENANT = 'personal';
+/** The `groupId` a tenant corresponds to, as handlers have always read it. */
+const groupIdOf = (tenant) => tenant === exports.PERSONAL_TENANT ? null : tenant;
+exports.groupIdOf = groupIdOf;
+/** Just the groups, for the `req.userGroups` every handler already reads. */
+const groupIdsOf = (tenants) => tenants.filter((tenant) => tenant !== exports.PERSONAL_TENANT);
+exports.groupIdsOf = groupIdsOf;
+/**
+ * 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.
+ */
+const readTenants = (stored) => {
+    const allowed = stored.tenants && stored.tenants.length > 0
+        ? stored.tenants
+        : [stored.groupId ?? exports.PERSONAL_TENANT];
+    const fallbackDefault = allowed[0];
+    const preferred = stored.defaultTenant ?? fallbackDefault;
+    return {
+        allowed,
+        default: allowed.includes(preferred) ? preferred : fallbackDefault
+    };
+};
+exports.readTenants = readTenants;
 //# sourceMappingURL=types.js.map

package/dist/apiKeys/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/apiKeys/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,+EAA+E;AAClE,QAAA,cAAc,GAAG;IAC5B,mBAAmB;IACnB,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,eAAe;CACP,CAAC;AAIJ,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AADxE,QAAA,aAAa,iBAC2D"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/apiKeys/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAEH,+EAA+E;AAClE,QAAA,cAAc,GAAG;IAC5B,mBAAmB;IACnB,oBAAoB;IACpB,YAAY;IACZ,aAAa;IACb,cAAc;IACd,eAAe;CACP,CAAC;AAIJ,MAAM,aAAa,GAAG,CAAC,KAAc,EAAwB,EAAE,CACpE,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AADxE,QAAA,aAAa,iBAC2D;AAErF;;;;;;;GAOG;AACU,QAAA,eAAe,GAAG,UAAU,CAAC;AAI1C,8EAA8E;AACvE,MAAM,SAAS,GAAG,CAAC,MAAc,EAAiB,EAAE,CACzD,MAAM,KAAK,uBAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;AADhC,QAAA,SAAS,aACuB;AAoB7C,6EAA6E;AACtE,MAAM,UAAU,GAAG,CAAC,OAAiB,EAAY,EAAE,CACxD,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,uBAAe,CAAC,CAAC;AAD5C,QAAA,UAAU,cACkC;AAEzD;;;;;;GAMG;AACI,MAAM,WAAW,GAAG,CAAC,MAI3B,EAAgB,EAAE;IACjB,MAAM,OAAO,GACX,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QACzC,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,uBAAe,CAAC,CAAC;IAE1C,MAAM,eAAe,GAAG,OAAO,CAAC,CAAC,CAAW,CAAC;IAC7C,MAAM,SAAS,GAAG,MAAM,CAAC,aAAa,IAAI,eAAe,CAAC;IAE1D,OAAO;QACL,OAAO;QACP,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe;KACnE,CAAC;AACJ,CAAC,CAAC;AAjBW,QAAA,WAAW,eAiBtB"}

package/dist/audit/AuditEvent.d.ts

@@ -0,0 +1,51 @@
+import mongoose, { Document } 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;
+}
+export declare const AuditEvent: mongoose.Model<IAuditEvent, {}, {}, {}, mongoose.Document<unknown, {}, IAuditEvent, {}, mongoose.DefaultSchemaOptions> & IAuditEvent & Required<{
+    _id: mongoose.Types.ObjectId;
+}> & {
+    __v: number;
+} & {
+    id: string;
+}, any, IAuditEvent>;
+//# sourceMappingURL=AuditEvent.d.ts.map

package/dist/audit/AuditEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuditEvent.d.ts","sourceRoot":"","sources":["../../src/audit/AuditEvent.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,EAAE,EAAE,QAAQ,EAAU,MAAM,UAAU,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;;;;GAOG;AACH,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,EAAE,EAAE,IAAI,CAAC;IACT,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;IAChD,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzD,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;CACjB;AAoCD,eAAO,MAAM,UAAU;;;;;;oBAEwC,CAAC"}

package/dist/audit/AuditEvent.js

@@ -0,0 +1,69 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditEvent = void 0;
+const mongoose_1 = __importStar(require("mongoose"));
+const AuditEventSchema = new mongoose_1.Schema({
+    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: mongoose_1.Schema.Types.Mixed },
+    snapshot: { type: mongoose_1.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 });
+exports.AuditEvent = mongoose_1.default.models.AuditEvent
+    ? mongoose_1.default.models.AuditEvent
+    : mongoose_1.default.model('AuditEvent', AuditEventSchema);
+//# sourceMappingURL=AuditEvent.js.map

package/dist/audit/AuditEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuditEvent.js","sourceRoot":"","sources":["../../src/audit/AuditEvent.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,qDAAsD;AA0CtD,MAAM,gBAAgB,GAAG,IAAI,iBAAM,CACjC;IACE,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;IACrD,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IACzC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE;IACtF,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC1C,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;IAC5B,SAAS,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE;IACjF,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;IACrD,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IAC5C,iBAAiB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;IACnC,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE;IACxC,OAAO,EAAE,EAAE,IAAI,EAAE,iBAAM,CAAC,KAAK,CAAC,KAAK,EAAE;IACrC,QAAQ,EAAE,EAAE,IAAI,EAAE,iBAAM,CAAC,KAAK,CAAC,KAAK,EAAE;IACtC,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;CACxB,EACD,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,CAClF,CAAC;AAEF,sDAAsD;AACtD,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,gBAAgB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,kBAAkB,EAAE,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;AAE5E,QAAA,UAAU,GAAG,kBAAQ,CAAC,MAAM,CAAC,UAAU;IAClD,CAAC,CAAE,kBAAQ,CAAC,MAAM,CAAC,UAA0C;IAC7D,CAAC,CAAC,kBAAQ,CAAC,KAAK,CAAc,YAAY,EAAE,gBAAgB,CAAC,CAAC"}

package/dist/audit/actor.d.ts

@@ -0,0 +1,41 @@
+import type { Request } from 'express';
+import { 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 declare function actorOf(req: Request): Actor | null;
+/** One line naming an actor, for a log message or an error. */
+export declare const describeActor: (actor: Actor) => string;
+//# sourceMappingURL=actor.d.ts.map

package/dist/audit/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../src/audit/actor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAmB,KAAK,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAEhE;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,WAAW,CAAC;AAEvD,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CAuBlD;AAED,+DAA+D;AAC/D,eAAO,MAAM,aAAa,GAAI,OAAO,KAAK,KAAG,MAC6B,CAAC"}

package/dist/audit/actor.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeActor = void 0;
+exports.actorOf = actorOf;
+const types_1 = require("../apiKeys/types");
+/**
+ * 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.
+ */
+function actorOf(req) {
+    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 || types_1.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. */
+const describeActor = (actor) => actor.kind === 'person' ? actor.label : `${actor.label} (${actor.kind})`;
+exports.describeActor = describeActor;
+//# sourceMappingURL=actor.js.map

package/dist/audit/actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.js","sourceRoot":"","sources":["../../src/audit/actor.ts"],"names":[],"mappings":";;;AAwCA,0BAuBC;AA9DD,4CAAgE;AAgChE;;;;;;GAMG;AACH,SAAgB,OAAO,CAAC,GAAY;IAClC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,CAAC,IAAI,EAAE,EAAE;QAAE,OAAO,IAAI,CAAC;IAE3B,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC;IAC9B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,IAAI,CAAC,EAAE;YACf,2EAA2E;YAC3E,+CAA+C;YAC/C,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,EAAE;YACzC,MAAM,EAAG,GAAG,CAAC,KAAK,EAAE,OAAkB,IAAI,uBAAe;SAC1D,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK;QACvD,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,YAAY,EAAE,UAAU,CAAC,YAAY;QACrC,MAAM,EAAE,UAAU,CAAC,QAAQ;KAC5B,CAAC;AACJ,CAAC;AAED,+DAA+D;AACxD,MAAM,aAAa,GAAG,CAAC,KAAY,EAAU,EAAE,CACpD,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC;AAD9D,QAAA,aAAa,iBACiD"}

package/dist/audit/context.d.ts

@@ -0,0 +1,40 @@
+import type { NextFunction, Request, RequestHandler, Response } from 'express';
+import { type Actor } from './actor';
+/**
+ * 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;
+}
+export declare const currentAuditContext: () => AuditContext | undefined;
+/**
+ * Run the rest of a request with its actor in scope.
+ *
+ * Mounted after authentication, since there is no actor before it.
+ */
+export declare const auditContext: (service: string) => RequestHandler;
+/** Run something with an explicit actor — for jobs and tests. */
+export declare const withAuditContext: <T>(context: AuditContext, fn: () => T) => T;
+/**
+ * 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 declare function beginAudit(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/audit/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/audit/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAW,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAG9C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAID,eAAO,MAAM,mBAAmB,QAAO,YAAY,GAAG,SAA+B,CAAC;AAEtF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACtB,SAAS,MAAM,KAAG,cASlB,CAAC;AAEJ,iEAAiE;AACjE,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,SAAS,YAAY,EAAE,IAAI,MAAM,CAAC,KAAG,CAC/C,CAAC;AAiB3B;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAShF"}

package/dist/audit/context.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withAuditContext = exports.auditContext = exports.currentAuditContext = void 0;
+exports.beginAudit = beginAudit;
+const node_async_hooks_1 = require("node:async_hooks");
+const actor_1 = require("./actor");
+const reads_1 = require("./reads");
+const storage = new node_async_hooks_1.AsyncLocalStorage();
+const currentAuditContext = () => storage.getStore();
+exports.currentAuditContext = currentAuditContext;
+/**
+ * Run the rest of a request with its actor in scope.
+ *
+ * Mounted after authentication, since there is no actor before it.
+ */
+const auditContext = (service) => (req, _res, next) => {
+    const actor = (0, actor_1.actorOf)(req);
+    if (!actor) {
+        next();
+        return;
+    }
+    storage.run({ actor, service }, next);
+};
+exports.auditContext = auditContext;
+/** Run something with an explicit actor — for jobs and tests. */
+const withAuditContext = (context, fn) => storage.run(context, fn);
+exports.withAuditContext = withAuditContext;
+/**
+ * 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 = () => 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.
+ */
+function beginAudit(req, res, next) {
+    const actor = (0, actor_1.actorOf)(req);
+    if (!actor) {
+        next();
+        return;
+    }
+    (0, reads_1.recordRead)(req, res, actor, serviceName());
+    storage.run({ actor, service: serviceName() }, next);
+}
+//# sourceMappingURL=context.js.map

package/dist/audit/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/audit/context.ts"],"names":[],"mappings":";;;AAyEA,gCASC;AAlFD,uDAAqD;AAErD,mCAA8C;AAC9C,mCAAqC;AAoBrC,MAAM,OAAO,GAAG,IAAI,oCAAiB,EAAgB,CAAC;AAE/C,MAAM,mBAAmB,GAAG,GAA6B,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;AAAzE,QAAA,mBAAmB,uBAAsD;AAEtF;;;;GAIG;AACI,MAAM,YAAY,GACvB,CAAC,OAAe,EAAkB,EAAE,CACpC,CAAC,GAAY,EAAE,IAAc,EAAE,IAAkB,EAAQ,EAAE;IACzD,MAAM,KAAK,GAAG,IAAA,eAAO,EAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,EAAE,CAAC;QACP,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;AACxC,CAAC,CAAC;AAVS,QAAA,YAAY,gBAUrB;AAEJ,iEAAiE;AAC1D,MAAM,gBAAgB,GAAG,CAAI,OAAqB,EAAE,EAAW,EAAK,EAAE,CAC3E,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AADd,QAAA,gBAAgB,oBACF;AAE3B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,GAAG,GAAW,EAAE,CAC/B,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,iBAAiB,CAAC;AAEhF;;;;;;;;;GASG;AACH,SAAgB,UAAU,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;IACxE,MAAM,KAAK,GAAG,IAAA,eAAO,EAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,IAAI,EAAE,CAAC;QACP,OAAO;IACT,CAAC;IAED,IAAA,kBAAU,EAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAC3C,OAAO,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/audit/index.d.ts

@@ -0,0 +1,12 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACjD,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC5F,YAAY,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvC,YAAY,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AACnD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/audit/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listAuditEvents = exports.resourceOf = exports.countRead = exports.auditReads = exports.auditPlugin = exports.withAuditContext = exports.currentAuditContext = exports.beginAudit = exports.auditContext = exports.AuditEvent = exports.describeActor = exports.actorOf = void 0;
+var actor_1 = require("./actor");
+Object.defineProperty(exports, "actorOf", { enumerable: true, get: function () { return actor_1.actorOf; } });
+Object.defineProperty(exports, "describeActor", { enumerable: true, get: function () { return actor_1.describeActor; } });
+var AuditEvent_1 = require("./AuditEvent");
+Object.defineProperty(exports, "AuditEvent", { enumerable: true, get: function () { return AuditEvent_1.AuditEvent; } });
+var context_1 = require("./context");
+Object.defineProperty(exports, "auditContext", { enumerable: true, get: function () { return context_1.auditContext; } });
+Object.defineProperty(exports, "beginAudit", { enumerable: true, get: function () { return context_1.beginAudit; } });
+Object.defineProperty(exports, "currentAuditContext", { enumerable: true, get: function () { return context_1.currentAuditContext; } });
+Object.defineProperty(exports, "withAuditContext", { enumerable: true, get: function () { return context_1.withAuditContext; } });
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "auditPlugin", { enumerable: true, get: function () { return plugin_1.auditPlugin; } });
+var reads_1 = require("./reads");
+Object.defineProperty(exports, "auditReads", { enumerable: true, get: function () { return reads_1.auditReads; } });
+Object.defineProperty(exports, "countRead", { enumerable: true, get: function () { return reads_1.countRead; } });
+Object.defineProperty(exports, "resourceOf", { enumerable: true, get: function () { return reads_1.resourceOf; } });
+var service_1 = require("./service");
+Object.defineProperty(exports, "listAuditEvents", { enumerable: true, get: function () { return service_1.listAuditEvents; } });
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":";;;AAAA,iCAAiD;AAAxC,gGAAA,OAAO,OAAA;AAAE,sGAAA,aAAa,OAAA;AAE/B,2CAA0C;AAAjC,wGAAA,UAAU,OAAA;AAEnB,qCAA4F;AAAnF,uGAAA,YAAY,OAAA;AAAE,qGAAA,UAAU,OAAA;AAAE,8GAAA,mBAAmB,OAAA;AAAE,2GAAA,gBAAgB,OAAA;AAExE,mCAAuC;AAA9B,qGAAA,WAAW,OAAA;AAEpB,iCAA4D;AAAnD,mGAAA,UAAU,OAAA;AAAE,kGAAA,SAAS,OAAA;AAAE,mGAAA,UAAU,OAAA;AAC1C,qCAA4C;AAAnC,0GAAA,eAAe,OAAA"}

package/dist/audit/plugin.d.ts

@@ -0,0 +1,23 @@
+import type { Schema } from 'mongoose';
+export interface AuditPluginOptions {
+    /** what these documents are called in a trail — 'activity', 'photo' */
+    resource: string;
+    /** fields never worth recording the content of */
+    redact?: string[];
+}
+/**
+ * Attribute and record every write to a collection.
+ *
+ * Applied to a model rather than called from its controllers, for two reasons.
+ * The data layer is the only place that knows which fields actually changed —
+ * a controller sees the patch that was requested, not the difference it made,
+ * and those differ whenever a field was already the value being set. And a
+ * plugin cannot be forgotten: a new endpoint that writes through the model is
+ * audited without anyone remembering to add a line.
+ *
+ * Writes made outside a request — a migration, a backfill script — find no
+ * actor and are recorded as nothing, which is honest. A row claiming a script
+ * was a person would be worse than no row.
+ */
+export declare function auditPlugin(schema: Schema, options: AuditPluginOptions): void;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/audit/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/audit/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,MAAM,EAAE,MAAM,UAAU,CAAC;AA6D9C,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CA2K7E"}