@awsmbiz/inbis-audit 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+# @awsmbiz/inbis-audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The audit trail for Inbis applications: one `audit_event` table for platform and app
+events, a D1 `AuditSink` (the interface from `@awsmbiz/inbis-core`) that redacts metadata before
+storing it, an extensible action registry, and package-owned D1 migrations (ADR-4).
+
+Installing it replaces `@awsmbiz/inbis-auth`'s interim `auth_audit_event` table (plan Q39): pass the
+sink to `createInbisAuth`, and copy the interim history over with `importAuthAuditHistory(db)`.
+
+## Public API
+
+| Entry | Contents |
+|---|---|
+| `@awsmbiz/inbis-audit` | `createD1AuditLog`, `createAuditActions`, `PLATFORM_AUDIT_NAMESPACES`, `AUDIT_MIGRATIONS_TABLE`, `importAuthAuditHistory`, `listAuthAuditEvents`; types `AuthAuditShapedRecord`, `AuditLog`, `AuditEventRecord`, `AuditTimelineFilter`, `AuditTimelineQuery`, `D1AuditLogOptions`, `AuditActions`, `AuditActionsInput`, `AuditActionCatalogue` |
+| `@awsmbiz/inbis-audit/hono` | `mountAuditTimeline`, `mountOwnActivity`; types `AuditTimelineItem`, `AuditTimelineResponse`, `MountAuditTimelineOptions`, `MountOwnActivityOptions` |
+| `migrations/` | Numbered, frozen SQL plus `migrations.lock.json`, shipped in the tarball |
+
+Peer dependencies: `drizzle-orm` ^0.45.4; `hono` ^4.13.14 (optional, for `/hono`).
+
+## Setting it up
+
+1. Declare an audit binding to the app's database, after auth's (and access-control's) and
+   before jobs' and the app's own (ADR-4 platform order), with the same `database_id`:
+
+   ```jsonc
+   "d1_databases": [
+     { "binding": "AUTH_DB", "database_name": "myapp-dev", "database_id": "<id>",
+       "migrations_dir": "node_modules/@awsmbiz/inbis-auth/migrations", "migrations_table": "_inbis_auth_migrations" },
+     { "binding": "AUDIT_DB", "database_name": "myapp-dev", "database_id": "<id>",
+       "migrations_dir": "node_modules/@awsmbiz/inbis-audit/migrations", "migrations_table": "_inbis_audit_migrations" },
+     { "binding": "DB", "database_name": "myapp-dev", "database_id": "<id>",
+       "migrations_dir": "migrations", "migrations_table": "d1_migrations" }
+   ]
+   ```
+
+   `pnpm exec inbis-db migrate --local` (or `--remote --env <env>`) applies them in that order.
+
+2. Register the actions the app records, and pass the sink to auth:
+
+   ```ts
+   import { createAuditActions, createD1AuditLog } from "@awsmbiz/inbis-audit";
+   import { AUTH_AUDIT_ACTIONS, createInbisAuth } from "@awsmbiz/inbis-auth";
+
+   // Once per isolate: the platform catalogues the app uses, plus its own.
+   const actions = createAuditActions({
+     platform: [AUTH_AUDIT_ACTIONS],
+     app: { invoiceSent: "billing.invoice.sent" },
+   });
+
+   // Per request:
+   const audit = createD1AuditLog(requireBinding(c.env, "AUDIT_DB"), { actions, strict: isLocal, logger: c.var.logger });
+   createInbisAuth({ ..., audit });
+   await audit.record({ action: "billing.invoice.sent", occurredAt: new Date(), actorId: user.id, subjectId: `invoice:${id}` });
+   ```
+
+## The action registry
+
+`createAuditActions({ platform, app })` lists every action name the trail accepts. Each
+platform package that records events exports its catalogue (`AUTH_AUDIT_ACTIONS`); the app
+adds its own, as an `as const` object or a list.
+
+- Names are dotted lowercase: `namespace.thing[.more]` (`[a-z][a-z0-9_]*` segments).
+- App actions may not use a platform namespace (`PLATFORM_AUDIT_NAMESPACES`: `access`,
+  `audit`, `auth`, `cache`, `jobs`, `notifications`, `platform`, `storage`).
+- Both are programming errors: `createAuditActions` throws at startup.
+
+`createD1AuditLog(db, { actions, strict, logger })` checks each event's action:
+
+- `strict: true` (local development and tests): an unregistered action throws and nothing is
+  stored. `@awsmbiz/inbis-auth` logs a failing sink as `auth.audit.record_failed`; tests should assert
+  there is none.
+- `strict: false` (default; deployed): the event is stored anyway and
+  `audit.action.unregistered` is logged, because losing an audit event is worse than an
+  unexpected name.
+
+## What is stored
+
+`audit_event` holds `id` (UUIDv7), `action`, `actor_id` (`null` for the system or an unknown
+actor), `subject_id` (e.g. `user:<id>`), `occurred_at` (epoch ms), `request_id` and
+`metadata`. Metadata passes through `redact()` from `@awsmbiz/inbis-core` before it is stored, so
+credential-looking fields (passwords, tokens, OTPs, codes, cookies, secrets) and
+`Bearer`/`Basic` values become `[REDACTED]` whatever the caller passed. Events have no
+foreign keys and outlive the users and records they name.
+
+Indexes serve timeline queries newest first: overall or by time range
+(`occurred_at, id`), and by actor, subject or action (each with `occurred_at`).
+
+## The activity timeline
+
+`AuditLog.list(query)` returns events newest first (`occurred_at`, then `id`), as
+`{ items, nextCursor }` (keyset; `limit` 1–200, default 50). Every filter given narrows the
+result: `action` (exact name), `actorId`, `subjectId` (e.g. `user:<id>`), `from` (inclusive) and
+`to` (exclusive) as `Date`s. Keep the same filters when passing `nextCursor` back as `cursor`.
+`AuditLog.count(filter)` counts the events matching the same filters, without paging (e.g. failed
+sign-ins in the last day for the admin dashboard, `mountAuthStats` in `@awsmbiz/inbis-auth/hono`).
+
+`@awsmbiz/inbis-audit/hono` serves it over HTTP. The package depends on no auth package, so the app
+passes the guard that admits the caller:
+
+```ts
+import { mountAuditTimeline, mountOwnActivity } from "@awsmbiz/inbis-audit/hono";
+import { requireAdmin, requireAuth } from "@awsmbiz/inbis-auth/hono";
+
+const log = (c) => createD1AuditLog(requireBinding(c.env, "AUDIT_DB"), { actions });
+mountAuditTimeline(app, { log, guard: requireAdmin() });
+mountOwnActivity(app, { log, guard: requireAuth(), actorIdOf: (c) => c.var.user?.id });
+```
+
+| Route | Who | Query |
+|---|---|---|
+| `GET /api/admin/audit-events` (`path` to change) | The guard's: pass the app's admin policy | `action`, `actor`, `subject`, `from`, `to`, `limit`, `cursor` |
+| `GET /api/me/activity` (`path` to change) | Anyone the guard admits; only events whose actor is the caller | `action`, `from`, `to`, `limit`, `cursor` (`actor`/`subject` are ignored) |
+
+`from`/`to` are ISO 8601 dates (`2026-11-01`, UTC midnight) or date-times; anything else is
+`422 VALIDATION_FAILED` with `details.issues[].path` `["from"]`/`["to"]`. Both answer
+`{ items: [{ id, action, actorId, subjectId, occurredAt (ISO), requestId, metadata }], nextCursor }`
+with `Cache-Control: no-store`. My activity returns the caller's own metadata (sign-in method,
+IP address, browser), so users can spot sign-ins they did not make; events *about* the user by
+someone else (an admin's ban, say) are not included, since their metadata is the admin's.
+
+`AuditLog.forgetUser({ id, email, phoneNumber })` strips `email`, `phoneNumber`, `ipAddress`
+and `userAgent` from the metadata of every event by or about the user, or naming its email
+(any case) or number, so only the user ID remains (plan §5.7). `@awsmbiz/inbis-auth` calls it on
+account deletion (it is the optional `forgetUser` of `AuditSink`).
+
+## Interim auth history
+
+`@awsmbiz/inbis-audit`'s migrations never touch `@awsmbiz/inbis-auth`'s tables, so the two can be added in
+either order. Taking over from auth's interim `auth_audit_event` table is an explicit step:
+
+- `importAuthAuditHistory(db)` copies every interim row into `audit_event` (same `id`;
+  `resource` becomes `subjectId`) and resolves with the number copied. It is idempotent (rows
+  already copied are skipped) and a no-op (`0`) on a database without the interim table, so run
+  it once after adopting audit, on each deploy, or from the cron trigger (the playground does
+  the latter: `createPlaygroundScheduled`). `db` is the audit binding.
+- The `inbis-auth bootstrap-admin` CLI writes SQL directly; it records its event in
+  `audit_event` whenever that table exists in the database, and in the interim table otherwise.
+- `listAuthAuditEvents(log, input)` reads the trail in auth's interim record shape, for
+  `mountAuthAudit(app, { list: (c, input) => listAuthAuditEvents(auditLog(c), input) })`, so
+  `GET /api/admin/auth-audit-events` keeps its response for existing callers.
+- The interim table stays: it is auth's fallback for apps without `@awsmbiz/inbis-audit` (Q39).
+
+## Changing the schema (maintainers)
+
+Migrations are append-only: add `migrations/000N_*.sql`, update `src/schema.ts` to match,
+then `pnpm exec inbis-db lock migrations`. `pnpm check:migrations` fails if a released file
+changed.

package/dist/audit-log-xkH9ZIGE.d.ts

@@ -0,0 +1,102 @@
+import { AuditSink, ForgottenUser, Logger } from "@awsmbiz/inbis-core";
+import { Page, PageInput } from "@awsmbiz/inbis-db";
+/**
+ * The action registry: every action name the app's audit trail accepts.
+ * Platform packages export their catalogues (e.g. `AUTH_AUDIT_ACTIONS` from
+ * `@awsmbiz/inbis-auth`); the app adds its own.
+ */
+/** A catalogue of action names: an `as const` object of names, or a list. */
+type AuditActionCatalogue = Readonly<Record<string, string>> | readonly string[];
+interface AuditActionsInput {
+  /** Catalogues exported by platform packages, e.g. `AUTH_AUDIT_ACTIONS`. */
+  platform?: readonly AuditActionCatalogue[];
+  /** The app's own actions. They may not use a platform namespace ({@link PLATFORM_AUDIT_NAMESPACES}). */
+  app?: AuditActionCatalogue;
+}
+/** The registered action names. */
+interface AuditActions {
+  has(action: string): boolean;
+  /** Every registered name, sorted. */
+  readonly all: readonly string[];
+}
+/**
+ * First segments reserved for platform packages. An app action such as
+ * `auth.something` is rejected, so app events never pass for platform ones.
+ */
+declare const PLATFORM_AUDIT_NAMESPACES: readonly ["access", "audit", "auth", "cache", "jobs", "notifications", "platform", "storage"];
+/**
+ * Builds the registry. Throws on a malformed name, or on an app action in a
+ * platform namespace: both are programming errors, found at startup.
+ */
+declare function createAuditActions({ platform, app }: AuditActionsInput): AuditActions;
+/** One stored audit event. */
+interface AuditEventRecord {
+  id: string;
+  /** Dotted action name, e.g. `auth.sign_in.succeeded`. */
+  action: string;
+  actorId: string | null;
+  /** `AuditEvent.subjectId`, e.g. `user:<id>`. */
+  subjectId: string | null;
+  occurredAt: Date;
+  requestId: string | null;
+  /** Redacted, secret-free detail. */
+  metadata: Record<string, unknown> | null;
+}
+/** Timeline filters; each one given narrows the result. */
+interface AuditTimelineFilter {
+  /** Exact action name, e.g. `auth.sign_in.failed`. */
+  action?: string | undefined;
+  /** Events performed by this user ID. */
+  actorId?: string | undefined;
+  /** Events about this subject, e.g. `user:<id>`. */
+  subjectId?: string | undefined;
+  /** Events at or after this instant. */
+  from?: Date | undefined;
+  /** Events before this instant (exclusive). */
+  to?: Date | undefined;
+}
+/** A timeline request: filters plus keyset paging. */
+type AuditTimelineQuery = AuditTimelineFilter & PageInput;
+/** The audit trail over `audit_event`: an `AuditSink`, plus reading. */
+interface AuditLog extends AuditSink {
+  /**
+   * After an account deletion: strips `email`, `phoneNumber`, `ipAddress` and
+   * `userAgent` from every event by or about the user, or naming its email
+   * (any case) or number, so only the user ID remains (plan §5.7).
+   */
+  forgetUser(user: ForgottenUser): Promise<void>;
+  /**
+   * The timeline: events matching every filter given, newest first (keyset
+   * pagination; `limit` defaults to 50, at most 200). Keep the same filters
+   * when following `nextCursor`.
+   */
+  list(query?: AuditTimelineQuery): Promise<Page<AuditEventRecord>>;
+  /**
+   * How many events match every filter given (the same filters as
+   * {@link list}, without paging), e.g. failed sign-ins in the last day.
+   */
+  count(filter?: AuditTimelineFilter): Promise<number>;
+  /**
+   * How many distinct actors performed the matching events (the same filters
+   * as {@link count}; events without an actor are not counted), e.g. users who
+   * signed in during the last 7 days.
+   */
+  countActors(filter?: AuditTimelineFilter): Promise<number>;
+}
+interface D1AuditLogOptions {
+  /** The registered action names (see `createAuditActions`). */
+  actions: AuditActions;
+  /**
+   * `true` (development and tests): an unregistered action throws and nothing
+   * is stored, so a typo fails the test that triggers it. `false` (default,
+   * production): it is stored anyway and logged as `audit.action.unregistered`,
+   * because losing an audit event is worse than an unexpected name.
+   */
+  strict?: boolean;
+  /** Receives the `audit.action.unregistered` warning. Defaults to a console JSON logger. */
+  logger?: Logger;
+}
+/** Creates the D1-backed audit log over the database holding `audit_event` (the app's audit binding). */
+declare function createD1AuditLog(d1: D1Database, { actions, strict, logger }: D1AuditLogOptions): AuditLog;
+export { D1AuditLogOptions as a, AuditActions as c, createAuditActions as d, AuditTimelineQuery as i, AuditActionsInput as l, AuditLog as n, createD1AuditLog as o, AuditTimelineFilter as r, AuditActionCatalogue as s, AuditEventRecord as t, PLATFORM_AUDIT_NAMESPACES as u };
+//# sourceMappingURL=audit-log-xkH9ZIGE.d.ts.map

package/dist/hono.d.ts

@@ -0,0 +1,46 @@
+import { n as AuditLog, t as AuditEventRecord } from "./audit-log-xkH9ZIGE.js";
+import { Context, Env, Hono, MiddlewareHandler } from "hono";
+/** An event as the timeline routes return it: {@link AuditEventRecord} with `occurredAt` as ISO 8601. */
+export interface AuditTimelineItem extends Omit<AuditEventRecord, "occurredAt"> {
+  occurredAt: string;
+}
+/** The timeline routes' response body. */
+export interface AuditTimelineResponse {
+  items: AuditTimelineItem[];
+  /** Pass as `cursor` (with the same filters) for the next page; `null` on the last. */
+  nextCursor: string | null;
+}
+interface TimelineRouteOptions<E extends Env> {
+  /** The app's audit log for the request. */
+  log: (c: Context<E>) => AuditLog;
+  /**
+   * Admits the caller, or throws (e.g. `requireAdmin()` / `requireAuth()` from
+   * `@awsmbiz/inbis-auth/hono`). Any env: guards are typed for their own variables.
+   */
+  guard: MiddlewareHandler;
+  /** Route path. */
+  path?: string;
+}
+export type MountAuditTimelineOptions<E extends Env = Env> = TimelineRouteOptions<E>;
+export interface MountOwnActivityOptions<E extends Env = Env> extends TimelineRouteOptions<E> {
+  /** The signed-in caller's user ID; `null`/`undefined` is refused with `401 UNAUTHENTICATED`. */
+  actorIdOf: (c: Context<E>) => string | null | undefined;
+}
+/**
+ * Mounts `GET /api/admin/audit-events` (default path): every audit event,
+ * newest first, as {@link AuditTimelineResponse}. Query: `action`, `actor`
+ * (user ID), `subject` (e.g. `user:<id>`), `from` (inclusive) and `to`
+ * (exclusive) as ISO 8601 dates or date-times, `limit` (1–200, default 50) and
+ * `cursor`. A malformed date is `422 VALIDATION_FAILED` (`details.issues[].path`).
+ * Admission is the `guard`'s: pass the app's admin policy.
+ */
+export declare function mountAuditTimeline<E extends Env>(app: Hono<E>, options: MountAuditTimelineOptions<E>): void;
+/**
+ * Mounts `GET /api/me/activity` (default path): the caller's own events (those
+ * it performed), newest first, as {@link AuditTimelineResponse}. Accepts
+ * `action`, `from`, `to`, `limit` and `cursor` like {@link mountAuditTimeline};
+ * the actor is always the caller, and any `actor` or `subject` parameter is ignored.
+ */
+export declare function mountOwnActivity<E extends Env>(app: Hono<E>, options: MountOwnActivityOptions<E>): void;
+export {};
+//# sourceMappingURL=hono.d.ts.map

package/dist/hono.js

@@ -0,0 +1,94 @@
+import { AppError, validationFailed } from "@awsmbiz/inbis-core";
+// src/hono.ts
+/**
+* Hono routes for the activity timeline: `@awsmbiz/inbis-audit/hono`.
+*
+* The package knows nothing about sessions or roles (it depends on no auth
+* package): the app passes the guard middleware that admits the caller, and
+* for the own-activity route, how to read the caller's user ID.
+*
+* ```ts
+* import { requireAdmin, requireAuth } from "@awsmbiz/inbis-auth/hono";
+* const log = (c) => createD1AuditLog(c.env.AUDIT_DB, { actions });
+* mountAuditTimeline(app, { log, guard: requireAdmin() });
+* mountOwnActivity(app, { log, guard: requireAuth(), actorIdOf: (c) => c.var.user?.id });
+* ```
+*/
+/** `YYYY-MM-DD` or a full ISO 8601 date-time. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?$/;
+function dateParam(c, name) {
+	const raw = c.req.query(name);
+	if (raw === void 0 || raw === "") return void 0;
+	const date = new Date(raw);
+	if (!ISO_DATE.test(raw) || Number.isNaN(date.getTime())) throw validationFailed([{
+		path: [name],
+		message: "Must be an ISO 8601 date or date-time."
+	}]);
+	return date;
+}
+function textParam(c, name) {
+	const raw = c.req.query(name);
+	return raw === void 0 || raw === "" ? void 0 : raw;
+}
+/** Paging, action and date range: the query parameters both routes accept. */
+function commonQuery(c) {
+	return {
+		limit: c.req.query("limit"),
+		cursor: c.req.query("cursor"),
+		action: textParam(c, "action"),
+		from: dateParam(c, "from"),
+		to: dateParam(c, "to")
+	};
+}
+async function respond(c, log, query) {
+	const page = await log.list(query);
+	const body = {
+		items: page.items.map((item) => ({
+			...item,
+			occurredAt: item.occurredAt.toISOString()
+		})),
+		nextCursor: page.nextCursor
+	};
+	c.header("cache-control", "no-store");
+	return c.json(body);
+}
+/**
+* Mounts `GET /api/admin/audit-events` (default path): every audit event,
+* newest first, as {@link AuditTimelineResponse}. Query: `action`, `actor`
+* (user ID), `subject` (e.g. `user:<id>`), `from` (inclusive) and `to`
+* (exclusive) as ISO 8601 dates or date-times, `limit` (1–200, default 50) and
+* `cursor`. A malformed date is `422 VALIDATION_FAILED` (`details.issues[].path`).
+* Admission is the `guard`'s: pass the app's admin policy.
+*/
+function mountAuditTimeline(app, options) {
+	const { log, guard } = options;
+	app.get(options.path ?? "/api/admin/audit-events", guard, (c) => respond(c, log(c), {
+		...commonQuery(c),
+		actorId: textParam(c, "actor"),
+		subjectId: textParam(c, "subject")
+	}));
+}
+/**
+* Mounts `GET /api/me/activity` (default path): the caller's own events (those
+* it performed), newest first, as {@link AuditTimelineResponse}. Accepts
+* `action`, `from`, `to`, `limit` and `cursor` like {@link mountAuditTimeline};
+* the actor is always the caller, and any `actor` or `subject` parameter is ignored.
+*/
+function mountOwnActivity(app, options) {
+	const { log, guard, actorIdOf } = options;
+	app.get(options.path ?? "/api/me/activity", guard, (c) => {
+		const actorId = actorIdOf(c);
+		if (actorId === null || actorId === void 0 || actorId === "") throw new AppError({
+			code: "UNAUTHENTICATED",
+			status: 401,
+			message: "Sign in to continue."
+		});
+		return respond(c, log(c), {
+			...commonQuery(c),
+			actorId
+		});
+	});
+}
+export { mountAuditTimeline, mountOwnActivity };
+
+//# sourceMappingURL=hono.js.map

package/dist/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.js","names":[],"sources":["../src/hono.ts"],"sourcesContent":["/**\n * Hono routes for the activity timeline: `@awsmbiz/inbis-audit/hono`.\n *\n * The package knows nothing about sessions or roles (it depends on no auth\n * package): the app passes the guard middleware that admits the caller, and\n * for the own-activity route, how to read the caller's user ID.\n *\n * ```ts\n * import { requireAdmin, requireAuth } from \"@awsmbiz/inbis-auth/hono\";\n * const log = (c) => createD1AuditLog(c.env.AUDIT_DB, { actions });\n * mountAuditTimeline(app, { log, guard: requireAdmin() });\n * mountOwnActivity(app, { log, guard: requireAuth(), actorIdOf: (c) => c.var.user?.id });\n * ```\n */\nimport { AppError, validationFailed } from \"@awsmbiz/inbis-core\";\nimport type { Context, Env, Hono, MiddlewareHandler } from \"hono\";\nimport type { AuditEventRecord, AuditLog, AuditTimelineQuery } from \"./audit-log.js\";\n\n/** An event as the timeline routes return it: {@link AuditEventRecord} with `occurredAt` as ISO 8601. */\nexport interface AuditTimelineItem extends Omit<AuditEventRecord, \"occurredAt\"> {\n  occurredAt: string;\n}\n\n/** The timeline routes' response body. */\nexport interface AuditTimelineResponse {\n  items: AuditTimelineItem[];\n  /** Pass as `cursor` (with the same filters) for the next page; `null` on the last. */\n  nextCursor: string | null;\n}\n\ninterface TimelineRouteOptions<E extends Env> {\n  /** The app's audit log for the request. */\n  log: (c: Context<E>) => AuditLog;\n  /**\n   * Admits the caller, or throws (e.g. `requireAdmin()` / `requireAuth()` from\n   * `@awsmbiz/inbis-auth/hono`). Any env: guards are typed for their own variables.\n   */\n  guard: MiddlewareHandler;\n  /** Route path. */\n  path?: string;\n}\n\nexport type MountAuditTimelineOptions<E extends Env = Env> = TimelineRouteOptions<E>;\n\nexport interface MountOwnActivityOptions<E extends Env = Env> extends TimelineRouteOptions<E> {\n  /** The signed-in caller's user ID; `null`/`undefined` is refused with `401 UNAUTHENTICATED`. */\n  actorIdOf: (c: Context<E>) => string | null | undefined;\n}\n\n/** `YYYY-MM-DD` or a full ISO 8601 date-time. */\nconst ISO_DATE = /^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2}))?$/;\n\nfunction dateParam(c: Context, name: \"from\" | \"to\"): Date | undefined {\n  const raw = c.req.query(name);\n  if (raw === undefined || raw === \"\") return undefined;\n  const date = new Date(raw);\n  if (!ISO_DATE.test(raw) || Number.isNaN(date.getTime())) {\n    throw validationFailed([{ path: [name], message: \"Must be an ISO 8601 date or date-time.\" }]);\n  }\n  return date;\n}\n\nfunction textParam(c: Context, name: string): string | undefined {\n  const raw = c.req.query(name);\n  return raw === undefined || raw === \"\" ? undefined : raw;\n}\n\n/** Paging, action and date range: the query parameters both routes accept. */\nfunction commonQuery(c: Context): AuditTimelineQuery {\n  return {\n    limit: c.req.query(\"limit\"),\n    cursor: c.req.query(\"cursor\"),\n    action: textParam(c, \"action\"),\n    from: dateParam(c, \"from\"),\n    to: dateParam(c, \"to\"),\n  };\n}\n\nasync function respond(c: Context, log: AuditLog, query: AuditTimelineQuery): Promise<Response> {\n  const page = await log.list(query);\n  const body: AuditTimelineResponse = {\n    items: page.items.map((item) => ({ ...item, occurredAt: item.occurredAt.toISOString() })),\n    nextCursor: page.nextCursor,\n  };\n  c.header(\"cache-control\", \"no-store\");\n  return c.json(body);\n}\n\n/**\n * Mounts `GET /api/admin/audit-events` (default path): every audit event,\n * newest first, as {@link AuditTimelineResponse}. Query: `action`, `actor`\n * (user ID), `subject` (e.g. `user:<id>`), `from` (inclusive) and `to`\n * (exclusive) as ISO 8601 dates or date-times, `limit` (1–200, default 50) and\n * `cursor`. A malformed date is `422 VALIDATION_FAILED` (`details.issues[].path`).\n * Admission is the `guard`'s: pass the app's admin policy.\n */\nexport function mountAuditTimeline<E extends Env>(app: Hono<E>, options: MountAuditTimelineOptions<E>): void {\n  const { log, guard } = options;\n  // Hono's handler types do not compose over a generic env: register on the plain app.\n  (app as unknown as Hono).get(options.path ?? \"/api/admin/audit-events\", guard, (c) =>\n    respond(c, log(c as unknown as Context<E>), { ...commonQuery(c), actorId: textParam(c, \"actor\"), subjectId: textParam(c, \"subject\") }),\n  );\n}\n\n/**\n * Mounts `GET /api/me/activity` (default path): the caller's own events (those\n * it performed), newest first, as {@link AuditTimelineResponse}. Accepts\n * `action`, `from`, `to`, `limit` and `cursor` like {@link mountAuditTimeline};\n * the actor is always the caller, and any `actor` or `subject` parameter is ignored.\n */\nexport function mountOwnActivity<E extends Env>(app: Hono<E>, options: MountOwnActivityOptions<E>): void {\n  const { log, guard, actorIdOf } = options;\n  (app as unknown as Hono).get(options.path ?? \"/api/me/activity\", guard, (c) => {\n    const actorId = actorIdOf(c as unknown as Context<E>);\n    if (actorId === null || actorId === undefined || actorId === \"\") {\n      throw new AppError({ code: \"UNAUTHENTICATED\", status: 401, message: \"Sign in to continue.\" });\n    }\n    return respond(c, log(c as unknown as Context<E>), { ...commonQuery(c), actorId });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAkDA,MAAM,WAAW;AAEjB,SAAS,UAAU,GAAY,MAAuC;CACpE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI;CAC5B,IAAI,QAAQ,KAAA,KAAa,QAAQ,IAAI,OAAO,KAAA;CAC5C,MAAM,OAAO,IAAI,KAAK,GAAG;CACzB,IAAI,CAAC,SAAS,KAAK,GAAG,KAAK,OAAO,MAAM,KAAK,QAAQ,CAAC,GACpD,MAAM,iBAAiB,CAAC;EAAE,MAAM,CAAC,IAAI;EAAG,SAAS;CAAyC,CAAC,CAAC;CAE9F,OAAO;AACT;AAEA,SAAS,UAAU,GAAY,MAAkC;CAC/D,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI;CAC5B,OAAO,QAAQ,KAAA,KAAa,QAAQ,KAAK,KAAA,IAAY;AACvD;;AAGA,SAAS,YAAY,GAAgC;CACnD,OAAO;EACL,OAAO,EAAE,IAAI,MAAM,OAAO;EAC1B,QAAQ,EAAE,IAAI,MAAM,QAAQ;EAC5B,QAAQ,UAAU,GAAG,QAAQ;EAC7B,MAAM,UAAU,GAAG,MAAM;EACzB,IAAI,UAAU,GAAG,IAAI;CACvB;AACF;AAEA,eAAe,QAAQ,GAAY,KAAe,OAA8C;CAC9F,MAAM,OAAO,MAAM,IAAI,KAAK,KAAK;CACjC,MAAM,OAA8B;EAClC,OAAO,KAAK,MAAM,KAAK,UAAU;GAAE,GAAG;GAAM,YAAY,KAAK,WAAW,YAAY;EAAE,EAAE;EACxF,YAAY,KAAK;CACnB;CACA,EAAE,OAAO,iBAAiB,UAAU;CACpC,OAAO,EAAE,KAAK,IAAI;AACpB;;;;;;;;;AAUA,SAAgB,mBAAkC,KAAc,SAA6C;CAC3G,MAAM,EAAE,KAAK,UAAU;CAEvB,IAAyB,IAAI,QAAQ,QAAQ,2BAA2B,QAAQ,MAC9E,QAAQ,GAAG,IAAI,CAA0B,GAAG;EAAE,GAAG,YAAY,CAAC;EAAG,SAAS,UAAU,GAAG,OAAO;EAAG,WAAW,UAAU,GAAG,SAAS;CAAE,CAAC,CACvI;AACF;;;;;;;AAQA,SAAgB,iBAAgC,KAAc,SAA2C;CACvG,MAAM,EAAE,KAAK,OAAO,cAAc;CAClC,IAAyB,IAAI,QAAQ,QAAQ,oBAAoB,QAAQ,MAAM;EAC7E,MAAM,UAAU,UAAU,CAA0B;EACpD,IAAI,YAAY,QAAQ,YAAY,KAAA,KAAa,YAAY,IAC3D,MAAM,IAAI,SAAS;GAAE,MAAM;GAAmB,QAAQ;GAAK,SAAS;EAAuB,CAAC;EAE9F,OAAO,QAAQ,GAAG,IAAI,CAA0B,GAAG;GAAE,GAAG,YAAY,CAAC;GAAG;EAAQ,CAAC;CACnF,CAAC;AACH"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { a as D1AuditLogOptions, c as AuditActions, d as createAuditActions, i as AuditTimelineQuery, l as AuditActionsInput, n as AuditLog, o as createD1AuditLog, r as AuditTimelineFilter, s as AuditActionCatalogue, t as AuditEventRecord, u as PLATFORM_AUDIT_NAMESPACES } from "./audit-log-xkH9ZIGE.js";
+import { Page, PageInput } from "@awsmbiz/inbis-db";
+/** An event in `@awsmbiz/inbis-auth`'s interim record shape (`AuthAuditEventRecord`): `resource` for `subjectId`. */
+type AuthAuditShapedRecord = Omit<AuditEventRecord, "subjectId"> & {
+  resource: string | null;
+};
+/**
+ * The trail, newest first, in `@awsmbiz/inbis-auth`'s interim record shape: pass it as
+ * `mountAuthAudit`'s `list` so `GET /api/admin/auth-audit-events` reads
+ * `audit_event` without changing its response for existing callers:
+ * `mountAuthAudit(app, { list: (c, input) => listAuthAuditEvents(auditOf(c), input) })`.
+ */
+export declare function listAuthAuditEvents(log: AuditLog, input?: PageInput): Promise<Page<AuthAuditShapedRecord>>;
+/**
+ * Copies every row of `@awsmbiz/inbis-auth`'s interim `auth_audit_event` table into
+ * `audit_event` (same `id`; `resource` becomes `subjectId`) and resolves with
+ * the number of rows copied. Idempotent: rows already copied are skipped, so
+ * an app can run it on every deploy or from its cron trigger. A no-op (`0`)
+ * on a database without the interim table. `db` is the app's audit binding
+ * (the same database as auth's, ADR-4).
+ */
+export declare function importAuthAuditHistory(db: D1Database): Promise<number>;
+/**
+ * The `migrations_table` of the app's audit D1 binding (ADR-4). Declare that
+ * binding after auth's (and access-control's) and before jobs'.
+ */
+export declare const AUDIT_MIGRATIONS_TABLE = "_inbis_audit_migrations";
+export { type AuditActionCatalogue, type AuditActions, type AuditActionsInput, type AuditEventRecord, type AuditLog, type AuditTimelineFilter, type AuditTimelineQuery, type AuthAuditShapedRecord, type D1AuditLogOptions, PLATFORM_AUDIT_NAMESPACES, createAuditActions, createD1AuditLog };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,174 @@
+import { createId, createLogger, redact } from "@awsmbiz/inbis-core";
+import { createDatabase, parsePageRequest, toPage } from "@awsmbiz/inbis-db";
+import { and, countDistinct, desc, eq, gte, isNotNull, lt, or, sql } from "drizzle-orm";
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+// src/actions.ts
+/**
+* First segments reserved for platform packages. An app action such as
+* `auth.something` is rejected, so app events never pass for platform ones.
+*/
+const PLATFORM_AUDIT_NAMESPACES = [
+	"access",
+	"audit",
+	"auth",
+	"cache",
+	"jobs",
+	"notifications",
+	"platform",
+	"storage"
+];
+/** `namespace.thing[.more]`: lowercase segments of letters, digits and `_`, at least two. */
+const ACTION_NAME = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+const namesOf = (catalogue) => Array.isArray(catalogue) ? catalogue : Object.values(catalogue);
+/**
+* Builds the registry. Throws on a malformed name, or on an app action in a
+* platform namespace: both are programming errors, found at startup.
+*/
+function createAuditActions({ platform = [], app = [] }) {
+	const names = /* @__PURE__ */ new Set();
+	const add = (name) => {
+		if (!ACTION_NAME.test(name)) throw new Error(`Audit action "${name}" is not a dotted lowercase name such as "billing.invoice.sent".`);
+		names.add(name);
+	};
+	for (const catalogue of platform) namesOf(catalogue).forEach(add);
+	for (const name of namesOf(app)) {
+		const namespace = name.split(".")[0] ?? "";
+		if (PLATFORM_AUDIT_NAMESPACES.includes(namespace)) throw new Error(`App audit action "${name}" uses the platform namespace "${namespace}". Use the app's own namespace.`);
+		add(name);
+	}
+	return {
+		has: (action) => names.has(action),
+		all: [...names].sort()
+	};
+}
+// src/schema.ts
+/**
+* The `audit_event` table, as `migrations/0001_audit_event.sql` creates it.
+* Internal: apps read the trail through `AuditLog`, never the table.
+*/
+const auditEvent = sqliteTable("audit_event", {
+	/** UUIDv7 (copied events keep their interim ID). */
+	id: text("id").primaryKey(),
+	/** Dotted action name from the action registry, e.g. `auth.sign_in.succeeded`. */
+	action: text("action").notNull(),
+	/** User who performed the action; `null` for the system or an unknown actor. */
+	actorId: text("actor_id"),
+	/** What the action applied to, e.g. `user:<id>`. */
+	subjectId: text("subject_id"),
+	occurredAt: integer("occurred_at", { mode: "timestamp_ms" }).notNull(),
+	requestId: text("request_id"),
+	/** Redacted JSON object. */
+	metadata: text("metadata")
+}, (table) => [
+	index("audit_event_occurred_at_idx").on(table.occurredAt, table.id),
+	index("audit_event_actor_id_idx").on(table.actorId, table.occurredAt),
+	index("audit_event_subject_id_idx").on(table.subjectId, table.occurredAt),
+	index("audit_event_action_idx").on(table.action, table.occurredAt)
+]);
+// src/audit-log.ts
+/** Cursor key: occurred-at milliseconds and ID, newest first. */
+const keyOf = (row) => `${String(row.occurredAt.getTime())}:${row.id}`;
+function parseKey(key) {
+	const separator = key.indexOf(":");
+	return {
+		at: new Date(Number(key.slice(0, separator))),
+		id: key.slice(separator + 1)
+	};
+}
+/** The SQL conditions of a timeline filter. */
+function filterConditions(filter) {
+	return [
+		filter.action === void 0 ? void 0 : eq(auditEvent.action, filter.action),
+		filter.actorId === void 0 ? void 0 : eq(auditEvent.actorId, filter.actorId),
+		filter.subjectId === void 0 ? void 0 : eq(auditEvent.subjectId, filter.subjectId),
+		filter.from === void 0 ? void 0 : gte(auditEvent.occurredAt, filter.from),
+		filter.to === void 0 ? void 0 : lt(auditEvent.occurredAt, filter.to)
+	];
+}
+/** Creates the D1-backed audit log over the database holding `audit_event` (the app's audit binding). */
+function createD1AuditLog(d1, { actions, strict = false, logger }) {
+	const db = createDatabase(d1);
+	return {
+		async record(event) {
+			if (!actions.has(event.action)) {
+				if (strict) throw new Error(`Audit action "${event.action}" is not registered (createAuditActions).`);
+				(logger ?? createLogger()).warn("audit.action.unregistered", { action: event.action });
+			}
+			await db.insert(auditEvent).values({
+				id: createId(),
+				action: event.action,
+				actorId: event.actorId,
+				subjectId: event.subjectId ?? null,
+				occurredAt: event.occurredAt,
+				requestId: event.requestId ?? null,
+				metadata: event.metadata === void 0 ? null : JSON.stringify(redact(event.metadata))
+			});
+		},
+		async forgetUser({ id, email, phoneNumber }) {
+			await db.update(auditEvent).set({ metadata: sql`json_remove(${auditEvent.metadata}, '$.email', '$.phoneNumber', '$.ipAddress', '$.userAgent')` }).where(and(isNotNull(auditEvent.metadata), or(eq(auditEvent.actorId, id), eq(auditEvent.subjectId, `user:${id}`), sql`lower(json_extract(${auditEvent.metadata}, '$.email')) = lower(${email})`, ...typeof phoneNumber === "string" ? [sql`json_extract(${auditEvent.metadata}, '$.phoneNumber') = ${phoneNumber}`] : [])));
+		},
+		async list(query = {}) {
+			const page = parsePageRequest(query, {
+				defaultLimit: 50,
+				maxLimit: 200
+			});
+			const after = page.after === void 0 ? void 0 : parseKey(page.after);
+			const conditions = [...filterConditions(query), after === void 0 ? void 0 : or(lt(auditEvent.occurredAt, after.at), and(eq(auditEvent.occurredAt, after.at), lt(auditEvent.id, after.id)))];
+			const rows = await db.select().from(auditEvent).where(and(...conditions)).orderBy(desc(auditEvent.occurredAt), desc(auditEvent.id)).limit(page.fetchLimit);
+			return toPage(rows.map((row) => ({
+				...row,
+				metadata: row.metadata === null ? null : JSON.parse(row.metadata)
+			})), page, keyOf);
+		},
+		async count(filter = {}) {
+			const [row] = await db.select({ total: sql`count(*)` }).from(auditEvent).where(and(...filterConditions(filter)));
+			return row?.total ?? 0;
+		},
+		async countActors(filter = {}) {
+			const [row] = await db.select({ total: countDistinct(auditEvent.actorId) }).from(auditEvent).where(and(...filterConditions(filter)));
+			return row?.total ?? 0;
+		}
+	};
+}
+// src/auth-history.ts
+/**
+* The trail, newest first, in `@awsmbiz/inbis-auth`'s interim record shape: pass it as
+* `mountAuthAudit`'s `list` so `GET /api/admin/auth-audit-events` reads
+* `audit_event` without changing its response for existing callers:
+* `mountAuthAudit(app, { list: (c, input) => listAuthAuditEvents(auditOf(c), input) })`.
+*/
+async function listAuthAuditEvents(log, input = {}) {
+	const page = await log.list(input);
+	return {
+		...page,
+		items: page.items.map(({ subjectId, ...item }) => ({
+			...item,
+			resource: subjectId
+		}))
+	};
+}
+/** auth's interim table (its `0002_auth_audit_event` migration). */
+const INTERIM_TABLE = "auth_audit_event";
+/**
+* Copies every row of `@awsmbiz/inbis-auth`'s interim `auth_audit_event` table into
+* `audit_event` (same `id`; `resource` becomes `subjectId`) and resolves with
+* the number of rows copied. Idempotent: rows already copied are skipped, so
+* an app can run it on every deploy or from its cron trigger. A no-op (`0`)
+* on a database without the interim table. `db` is the app's audit binding
+* (the same database as auth's, ADR-4).
+*/
+async function importAuthAuditHistory(db) {
+	if (await db.prepare("SELECT 1 AS found FROM sqlite_master WHERE type = 'table' AND name = ?").bind(INTERIM_TABLE).first("found") === null) return 0;
+	const { meta } = await db.prepare(`INSERT OR IGNORE INTO audit_event (id, action, actor_id, subject_id, occurred_at, request_id, metadata)
+       SELECT id, action, actor_id, resource, occurred_at, request_id, metadata FROM ${INTERIM_TABLE}`).run();
+	return meta.changes;
+}
+// src/index.ts
+/**
+* The `migrations_table` of the app's audit D1 binding (ADR-4). Declare that
+* binding after auth's (and access-control's) and before jobs'.
+*/
+const AUDIT_MIGRATIONS_TABLE = "_inbis_audit_migrations";
+export { AUDIT_MIGRATIONS_TABLE, PLATFORM_AUDIT_NAMESPACES, createAuditActions, createD1AuditLog, importAuthAuditHistory, listAuthAuditEvents };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/actions.ts","../src/schema.ts","../src/audit-log.ts","../src/auth-history.ts","../src/index.ts"],"sourcesContent":["/**\n * The action registry: every action name the app's audit trail accepts.\n * Platform packages export their catalogues (e.g. `AUTH_AUDIT_ACTIONS` from\n * `@awsmbiz/inbis-auth`); the app adds its own.\n */\n\n/** A catalogue of action names: an `as const` object of names, or a list. */\nexport type AuditActionCatalogue = Readonly<Record<string, string>> | readonly string[];\n\nexport interface AuditActionsInput {\n  /** Catalogues exported by platform packages, e.g. `AUTH_AUDIT_ACTIONS`. */\n  platform?: readonly AuditActionCatalogue[];\n  /** The app's own actions. They may not use a platform namespace ({@link PLATFORM_AUDIT_NAMESPACES}). */\n  app?: AuditActionCatalogue;\n}\n\n/** The registered action names. */\nexport interface AuditActions {\n  has(action: string): boolean;\n  /** Every registered name, sorted. */\n  readonly all: readonly string[];\n}\n\n/**\n * First segments reserved for platform packages. An app action such as\n * `auth.something` is rejected, so app events never pass for platform ones.\n */\nexport const PLATFORM_AUDIT_NAMESPACES = [\"access\", \"audit\", \"auth\", \"cache\", \"jobs\", \"notifications\", \"platform\", \"storage\"] as const;\n\n/** `namespace.thing[.more]`: lowercase segments of letters, digits and `_`, at least two. */\nconst ACTION_NAME = /^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)+$/;\n\nconst namesOf = (catalogue: AuditActionCatalogue): readonly string[] =>\n  Array.isArray(catalogue) ? (catalogue as readonly string[]) : Object.values(catalogue);\n\n/**\n * Builds the registry. Throws on a malformed name, or on an app action in a\n * platform namespace: both are programming errors, found at startup.\n */\nexport function createAuditActions({ platform = [], app = [] }: AuditActionsInput): AuditActions {\n  const names = new Set<string>();\n  const add = (name: string) => {\n    if (!ACTION_NAME.test(name)) {\n      throw new Error(`Audit action \"${name}\" is not a dotted lowercase name such as \"billing.invoice.sent\".`);\n    }\n    names.add(name);\n  };\n  for (const catalogue of platform) namesOf(catalogue).forEach(add);\n  for (const name of namesOf(app)) {\n    const namespace = name.split(\".\")[0] ?? \"\";\n    if ((PLATFORM_AUDIT_NAMESPACES as readonly string[]).includes(namespace)) {\n      throw new Error(`App audit action \"${name}\" uses the platform namespace \"${namespace}\". Use the app's own namespace.`);\n    }\n    add(name);\n  }\n  const all = [...names].sort();\n  return { has: (action) => names.has(action), all };\n}\n","/**\n * The `audit_event` table, as `migrations/0001_audit_event.sql` creates it.\n * Internal: apps read the trail through `AuditLog`, never the table.\n */\nimport { index, integer, sqliteTable, text } from \"drizzle-orm/sqlite-core\";\n\nexport const auditEvent = sqliteTable(\n  \"audit_event\",\n  {\n    /** UUIDv7 (copied events keep their interim ID). */\n    id: text(\"id\").primaryKey(),\n    /** Dotted action name from the action registry, e.g. `auth.sign_in.succeeded`. */\n    action: text(\"action\").notNull(),\n    /** User who performed the action; `null` for the system or an unknown actor. */\n    actorId: text(\"actor_id\"),\n    /** What the action applied to, e.g. `user:<id>`. */\n    subjectId: text(\"subject_id\"),\n    occurredAt: integer(\"occurred_at\", { mode: \"timestamp_ms\" }).notNull(),\n    requestId: text(\"request_id\"),\n    /** Redacted JSON object. */\n    metadata: text(\"metadata\"),\n  },\n  (table) => [\n    index(\"audit_event_occurred_at_idx\").on(table.occurredAt, table.id),\n    index(\"audit_event_actor_id_idx\").on(table.actorId, table.occurredAt),\n    index(\"audit_event_subject_id_idx\").on(table.subjectId, table.occurredAt),\n    index(\"audit_event_action_idx\").on(table.action, table.occurredAt),\n  ],\n);\n","import { createId, createLogger, redact, type AuditEvent, type AuditSink, type ForgottenUser, type Logger } from \"@awsmbiz/inbis-core\";\nimport { createDatabase, parsePageRequest, toPage, type Page, type PageInput } from \"@awsmbiz/inbis-db\";\nimport { and, countDistinct, desc, eq, gte, isNotNull, lt, or, sql, type SQL } from \"drizzle-orm\";\nimport type { AuditActions } from \"./actions.js\";\nimport { auditEvent } from \"./schema.js\";\n\n/** One stored audit event. */\nexport interface AuditEventRecord {\n  id: string;\n  /** Dotted action name, e.g. `auth.sign_in.succeeded`. */\n  action: string;\n  actorId: string | null;\n  /** `AuditEvent.subjectId`, e.g. `user:<id>`. */\n  subjectId: string | null;\n  occurredAt: Date;\n  requestId: string | null;\n  /** Redacted, secret-free detail. */\n  metadata: Record<string, unknown> | null;\n}\n\n/** Timeline filters; each one given narrows the result. */\nexport interface AuditTimelineFilter {\n  /** Exact action name, e.g. `auth.sign_in.failed`. */\n  action?: string | undefined;\n  /** Events performed by this user ID. */\n  actorId?: string | undefined;\n  /** Events about this subject, e.g. `user:<id>`. */\n  subjectId?: string | undefined;\n  /** Events at or after this instant. */\n  from?: Date | undefined;\n  /** Events before this instant (exclusive). */\n  to?: Date | undefined;\n}\n\n/** A timeline request: filters plus keyset paging. */\nexport type AuditTimelineQuery = AuditTimelineFilter & PageInput;\n\n/** The audit trail over `audit_event`: an `AuditSink`, plus reading. */\nexport interface AuditLog extends AuditSink {\n  /**\n   * After an account deletion: strips `email`, `phoneNumber`, `ipAddress` and\n   * `userAgent` from every event by or about the user, or naming its email\n   * (any case) or number, so only the user ID remains (plan §5.7).\n   */\n  forgetUser(user: ForgottenUser): Promise<void>;\n  /**\n   * The timeline: events matching every filter given, newest first (keyset\n   * pagination; `limit` defaults to 50, at most 200). Keep the same filters\n   * when following `nextCursor`.\n   */\n  list(query?: AuditTimelineQuery): Promise<Page<AuditEventRecord>>;\n  /**\n   * How many events match every filter given (the same filters as\n   * {@link list}, without paging), e.g. failed sign-ins in the last day.\n   */\n  count(filter?: AuditTimelineFilter): Promise<number>;\n  /**\n   * How many distinct actors performed the matching events (the same filters\n   * as {@link count}; events without an actor are not counted), e.g. users who\n   * signed in during the last 7 days.\n   */\n  countActors(filter?: AuditTimelineFilter): Promise<number>;\n}\n\nexport interface D1AuditLogOptions {\n  /** The registered action names (see `createAuditActions`). */\n  actions: AuditActions;\n  /**\n   * `true` (development and tests): an unregistered action throws and nothing\n   * is stored, so a typo fails the test that triggers it. `false` (default,\n   * production): it is stored anyway and logged as `audit.action.unregistered`,\n   * because losing an audit event is worse than an unexpected name.\n   */\n  strict?: boolean;\n  /** Receives the `audit.action.unregistered` warning. Defaults to a console JSON logger. */\n  logger?: Logger;\n}\n\n/** Cursor key: occurred-at milliseconds and ID, newest first. */\nconst keyOf = (row: { occurredAt: Date; id: string }) => `${String(row.occurredAt.getTime())}:${row.id}`;\n\nfunction parseKey(key: string): { at: Date; id: string } {\n  const separator = key.indexOf(\":\");\n  return { at: new Date(Number(key.slice(0, separator))), id: key.slice(separator + 1) };\n}\n\n/** The SQL conditions of a timeline filter. */\nfunction filterConditions(filter: AuditTimelineFilter): (SQL | undefined)[] {\n  return [\n    filter.action === undefined ? undefined : eq(auditEvent.action, filter.action),\n    filter.actorId === undefined ? undefined : eq(auditEvent.actorId, filter.actorId),\n    filter.subjectId === undefined ? undefined : eq(auditEvent.subjectId, filter.subjectId),\n    filter.from === undefined ? undefined : gte(auditEvent.occurredAt, filter.from),\n    filter.to === undefined ? undefined : lt(auditEvent.occurredAt, filter.to),\n  ];\n}\n\n/** Creates the D1-backed audit log over the database holding `audit_event` (the app's audit binding). */\nexport function createD1AuditLog(d1: D1Database, { actions, strict = false, logger }: D1AuditLogOptions): AuditLog {\n  const db = createDatabase(d1);\n  return {\n    async record(event: AuditEvent) {\n      if (!actions.has(event.action)) {\n        if (strict) throw new Error(`Audit action \"${event.action}\" is not registered (createAuditActions).`);\n        (logger ?? createLogger()).warn(\"audit.action.unregistered\", { action: event.action });\n      }\n      await db.insert(auditEvent).values({\n        id: createId(),\n        action: event.action,\n        actorId: event.actorId,\n        subjectId: event.subjectId ?? null,\n        occurredAt: event.occurredAt,\n        requestId: event.requestId ?? null,\n        // Redacted at rest, whatever the caller passed.\n        metadata: event.metadata === undefined ? null : JSON.stringify(redact(event.metadata)),\n      });\n    },\n    async forgetUser({ id, email, phoneNumber }) {\n      await db\n        .update(auditEvent)\n        .set({\n          metadata: sql`json_remove(${auditEvent.metadata}, '$.email', '$.phoneNumber', '$.ipAddress', '$.userAgent')`,\n        })\n        .where(\n          and(\n            isNotNull(auditEvent.metadata),\n            or(\n              eq(auditEvent.actorId, id),\n              eq(auditEvent.subjectId, `user:${id}`),\n              sql`lower(json_extract(${auditEvent.metadata}, '$.email')) = lower(${email})`,\n              ...(typeof phoneNumber === \"string\"\n                ? [sql`json_extract(${auditEvent.metadata}, '$.phoneNumber') = ${phoneNumber}`]\n                : []),\n            ),\n          ),\n        );\n    },\n    async list(query = {}) {\n      const page = parsePageRequest(query, { defaultLimit: 50, maxLimit: 200 });\n      const after = page.after === undefined ? undefined : parseKey(page.after);\n      const conditions: (SQL | undefined)[] = [\n        ...filterConditions(query),\n        after === undefined\n          ? undefined\n          : or(lt(auditEvent.occurredAt, after.at), and(eq(auditEvent.occurredAt, after.at), lt(auditEvent.id, after.id))),\n      ];\n      const rows = await db\n        .select()\n        .from(auditEvent)\n        .where(and(...conditions))\n        .orderBy(desc(auditEvent.occurredAt), desc(auditEvent.id))\n        .limit(page.fetchLimit);\n      return toPage(\n        rows.map((row) => ({\n          ...row,\n          metadata: row.metadata === null ? null : (JSON.parse(row.metadata) as Record<string, unknown>),\n        })),\n        page,\n        keyOf,\n      );\n    },\n    async count(filter = {}) {\n      const [row] = await db\n        .select({ total: sql<number>`count(*)` })\n        .from(auditEvent)\n        .where(and(...filterConditions(filter)));\n      return row?.total ?? 0;\n    },\n    async countActors(filter = {}) {\n      const [row] = await db\n        .select({ total: countDistinct(auditEvent.actorId) })\n        .from(auditEvent)\n        .where(and(...filterConditions(filter)));\n      return row?.total ?? 0;\n    },\n  };\n}\n","/**\n * Taking over from `@awsmbiz/inbis-auth`'s interim audit table (plan Q39). The\n * migrations never touch auth's tables (auth may be added before or after\n * audit), so the copy is an explicit step the app runs; and the trail can be\n * read in auth's interim record shape.\n */\nimport type { Page, PageInput } from \"@awsmbiz/inbis-db\";\nimport type { AuditEventRecord, AuditLog } from \"./audit-log.js\";\n\n/** An event in `@awsmbiz/inbis-auth`'s interim record shape (`AuthAuditEventRecord`): `resource` for `subjectId`. */\nexport type AuthAuditShapedRecord = Omit<AuditEventRecord, \"subjectId\"> & { resource: string | null };\n\n/**\n * The trail, newest first, in `@awsmbiz/inbis-auth`'s interim record shape: pass it as\n * `mountAuthAudit`'s `list` so `GET /api/admin/auth-audit-events` reads\n * `audit_event` without changing its response for existing callers:\n * `mountAuthAudit(app, { list: (c, input) => listAuthAuditEvents(auditOf(c), input) })`.\n */\nexport async function listAuthAuditEvents(log: AuditLog, input: PageInput = {}): Promise<Page<AuthAuditShapedRecord>> {\n  const page = await log.list(input);\n  return { ...page, items: page.items.map(({ subjectId, ...item }) => ({ ...item, resource: subjectId })) };\n}\n\n/** auth's interim table (its `0002_auth_audit_event` migration). */\nconst INTERIM_TABLE = \"auth_audit_event\";\n\n/**\n * Copies every row of `@awsmbiz/inbis-auth`'s interim `auth_audit_event` table into\n * `audit_event` (same `id`; `resource` becomes `subjectId`) and resolves with\n * the number of rows copied. Idempotent: rows already copied are skipped, so\n * an app can run it on every deploy or from its cron trigger. A no-op (`0`)\n * on a database without the interim table. `db` is the app's audit binding\n * (the same database as auth's, ADR-4).\n */\nexport async function importAuthAuditHistory(db: D1Database): Promise<number> {\n  const interim = await db\n    .prepare(\"SELECT 1 AS found FROM sqlite_master WHERE type = 'table' AND name = ?\")\n    .bind(INTERIM_TABLE)\n    .first<number>(\"found\");\n  if (interim === null) return 0;\n  const { meta } = await db\n    .prepare(\n      `INSERT OR IGNORE INTO audit_event (id, action, actor_id, subject_id, occurred_at, request_id, metadata)\n       SELECT id, action, actor_id, resource, occurred_at, request_id, metadata FROM ${INTERIM_TABLE}`,\n    )\n    .run();\n  return meta.changes;\n}\n","export {\n  createAuditActions,\n  PLATFORM_AUDIT_NAMESPACES,\n  type AuditActionCatalogue,\n  type AuditActions,\n  type AuditActionsInput,\n} from \"./actions.js\";\nexport {\n  createD1AuditLog,\n  type AuditEventRecord,\n  type AuditLog,\n  type AuditTimelineFilter,\n  type AuditTimelineQuery,\n  type D1AuditLogOptions,\n} from \"./audit-log.js\";\nexport { importAuthAuditHistory, listAuthAuditEvents, type AuthAuditShapedRecord } from \"./auth-history.js\";\n\n/**\n * The `migrations_table` of the app's audit D1 binding (ADR-4). Declare that\n * binding after auth's (and access-control's) and before jobs'.\n */\nexport const AUDIT_MIGRATIONS_TABLE = \"_inbis_audit_migrations\";\n"],"mappings":"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"}

package/migrations/0001_audit_event.sql

@@ -0,0 +1,18 @@
+-- @inbis/audit 0001_audit_event
+-- The audit trail (plan §5.8): one table for platform and app events.
+-- Source: src/schema.ts. Timestamps are epoch milliseconds. No foreign keys:
+-- events outlive the users and records they name.
+CREATE TABLE `audit_event` (
+	`id` text PRIMARY KEY NOT NULL,
+	`action` text NOT NULL,
+	`actor_id` text,
+	`subject_id` text,
+	`occurred_at` integer NOT NULL,
+	`request_id` text,
+	`metadata` text
+);
+-- Timeline queries: newest first overall, or for one actor, subject or action.
+CREATE INDEX `audit_event_occurred_at_idx` ON `audit_event` (`occurred_at`, `id`);
+CREATE INDEX `audit_event_actor_id_idx` ON `audit_event` (`actor_id`, `occurred_at`);
+CREATE INDEX `audit_event_subject_id_idx` ON `audit_event` (`subject_id`, `occurred_at`);
+CREATE INDEX `audit_event_action_idx` ON `audit_event` (`action`, `occurred_at`);

package/migrations/migrations.lock.json

@@ -0,0 +1,3 @@
+{
+  "0001_audit_event.sql": "sha256:a182ad4f1c9a96557f5b7dcd108b7ca51e7546737b94d0182c502cd899542c94"
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@awsmbiz/inbis-audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Audit trail for Inbis applications: the audit_event table, a D1 AuditSink with redacted metadata, an extensible action registry and package-owned D1 migrations, plus a filterable activity timeline with Hono routes.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awsmbiz/inbis-platform.git",
+    "directory": "packages/audit"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "migrations"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "default": "./dist/hono.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@awsmbiz/inbis-core": "0.2.0",
+    "@awsmbiz/inbis-db": "0.2.0"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.4",
+    "hono": "^4.13.14"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@cloudflare/vitest-plugin": "1.4.11",
+    "@cloudflare/workers-types": "5.20261030.1",
+    "@awsmbiz/inbis-auth": "0.2.0",
+    "@awsmbiz/inbis-eslint-config": "0.2.0",
+    "@awsmbiz/inbis-tsconfig": "0.2.0",
+    "drizzle-orm": "0.45.4",
+    "eslint": "10.14.0",
+    "hono": "4.13.14",
+    "publint": "0.3.25",
+    "tsdown": "0.23.4",
+    "typescript": "6.0.3",
+    "vitest": "5.0.5",
+    "wrangler": "4.156.0"
+  },
+  "peerDependenciesMeta": {
+    "hono": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run",
+    "check:exports": "publint --strict && attw --pack . --profile esm-only",
+    "check:migrations": "inbis-db check-lock migrations --base \"${MIGRATIONS_BASE_REF:-origin/main}\""
+  }
 }