@things-factory/auth-base 10.1.192 → 10.1.198

package/dist-server/service/audit/audit-recorder.js

@@ -0,0 +1,247 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runInAuditScope = runInAuditScope;
+exports.currentAuditScope = currentAuditScope;
+exports.noteAuditAction = noteAuditAction;
+exports.recordAuditAction = recordAuditAction;
+exports.addressOf = addressOf;
+exports.operationOf = operationOf;
+exports.auditHealth = auditHealth;
+exports.flushAudit = flushAudit;
+const async_hooks_1 = require("async_hooks");
+const crypto_1 = require("crypto");
+const graphql_1 = require("graphql");
+const env_1 = require("@things-factory/env");
+const shell_1 = require("@things-factory/shell");
+const audit_action_js_1 = require("./audit-action.js");
+const audit_kinds_js_1 = require("./audit-kinds.js");
+const audit_request_js_1 = require("./audit-request.js");
+/**
+ * ── The audit recorder (ADR-0141) ──────────────────────────────────────────
+ *
+ * A request runs inside a scope (`runInAuditScope`, installed once by the auth middleware). Door
+ * checks and results are merged into the scope while the request runs and written with the request
+ * row when it ends - one write per request, apart from the business transaction, and never in the
+ * way of the answer (§4-4). Events (`recordAuditAction`) are written when they happen: inside the
+ * caller's transaction when it hands one (§4-1, they fail together), on their own otherwise (§4-2 ·
+ * §4-3, a failure is counted and does not undo what already happened).
+ *
+ * Who and where are read from the request's context at write time, so a door checked before the
+ * user was known still lands under them once they are.
+ */
+const MAX_TARGETS = 100;
+const storage = new async_hooks_1.AsyncLocalStorage();
+/** Runs `work` as one audited request; the request row and merged actions are written when it ends. */
+async function runInAuditScope(context, channel, work) {
+    const scope = {
+        requestId: (0, crypto_1.randomUUID)(),
+        channel,
+        context,
+        startedAt: Date.now(),
+        merged: new Map(),
+        recorded: false
+    };
+    try {
+        return await storage.run(scope, work);
+    }
+    finally {
+        track(finishAuditScope(scope));
+    }
+}
+function currentAuditScope() {
+    return storage.getStore();
+}
+/* ── merging door checks and results ───────────────────────────────────── */
+function keyOf(input) {
+    return [input.kind, input.door, input.decision, input.basis, input.outcome, input.code, input.targetKind, input.targetRole].join('|');
+}
+/**
+ * Notes a door check or result in the running request. Equal ones become one row with a count; their
+ * targets are kept together, up to 100 (ADR-0141 §3.2). Outside any request this does nothing - a
+ * subscription stream or a boot task is not audited at the door (§9 step 4).
+ */
+function noteAuditAction(input) {
+    const scope = currentAuditScope();
+    if (!scope)
+        return;
+    (0, audit_kinds_js_1.allowedDetail)(input.kind, input.detail);
+    const key = keyOf(input);
+    let merged = scope.merged.get(key);
+    if (!merged) {
+        merged = { ...input, count: 0, targets: new Set(), truncated: false, returned: undefined };
+        scope.merged.set(key, merged);
+    }
+    merged.count++;
+    if (typeof input.returned === 'number') {
+        merged.returned = (merged.returned ?? 0) + input.returned;
+    }
+    for (const id of input.targetIds || []) {
+        if (merged.targets.has(id))
+            continue;
+        if (merged.targets.size >= MAX_TARGETS) {
+            merged.truncated = true;
+            break;
+        }
+        merged.targets.add(id);
+    }
+}
+/**
+ * Writes one event now. With `manager` it shares the caller's transaction and throws with it;
+ * without, it is written on its own and a failure is only counted (ADR-0141 §4-2 · §4-3 · §4-5).
+ */
+async function recordAuditAction(input, options = {}) {
+    const scope = currentAuditScope();
+    const row = rowOf(input, scope, options);
+    if (scope) {
+        scope.recorded = true;
+        if (options.actorId)
+            scope.eventActorId ??= options.actorId;
+        if (options.domainId)
+            scope.eventDomainId ??= options.domainId;
+    }
+    if (options.manager) {
+        await options.manager.getRepository(audit_action_js_1.AuditAction).insert(row);
+        return;
+    }
+    const writing = (0, shell_1.getRepository)(audit_action_js_1.AuditAction)
+        .insert(row)
+        .then(() => undefined, error => countFailure(error, input.kind));
+    track(writing);
+    await writing;
+}
+function rowOf(input, scope, options, count = 1, targets, truncated = false) {
+    const state = scope?.context?.state || {};
+    const actorId = options.actorId !== undefined ? options.actorId : state.user?.id;
+    const domainId = options.domainId !== undefined ? options.domainId : state.domain?.id;
+    const ids = targets ?? (input.targetIds || []).slice(0, MAX_TARGETS);
+    return {
+        requestId: scope?.requestId ?? null,
+        domain: domainId ? { id: domainId } : null,
+        actor: actorId ? { id: actorId } : null,
+        kind: input.kind,
+        door: input.door ?? null,
+        decision: input.decision ?? null,
+        basis: input.basis ?? null,
+        outcome: input.outcome ?? null,
+        code: input.code ? String(input.code).slice(0, 64) : null,
+        count,
+        returned: input.returned ?? null,
+        targetKind: input.targetKind ?? null,
+        targetIds: ids.length ? ids : null,
+        truncated: truncated || (input.targetIds || []).length > MAX_TARGETS,
+        targetRole: input.targetRole ?? null,
+        objectKind: input.objectKind ?? null,
+        objectId: input.objectId ? String(input.objectId).slice(0, 128) : null,
+        detail: (0, audit_kinds_js_1.allowedDetail)(input.kind, input.detail) ?? null
+    };
+}
+/* ── the request row ────────────────────────────────────────────────────── */
+/** The address a request came from - the first `x-forwarded-for` value, as the check-in record always took it. */
+function addressOf(context) {
+    const forwarded = context?.req?.headers?.['x-forwarded-for'];
+    const address = forwarded ? forwarded.split(',')[0].trim() : context?.req?.socket?.remoteAddress;
+    return address ? String(address).slice(0, 64) : undefined;
+}
+/**
+ * What a GraphQL request asked: its operation type and the root fields by their schema names - never
+ * an argument or a variable (ADR-0141 §3.4). A field with no `@privilege` leaves no action, so these
+ * names are what says which open door a request used. The parsed document is Apollo's and is not
+ * reachable from here; parsing again is the cost of knowing.
+ */
+function operationOf(body) {
+    const first = Array.isArray(body) ? body[0] : body;
+    if (!first || typeof first !== 'object' || typeof first.query !== 'string')
+        return {};
+    const name = typeof first.operationName === 'string' ? first.operationName.slice(0, 128) : undefined;
+    try {
+        const document = (0, graphql_1.parse)(first.query);
+        const operations = document.definitions.filter((one) => one.kind === graphql_1.Kind.OPERATION_DEFINITION);
+        const operation = operations.find(one => !name || one.name?.value === name) ?? operations[0];
+        if (!operation)
+            return { operationName: name };
+        const fragments = new Map(document.definitions.flatMap(one => (one.kind === graphql_1.Kind.FRAGMENT_DEFINITION ? [[one.name.value, one.selectionSet]] : [])));
+        const names = new Set();
+        const walk = (set, seen) => {
+            for (const selection of set.selections) {
+                if (selection.kind === graphql_1.Kind.FIELD)
+                    names.add(selection.name.value);
+                else if (selection.kind === graphql_1.Kind.INLINE_FRAGMENT)
+                    walk(selection.selectionSet, seen);
+                else if (selection.kind === graphql_1.Kind.FRAGMENT_SPREAD && !seen.has(selection.name.value)) {
+                    const spread = fragments.get(selection.name.value);
+                    if (spread)
+                        walk(spread, new Set([...seen, selection.name.value]));
+                }
+            }
+        };
+        walk(operation.selectionSet, new Set());
+        return { operationType: operation.operation, operationName: name, fields: [...names].join(',').slice(0, 256) || undefined };
+    }
+    catch {
+        return { operationName: name };
+    }
+}
+async function finishAuditScope(scope) {
+    if (scope.channel === 'http' && !scope.recorded && scope.merged.size === 0)
+        return;
+    const context = scope.context;
+    const state = context?.state || {};
+    const domainId = state.domain?.id ?? scope.eventDomainId;
+    const actorId = state.user?.id ?? scope.eventActorId;
+    const request = {
+        id: scope.requestId,
+        domain: domainId ? { id: domainId } : null,
+        actor: actorId ? { id: actorId } : null,
+        ip: addressOf(context) ?? null,
+        userAgent: context?.request?.header?.['user-agent']?.slice(0, 256) ?? null,
+        durationMs: Date.now() - scope.startedAt,
+        channel: scope.channel,
+        route: scope.channel === 'http' ? (context?._matchedRoute ? String(context._matchedRoute).slice(0, 128) : null) : null,
+        ...(scope.channel === 'graphql' ? operationOf(context?.request?.body) : {})
+    };
+    const actions = [...scope.merged.values()].map(merged => rowOf(merged, scope, {}, merged.count, [...merged.targets], merged.truncated));
+    /*
+     * Two plain inserts, no transaction of their own: a sqlite database has one connection, and a
+     * transaction opened here collided with the requests' own (「cannot start a transaction within a
+     * transaction」, seen on Office's development database). The line and its actions are both best
+     * effort (§4-4); one failing is counted like the other.
+     */
+    try {
+        await (0, shell_1.getRepository)(audit_request_js_1.AuditRequest).insert(request);
+        if (actions.length)
+            await (0, shell_1.getRepository)(audit_action_js_1.AuditAction).insert(actions);
+    }
+    catch (error) {
+        countFailure(error, 'request');
+    }
+}
+/* ── failures, counted apart from the audit store (ADR-0141 §4-5) ──────── */
+const health = {
+    since: new Date(),
+    failures: 0,
+    firstFailedAt: null,
+    lastFailedAt: null
+};
+function countFailure(error, what) {
+    const now = new Date();
+    health.failures++;
+    health.firstFailedAt ??= now;
+    health.lastFailedAt = now;
+    env_1.logger.error(`[audit] not written (${what}): ${error?.message}`);
+}
+/** Failures this server process detected since it started. Not those it never got to try. */
+function auditHealth() {
+    return { ...health };
+}
+/* ── for tests: wait for every write started so far ────────────────────── */
+const pending = new Set();
+function track(promise) {
+    pending.add(promise);
+    promise.finally(() => pending.delete(promise));
+}
+async function flushAudit() {
+    while (pending.size) {
+        await Promise.allSettled([...pending]);
+    }
+}
+//# sourceMappingURL=audit-recorder.js.map

package/dist-server/service/audit/audit-recorder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-recorder.js","sourceRoot":"","sources":["../../../server/service/audit/audit-recorder.ts"],"names":[],"mappings":"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","sourcesContent":["import { AsyncLocalStorage } from 'async_hooks'\nimport { randomUUID } from 'crypto'\nimport { Kind, OperationDefinitionNode, parse, SelectionSetNode } from 'graphql'\nimport { EntityManager } from 'typeorm'\n\nimport { logger } from '@things-factory/env'\nimport { getRepository } from '@things-factory/shell'\n\nimport { AuditAction } from './audit-action.js'\nimport { allowedDetail, AuditDetailValue } from './audit-kinds.js'\nimport { AuditRequest } from './audit-request.js'\n\n/**\n * ── The audit recorder (ADR-0141) ──────────────────────────────────────────\n *\n * A request runs inside a scope (`runInAuditScope`, installed once by the auth middleware). Door\n * checks and results are merged into the scope while the request runs and written with the request\n * row when it ends - one write per request, apart from the business transaction, and never in the\n * way of the answer (§4-4). Events (`recordAuditAction`) are written when they happen: inside the\n * caller's transaction when it hands one (§4-1, they fail together), on their own otherwise (§4-2 ·\n * §4-3, a failure is counted and does not undo what already happened).\n *\n * Who and where are read from the request's context at write time, so a door checked before the\n * user was known still lands under them once they are.\n */\n\nconst MAX_TARGETS = 100\n\nexport type AuditChannel = 'graphql' | 'http'\n\nexport interface AuditActionInput {\n  kind: string\n  door?: string\n  decision?: 'granted' | 'denied'\n  basis?: string\n  outcome?: 'ok' | 'error'\n  code?: string\n  returned?: number\n  targetKind?: string\n  targetIds?: string[]\n  targetRole?: 'requested' | 'handled'\n  objectKind?: string\n  objectId?: string\n  detail?: Record<string, AuditDetailValue>\n}\n\ninterface MergedAction extends AuditActionInput {\n  count: number\n  targets: Set<string>\n  truncated: boolean\n}\n\nexport interface AuditScope {\n  requestId: string\n  channel: AuditChannel\n  context: any\n  startedAt: number\n  merged: Map<string, MergedAction>\n  /* An http request is kept only when something in it was recorded. */\n  recorded: boolean\n  /* Who and where its events named, for a request that ran before the context knew (a sign-in, a check-in). */\n  eventActorId?: string\n  eventDomainId?: string\n}\n\nconst storage = new AsyncLocalStorage<AuditScope>()\n\n/** Runs `work` as one audited request; the request row and merged actions are written when it ends. */\nexport async function runInAuditScope<T>(context: any, channel: AuditChannel, work: () => Promise<T>): Promise<T> {\n  const scope: AuditScope = {\n    requestId: randomUUID(),\n    channel,\n    context,\n    startedAt: Date.now(),\n    merged: new Map(),\n    recorded: false\n  }\n\n  try {\n    return await storage.run(scope, work)\n  } finally {\n    track(finishAuditScope(scope))\n  }\n}\n\nexport function currentAuditScope(): AuditScope | undefined {\n  return storage.getStore()\n}\n\n/* ── merging door checks and results ───────────────────────────────────── */\n\nfunction keyOf(input: AuditActionInput) {\n  return [input.kind, input.door, input.decision, input.basis, input.outcome, input.code, input.targetKind, input.targetRole].join('|')\n}\n\n/**\n * Notes a door check or result in the running request. Equal ones become one row with a count; their\n * targets are kept together, up to 100 (ADR-0141 §3.2). Outside any request this does nothing - a\n * subscription stream or a boot task is not audited at the door (§9 step 4).\n */\nexport function noteAuditAction(input: AuditActionInput) {\n  const scope = currentAuditScope()\n  if (!scope) return\n\n  allowedDetail(input.kind, input.detail)\n\n  const key = keyOf(input)\n  let merged = scope.merged.get(key)\n  if (!merged) {\n    merged = { ...input, count: 0, targets: new Set(), truncated: false, returned: undefined }\n    scope.merged.set(key, merged)\n  }\n\n  merged.count++\n  if (typeof input.returned === 'number') {\n    merged.returned = (merged.returned ?? 0) + input.returned\n  }\n  for (const id of input.targetIds || []) {\n    if (merged.targets.has(id)) continue\n    if (merged.targets.size >= MAX_TARGETS) {\n      merged.truncated = true\n      break\n    }\n    merged.targets.add(id)\n  }\n}\n\n/* ── events ─────────────────────────────────────────────────────────────── */\n\nexport interface RecordOptions {\n  /** The business transaction. Given, the event is written in it and a failure fails the change (§4-1). */\n  manager?: EntityManager\n  /** Who did it, when the context does not know yet (a sign-in). `null` says nobody is known. */\n  actorId?: string | null\n  /** Where, when it is not the request's domain (a role of another domain, a sign-in with no domain). */\n  domainId?: string | null\n}\n\n/**\n * Writes one event now. With `manager` it shares the caller's transaction and throws with it;\n * without, it is written on its own and a failure is only counted (ADR-0141 §4-2 · §4-3 · §4-5).\n */\nexport async function recordAuditAction(input: AuditActionInput, options: RecordOptions = {}): Promise<void> {\n  const scope = currentAuditScope()\n  const row = rowOf(input, scope, options)\n\n  if (scope) {\n    scope.recorded = true\n    if (options.actorId) scope.eventActorId ??= options.actorId\n    if (options.domainId) scope.eventDomainId ??= options.domainId\n  }\n\n  if (options.manager) {\n    await options.manager.getRepository(AuditAction).insert(row)\n    return\n  }\n\n  const writing = getRepository(AuditAction)\n    .insert(row)\n    .then(\n      () => undefined,\n      error => countFailure(error, input.kind)\n    )\n  track(writing)\n  await writing\n}\n\nfunction rowOf(input: AuditActionInput, scope: AuditScope | undefined, options: RecordOptions, count = 1, targets?: string[], truncated = false) {\n  const state = scope?.context?.state || {}\n  const actorId = options.actorId !== undefined ? options.actorId : state.user?.id\n  const domainId = options.domainId !== undefined ? options.domainId : state.domain?.id\n  const ids = targets ?? (input.targetIds || []).slice(0, MAX_TARGETS)\n\n  return {\n    requestId: scope?.requestId ?? null,\n    domain: domainId ? { id: domainId } : null,\n    actor: actorId ? { id: actorId } : null,\n    kind: input.kind,\n    door: input.door ?? null,\n    decision: input.decision ?? null,\n    basis: input.basis ?? null,\n    outcome: input.outcome ?? null,\n    code: input.code ? String(input.code).slice(0, 64) : null,\n    count,\n    returned: input.returned ?? null,\n    targetKind: input.targetKind ?? null,\n    targetIds: ids.length ? ids : null,\n    truncated: truncated || (input.targetIds || []).length > MAX_TARGETS,\n    targetRole: input.targetRole ?? null,\n    objectKind: input.objectKind ?? null,\n    objectId: input.objectId ? String(input.objectId).slice(0, 128) : null,\n    detail: allowedDetail(input.kind, input.detail) ?? null\n  } as any\n}\n\n/* ── the request row ────────────────────────────────────────────────────── */\n\n/** The address a request came from - the first `x-forwarded-for` value, as the check-in record always took it. */\nexport function addressOf(context: any): string | undefined {\n  const forwarded = context?.req?.headers?.['x-forwarded-for'] as string | undefined\n  const address = forwarded ? forwarded.split(',')[0].trim() : context?.req?.socket?.remoteAddress\n  return address ? String(address).slice(0, 64) : undefined\n}\n\n/**\n * What a GraphQL request asked: its operation type and the root fields by their schema names - never\n * an argument or a variable (ADR-0141 §3.4). A field with no `@privilege` leaves no action, so these\n * names are what says which open door a request used. The parsed document is Apollo's and is not\n * reachable from here; parsing again is the cost of knowing.\n */\nexport function operationOf(body: any): { operationType?: string; operationName?: string; fields?: string } {\n  const first = Array.isArray(body) ? body[0] : body\n  if (!first || typeof first !== 'object' || typeof first.query !== 'string') return {}\n\n  const name = typeof first.operationName === 'string' ? first.operationName.slice(0, 128) : undefined\n\n  try {\n    const document = parse(first.query)\n    const operations = document.definitions.filter((one): one is OperationDefinitionNode => one.kind === Kind.OPERATION_DEFINITION)\n    const operation = operations.find(one => !name || one.name?.value === name) ?? operations[0]\n    if (!operation) return { operationName: name }\n\n    const fragments = new Map(\n      document.definitions.flatMap(one => (one.kind === Kind.FRAGMENT_DEFINITION ? [[one.name.value, one.selectionSet] as const] : []))\n    )\n    const names = new Set<string>()\n    const walk = (set: SelectionSetNode, seen: Set<string>) => {\n      for (const selection of set.selections) {\n        if (selection.kind === Kind.FIELD) names.add(selection.name.value)\n        else if (selection.kind === Kind.INLINE_FRAGMENT) walk(selection.selectionSet, seen)\n        else if (selection.kind === Kind.FRAGMENT_SPREAD && !seen.has(selection.name.value)) {\n          const spread = fragments.get(selection.name.value)\n          if (spread) walk(spread, new Set([...seen, selection.name.value]))\n        }\n      }\n    }\n    walk(operation.selectionSet, new Set())\n\n    return { operationType: operation.operation, operationName: name, fields: [...names].join(',').slice(0, 256) || undefined }\n  } catch {\n    return { operationName: name }\n  }\n}\n\nasync function finishAuditScope(scope: AuditScope): Promise<void> {\n  if (scope.channel === 'http' && !scope.recorded && scope.merged.size === 0) return\n\n  const context = scope.context\n  const state = context?.state || {}\n\n  const domainId = state.domain?.id ?? scope.eventDomainId\n  const actorId = state.user?.id ?? scope.eventActorId\n\n  const request = {\n    id: scope.requestId,\n    domain: domainId ? { id: domainId } : null,\n    actor: actorId ? { id: actorId } : null,\n    ip: addressOf(context) ?? null,\n    userAgent: (context?.request?.header?.['user-agent'] as string | undefined)?.slice(0, 256) ?? null,\n    durationMs: Date.now() - scope.startedAt,\n    channel: scope.channel,\n    route: scope.channel === 'http' ? (context?._matchedRoute ? String(context._matchedRoute).slice(0, 128) : null) : null,\n    ...(scope.channel === 'graphql' ? operationOf(context?.request?.body) : {})\n  } as any\n\n  const actions = [...scope.merged.values()].map(merged =>\n    rowOf(merged, scope, {}, merged.count, [...merged.targets], merged.truncated)\n  )\n\n  /*\n   * Two plain inserts, no transaction of their own: a sqlite database has one connection, and a\n   * transaction opened here collided with the requests' own (「cannot start a transaction within a\n   * transaction」, seen on Office's development database). The line and its actions are both best\n   * effort (§4-4); one failing is counted like the other.\n   */\n  try {\n    await getRepository(AuditRequest).insert(request)\n    if (actions.length) await getRepository(AuditAction).insert(actions)\n  } catch (error) {\n    countFailure(error, 'request')\n  }\n}\n\n/* ── failures, counted apart from the audit store (ADR-0141 §4-5) ──────── */\n\nconst health = {\n  since: new Date(),\n  failures: 0,\n  firstFailedAt: null as Date | null,\n  lastFailedAt: null as Date | null\n}\n\nfunction countFailure(error: unknown, what: string) {\n  const now = new Date()\n  health.failures++\n  health.firstFailedAt ??= now\n  health.lastFailedAt = now\n  logger.error(`[audit] not written (${what}): ${(error as Error)?.message}`)\n}\n\n/** Failures this server process detected since it started. Not those it never got to try. */\nexport function auditHealth() {\n  return { ...health }\n}\n\n/* ── for tests: wait for every write started so far ────────────────────── */\n\nconst pending = new Set<Promise<unknown>>()\n\nfunction track(promise: Promise<unknown>) {\n  pending.add(promise)\n  promise.finally(() => pending.delete(promise))\n}\n\nexport async function flushAudit(): Promise<void> {\n  while (pending.size) {\n    await Promise.allSettled([...pending])\n  }\n}\n"]}

package/dist-server/service/audit/audit-request.d.ts

@@ -0,0 +1,28 @@
+import { Domain } from '@things-factory/shell';
+import { User } from '../user/user.js';
+/**
+ * One request that reached the server, as the audit keeps it (ADR-0141 §3.1).
+ *
+ * Every GraphQL request has one; any other request has one when it left at least one action
+ * (a sign-in, a check-in). What happened inside is in `AuditAction` rows carrying this id.
+ *
+ * The row is never changed or deleted by the application (ADR-0141 §4-6), so the entity has no
+ * updater, `updatedAt` or `deletedAt`. Its relations carry no foreign key: an audit row must
+ * neither stop a user or domain from being removed nor go with them.
+ */
+export declare class AuditRequest {
+    id: string;
+    domain?: Domain;
+    domainId?: string;
+    actor?: User;
+    actorId?: string;
+    createdAt: Date;
+    ip?: string;
+    userAgent?: string;
+    durationMs?: number;
+    channel: string;
+    operationType?: string;
+    operationName?: string;
+    fields?: string;
+    route?: string;
+}

package/dist-server/service/audit/audit-request.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditRequest = void 0;
+const tslib_1 = require("tslib");
+const type_graphql_1 = require("type-graphql");
+const typeorm_1 = require("typeorm");
+const shell_1 = require("@things-factory/shell");
+const user_js_1 = require("../user/user.js");
+/**
+ * One request that reached the server, as the audit keeps it (ADR-0141 §3.1).
+ *
+ * Every GraphQL request has one; any other request has one when it left at least one action
+ * (a sign-in, a check-in). What happened inside is in `AuditAction` rows carrying this id.
+ *
+ * The row is never changed or deleted by the application (ADR-0141 §4-6), so the entity has no
+ * updater, `updatedAt` or `deletedAt`. Its relations carry no foreign key: an audit row must
+ * neither stop a user or domain from being removed nor go with them.
+ */
+let AuditRequest = class AuditRequest {
+};
+exports.AuditRequest = AuditRequest;
+tslib_1.__decorate([
+    (0, typeorm_1.PrimaryColumn)({ type: 'varchar', length: 36 }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.ID, { description: 'Request id, shared by the actions of this request.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "id", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => shell_1.Domain, { nullable: true, createForeignKeyConstraints: false }),
+    (0, type_graphql_1.Field)(type => shell_1.Domain, { nullable: true, description: 'The domain the request was made in.' }),
+    tslib_1.__metadata("design:type", shell_1.Domain)
+], AuditRequest.prototype, "domain", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((request) => request.domain),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "domainId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.ManyToOne)(type => user_js_1.User, { nullable: true, createForeignKeyConstraints: false }),
+    (0, type_graphql_1.Field)(type => user_js_1.User, { nullable: true, description: 'Who made the request. Empty when nobody was signed in.' }),
+    tslib_1.__metadata("design:type", user_js_1.User)
+], AuditRequest.prototype, "actor", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.RelationId)((request) => request.actor),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "actorId", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.CreateDateColumn)(),
+    (0, type_graphql_1.Field)({ description: 'When the server finished the request.' }),
+    tslib_1.__metadata("design:type", Date)
+], AuditRequest.prototype, "createdAt", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true, length: 64 }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'Address the request came from.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "ip", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true, length: 256 }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'User-Agent header, cut at 256 characters.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "userAgent", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ type: 'int', nullable: true }),
+    (0, type_graphql_1.Field)(type => type_graphql_1.Int, { nullable: true, description: 'Milliseconds the server spent on the request.' }),
+    tslib_1.__metadata("design:type", Number)
+], AuditRequest.prototype, "durationMs", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ length: 16 }),
+    (0, type_graphql_1.Field)({ description: 'graphql, or http for any other request.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "channel", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true, length: 16 }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'query, mutation or subscription - for a GraphQL request.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "operationType", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true, length: 128 }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'The operation name the client gave. For reference only - the client chooses it.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "operationName", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true, length: 256 }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'The root fields a GraphQL request asked, by their schema names - never an argument.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "fields", void 0);
+tslib_1.__decorate([
+    (0, typeorm_1.Column)({ nullable: true, length: 128 }),
+    (0, type_graphql_1.Field)({ nullable: true, description: 'The route pattern of a request outside GraphQL. Never the path itself.' }),
+    tslib_1.__metadata("design:type", String)
+], AuditRequest.prototype, "route", void 0);
+exports.AuditRequest = AuditRequest = tslib_1.__decorate([
+    (0, typeorm_1.Entity)(),
+    (0, typeorm_1.Index)('ix_audit_request_0', (request) => [request.domain, request.createdAt]),
+    (0, typeorm_1.Index)('ix_audit_request_1', (request) => [request.actor, request.createdAt]),
+    (0, type_graphql_1.ObjectType)({ description: 'A request that reached the server, as the audit keeps it.' })
+], AuditRequest);
+//# sourceMappingURL=audit-request.js.map

package/dist-server/service/audit/audit-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-request.js","sourceRoot":"","sources":["../../../server/service/audit/audit-request.ts"],"names":[],"mappings":"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","sourcesContent":["import { Field, ID, Int, ObjectType } from 'type-graphql'\nimport { Column, CreateDateColumn, Entity, Index, ManyToOne, PrimaryColumn, RelationId } from 'typeorm'\n\nimport { Domain } from '@things-factory/shell'\n\nimport { User } from '../user/user.js'\n\n/**\n * One request that reached the server, as the audit keeps it (ADR-0141 §3.1).\n *\n * Every GraphQL request has one; any other request has one when it left at least one action\n * (a sign-in, a check-in). What happened inside is in `AuditAction` rows carrying this id.\n *\n * The row is never changed or deleted by the application (ADR-0141 §4-6), so the entity has no\n * updater, `updatedAt` or `deletedAt`. Its relations carry no foreign key: an audit row must\n * neither stop a user or domain from being removed nor go with them.\n */\n@Entity()\n@Index('ix_audit_request_0', (request: AuditRequest) => [request.domain, request.createdAt])\n@Index('ix_audit_request_1', (request: AuditRequest) => [request.actor, request.createdAt])\n@ObjectType({ description: 'A request that reached the server, as the audit keeps it.' })\nexport class AuditRequest {\n  /* Given by the recorder at the start of the request, so actions written mid-request can name it. */\n  @PrimaryColumn({ type: 'varchar', length: 36 })\n  @Field(type => ID, { description: 'Request id, shared by the actions of this request.' })\n  id: string\n\n  @ManyToOne(type => Domain, { nullable: true, createForeignKeyConstraints: false })\n  @Field(type => Domain, { nullable: true, description: 'The domain the request was made in.' })\n  domain?: Domain\n\n  @RelationId((request: AuditRequest) => request.domain)\n  domainId?: string\n\n  @ManyToOne(type => User, { nullable: true, createForeignKeyConstraints: false })\n  @Field(type => User, { nullable: true, description: 'Who made the request. Empty when nobody was signed in.' })\n  actor?: User\n\n  @RelationId((request: AuditRequest) => request.actor)\n  actorId?: string\n\n  @CreateDateColumn()\n  @Field({ description: 'When the server finished the request.' })\n  createdAt: Date\n\n  @Column({ nullable: true, length: 64 })\n  @Field({ nullable: true, description: 'Address the request came from.' })\n  ip?: string\n\n  @Column({ nullable: true, length: 256 })\n  @Field({ nullable: true, description: 'User-Agent header, cut at 256 characters.' })\n  userAgent?: string\n\n  @Column({ type: 'int', nullable: true })\n  @Field(type => Int, { nullable: true, description: 'Milliseconds the server spent on the request.' })\n  durationMs?: number\n\n  @Column({ length: 16 })\n  @Field({ description: 'graphql, or http for any other request.' })\n  channel: string\n\n  @Column({ nullable: true, length: 16 })\n  @Field({ nullable: true, description: 'query, mutation or subscription - for a GraphQL request.' })\n  operationType?: string\n\n  @Column({ nullable: true, length: 128 })\n  @Field({ nullable: true, description: 'The operation name the client gave. For reference only - the client chooses it.' })\n  operationName?: string\n\n  @Column({ nullable: true, length: 256 })\n  @Field({ nullable: true, description: 'The root fields a GraphQL request asked, by their schema names - never an argument.' })\n  fields?: string\n\n  @Column({ nullable: true, length: 128 })\n  @Field({ nullable: true, description: 'The route pattern of a request outside GraphQL. Never the path itself.' })\n  route?: string\n}\n"]}

package/dist-server/service/audit/audit-retention.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Audit rows older than the retention are removed by this task and by nothing else - the
+ * application has no door that changes or deletes them (ADR-0141 §4-6 · §7). One year unless
+ * `audit/retentionDays` says otherwise.
+ */
+export declare function auditRetentionDays(): number;
+/** Removes what is older than the retention, counted from `now`. */
+export declare function purgeExpiredAudit(now?: Date): Promise<{
+    requests: number;
+    actions: number;
+}>;
+export declare function startAuditRetention(): import("@things-factory/task-lease").PeriodicTask;

package/dist-server/service/audit/audit-retention.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.auditRetentionDays = auditRetentionDays;
+exports.purgeExpiredAudit = purgeExpiredAudit;
+exports.startAuditRetention = startAuditRetention;
+const typeorm_1 = require("typeorm");
+const env_1 = require("@things-factory/env");
+const shell_1 = require("@things-factory/shell");
+const task_lease_1 = require("@things-factory/task-lease");
+const audit_action_js_1 = require("./audit-action.js");
+const audit_request_js_1 = require("./audit-request.js");
+/**
+ * Audit rows older than the retention are removed by this task and by nothing else - the
+ * application has no door that changes or deletes them (ADR-0141 §4-6 · §7). One year unless
+ * `audit/retentionDays` says otherwise.
+ */
+function auditRetentionDays() {
+    const days = Number(env_1.config.get('audit/retentionDays'));
+    return Number.isFinite(days) && days > 0 ? days : 365;
+}
+/** Removes what is older than the retention, counted from `now`. */
+async function purgeExpiredAudit(now = new Date()) {
+    const before = new Date(now.getTime() - auditRetentionDays() * 24 * 60 * 60 * 1000);
+    const actions = await (0, shell_1.getRepository)(audit_action_js_1.AuditAction).delete({ createdAt: (0, typeorm_1.LessThan)(before) });
+    const requests = await (0, shell_1.getRepository)(audit_request_js_1.AuditRequest).delete({ createdAt: (0, typeorm_1.LessThan)(before) });
+    return { requests: requests.affected ?? 0, actions: actions.affected ?? 0 };
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+function startAuditRetention() {
+    return (0, task_lease_1.startPeriodicTask)({
+        name: 'audit-retention',
+        intervalMs: DAY_MS,
+        work: async () => {
+            const removed = await purgeExpiredAudit();
+            if (removed.requests || removed.actions) {
+                env_1.logger.info(`[audit] removed ${removed.requests} requests and ${removed.actions} actions past ${auditRetentionDays()} days`);
+            }
+        },
+        onFailure: failure => env_1.logger.error(`[audit] retention round failed: ${failure.error}`)
+    });
+}
+//# sourceMappingURL=audit-retention.js.map

package/dist-server/service/audit/audit-retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-retention.js","sourceRoot":"","sources":["../../../server/service/audit/audit-retention.ts"],"names":[],"mappings":";;AAcA,gDAGC;AAGD,8CAOC;AAID,kDAYC;AA3CD,qCAAkC;AAElC,6CAAoD;AACpD,iDAAqD;AACrD,2DAA8D;AAE9D,uDAA+C;AAC/C,yDAAiD;AAEjD;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,MAAM,IAAI,GAAG,MAAM,CAAC,YAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,CAAA;IACtD,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;AACvD,CAAC;AAED,oEAAoE;AAC7D,KAAK,UAAU,iBAAiB,CAAC,GAAG,GAAG,IAAI,IAAI,EAAE;IACtD,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,kBAAkB,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAA;IAEnF,MAAM,OAAO,GAAG,MAAM,IAAA,qBAAa,EAAC,6BAAW,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAA,kBAAQ,EAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IACxF,MAAM,QAAQ,GAAG,MAAM,IAAA,qBAAa,EAAC,+BAAY,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,IAAA,kBAAQ,EAAC,MAAM,CAAC,EAAE,CAAC,CAAA;IAE1F,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC,EAAE,CAAA;AAC7E,CAAC;AAED,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAElC,SAAgB,mBAAmB;IACjC,OAAO,IAAA,8BAAiB,EAAC;QACvB,IAAI,EAAE,iBAAiB;QACvB,UAAU,EAAE,MAAM;QAClB,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,MAAM,OAAO,GAAG,MAAM,iBAAiB,EAAE,CAAA;YACzC,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACxC,YAAM,CAAC,IAAI,CAAC,mBAAmB,OAAO,CAAC,QAAQ,iBAAiB,OAAO,CAAC,OAAO,iBAAiB,kBAAkB,EAAE,OAAO,CAAC,CAAA;YAC9H,CAAC;QACH,CAAC;QACD,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,YAAM,CAAC,KAAK,CAAC,mCAAmC,OAAO,CAAC,KAAK,EAAE,CAAC;KACvF,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import { LessThan } from 'typeorm'\n\nimport { config, logger } from '@things-factory/env'\nimport { getRepository } from '@things-factory/shell'\nimport { startPeriodicTask } from '@things-factory/task-lease'\n\nimport { AuditAction } from './audit-action.js'\nimport { AuditRequest } from './audit-request.js'\n\n/**\n * Audit rows older than the retention are removed by this task and by nothing else - the\n * application has no door that changes or deletes them (ADR-0141 §4-6 · §7). One year unless\n * `audit/retentionDays` says otherwise.\n */\nexport function auditRetentionDays(): number {\n  const days = Number(config.get('audit/retentionDays'))\n  return Number.isFinite(days) && days > 0 ? days : 365\n}\n\n/** Removes what is older than the retention, counted from `now`. */\nexport async function purgeExpiredAudit(now = new Date()): Promise<{ requests: number; actions: number }> {\n  const before = new Date(now.getTime() - auditRetentionDays() * 24 * 60 * 60 * 1000)\n\n  const actions = await getRepository(AuditAction).delete({ createdAt: LessThan(before) })\n  const requests = await getRepository(AuditRequest).delete({ createdAt: LessThan(before) })\n\n  return { requests: requests.affected ?? 0, actions: actions.affected ?? 0 }\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000\n\nexport function startAuditRetention() {\n  return startPeriodicTask({\n    name: 'audit-retention',\n    intervalMs: DAY_MS,\n    work: async () => {\n      const removed = await purgeExpiredAudit()\n      if (removed.requests || removed.actions) {\n        logger.info(`[audit] removed ${removed.requests} requests and ${removed.actions} actions past ${auditRetentionDays()} days`)\n      }\n    },\n    onFailure: failure => logger.error(`[audit] retention round failed: ${failure.error}`)\n  })\n}\n"]}

package/dist-server/service/audit/audit-subscriber.d.ts

@@ -0,0 +1,39 @@
+import { EntitySubscriberInterface, InsertEvent, RemoveEvent, UpdateEvent } from 'typeorm';
+import { DomainOwner } from '../domain-owner/domain-owner.js';
+import { Invitation } from '../invitation/invitation.js';
+import { User } from '../user/user.js';
+import { WebAuthCredential } from '../web-auth-credential/web-auth-credential.js';
+/**
+ * ── Grants are junction rows ──────────────────────────────────────────────
+ *
+ * A role given to a user is a `users_roles` row; a privilege given to a role, a `roles_privileges`
+ * row. When only those change, TypeORM updates no entity and sends no update event - it inserts and
+ * removes junction rows, and those it does announce. So grants are read here, from the junction, for
+ * every path that saves a user's roles or a role's privileges, a new user's or role's included.
+ *
+ * This listens to every entity (a junction has no class to name) and leaves at once on anything
+ * that is not one of the two junctions.
+ */
+export declare class GrantAuditSubscriber implements EntitySubscriberInterface<any> {
+    afterInsert(event: InsertEvent<any>): Promise<void>;
+    afterRemove(event: RemoveEvent<any>): Promise<void>;
+    private record;
+}
+export declare class UserAuditSubscriber implements EntitySubscriberInterface<User> {
+    listenTo(): typeof User;
+    afterUpdate(event: UpdateEvent<User>): Promise<void>;
+}
+export declare class DomainOwnerAuditSubscriber implements EntitySubscriberInterface<DomainOwner> {
+    listenTo(): typeof DomainOwner;
+    afterInsert(event: InsertEvent<DomainOwner>): Promise<void>;
+}
+export declare class InvitationAuditSubscriber implements EntitySubscriberInterface<Invitation> {
+    listenTo(): typeof Invitation;
+    afterInsert(event: InsertEvent<Invitation>): Promise<void>;
+    afterUpdate(event: UpdateEvent<Invitation>): Promise<void>;
+}
+export declare class WebAuthCredentialAuditSubscriber implements EntitySubscriberInterface<WebAuthCredential> {
+    listenTo(): typeof WebAuthCredential;
+    afterInsert(event: InsertEvent<WebAuthCredential>): Promise<void>;
+}
+export declare const auditSubscribers: (typeof GrantAuditSubscriber | typeof UserAuditSubscriber | typeof DomainOwnerAuditSubscriber | typeof InvitationAuditSubscriber | typeof WebAuthCredentialAuditSubscriber)[];