@krizaka/audit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @krizaka/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.
+**Who did what, for every Krizaka product.** The trail is append-only and lives in the product's database, in the Postgres schema `audit`.
+- **Two ways to write:** inside the caller's transaction (it commits or rolls back with the work), or quietly beside it (a failure is logged, never thrown).
+- **For the admin:** filtered and paginated.
+- **For Loi 25:** exported and redacted.
+- **Retention:** purged after a retention the admin sets.
+
+There is no database client and no wall clock: you pass a `Query` and a `Clock`.
+
+```bash
+pnpm add @krizaka/audit @krizaka/db
+```
+
+## Add its schema to your migrations
+
+The schema is embedded through `@krizaka/db`, in your own sequence:
+
+```ts
+import { emitMigration } from "@krizaka/db";
+import { auditSchema } from "@krizaka/audit";
+
+// commit the output as one of your migrations (drizzle-kit `generate --custom`, or your list)
+emitMigration(auditSchema, 1, { tables: { owner: "accounts" } });
+```
+
+The table is `audit.entry`. It holds the time, the actor (references your `accounts`, `ON DELETE SET NULL`), a readable label, the dotted action (`billing.checkout_started`), an optional target, the detail (jsonb) and the IP.
+
+## Use
+
+```ts
+import { createAudit } from "@krizaka/audit";
+import { transaction } from "@krizaka/db";
+
+const audit = createAudit({ clock: { now: () => new Date() }, onError: (e) => logger.warn(e) });
+
+// Inside a unit of work: the entry exists only if the work commits.
+await transaction(connect, async (tx) => {
+  await suspendUser(tx, userId);
+  await audit.record(tx, { actorId: admin.id, actorLabel: admin.name, action: "admin.user_suspended", target: { type: "account", id: userId } });
+});
+
+// Beside it: never fails the request.
+await audit.recordQuietly(query, { actorId: null, actorLabel: "stripe webhook", action: "billing.event_ignored", detail: { type } });
+
+// The admin's view: newest first, filtered, paged by cursor.
+const page = await audit.list(query, { actionPrefix: "admin.", limit: 50 });
+const next = await audit.list(query, { actionPrefix: "admin.", limit: 50, before: page.at(-1)?.id });
+```
+
+- **Loi 25:**
+  - `exportFor(query, accountId)` gives the person's entries;
+  - `redactActor(tx, accountId)` keeps the facts and removes the person: the id and IP become null, and the label becomes « erased ».
+
+  Put as little personal data in `detail` as the action needs.
+- **Retention:** register `auditSettings` in your `@krizaka/settings` registry (`audit.retentionDays`: default 1095, 30–3650 days). Your job then calls `audit.purge(tx, { retentionDays })`.
+- **Input from a request is checked the same way for every store:** a page size must be a positive integer (capped at 200), a cursor must be an entry id, an IP must be an address, and a retention must be within the setting's bounds (30–3650 days), so a bad value never purges the whole trail. Each refusal is an `AuditError` with a stable code (`AUDIT_BAD_FILTER`, `AUDIT_BAD_IP`, `AUDIT_BAD_RETENTION`…).
+- **A fixed list of actions:** `createAudit({ allowedActions: [...] })` refuses anything else (`AUDIT_UNKNOWN_ACTION`).
+- **Another store** runs the contract kit: `auditStoreContract` from `@krizaka/audit/testkit`. `memoryAuditStore()` is the reference.

package/dist/index.d.ts

@@ -0,0 +1,104 @@
+import { A as AuditEntryInput, a as AuditFilters, b as AuditEntry, c as AuditStore, d as AuditInsert } from './port-B2kkvTQu.js';
+export { e as AUDIT_CODE, f as AuditCode, g as AuditError } from './port-B2kkvTQu.js';
+import * as _krizaka_db from '@krizaka/db';
+import { Query, Clock } from '@krizaka/db';
+export { Clock, Query } from '@krizaka/db';
+import * as _krizaka_settings from '@krizaka/settings';
+
+interface AuditDeps {
+    clock: Clock;
+    /** The store over a query (a pool or a transaction). Default: the PostgreSQL store on schema `audit`. */
+    storeFor?: (query: Query) => AuditStore;
+    /** The Postgres schema, when the product renamed the module's (used by the default store). */
+    schema?: string;
+    /** The product's fixed list of actions, when it keeps one (refused otherwise). */
+    allowedActions?: readonly string[];
+    /** Where a quiet write's failure goes (the product's logger). */
+    onError?: (error: unknown, entry: AuditEntryInput) => void | Promise<void>;
+}
+/** The trail as a product uses it. Every function takes the `Query` it writes through: pass `tx` to join a unit of work. */
+interface Audit {
+    /** Records an entry; throws on failure, so it can join the caller's transaction (it commits or rolls back with it). */
+    record(query: Query, entry: AuditEntryInput): Promise<void>;
+    /** Records an entry beside the work: a failure goes to `onError`, never to the caller. */
+    recordQuietly(query: Query, entry: AuditEntryInput): Promise<void>;
+    list(query: Query, filters: AuditFilters): Promise<AuditEntry[]>;
+    /** One actor's entries, for the Loi 25 export. */
+    exportFor(query: Query, actorId: string): Promise<AuditEntry[]>;
+    /** Detaches one actor from the trail (Loi 25 erasure): the facts stay, the person does not. */
+    redactActor(query: Query, actorId: string): Promise<number>;
+    /** Removes what is older than `retentionDays` (the `audit.retentionDays` setting). */
+    purge(query: Query, options: {
+        retentionDays: number;
+    }): Promise<number>;
+}
+/**
+ * The audit trail of a product.
+ * @param deps the clock, the store, the product's action list and error sink
+ * @returns the trail's functions
+ */
+declare function createAudit(deps: AuditDeps): Audit;
+
+/** Whether an entry passes the admin's filters (the same semantics as the database store). */
+declare function matches(entry: AuditEntry, filters: AuditFilters): boolean;
+/**
+ * An in-memory trail, for unit tests and demos. Ids grow like the table's `bigserial`.
+ * @returns a store that passes `auditStoreContract`
+ */
+declare function memoryAuditStore(): AuditStore;
+
+/**
+ * The PostgreSQL store, on `<schema>.entry` (`auditSchema`), over the product's query: a pool, or an open transaction.
+ * @param query the product's SQL runner
+ * @param schema the Postgres schema, when the product renamed it (default `audit`)
+ * @returns a store that passes `auditStoreContract`
+ * @throws DbError `DB_UNSAFE_IDENTIFIER` for a schema that is not an identifier
+ */
+declare function dbAuditStore(query: Query, schema?: string): AuditStore;
+
+/** The size of a page of the trail, for the admin. */
+declare const PAGE: {
+    readonly default: 50;
+    readonly max: 200;
+};
+/**
+ * Checks an entry against the trail's rules and the product's list of actions, and flattens it for a store.
+ * @param input what the product records
+ * @param at when (the injected clock)
+ * @param allowedActions the product's actions, when it keeps a fixed list
+ * @returns the row to write
+ * @throws AuditError `AUDIT_BAD_ACTION`, `AUDIT_UNKNOWN_ACTION`, `AUDIT_BAD_LABEL`, `AUDIT_BAD_IP`
+ */
+declare function toInsert(input: AuditEntryInput, at: Date, allowedActions?: readonly string[]): AuditInsert;
+/**
+ * The page size a store uses: the caller's, capped at `PAGE.max`, or `PAGE.default`.
+ * @param limit the requested size (already checked by `checkFilters`)
+ */
+declare const pageSize: (limit: number | undefined) => number;
+/**
+ * Checks filters that may come from a request: a page size that is a positive integer, a cursor that is an entry id.
+ * @throws AuditError `AUDIT_BAD_FILTER`
+ */
+declare function checkFilters(filters: AuditFilters): void;
+/**
+ * Checks a retention against the setting's bounds, so a wrong value can never purge the whole trail.
+ * @throws AuditError `AUDIT_BAD_RETENTION`
+ */
+declare function checkRetention(days: number): void;
+
+/**
+ * The tables of « audit », in their own Postgres schema (ADR-001 §3). The one product table referenced is the owner (the
+ * account table), declared by the product; deleting an account keeps its entries with the actor detached.
+ * Version 1 is frozen once released: a change is version 2.
+ */
+declare const auditSchema: _krizaka_db.ModuleSchema;
+
+/**
+ * The settings of « audit », a fragment the product adds to its registry: the admin sets how long the trail is kept, and
+ * the product's job calls `purge` with it. Global scope only.
+ */
+declare const auditSettings: {
+    readonly "audit.retentionDays": _krizaka_settings.Def<number>;
+};
+
+export { type Audit, type AuditDeps, AuditEntry, AuditEntryInput, AuditFilters, AuditInsert, AuditStore, PAGE, auditSchema, auditSettings, checkFilters, checkRetention, createAudit, dbAuditStore, matches, memoryAuditStore, pageSize, toInsert };

package/dist/index.js

@@ -0,0 +1,226 @@
+// src/audit.ts
+import { ident as ident2 } from "@krizaka/db";
+import { subDays } from "date-fns";
+
+// src/persistence.ts
+import { ident } from "@krizaka/db";
+
+// src/rules.ts
+import { isIP } from "net";
+
+// src/port.ts
+var AUDIT_CODE = {
+  badAction: "AUDIT_BAD_ACTION",
+  unknownAction: "AUDIT_UNKNOWN_ACTION",
+  badLabel: "AUDIT_BAD_LABEL",
+  badIp: "AUDIT_BAD_IP",
+  badFilter: "AUDIT_BAD_FILTER",
+  badRetention: "AUDIT_BAD_RETENTION"
+};
+var AuditError = class extends Error {
+  constructor(code, value) {
+    super(`${code}: ${value}`);
+    this.code = code;
+    this.value = value;
+    this.name = "AuditError";
+  }
+  code;
+  value;
+};
+
+// src/settings.ts
+import { integer } from "@krizaka/settings";
+var auditSettings = {
+  // @fixed: three years by default; the admin chooses between one month and ten years.
+  "audit.retentionDays": integer("audit", 1095, { min: 30, max: 3650, unit: "days" })
+};
+
+// src/rules.ts
+var PAGE = {
+  // @fixed: a page the admin reads at once; beyond it, the cursor.
+  default: 50,
+  // @fixed: the most one request may return, whatever the caller asks.
+  max: 200
+};
+var ACTION = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)*$/;
+function toInsert(input, at, allowedActions) {
+  if (!ACTION.test(input.action) || input.action.length > 80) throw new AuditError(AUDIT_CODE.badAction, input.action);
+  if (allowedActions && !allowedActions.includes(input.action)) throw new AuditError(AUDIT_CODE.unknownAction, input.action);
+  if (input.ip != null && isIP(input.ip) === 0) throw new AuditError(AUDIT_CODE.badIp, input.ip);
+  const label = input.actorLabel.trim();
+  if (label.length < 1 || label.length > 120) throw new AuditError(AUDIT_CODE.badLabel, input.actorLabel);
+  return {
+    at,
+    actorId: input.actorId,
+    actorLabel: label,
+    action: input.action,
+    targetType: input.target?.type ?? null,
+    targetId: input.target?.id ?? null,
+    detail: input.detail ?? {},
+    ip: input.ip ?? null
+  };
+}
+var pageSize = (limit) => Math.min(limit ?? PAGE.default, PAGE.max);
+var CURSOR = /^[1-9][0-9]{0,18}$/;
+var BIGINT_MAX = 9223372036854775807n;
+function checkFilters(filters) {
+  if (filters.limit !== void 0 && !(Number.isInteger(filters.limit) && filters.limit > 0)) throw new AuditError(AUDIT_CODE.badFilter, `limit ${String(filters.limit)}`);
+  if (filters.before !== void 0 && !(CURSOR.test(filters.before) && BigInt(filters.before) <= BIGINT_MAX)) throw new AuditError(AUDIT_CODE.badFilter, `before ${filters.before}`);
+}
+function checkRetention(days) {
+  const { min = 1, max = Number.MAX_SAFE_INTEGER } = auditSettings["audit.retentionDays"];
+  if (!Number.isInteger(days) || days < min || days > max) throw new AuditError(AUDIT_CODE.badRetention, String(days));
+}
+
+// src/persistence.ts
+var COLUMNS = "id::text AS id, at, actor_id, actor_label, action, target_type, target_id, detail, host(ip) AS ip";
+var toEntry = (r) => ({ id: r.id, at: r.at, actorId: r.actor_id, actorLabel: r.actor_label, action: r.action, targetType: r.target_type, targetId: r.target_id, detail: r.detail, ip: r.ip });
+function where(filters) {
+  const parts = [];
+  const params = [];
+  const add = (clause, value) => {
+    params.push(value);
+    parts.push(clause(params.length));
+  };
+  if (filters.actorId !== void 0) add((n) => `actor_id = $${n}`, filters.actorId);
+  if (filters.actionPrefix !== void 0) add((n) => `starts_with(action, $${n})`, filters.actionPrefix);
+  if (filters.target !== void 0) {
+    add((n) => `target_type = $${n}`, filters.target.type);
+    add((n) => `target_id = $${n}`, filters.target.id);
+  }
+  if (filters.from !== void 0) add((n) => `at >= $${n}`, filters.from);
+  if (filters.to !== void 0) add((n) => `at < $${n}`, filters.to);
+  if (filters.before !== void 0) add((n) => `id < $${n}::bigint`, filters.before);
+  return { sql: parts.length > 0 ? `WHERE ${parts.join(" AND ")}` : "", params };
+}
+function dbAuditStore(query, schema = "audit") {
+  const table = `${ident(schema)}.entry`;
+  const rows = async (sql, params) => (await query(sql, params)).map(toEntry);
+  return {
+    async insert(e) {
+      await query(`INSERT INTO ${table} (at, actor_id, actor_label, action, target_type, target_id, detail, ip) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [e.at, e.actorId, e.actorLabel, e.action, e.targetType, e.targetId, JSON.stringify(e.detail), e.ip]);
+    },
+    async list(filters) {
+      const { sql, params } = where(filters);
+      return rows(`SELECT ${COLUMNS} FROM ${table} ${sql} ORDER BY id DESC LIMIT $${params.length + 1}`, [...params, pageSize(filters.limit)]);
+    },
+    forActor: (actorId) => rows(`SELECT ${COLUMNS} FROM ${table} WHERE actor_id = $1 ORDER BY id DESC`, [actorId]),
+    async redactActor(actorId) {
+      return (await query(`UPDATE ${table} SET actor_id = NULL, actor_label = 'erased', ip = NULL WHERE actor_id = $1 RETURNING id`, [actorId])).length;
+    },
+    async purgeBefore(before) {
+      return (await query(`DELETE FROM ${table} WHERE at < $1 RETURNING id`, [before])).length;
+    }
+  };
+}
+
+// src/audit.ts
+async function report(onError, error, entry) {
+  try {
+    await onError?.(error, entry);
+  } catch {
+  }
+}
+function createAudit(deps) {
+  const schema = ident2(deps.schema ?? "audit");
+  const storeFor = deps.storeFor ?? ((query) => dbAuditStore(query, schema));
+  const record = async (query, entry) => storeFor(query).insert(toInsert(entry, deps.clock.now(), deps.allowedActions));
+  return {
+    record,
+    async recordQuietly(query, entry) {
+      try {
+        await record(query, entry);
+      } catch (error) {
+        await report(deps.onError, error, entry);
+      }
+    },
+    async list(query, filters) {
+      checkFilters(filters);
+      return storeFor(query).list(filters);
+    },
+    exportFor: (query, actorId) => storeFor(query).forActor(actorId),
+    redactActor: (query, actorId) => storeFor(query).redactActor(actorId),
+    async purge(query, { retentionDays }) {
+      checkRetention(retentionDays);
+      return storeFor(query).purgeBefore(subDays(deps.clock.now(), retentionDays));
+    }
+  };
+}
+
+// src/memory.ts
+function matches(entry, filters) {
+  return (filters.actorId === void 0 || entry.actorId === filters.actorId) && (filters.actionPrefix === void 0 || entry.action.startsWith(filters.actionPrefix)) && (filters.target === void 0 || entry.targetType === filters.target.type && entry.targetId === filters.target.id) && (filters.from === void 0 || entry.at >= filters.from) && (filters.to === void 0 || entry.at < filters.to) && (filters.before === void 0 || BigInt(entry.id) < BigInt(filters.before));
+}
+function memoryAuditStore() {
+  const rows = [];
+  let lastId = 0n;
+  const copy = (e) => structuredClone(e);
+  const newestFirst = () => [...rows].sort((a, b) => Number(BigInt(b.id) - BigInt(a.id)));
+  return {
+    async insert(entry) {
+      lastId += 1n;
+      rows.push(copy({ ...entry, id: String(lastId) }));
+    },
+    async list(filters) {
+      return newestFirst().filter((e) => matches(e, filters)).slice(0, pageSize(filters.limit)).map(copy);
+    },
+    async forActor(actorId) {
+      return newestFirst().filter((e) => e.actorId === actorId).map(copy);
+    },
+    async redactActor(actorId) {
+      const mine = rows.filter((e) => e.actorId === actorId);
+      for (const e of mine) Object.assign(e, { actorId: null, actorLabel: "erased", ip: null });
+      return mine.length;
+    },
+    async purgeBefore(before) {
+      const old = rows.filter((e) => e.at < before);
+      for (const e of old) rows.splice(rows.indexOf(e), 1);
+      return old.length;
+    }
+  };
+}
+
+// src/schema.ts
+import { defineModule } from "@krizaka/db";
+var auditSchema = defineModule({
+  module: "audit",
+  tables: ["owner"],
+  migrations: [
+    {
+      version: 1,
+      name: "entries",
+      sql: (c) => `
+CREATE TABLE ${c.schema}.entry (
+  id          bigserial PRIMARY KEY,
+  at          timestamptz NOT NULL,
+  actor_id    uuid REFERENCES ${c.tables.owner}(id) ON DELETE SET NULL,
+  actor_label text NOT NULL CHECK (char_length(actor_label) BETWEEN 1 AND 120),
+  action      text NOT NULL CHECK (action ~ '^[a-z][a-z0-9_]*(\\.[a-z0-9_]+)*$' AND char_length(action) <= 80),
+  target_type text CHECK (target_type IS NULL OR char_length(target_type) <= 40),
+  target_id   text CHECK (target_id IS NULL OR char_length(target_id) <= 200),
+  detail      jsonb NOT NULL DEFAULT '{}'::jsonb,
+  ip          inet
+);
+CREATE INDEX entry_at ON ${c.schema}.entry (at DESC);
+CREATE INDEX entry_action ON ${c.schema}.entry (action, at DESC);
+CREATE INDEX entry_target ON ${c.schema}.entry (target_type, target_id, at DESC);
+CREATE INDEX entry_actor ON ${c.schema}.entry (actor_id) WHERE actor_id IS NOT NULL;`
+    }
+  ]
+});
+export {
+  AUDIT_CODE,
+  AuditError,
+  PAGE,
+  auditSchema,
+  auditSettings,
+  checkFilters,
+  checkRetention,
+  createAudit,
+  dbAuditStore,
+  matches,
+  memoryAuditStore,
+  pageSize,
+  toInsert
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/audit.ts","../src/persistence.ts","../src/rules.ts","../src/port.ts","../src/settings.ts","../src/memory.ts","../src/schema.ts"],"sourcesContent":["import { ident } from \"@krizaka/db\";\nimport { subDays } from \"date-fns\";\n\nimport { dbAuditStore } from \"./persistence\";\nimport type { AuditEntry, AuditEntryInput, AuditFilters, AuditStore, Clock, Query } from \"./port\";\nimport { checkFilters, checkRetention, toInsert } from \"./rules\";\n\nexport interface AuditDeps {\n  clock: Clock;\n  /** The store over a query (a pool or a transaction). Default: the PostgreSQL store on schema `audit`. */\n  storeFor?: (query: Query) => AuditStore;\n  /** The Postgres schema, when the product renamed the module's (used by the default store). */\n  schema?: string;\n  /** The product's fixed list of actions, when it keeps one (refused otherwise). */\n  allowedActions?: readonly string[];\n  /** Where a quiet write's failure goes (the product's logger). */\n  onError?: (error: unknown, entry: AuditEntryInput) => void | Promise<void>;\n}\n\n/** The trail as a product uses it. Every function takes the `Query` it writes through: pass `tx` to join a unit of work. */\nexport interface Audit {\n  /** Records an entry; throws on failure, so it can join the caller's transaction (it commits or rolls back with it). */\n  record(query: Query, entry: AuditEntryInput): Promise<void>;\n  /** Records an entry beside the work: a failure goes to `onError`, never to the caller. */\n  recordQuietly(query: Query, entry: AuditEntryInput): Promise<void>;\n  list(query: Query, filters: AuditFilters): Promise<AuditEntry[]>;\n  /** One actor's entries, for the Loi 25 export. */\n  exportFor(query: Query, actorId: string): Promise<AuditEntry[]>;\n  /** Detaches one actor from the trail (Loi 25 erasure): the facts stay, the person does not. */\n  redactActor(query: Query, actorId: string): Promise<number>;\n  /** Removes what is older than `retentionDays` (the `audit.retentionDays` setting). */\n  purge(query: Query, options: { retentionDays: number }): Promise<number>;\n}\n\n/** Hands a quiet write's failure to the sink; a sink that throws or rejects is swallowed too: `recordQuietly` never throws. */\nasync function report(onError: AuditDeps[\"onError\"], error: unknown, entry: AuditEntryInput): Promise<void> {\n  try {\n    await onError?.(error, entry);\n  } catch {\n    // The sink is the product's logger; a failing logger must not fail the request it was only meant to observe.\n  }\n}\n\n/**\n * The audit trail of a product.\n * @param deps the clock, the store, the product's action list and error sink\n * @returns the trail's functions\n */\nexport function createAudit(deps: AuditDeps): Audit {\n  const schema = ident(deps.schema ?? \"audit\");\n  const storeFor = deps.storeFor ?? ((query: Query) => dbAuditStore(query, schema));\n  const record = async (query: Query, entry: AuditEntryInput) => storeFor(query).insert(toInsert(entry, deps.clock.now(), deps.allowedActions));\n  return {\n    record,\n    async recordQuietly(query, entry) {\n      try {\n        await record(query, entry);\n      } catch (error) {\n        await report(deps.onError, error, entry);\n      }\n    },\n    async list(query, filters) {\n      checkFilters(filters);\n      return storeFor(query).list(filters);\n    },\n    exportFor: (query, actorId) => storeFor(query).forActor(actorId),\n    redactActor: (query, actorId) => storeFor(query).redactActor(actorId),\n    async purge(query, { retentionDays }) {\n      checkRetention(retentionDays);\n      return storeFor(query).purgeBefore(subDays(deps.clock.now(), retentionDays));\n    },\n  };\n}\n","import { ident, type Query } from \"@krizaka/db\";\n\nimport type { AuditEntry, AuditFilters, AuditStore } from \"./port\";\nimport { pageSize } from \"./rules\";\n\ninterface Row {\n  id: string;\n  at: Date;\n  actor_id: string | null;\n  actor_label: string;\n  action: string;\n  target_type: string | null;\n  target_id: string | null;\n  detail: Record<string, unknown>;\n  ip: string | null;\n}\n\nconst COLUMNS = \"id::text AS id, at, actor_id, actor_label, action, target_type, target_id, detail, host(ip) AS ip\";\nconst toEntry = (r: Row): AuditEntry => ({ id: r.id, at: r.at, actorId: r.actor_id, actorLabel: r.actor_label, action: r.action, targetType: r.target_type, targetId: r.target_id, detail: r.detail, ip: r.ip });\n\n/** The WHERE clause of the admin's filters, with its parameters ($1, $2… in order). */\nfunction where(filters: AuditFilters): { sql: string; params: unknown[] } {\n  const parts: string[] = [];\n  const params: unknown[] = [];\n  const add = (clause: (n: number) => string, value: unknown) => { params.push(value); parts.push(clause(params.length)); };\n  if (filters.actorId !== undefined) add((n) => `actor_id = $${n}`, filters.actorId);\n  if (filters.actionPrefix !== undefined) add((n) => `starts_with(action, $${n})`, filters.actionPrefix);\n  if (filters.target !== undefined) { add((n) => `target_type = $${n}`, filters.target.type); add((n) => `target_id = $${n}`, filters.target.id); }\n  if (filters.from !== undefined) add((n) => `at >= $${n}`, filters.from);\n  if (filters.to !== undefined) add((n) => `at < $${n}`, filters.to);\n  if (filters.before !== undefined) add((n) => `id < $${n}::bigint`, filters.before);\n  return { sql: parts.length > 0 ? `WHERE ${parts.join(\" AND \")}` : \"\", params };\n}\n\n/**\n * The PostgreSQL store, on `<schema>.entry` (`auditSchema`), over the product's query: a pool, or an open transaction.\n * @param query the product's SQL runner\n * @param schema the Postgres schema, when the product renamed it (default `audit`)\n * @returns a store that passes `auditStoreContract`\n * @throws DbError `DB_UNSAFE_IDENTIFIER` for a schema that is not an identifier\n */\nexport function dbAuditStore(query: Query, schema = \"audit\"): AuditStore {\n  const table = `${ident(schema)}.entry`;\n  const rows = async (sql: string, params?: unknown[]) => (await query<Row>(sql, params)).map(toEntry);\n  return {\n    async insert(e) {\n      await query(`INSERT INTO ${table} (at, actor_id, actor_label, action, target_type, target_id, detail, ip) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [e.at, e.actorId, e.actorLabel, e.action, e.targetType, e.targetId, JSON.stringify(e.detail), e.ip]);\n    },\n    async list(filters) {\n      const { sql, params } = where(filters);\n      return rows(`SELECT ${COLUMNS} FROM ${table} ${sql} ORDER BY id DESC LIMIT $${params.length + 1}`, [...params, pageSize(filters.limit)]);\n    },\n    forActor: (actorId) => rows(`SELECT ${COLUMNS} FROM ${table} WHERE actor_id = $1 ORDER BY id DESC`, [actorId]),\n    async redactActor(actorId) {\n      return (await query(`UPDATE ${table} SET actor_id = NULL, actor_label = 'erased', ip = NULL WHERE actor_id = $1 RETURNING id`, [actorId])).length;\n    },\n    async purgeBefore(before) {\n      return (await query(`DELETE FROM ${table} WHERE at < $1 RETURNING id`, [before])).length;\n    },\n  };\n}\n","import { isIP } from \"node:net\";\n\nimport { AUDIT_CODE, type AuditEntryInput, AuditError, type AuditFilters, type AuditInsert } from \"./port\";\nimport { auditSettings } from \"./settings\";\n\n/** The size of a page of the trail, for the admin. */\nexport const PAGE = {\n  // @fixed: a page the admin reads at once; beyond it, the cursor.\n  default: 50,\n  // @fixed: the most one request may return, whatever the caller asks.\n  max: 200,\n} as const;\n\nconst ACTION = /^[a-z][a-z0-9_]*(\\.[a-z0-9_]+)*$/;\n\n/**\n * Checks an entry against the trail's rules and the product's list of actions, and flattens it for a store.\n * @param input what the product records\n * @param at when (the injected clock)\n * @param allowedActions the product's actions, when it keeps a fixed list\n * @returns the row to write\n * @throws AuditError `AUDIT_BAD_ACTION`, `AUDIT_UNKNOWN_ACTION`, `AUDIT_BAD_LABEL`, `AUDIT_BAD_IP`\n */\nexport function toInsert(input: AuditEntryInput, at: Date, allowedActions?: readonly string[]): AuditInsert {\n  if (!ACTION.test(input.action) || input.action.length > 80) throw new AuditError(AUDIT_CODE.badAction, input.action);\n  if (allowedActions && !allowedActions.includes(input.action)) throw new AuditError(AUDIT_CODE.unknownAction, input.action);\n  if (input.ip != null && isIP(input.ip) === 0) throw new AuditError(AUDIT_CODE.badIp, input.ip);\n  const label = input.actorLabel.trim();\n  if (label.length < 1 || label.length > 120) throw new AuditError(AUDIT_CODE.badLabel, input.actorLabel);\n  return {\n    at,\n    actorId: input.actorId,\n    actorLabel: label,\n    action: input.action,\n    targetType: input.target?.type ?? null,\n    targetId: input.target?.id ?? null,\n    detail: input.detail ?? {},\n    ip: input.ip ?? null,\n  };\n}\n\n/**\n * The page size a store uses: the caller's, capped at `PAGE.max`, or `PAGE.default`.\n * @param limit the requested size (already checked by `checkFilters`)\n */\nexport const pageSize = (limit: number | undefined): number => Math.min(limit ?? PAGE.default, PAGE.max);\n\nconst CURSOR = /^[1-9][0-9]{0,18}$/;\n/** PostgreSQL's largest `bigint`: an entry id, and so a cursor, is never above it. */\nconst BIGINT_MAX = 9_223_372_036_854_775_807n;\n\n/**\n * Checks filters that may come from a request: a page size that is a positive integer, a cursor that is an entry id.\n * @throws AuditError `AUDIT_BAD_FILTER`\n */\nexport function checkFilters(filters: AuditFilters): void {\n  if (filters.limit !== undefined && !(Number.isInteger(filters.limit) && filters.limit > 0)) throw new AuditError(AUDIT_CODE.badFilter, `limit ${String(filters.limit)}`);\n  if (filters.before !== undefined && !(CURSOR.test(filters.before) && BigInt(filters.before) <= BIGINT_MAX)) throw new AuditError(AUDIT_CODE.badFilter, `before ${filters.before}`);\n}\n\n/**\n * Checks a retention against the setting's bounds, so a wrong value can never purge the whole trail.\n * @throws AuditError `AUDIT_BAD_RETENTION`\n */\nexport function checkRetention(days: number): void {\n  const { min = 1, max = Number.MAX_SAFE_INTEGER } = auditSettings[\"audit.retentionDays\"];\n  if (!Number.isInteger(days) || days < min || days > max) throw new AuditError(AUDIT_CODE.badRetention, String(days));\n}\n","/**\n * The ports of « audit »: who did what, when, to what. Generic: no product import, no database client (a `Query` comes in),\n * no wall clock (a `Clock` comes in). What an action means is the product's; the package keeps the trail.\n */\nexport type { Clock, Query } from \"@krizaka/db\";\n\n/** What a product records. `actorId` is null for the system or a deleted account; the label stays readable. */\nexport interface AuditEntryInput {\n  actorId: string | null;\n  /** A readable name of who acted (« Eric », « system », « stripe webhook »). */\n  actorLabel: string;\n  /** The product's action, dotted (`billing.checkout_started`, `admin.user_suspended`). */\n  action: string;\n  target?: { type: string; id: string } | null;\n  /** Facts about the action. Never a secret, and as little personal data as the action needs. */\n  detail?: Record<string, unknown>;\n  ip?: string | null;\n}\n\n/** What a store writes: the input, flattened, with its time. */\nexport interface AuditInsert {\n  at: Date;\n  actorId: string | null;\n  actorLabel: string;\n  action: string;\n  targetType: string | null;\n  targetId: string | null;\n  detail: Record<string, unknown>;\n  ip: string | null;\n}\n\n/** An entry as read back: its id (a cursor too) and everything written. */\nexport interface AuditEntry extends AuditInsert {\n  id: string;\n}\n\n/** How the admin filters the trail. Newest first; `before` is the last id of the previous page. */\nexport interface AuditFilters {\n  actorId?: string;\n  actionPrefix?: string;\n  target?: { type: string; id: string };\n  from?: Date;\n  to?: Date;\n  limit?: number;\n  before?: string;\n}\n\n/** Where the trail lives. Every adapter runs `auditStoreContract` (`@krizaka/audit/testkit`). */\nexport interface AuditStore {\n  insert(entry: AuditInsert): Promise<void>;\n  list(filters: AuditFilters): Promise<AuditEntry[]>;\n  /** Every entry of one actor (Loi 25 export). */\n  forActor(actorId: string): Promise<AuditEntry[]>;\n  /** Detaches one actor from the trail: id and IP removed, label « erased »; the facts stay. Returns how many entries changed. */\n  redactActor(actorId: string): Promise<number>;\n  /** Removes the entries older than `before`. Returns how many. */\n  purgeBefore(before: Date): Promise<number>;\n}\n\nexport const AUDIT_CODE = {\n  badAction: \"AUDIT_BAD_ACTION\",\n  unknownAction: \"AUDIT_UNKNOWN_ACTION\",\n  badLabel: \"AUDIT_BAD_LABEL\",\n  badIp: \"AUDIT_BAD_IP\",\n  badFilter: \"AUDIT_BAD_FILTER\",\n  badRetention: \"AUDIT_BAD_RETENTION\",\n} as const;\nexport type AuditCode = (typeof AUDIT_CODE)[keyof typeof AUDIT_CODE];\n\nexport class AuditError extends Error {\n  constructor(\n    readonly code: AuditCode,\n    readonly value: string,\n  ) {\n    super(`${code}: ${value}`);\n    this.name = \"AuditError\";\n  }\n}\n","import { integer, type Registry } from \"@krizaka/settings\";\n\n/**\n * The settings of « audit », a fragment the product adds to its registry: the admin sets how long the trail is kept, and\n * the product's job calls `purge` with it. Global scope only.\n */\nexport const auditSettings = {\n  // @fixed: three years by default; the admin chooses between one month and ten years.\n  \"audit.retentionDays\": integer(\"audit\", 1095, { min: 30, max: 3650, unit: \"days\" }),\n} as const satisfies Registry;\n","import type { AuditEntry, AuditFilters, AuditStore } from \"./port\";\nimport { pageSize } from \"./rules\";\n\n/** Whether an entry passes the admin's filters (the same semantics as the database store). */\nexport function matches(entry: AuditEntry, filters: AuditFilters): boolean {\n  return (\n    (filters.actorId === undefined || entry.actorId === filters.actorId) &&\n    (filters.actionPrefix === undefined || entry.action.startsWith(filters.actionPrefix)) &&\n    (filters.target === undefined || (entry.targetType === filters.target.type && entry.targetId === filters.target.id)) &&\n    (filters.from === undefined || entry.at >= filters.from) &&\n    (filters.to === undefined || entry.at < filters.to) &&\n    (filters.before === undefined || BigInt(entry.id) < BigInt(filters.before))\n  );\n}\n\n/**\n * An in-memory trail, for unit tests and demos. Ids grow like the table's `bigserial`.\n * @returns a store that passes `auditStoreContract`\n */\nexport function memoryAuditStore(): AuditStore {\n  const rows: AuditEntry[] = [];\n  let lastId = 0n; // like the table's sequence: never reused, even after a purge\n  /** An independent copy: nothing given or read can change the stored trail. */\n  const copy = (e: AuditEntry): AuditEntry => structuredClone(e);\n  const newestFirst = () => [...rows].sort((a, b) => Number(BigInt(b.id) - BigInt(a.id)));\n  return {\n    async insert(entry) {\n      lastId += 1n;\n      rows.push(copy({ ...entry, id: String(lastId) }));\n    },\n    async list(filters) { return newestFirst().filter((e) => matches(e, filters)).slice(0, pageSize(filters.limit)).map(copy); },\n    async forActor(actorId) { return newestFirst().filter((e) => e.actorId === actorId).map(copy); },\n    async redactActor(actorId) {\n      const mine = rows.filter((e) => e.actorId === actorId);\n      for (const e of mine) Object.assign(e, { actorId: null, actorLabel: \"erased\", ip: null });\n      return mine.length;\n    },\n    async purgeBefore(before) {\n      const old = rows.filter((e) => e.at < before);\n      for (const e of old) rows.splice(rows.indexOf(e), 1);\n      return old.length;\n    },\n  };\n}\n","import { defineModule } from \"@krizaka/db\";\n\n/**\n * The tables of « audit », in their own Postgres schema (ADR-001 §3). The one product table referenced is the owner (the\n * account table), declared by the product; deleting an account keeps its entries with the actor detached.\n * Version 1 is frozen once released: a change is version 2.\n */\nexport const auditSchema = defineModule({\n  module: \"audit\",\n  tables: [\"owner\"],\n  migrations: [\n    {\n      version: 1,\n      name: \"entries\",\n      sql: (c) => `\nCREATE TABLE ${c.schema}.entry (\n  id          bigserial PRIMARY KEY,\n  at          timestamptz NOT NULL,\n  actor_id    uuid REFERENCES ${c.tables.owner}(id) ON DELETE SET NULL,\n  actor_label text NOT NULL CHECK (char_length(actor_label) BETWEEN 1 AND 120),\n  action      text NOT NULL CHECK (action ~ '^[a-z][a-z0-9_]*(\\\\.[a-z0-9_]+)*$' AND char_length(action) <= 80),\n  target_type text CHECK (target_type IS NULL OR char_length(target_type) <= 40),\n  target_id   text CHECK (target_id IS NULL OR char_length(target_id) <= 200),\n  detail      jsonb NOT NULL DEFAULT '{}'::jsonb,\n  ip          inet\n);\nCREATE INDEX entry_at ON ${c.schema}.entry (at DESC);\nCREATE INDEX entry_action ON ${c.schema}.entry (action, at DESC);\nCREATE INDEX entry_target ON ${c.schema}.entry (target_type, target_id, at DESC);\nCREATE INDEX entry_actor ON ${c.schema}.entry (actor_id) WHERE actor_id IS NOT NULL;`,\n    },\n  ],\n});\n"],"mappings":"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","names":["ident","ident"]}

package/dist/port-B2kkvTQu.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The ports of « audit »: who did what, when, to what. Generic: no product import, no database client (a `Query` comes in),
+ * no wall clock (a `Clock` comes in). What an action means is the product's; the package keeps the trail.
+ */
+
+/** What a product records. `actorId` is null for the system or a deleted account; the label stays readable. */
+interface AuditEntryInput {
+    actorId: string | null;
+    /** A readable name of who acted (« Eric », « system », « stripe webhook »). */
+    actorLabel: string;
+    /** The product's action, dotted (`billing.checkout_started`, `admin.user_suspended`). */
+    action: string;
+    target?: {
+        type: string;
+        id: string;
+    } | null;
+    /** Facts about the action. Never a secret, and as little personal data as the action needs. */
+    detail?: Record<string, unknown>;
+    ip?: string | null;
+}
+/** What a store writes: the input, flattened, with its time. */
+interface AuditInsert {
+    at: Date;
+    actorId: string | null;
+    actorLabel: string;
+    action: string;
+    targetType: string | null;
+    targetId: string | null;
+    detail: Record<string, unknown>;
+    ip: string | null;
+}
+/** An entry as read back: its id (a cursor too) and everything written. */
+interface AuditEntry extends AuditInsert {
+    id: string;
+}
+/** How the admin filters the trail. Newest first; `before` is the last id of the previous page. */
+interface AuditFilters {
+    actorId?: string;
+    actionPrefix?: string;
+    target?: {
+        type: string;
+        id: string;
+    };
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    before?: string;
+}
+/** Where the trail lives. Every adapter runs `auditStoreContract` (`@krizaka/audit/testkit`). */
+interface AuditStore {
+    insert(entry: AuditInsert): Promise<void>;
+    list(filters: AuditFilters): Promise<AuditEntry[]>;
+    /** Every entry of one actor (Loi 25 export). */
+    forActor(actorId: string): Promise<AuditEntry[]>;
+    /** Detaches one actor from the trail: id and IP removed, label « erased »; the facts stay. Returns how many entries changed. */
+    redactActor(actorId: string): Promise<number>;
+    /** Removes the entries older than `before`. Returns how many. */
+    purgeBefore(before: Date): Promise<number>;
+}
+declare const AUDIT_CODE: {
+    readonly badAction: "AUDIT_BAD_ACTION";
+    readonly unknownAction: "AUDIT_UNKNOWN_ACTION";
+    readonly badLabel: "AUDIT_BAD_LABEL";
+    readonly badIp: "AUDIT_BAD_IP";
+    readonly badFilter: "AUDIT_BAD_FILTER";
+    readonly badRetention: "AUDIT_BAD_RETENTION";
+};
+type AuditCode = (typeof AUDIT_CODE)[keyof typeof AUDIT_CODE];
+declare class AuditError extends Error {
+    readonly code: AuditCode;
+    readonly value: string;
+    constructor(code: AuditCode, value: string);
+}
+
+export { type AuditEntryInput as A, type AuditFilters as a, type AuditEntry as b, type AuditStore as c, type AuditInsert as d, AUDIT_CODE as e, type AuditCode as f, AuditError as g };

package/dist/testkit.d.ts

@@ -0,0 +1,12 @@
+import { c as AuditStore } from './port-B2kkvTQu.js';
+
+/**
+ * What every AuditStore adapter must do: the same behaviour behind the same port. `owner(n)` gives an actor id the adapter
+ * accepts (an account of the product). Each case writes under its own action prefix, so the cases share one database.
+ * @param name the adapter's name, shown in the test titles
+ * @param make builds the store
+ * @param owner the n-th actor id
+ */
+declare function auditStoreContract(name: string, make: () => AuditStore | Promise<AuditStore>, owner: (n: number) => string | Promise<string>): void;
+
+export { auditStoreContract };

package/dist/testkit.js

@@ -0,0 +1,103 @@
+// src/testkit.ts
+import { expect, it } from "vitest";
+function auditStoreContract(name, make, owner) {
+  const tag = () => `t${Math.random().toString(36).slice(2, 10)}`;
+  const entry = (prefix, over = {}) => ({
+    at: /* @__PURE__ */ new Date("2026-10-23T10:00:00Z"),
+    actorId: null,
+    actorLabel: "system",
+    action: `${prefix}.done`,
+    targetType: null,
+    targetId: null,
+    detail: {},
+    ip: null,
+    ...over
+  });
+  it(`${name}: keeps every field and lists the newest first`, async () => {
+    const store = await make();
+    const p = tag();
+    const actor = await owner(1);
+    await store.insert(entry(p, { at: /* @__PURE__ */ new Date("2026-10-23T09:00:00Z"), action: `${p}.first` }));
+    await store.insert(entry(p, { actorId: actor, actorLabel: "Eric", action: `${p}.second`, targetType: "shop", targetId: "s1", detail: { n: 2, tags: ["a"] }, ip: "203.0.113.9" }));
+    const listed = await store.list({ actionPrefix: `${p}.` });
+    expect(listed.map((e) => e.action)).toEqual([`${p}.second`, `${p}.first`]);
+    expect(listed[0]).toMatchObject({ actorId: actor, actorLabel: "Eric", targetType: "shop", targetId: "s1", detail: { n: 2, tags: ["a"] }, ip: "203.0.113.9" });
+    expect(listed[0].at.toISOString()).toBe("2026-10-23T10:00:00.000Z");
+    expect(typeof listed[0].id).toBe("string");
+  });
+  it(`${name}: filters by actor, target and time window`, async () => {
+    const store = await make();
+    const p = tag();
+    const [a, b] = [await owner(2), await owner(3)];
+    await store.insert(entry(p, { actorId: a, targetType: "shop", targetId: "x", at: /* @__PURE__ */ new Date("2026-10-01T00:00:00Z") }));
+    await store.insert(entry(p, { actorId: b, targetType: "shop", targetId: "y", at: /* @__PURE__ */ new Date("2026-10-10T00:00:00Z") }));
+    expect(await store.list({ actionPrefix: p, actorId: a })).toHaveLength(1);
+    expect((await store.list({ actionPrefix: p, target: { type: "shop", id: "y" } }))[0].actorId).toBe(b);
+    expect(await store.list({ actionPrefix: p, from: /* @__PURE__ */ new Date("2026-10-05T00:00:00Z") })).toHaveLength(1);
+    expect(await store.list({ actionPrefix: p, to: /* @__PURE__ */ new Date("2026-10-05T00:00:00Z") })).toHaveLength(1);
+  });
+  it(`${name}: pages with a limit and a cursor (the last id seen)`, async () => {
+    const store = await make();
+    const p = tag();
+    for (let i = 0; i < 5; i++) await store.insert(entry(p, { action: `${p}.n${i}` }));
+    const page1 = await store.list({ actionPrefix: p, limit: 2 });
+    const page2 = await store.list({ actionPrefix: p, limit: 2, before: page1.at(-1).id });
+    expect(page1.map((e) => e.action)).toEqual([`${p}.n4`, `${p}.n3`]);
+    expect(page2.map((e) => e.action)).toEqual([`${p}.n2`, `${p}.n1`]);
+  });
+  it(`${name}: exports one actor's entries and redacts them (Loi 25), leaving the others`, async () => {
+    const store = await make();
+    const p = tag();
+    const [gone, stays] = [await owner(4), await owner(5)];
+    await store.insert(entry(p, { actorId: gone, actorLabel: "Gone", ip: "198.51.100.1" }));
+    await store.insert(entry(p, { actorId: stays, actorLabel: "Stays" }));
+    expect((await store.forActor(gone)).filter((e) => e.action.startsWith(p))).toHaveLength(1);
+    expect(await store.redactActor(gone)).toBeGreaterThanOrEqual(1);
+    const after = await store.list({ actionPrefix: p });
+    expect(after.find((e) => e.actorLabel === "Stays").actorId).toBe(stays);
+    expect(after.find((e) => e.actorLabel !== "Stays")).toMatchObject({ actorId: null, actorLabel: "erased", ip: null });
+    expect((await store.forActor(gone)).filter((e) => e.action.startsWith(p))).toEqual([]);
+  });
+  it(`${name}: ids never repeat after a purge, so a cursor never skips an entry`, async () => {
+    const store = await make();
+    const p = tag();
+    await store.insert(entry(p, { action: `${p}.old`, at: /* @__PURE__ */ new Date("2020-01-01T00:00:00Z") }));
+    await store.insert(entry(p, { action: `${p}.kept`, at: /* @__PURE__ */ new Date("2026-10-01T00:00:00Z") }));
+    await store.purgeBefore(/* @__PURE__ */ new Date("2021-01-01T00:00:00Z"));
+    await store.insert(entry(p, { action: `${p}.after`, at: /* @__PURE__ */ new Date("2026-10-02T00:00:00Z") }));
+    const all = await store.list({ actionPrefix: p });
+    expect(new Set(all.map((e) => e.id)).size).toBe(all.length);
+    const first = await store.list({ actionPrefix: p, limit: 1 });
+    const rest = await store.list({ actionPrefix: p, before: first[0].id });
+    expect([...first, ...rest].map((e) => e.action)).toEqual([`${p}.after`, `${p}.kept`]);
+  });
+  it(`${name}: the trail cannot be changed by mutating what was given or what was read`, async () => {
+    const store = await make();
+    const p = tag();
+    const input = entry(p, { detail: { nested: { n: 1 } } });
+    await store.insert(input);
+    input.at.setUTCFullYear(1999);
+    input.detail.nested.n = 99;
+    const [read] = await store.list({ actionPrefix: p });
+    read.at.setUTCFullYear(1999);
+    read.detail.nested.n = 42;
+    read.actorLabel = "forged";
+    const [again] = await store.list({ actionPrefix: p });
+    expect(again).toMatchObject({ actorLabel: "system", detail: { nested: { n: 1 } } });
+    expect(again.at.toISOString()).toBe("2026-10-23T10:00:00.000Z");
+    const [exported] = await store.forActor("00000000-0000-4000-8000-000000000000");
+    expect(exported).toBeUndefined();
+  });
+  it(`${name}: purges only what is older than the given time, and counts it`, async () => {
+    const store = await make();
+    const p = tag();
+    await store.insert(entry(p, { action: `${p}.old`, at: /* @__PURE__ */ new Date("2020-01-01T00:00:00Z") }));
+    await store.insert(entry(p, { action: `${p}.new`, at: /* @__PURE__ */ new Date("2026-10-01T00:00:00Z") }));
+    expect(await store.purgeBefore(/* @__PURE__ */ new Date("2021-01-01T00:00:00Z"))).toBeGreaterThanOrEqual(1);
+    expect((await store.list({ actionPrefix: p })).map((e) => e.action)).toEqual([`${p}.new`]);
+  });
+}
+export {
+  auditStoreContract
+};
+//# sourceMappingURL=testkit.js.map

package/dist/testkit.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/testkit.ts"],"sourcesContent":["import { expect, it } from \"vitest\";\n\nimport type { AuditInsert, AuditStore } from \"./port\";\n\n/**\n * What every AuditStore adapter must do: the same behaviour behind the same port. `owner(n)` gives an actor id the adapter\n * accepts (an account of the product). Each case writes under its own action prefix, so the cases share one database.\n * @param name the adapter's name, shown in the test titles\n * @param make builds the store\n * @param owner the n-th actor id\n */\nexport function auditStoreContract(name: string, make: () => AuditStore | Promise<AuditStore>, owner: (n: number) => string | Promise<string>) {\n  const tag = () => `t${Math.random().toString(36).slice(2, 10)}`;\n  const entry = (prefix: string, over: Partial<AuditInsert> = {}): AuditInsert => ({\n    at: new Date(\"2026-10-23T10:00:00Z\"),\n    actorId: null,\n    actorLabel: \"system\",\n    action: `${prefix}.done`,\n    targetType: null,\n    targetId: null,\n    detail: {},\n    ip: null,\n    ...over,\n  });\n\n  it(`${name}: keeps every field and lists the newest first`, async () => {\n    const store = await make();\n    const p = tag();\n    const actor = await owner(1);\n    await store.insert(entry(p, { at: new Date(\"2026-10-23T09:00:00Z\"), action: `${p}.first` }));\n    await store.insert(entry(p, { actorId: actor, actorLabel: \"Eric\", action: `${p}.second`, targetType: \"shop\", targetId: \"s1\", detail: { n: 2, tags: [\"a\"] }, ip: \"203.0.113.9\" }));\n    const listed = await store.list({ actionPrefix: `${p}.` });\n    expect(listed.map((e) => e.action)).toEqual([`${p}.second`, `${p}.first`]);\n    expect(listed[0]).toMatchObject({ actorId: actor, actorLabel: \"Eric\", targetType: \"shop\", targetId: \"s1\", detail: { n: 2, tags: [\"a\"] }, ip: \"203.0.113.9\" });\n    expect(listed[0]!.at.toISOString()).toBe(\"2026-10-23T10:00:00.000Z\");\n    expect(typeof listed[0]!.id).toBe(\"string\");\n  });\n\n  it(`${name}: filters by actor, target and time window`, async () => {\n    const store = await make();\n    const p = tag();\n    const [a, b] = [await owner(2), await owner(3)];\n    await store.insert(entry(p, { actorId: a, targetType: \"shop\", targetId: \"x\", at: new Date(\"2026-10-01T00:00:00Z\") }));\n    await store.insert(entry(p, { actorId: b, targetType: \"shop\", targetId: \"y\", at: new Date(\"2026-10-10T00:00:00Z\") }));\n    expect(await store.list({ actionPrefix: p, actorId: a })).toHaveLength(1);\n    expect((await store.list({ actionPrefix: p, target: { type: \"shop\", id: \"y\" } }))[0]!.actorId).toBe(b);\n    expect(await store.list({ actionPrefix: p, from: new Date(\"2026-10-05T00:00:00Z\") })).toHaveLength(1);\n    expect(await store.list({ actionPrefix: p, to: new Date(\"2026-10-05T00:00:00Z\") })).toHaveLength(1);\n  });\n\n  it(`${name}: pages with a limit and a cursor (the last id seen)`, async () => {\n    const store = await make();\n    const p = tag();\n    for (let i = 0; i < 5; i++) await store.insert(entry(p, { action: `${p}.n${i}` }));\n    const page1 = await store.list({ actionPrefix: p, limit: 2 });\n    const page2 = await store.list({ actionPrefix: p, limit: 2, before: page1.at(-1)!.id });\n    expect(page1.map((e) => e.action)).toEqual([`${p}.n4`, `${p}.n3`]);\n    expect(page2.map((e) => e.action)).toEqual([`${p}.n2`, `${p}.n1`]);\n  });\n\n  it(`${name}: exports one actor's entries and redacts them (Loi 25), leaving the others`, async () => {\n    const store = await make();\n    const p = tag();\n    const [gone, stays] = [await owner(4), await owner(5)];\n    await store.insert(entry(p, { actorId: gone, actorLabel: \"Gone\", ip: \"198.51.100.1\" }));\n    await store.insert(entry(p, { actorId: stays, actorLabel: \"Stays\" }));\n    expect((await store.forActor(gone)).filter((e) => e.action.startsWith(p))).toHaveLength(1);\n    expect(await store.redactActor(gone)).toBeGreaterThanOrEqual(1);\n    const after = await store.list({ actionPrefix: p });\n    expect(after.find((e) => e.actorLabel === \"Stays\")!.actorId).toBe(stays);\n    expect(after.find((e) => e.actorLabel !== \"Stays\")).toMatchObject({ actorId: null, actorLabel: \"erased\", ip: null });\n    expect((await store.forActor(gone)).filter((e) => e.action.startsWith(p))).toEqual([]);\n  });\n\n  it(`${name}: ids never repeat after a purge, so a cursor never skips an entry`, async () => {\n    const store = await make();\n    const p = tag();\n    await store.insert(entry(p, { action: `${p}.old`, at: new Date(\"2020-01-01T00:00:00Z\") }));\n    await store.insert(entry(p, { action: `${p}.kept`, at: new Date(\"2026-10-01T00:00:00Z\") }));\n    await store.purgeBefore(new Date(\"2021-01-01T00:00:00Z\"));\n    await store.insert(entry(p, { action: `${p}.after`, at: new Date(\"2026-10-02T00:00:00Z\") }));\n    const all = await store.list({ actionPrefix: p });\n    expect(new Set(all.map((e) => e.id)).size).toBe(all.length);\n    const first = await store.list({ actionPrefix: p, limit: 1 });\n    const rest = await store.list({ actionPrefix: p, before: first[0]!.id });\n    expect([...first, ...rest].map((e) => e.action)).toEqual([`${p}.after`, `${p}.kept`]);\n  });\n\n  it(`${name}: the trail cannot be changed by mutating what was given or what was read`, async () => {\n    const store = await make();\n    const p = tag();\n    const input = entry(p, { detail: { nested: { n: 1 } } });\n    await store.insert(input);\n    input.at.setUTCFullYear(1999);\n    (input.detail.nested as { n: number }).n = 99;\n    const [read] = await store.list({ actionPrefix: p });\n    read!.at.setUTCFullYear(1999);\n    (read!.detail.nested as { n: number }).n = 42;\n    read!.actorLabel = \"forged\";\n    const [again] = await store.list({ actionPrefix: p });\n    expect(again).toMatchObject({ actorLabel: \"system\", detail: { nested: { n: 1 } } });\n    expect(again!.at.toISOString()).toBe(\"2026-10-23T10:00:00.000Z\");\n    const [exported] = await store.forActor(\"00000000-0000-4000-8000-000000000000\");\n    expect(exported).toBeUndefined();\n  });\n\n  it(`${name}: purges only what is older than the given time, and counts it`, async () => {\n    const store = await make();\n    const p = tag();\n    await store.insert(entry(p, { action: `${p}.old`, at: new Date(\"2020-01-01T00:00:00Z\") }));\n    await store.insert(entry(p, { action: `${p}.new`, at: new Date(\"2026-10-01T00:00:00Z\") }));\n    expect(await store.purgeBefore(new Date(\"2021-01-01T00:00:00Z\"))).toBeGreaterThanOrEqual(1);\n    expect((await store.list({ actionPrefix: p })).map((e) => e.action)).toEqual([`${p}.new`]);\n  });\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,77 @@
 {
   "name": "@krizaka/audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Who did what, for every Krizaka product: an append-only audit trail in its own schema, written inside the caller's transaction or quietly beside it, filtered for the admin, exported and redacted for Loi 25, purged after a retention set by the admin. No database client, no wall clock.",
+  "keywords": [
+    "krizaka",
+    "audit",
+    "audit-log",
+    "loi-25",
+    "postgresql"
+  ],
+  "homepage": "https://github.com/krizaka/krizaka-ts/tree/main/packages/audit",
+  "bugs": "https://github.com/krizaka/krizaka-ts/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krizaka/krizaka-ts.git",
+    "directory": "packages/audit"
+  },
+  "license": "Apache-2.0",
+  "author": "Krizaka (https://www.krizaka.com)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testkit": {
+      "types": "./dist/testkit.d.ts",
+      "import": "./dist/testkit.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/pg": "^8.23.1",
+    "eslint": "^9.39.0",
+    "pg": "^8.23.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "zod": "^4.6.7",
+    "@krizaka/config": "^0.8.0"
+  },
+  "dependencies": {
+    "date-fns": "^4.4.0",
+    "@krizaka/settings": "^0.1.0",
+    "@krizaka/db": "^0.1.0"
+  },
+  "peerDependencies": {
+    "vitest": ">=4",
+    "zod": ">=3.23"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "lint": "eslint . --max-warnings 0 && tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm run lint && pnpm run test && pnpm run build"
+  }
 }