@better-forge/audit 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BetterStatusPage contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @better-forge/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.
+Audit log: write, read, entity-type registry and routes.
+
+Status: skeleton. Depends on: `@better-forge/db`.

package/dist/audit.d.ts

@@ -0,0 +1,31 @@
+import type { FastifyPluginAsync } from 'fastify';
+import type { AuditAction } from '@better-forge/contracts';
+import type { SqliteDatabase } from '@better-forge/db';
+/** Keys whose values never reach the log. */
+export declare const DEFAULT_SENSITIVE_KEYS: RegExp;
+export interface Actor {
+    userId: number;
+    userEmail: string;
+}
+export interface AuditOptions {
+    /** The application's database handle. It is used lazily, so it may be opened after this is created. */
+    db: SqliteDatabase;
+    /** Keys whose values are replaced by `[redacted]`. */
+    sensitiveKeys?: RegExp;
+}
+/** Audit log: writing entries, redacted diffs and the admin read route. All state is in the returned closure. */
+export declare function createAudit(options: AuditOptions): {
+    write: (who: Actor, action: AuditAction, entityType: string, entityId: number | string | null, entityName: string, diff?: Record<string, unknown>) => Promise<void>;
+    diffObjects: (before: Record<string, unknown>, after: Record<string, unknown>) => Record<string, {
+        from: unknown;
+        to: unknown;
+    }>;
+    snapshot: (obj: Record<string, unknown>) => Record<string, unknown>;
+    actor: (identity: {
+        userId: number;
+        email: string;
+    }) => Actor;
+    routes: FastifyPluginAsync;
+};
+export type Audit = ReturnType<typeof createAudit>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAItD,6CAA6C;AAC7C,eAAO,MAAM,sBAAsB,QAAqG,CAAA;AAExI,MAAM,WAAW,KAAK;IACpB,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,uGAAuG;IACvG,EAAE,EAAE,cAAc,CAAA;IAClB,sDAAsD;IACtD,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,iHAAiH;AACjH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY;iBAuDxC,KAAK,UACF,WAAW,cACP,MAAM,YACR,MAAM,GAAG,MAAM,GAAG,IAAI,cACpB,MAAM,SACX,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC,IAAI,CAAC;0BArCN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,MAAM,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,EAAE,EAAE,OAAO,CAAA;KAAE,CAAC;oBAe1B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;sBAK/C;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,KAAG,KAAK;;EA6EnE;AAED,MAAM,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,WAAW,CAAC,CAAA"}

package/dist/audit.js

@@ -0,0 +1,107 @@
+import { and, desc, eq, gte, like, lte, sql } from 'drizzle-orm';
+import { parsePagination } from './pagination.js';
+import { auditLog } from './tables.js';
+/** Keys whose values never reach the log. */
+export const DEFAULT_SENSITIVE_KEYS = /(password|secret|token|authorization|cookie|credential|vaultconfig|encryptedvalue|recoverycode)/i;
+/** Audit log: writing entries, redacted diffs and the admin read route. All state is in the returned closure. */
+export function createAudit(options) {
+    const { db } = options;
+    const sensitiveKey = options.sensitiveKeys ?? DEFAULT_SENSITIVE_KEYS;
+    function redactValue(value) {
+        if (Array.isArray(value))
+            return value.map(redactValue);
+        if (value && typeof value === 'object')
+            return redactObj(value);
+        return value;
+    }
+    /** Mask sensitive keys in a flat object. */
+    function redactObj(obj) {
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            out[k] = sensitiveKey.test(k) ? '[redacted]' : redactValue(v);
+        }
+        return out;
+    }
+    /**
+     * Compute a field-level diff between two flat objects.
+     * Only changed keys are included. Sensitive keys are masked.
+     */
+    function diffObjects(before, after) {
+        const diff = {};
+        const keys = new Set([...Object.keys(before), ...Object.keys(after)]);
+        for (const key of keys) {
+            if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) {
+                diff[key] = {
+                    from: sensitiveKey.test(key) ? '[redacted]' : redactValue(before[key]),
+                    to: sensitiveKey.test(key) ? '[redacted]' : redactValue(after[key]),
+                };
+            }
+        }
+        return diff;
+    }
+    /** Snapshot of an entity for a create/delete entry. Sensitive keys masked. */
+    function snapshot(obj) {
+        return redactObj(obj);
+    }
+    /** Audit actor for an authenticated identity; an API token appears under its own name, with user id 0 (no user). */
+    function actor(identity) {
+        return { userId: identity.userId, userEmail: identity.email };
+    }
+    /**
+     * Write an audit log entry. Failures are swallowed so they never break the
+     * primary operation.
+     */
+    async function write(who, action, entityType, entityId, entityName, diff) {
+        try {
+            await db.insert(auditLog).values({
+                userId: who.userId,
+                userEmail: who.userEmail,
+                action,
+                entityType,
+                entityId: entityId !== null ? String(entityId) : null,
+                entityName,
+                diff: diff ? JSON.stringify(redactObj(diff)) : null,
+                timestamp: Date.now(),
+            });
+        }
+        catch (err) {
+            console.error('[audit] write failed:', err);
+        }
+    }
+    /** `GET /`: the log, newest first, filterable. Register it under the prefix and the guards of your choice. */
+    const routes = async (app) => {
+        app.get('/', async (req) => {
+            const { page, limit, offset } = parsePagination(req.query, { defaultLimit: 50, maxLimit: 100 });
+            const conditions = [];
+            if (req.query.userEmail)
+                conditions.push(like(auditLog.userEmail, `%${req.query.userEmail}%`));
+            if (req.query.entityType)
+                conditions.push(eq(auditLog.entityType, req.query.entityType));
+            if (req.query.action)
+                conditions.push(eq(auditLog.action, req.query.action));
+            if (req.query.from)
+                conditions.push(gte(auditLog.timestamp, Number(req.query.from)));
+            if (req.query.to)
+                conditions.push(lte(auditLog.timestamp, Number(req.query.to)));
+            const where = conditions.length > 0 ? and(...conditions) : undefined;
+            const [entries, countResult] = await Promise.all([
+                db.select().from(auditLog)
+                    .where(where)
+                    .orderBy(desc(auditLog.timestamp))
+                    .limit(limit)
+                    .offset(offset),
+                db.select({ count: sql `count(*)` }).from(auditLog).where(where),
+            ]);
+            const total = countResult[0]?.count ?? 0;
+            return {
+                entries: entries.map((e) => ({ ...e, diff: e.diff ? JSON.parse(e.diff) : null })),
+                total,
+                page,
+                limit,
+                pages: Math.ceil(total / limit),
+            };
+        });
+    };
+    return { write, diffObjects, snapshot, actor, routes };
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../src/audit.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createAudit, DEFAULT_SENSITIVE_KEYS, type Actor, type Audit, type AuditOptions } from './audit.js';
+export { auditDbModule } from './module.js';
+export { auditLog } from './tables.js';
+export { parsePagination, type Pagination, type PaginationOptions } from './pagination.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,KAAK,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAC3G,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createAudit, DEFAULT_SENSITIVE_KEYS } from './audit.js';
+export { auditDbModule } from './module.js';
+export { auditLog } from './tables.js';
+export { parsePagination } from './pagination.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAA6C,MAAM,YAAY,CAAA;AAC3G,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,OAAO,EAAE,eAAe,EAA2C,MAAM,iBAAiB,CAAA"}

package/dist/migrations.d.ts

@@ -0,0 +1,4 @@
+import type { MigrationStep } from '@better-forge/db';
+/** The audit log. Steps run in this order. */
+export declare const auditMigrations: readonly MigrationStep[];
+//# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,8CAA8C;AAC9C,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAgBnD,CAAA"}

package/dist/migrations.js

@@ -0,0 +1,19 @@
+/** The audit log. Steps run in this order. */
+export const auditMigrations = [
+    { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS audit_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  user_email TEXT NOT NULL,
+  action TEXT NOT NULL,
+  entity_type TEXT NOT NULL,
+  entity_id TEXT,
+  entity_name TEXT NOT NULL,
+  diff TEXT,
+  timestamp INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_audit_log_timestamp ON audit_log(timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_log_user ON audit_log(user_id);
+` },
+];
+//# sourceMappingURL=migrations.js.map

package/dist/migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.js","sourceRoot":"","sources":["../src/migrations.ts"],"names":[],"mappings":"AAEA,8CAA8C;AAC9C,MAAM,CAAC,MAAM,eAAe,GAA6B;IACvD,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;;;;;;;;;;;;;;CActB,EAAE;CACF,CAAA"}

package/dist/module.d.ts

@@ -0,0 +1,8 @@
+import * as tables from './tables.js';
+/** The audit log table and its migrations, for the application's list of database modules. */
+export declare const auditDbModule: {
+    id: string;
+    tables: typeof tables;
+    migrations: readonly import("@better-forge/db").MigrationStep[];
+};
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AAGrC,8FAA8F;AAC9F,eAAO,MAAM,aAAa;;;;CAA0E,CAAA"}

package/dist/module.js

@@ -0,0 +1,5 @@
+import * as tables from './tables.js';
+import { auditMigrations } from './migrations.js';
+/** The audit log table and its migrations, for the application's list of database modules. */
+export const auditDbModule = { id: 'audit', tables, migrations: auditMigrations };
+//# sourceMappingURL=module.js.map

package/dist/module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.js","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAA;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAEjD,8FAA8F;AAC9F,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAqB,CAAA"}

package/dist/pagination.d.ts

@@ -0,0 +1,20 @@
+export interface Pagination {
+    page: number;
+    limit: number;
+    offset: number;
+}
+export interface PaginationOptions {
+    defaultLimit: number;
+    maxLimit: number;
+    /** Highest page accepted; keeps OFFSET within a sane range. */
+    maxPage?: number;
+}
+/**
+ * Lenient paging for admin lists: missing, non-numeric or out-of-range values fall back to the
+ * default or are clamped into range, so a hand-edited URL never fails the page.
+ */
+export declare function parsePagination(query: {
+    page?: string;
+    limit?: string;
+}, options: PaginationOptions): Pagination;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAOhH"}

package/dist/pagination.js

@@ -0,0 +1,14 @@
+const DEFAULT_MAX_PAGE = 100_000;
+/**
+ * Lenient paging for admin lists: missing, non-numeric or out-of-range values fall back to the
+ * default or are clamped into range, so a hand-edited URL never fails the page.
+ */
+export function parsePagination(query, options) {
+    const maxPage = options.maxPage ?? DEFAULT_MAX_PAGE;
+    const rawPage = Math.floor(Number(query.page ?? 1)) || 1;
+    const rawLimit = Math.floor(Number(query.limit ?? options.defaultLimit)) || options.defaultLimit;
+    const page = Math.min(maxPage, Math.max(1, rawPage));
+    const limit = Math.min(options.maxLimit, Math.max(1, rawLimit));
+    return { page, limit, offset: (page - 1) * limit };
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAaA,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEhC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAwC,EAAE,OAA0B;IAClG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAA;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,OAAO,CAAC,YAAY,CAAA;IAChG,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAA;IACpD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAA;IAC/D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,EAAE,CAAA;AACpD,CAAC"}

package/dist/tables.d.ts

@@ -0,0 +1,173 @@
+export declare const auditLog: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "audit_log";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "audit_log";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "user_id";
+            tableName: "audit_log";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userEmail: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "user_email";
+            tableName: "audit_log";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        action: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "action";
+            tableName: "audit_log";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        entityType: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "entity_type";
+            tableName: "audit_log";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        entityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "entity_id";
+            tableName: "audit_log";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        entityName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "entity_name";
+            tableName: "audit_log";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        diff: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "diff";
+            tableName: "audit_log";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        timestamp: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "timestamp";
+            tableName: "audit_log";
+            dataType: "number";
+            columnType: "SQLiteInteger";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+//# sourceMappingURL=tables.d.ts.map

package/dist/tables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.d.ts","sourceRoot":"","sources":["../src/tables.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAUnB,CAAA"}

package/dist/tables.js

@@ -0,0 +1,13 @@
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core';
+export const auditLog = sqliteTable('audit_log', {
+    id: integer('id').primaryKey({ autoIncrement: true }),
+    userId: integer('user_id').notNull(),
+    userEmail: text('user_email').notNull(),
+    action: text('action').notNull(), // 'create' | 'update' | 'delete'
+    entityType: text('entity_type').notNull(),
+    entityId: text('entity_id'),
+    entityName: text('entity_name').notNull(),
+    diff: text('diff'), // JSON | null
+    timestamp: integer('timestamp').notNull(),
+});
+//# sourceMappingURL=tables.js.map

package/dist/tables.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tables.js","sourceRoot":"","sources":["../src/tables.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAA;AAEpE,MAAM,CAAC,MAAM,QAAQ,GAAG,WAAW,CAAC,WAAW,EAAE;IAC/C,EAAE,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;IACrD,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE;IACpC,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IACvC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAQ,iCAAiC;IACzE,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,QAAQ,EAAE,IAAI,CAAC,WAAW,CAAC;IAC3B,UAAU,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE;IACzC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,EAAsB,cAAc;IACtD,SAAS,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,OAAO,EAAE;CAC1C,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@better-forge/audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Audit log: write, read, entity-type registry and routes.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BElluu/Better-Forge.git",
+    "directory": "packages/audit"
+  },
+  "homepage": "https://github.com/BElluu/Better-Forge/tree/main/packages/audit#readme",
+  "bugs": {
+    "url": "https://github.com/BElluu/Better-Forge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.*"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch --preserveWatchOutput"
+  },
+  "peerDependencies": {
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.3.2",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@better-forge/contracts": "0.1.1",
+    "@better-forge/db": "0.1.1"
+  },
+  "engines": {
+    "node": ">=26.10.0"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,149 @@
+import type { FastifyPluginAsync } from 'fastify'
+import { and, desc, eq, gte, like, lte, sql } from 'drizzle-orm'
+import type { AuditAction } from '@better-forge/contracts'
+import type { SqliteDatabase } from '@better-forge/db'
+import { parsePagination } from './pagination.js'
+import { auditLog } from './tables.js'
+
+/** Keys whose values never reach the log. */
+export const DEFAULT_SENSITIVE_KEYS = /(password|secret|token|authorization|cookie|credential|vaultconfig|encryptedvalue|recoverycode)/i
+
+export interface Actor {
+  userId: number
+  userEmail: string
+}
+
+export interface AuditOptions {
+  /** The application's database handle. It is used lazily, so it may be opened after this is created. */
+  db: SqliteDatabase
+  /** Keys whose values are replaced by `[redacted]`. */
+  sensitiveKeys?: RegExp
+}
+
+/** Audit log: writing entries, redacted diffs and the admin read route. All state is in the returned closure. */
+export function createAudit(options: AuditOptions) {
+  const { db } = options
+  const sensitiveKey = options.sensitiveKeys ?? DEFAULT_SENSITIVE_KEYS
+
+  function redactValue(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(redactValue)
+    if (value && typeof value === 'object') return redactObj(value as Record<string, unknown>)
+    return value
+  }
+
+  /** Mask sensitive keys in a flat object. */
+  function redactObj(obj: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = sensitiveKey.test(k) ? '[redacted]' : redactValue(v)
+    }
+    return out
+  }
+
+  /**
+   * Compute a field-level diff between two flat objects.
+   * Only changed keys are included. Sensitive keys are masked.
+   */
+  function diffObjects(
+    before: Record<string, unknown>,
+    after: Record<string, unknown>,
+  ): Record<string, { from: unknown; to: unknown }> {
+    const diff: Record<string, { from: unknown; to: unknown }> = {}
+    const keys = new Set([...Object.keys(before), ...Object.keys(after)])
+    for (const key of keys) {
+      if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) {
+        diff[key] = {
+          from: sensitiveKey.test(key) ? '[redacted]' : redactValue(before[key]),
+          to: sensitiveKey.test(key) ? '[redacted]' : redactValue(after[key]),
+        }
+      }
+    }
+    return diff
+  }
+
+  /** Snapshot of an entity for a create/delete entry. Sensitive keys masked. */
+  function snapshot(obj: Record<string, unknown>): Record<string, unknown> {
+    return redactObj(obj)
+  }
+
+  /** Audit actor for an authenticated identity; an API token appears under its own name, with user id 0 (no user). */
+  function actor(identity: { userId: number; email: string }): Actor {
+    return { userId: identity.userId, userEmail: identity.email }
+  }
+
+  /**
+   * Write an audit log entry. Failures are swallowed so they never break the
+   * primary operation.
+   */
+  async function write(
+    who: Actor,
+    action: AuditAction,
+    entityType: string,
+    entityId: number | string | null,
+    entityName: string,
+    diff?: Record<string, unknown>,
+  ): Promise<void> {
+    try {
+      await db.insert(auditLog).values({
+        userId: who.userId,
+        userEmail: who.userEmail,
+        action,
+        entityType,
+        entityId: entityId !== null ? String(entityId) : null,
+        entityName,
+        diff: diff ? JSON.stringify(redactObj(diff)) : null,
+        timestamp: Date.now(),
+      })
+    } catch (err) {
+      console.error('[audit] write failed:', err)
+    }
+  }
+
+  /** `GET /`: the log, newest first, filterable. Register it under the prefix and the guards of your choice. */
+  const routes: FastifyPluginAsync = async (app) => {
+    app.get<{
+      Querystring: {
+        page?: string
+        limit?: string
+        userEmail?: string
+        entityType?: string
+        action?: string
+        from?: string   // unix ms
+        to?: string     // unix ms
+      }
+    }>('/', async (req) => {
+      const { page, limit, offset } = parsePagination(req.query, { defaultLimit: 50, maxLimit: 100 })
+
+      const conditions = []
+      if (req.query.userEmail) conditions.push(like(auditLog.userEmail, `%${req.query.userEmail}%`))
+      if (req.query.entityType) conditions.push(eq(auditLog.entityType, req.query.entityType))
+      if (req.query.action)     conditions.push(eq(auditLog.action, req.query.action))
+      if (req.query.from)       conditions.push(gte(auditLog.timestamp, Number(req.query.from)))
+      if (req.query.to)         conditions.push(lte(auditLog.timestamp, Number(req.query.to)))
+
+      const where = conditions.length > 0 ? and(...conditions) : undefined
+
+      const [entries, countResult] = await Promise.all([
+        db.select().from(auditLog)
+          .where(where)
+          .orderBy(desc(auditLog.timestamp))
+          .limit(limit)
+          .offset(offset),
+        db.select({ count: sql<number>`count(*)` }).from(auditLog).where(where),
+      ])
+
+      const total = countResult[0]?.count ?? 0
+      return {
+        entries: entries.map((e) => ({ ...e, diff: e.diff ? JSON.parse(e.diff) : null })),
+        total,
+        page,
+        limit,
+        pages: Math.ceil(total / limit),
+      }
+    })
+  }
+
+  return { write, diffObjects, snapshot, actor, routes }
+}
+
+export type Audit = ReturnType<typeof createAudit>

package/src/index.ts

@@ -0,0 +1,4 @@
+export { createAudit, DEFAULT_SENSITIVE_KEYS, type Actor, type Audit, type AuditOptions } from './audit.js'
+export { auditDbModule } from './module.js'
+export { auditLog } from './tables.js'
+export { parsePagination, type Pagination, type PaginationOptions } from './pagination.js'

package/src/migrations.ts

@@ -0,0 +1,20 @@
+import type { MigrationStep } from '@better-forge/db'
+
+/** The audit log. Steps run in this order. */
+export const auditMigrations: readonly MigrationStep[] = [
+  { kind: 'exec', sql: `
+CREATE TABLE IF NOT EXISTS audit_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_id INTEGER NOT NULL,
+  user_email TEXT NOT NULL,
+  action TEXT NOT NULL,
+  entity_type TEXT NOT NULL,
+  entity_id TEXT,
+  entity_name TEXT NOT NULL,
+  diff TEXT,
+  timestamp INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_audit_log_timestamp ON audit_log(timestamp DESC);
+CREATE INDEX IF NOT EXISTS idx_audit_log_user ON audit_log(user_id);
+` },
+]

package/src/module.ts

@@ -0,0 +1,6 @@
+import type { DbModule } from '@better-forge/db'
+import * as tables from './tables.js'
+import { auditMigrations } from './migrations.js'
+
+/** The audit log table and its migrations, for the application's list of database modules. */
+export const auditDbModule = { id: 'audit', tables, migrations: auditMigrations } satisfies DbModule

package/src/pagination.ts

@@ -0,0 +1,27 @@
+export interface Pagination {
+  page: number
+  limit: number
+  offset: number
+}
+
+export interface PaginationOptions {
+  defaultLimit: number
+  maxLimit: number
+  /** Highest page accepted; keeps OFFSET within a sane range. */
+  maxPage?: number
+}
+
+const DEFAULT_MAX_PAGE = 100_000
+
+/**
+ * Lenient paging for admin lists: missing, non-numeric or out-of-range values fall back to the
+ * default or are clamped into range, so a hand-edited URL never fails the page.
+ */
+export function parsePagination(query: { page?: string; limit?: string }, options: PaginationOptions): Pagination {
+  const maxPage = options.maxPage ?? DEFAULT_MAX_PAGE
+  const rawPage = Math.floor(Number(query.page ?? 1)) || 1
+  const rawLimit = Math.floor(Number(query.limit ?? options.defaultLimit)) || options.defaultLimit
+  const page = Math.min(maxPage, Math.max(1, rawPage))
+  const limit = Math.min(options.maxLimit, Math.max(1, rawLimit))
+  return { page, limit, offset: (page - 1) * limit }
+}

package/src/tables.ts

@@ -0,0 +1,13 @@
+import { sqliteTable, integer, text } from 'drizzle-orm/sqlite-core'
+
+export const auditLog = sqliteTable('audit_log', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  userId: integer('user_id').notNull(),
+  userEmail: text('user_email').notNull(),
+  action: text('action').notNull(),       // 'create' | 'update' | 'delete'
+  entityType: text('entity_type').notNull(),
+  entityId: text('entity_id'),
+  entityName: text('entity_name').notNull(),
+  diff: text('diff'),                     // JSON | null
+  timestamp: integer('timestamp').notNull(),
+})