@12-apps/prisma 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/prisma",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Prisma host: the multi-file schema folder, the plugin migration seam, and the shared PrismaClient singleton with its audit / append-only extensions",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,7 @@
     }
   },
   "scripts": {
-    "build": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate && tsc",
+    "build": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-audit-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate && tsc",
     "clean": "rm -rf dist node_modules coverage",
     "test": "node ../../scripts/vitest-with-teardown.mjs run",
     "test:watch": "vitest watch",
@@ -20,7 +20,7 @@
     "lint": "pnpm run lint:files .",
     "lint:fix": "bash -c 'eslint \"${@:-.}\" --max-warnings 0 --fix' _",
     "typecheck": "tsc --noEmit",
-    "prisma:generate": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate",
+    "prisma:generate": "node scripts/sync-lifecycle-schema.mjs && node scripts/sync-research-schema.mjs && node scripts/sync-shift-schema.mjs --check && node scripts/sync-jobs-schema.mjs --check && node scripts/sync-entitlements-schema.mjs --check && node scripts/sync-payments-schema.mjs --check && node scripts/sync-report-builder-schema.mjs --check && node scripts/sync-rbac-schema.mjs --check && node scripts/sync-onboarding-schema.mjs --check && node scripts/sync-mcp-schema.mjs --check && node scripts/sync-audit-schema.mjs --check && node scripts/sync-prisma-plugins.mjs --check && prisma generate",
     "prisma:migrate": "prisma migrate dev",
     "prisma:push": "prisma db push",
     "prisma:studio": "prisma studio",
@@ -43,7 +43,9 @@
     "prisma:sync-onboarding": "node scripts/sync-onboarding-schema.mjs",
     "prisma:sync-onboarding:check": "node scripts/sync-onboarding-schema.mjs --check",
     "prisma:sync-mcp": "node scripts/sync-mcp-schema.mjs",
-    "prisma:sync-mcp:check": "node scripts/sync-mcp-schema.mjs --check"
+    "prisma:sync-mcp:check": "node scripts/sync-mcp-schema.mjs --check",
+    "prisma:sync-audit": "node scripts/sync-audit-schema.mjs",
+    "prisma:sync-audit:check": "node scripts/sync-audit-schema.mjs --check"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.2.17",
@@ -53,6 +55,7 @@
     "pglite-prisma-adapter": "0.7.2"
   },
   "devDependencies": {
+    "@12-apps/audit": "^1.0.0",
     "@12-apps/entitlements": "^1.20.1",
     "@12-apps/entity-lifecycle": "^2.1.0",
     "@12-apps/eslint-config": "^1.20.0",
@@ -61,7 +64,7 @@
     "@12-apps/onboarding": "^1.20.0",
     "@12-apps/payments-backend": "^2.0.0",
     "@12-apps/product-research": "^2.0.0",
-    "@12-apps/rbac": "^1.20.0",
+    "@12-apps/rbac": "^2.0.0",
     "@12-apps/report-builder": "^3.0.0",
     "@12-apps/shift": "^2.0.0",
     "@12-apps/typescript-config": "^1.20.0",

package/prisma/migrations/20260813120000_add_audit_log/migration.sql

@@ -0,0 +1,87 @@
+-- @12-apps/audit (12-14): the append-only action audit log, owned by the
+-- package and copied into a host's migrations folder by its plugin-migration
+-- sync. Runs identically on PostgreSQL and PGlite.
+--
+-- Append-only is enforced at the CLIENT layer (update/upsert/delete on the
+-- model throw — see src/server/append-only-extension.ts), not by a DB trigger,
+-- matching the house pattern. The only sanctioned removal is the retention
+-- sweep, which goes through raw SQL over the `created_at` index below. Raw SQL
+-- therefore BYPASSES the guard entirely — that is the documented blind spot,
+-- and it is what makes the sweep possible at all.
+--
+-- ── REPLAY-SAFE ON PURPOSE ────────────────────────────────────────────────
+-- Every statement here is idempotent (`IF NOT EXISTS`), because the first host
+-- to adopt this package already HAS an `audit_logs` table created by its own,
+-- earlier migration. A package migration is applied by name order, so this one
+-- sorts AFTER the host's — and a bare `CREATE TABLE` would then fail
+-- `prisma migrate deploy` on an existing database AND on a fresh one built from
+-- the full folder. `prisma migrate resolve --applied` can only paper over the
+-- first case, by hand, once per database; three PRs in this series have already
+-- hit that wall (one deferred adoption entirely, one had to teach the plugin
+-- sync a name-keyed carve-out). So the migration adopts an existing table
+-- instead of demanding a baseline:
+--
+--   * a fresh host gets the table, the column and the five indexes;
+--   * a host that already has the table gets only what it is missing;
+--   * replaying the whole folder is a no-op.
+--
+-- What it deliberately does NOT do is reconcile a DIFFERENT shape. If a host's
+-- pre-existing `audit_logs` is missing a column this package writes (other than
+-- `on_behalf_of_user_id`, handled below) or types one differently, that is a
+-- real divergence and belongs in the host's own migration — silently altering
+-- columns under an append-only trail is not something a package should do.
+
+CREATE TABLE IF NOT EXISTS "audit_logs" (
+    "id" TEXT NOT NULL,
+    "client_id" TEXT NOT NULL,
+    "actor_user_id" TEXT,
+    "actor_role" TEXT,
+    "scope" TEXT,
+    "on_behalf_of_user_id" TEXT,
+    "action" TEXT NOT NULL,
+    "resource_type" TEXT NOT NULL,
+    "resource_id" TEXT NOT NULL,
+    "before" JSONB NOT NULL DEFAULT '{}',
+    "after" JSONB NOT NULL DEFAULT '{}',
+    "request_id" TEXT,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "audit_logs_pkey" PRIMARY KEY ("id")
+);
+
+-- The impersonation half of the attribution pair, as a separate ADD COLUMN and
+-- not only as a column of the CREATE above: a host that adopted an audit table
+-- before impersonation existed has the table but not the column, and the
+-- CREATE is a no-op for it. Nullable, no default, no backfill — NULL is the
+-- honest and permanent value for every write made outside a session, and this
+-- table is append-only, so the value is written at INSERT or never.
+-- ADD COLUMN of a nullable column with no default is metadata-only in
+-- PostgreSQL (no rewrite, no scan), so it is safe on a large trail.
+ALTER TABLE "audit_logs" ADD COLUMN IF NOT EXISTS "on_behalf_of_user_id" TEXT;
+
+-- The viewer's tenant-scoped filters: date (the default newest-first listing),
+-- actor, resource.
+CREATE INDEX IF NOT EXISTS "audit_logs_client_id_created_at_idx"
+    ON "audit_logs"("client_id", "created_at");
+CREATE INDEX IF NOT EXISTS "audit_logs_client_id_actor_user_id_created_at_idx"
+    ON "audit_logs"("client_id", "actor_user_id", "created_at");
+CREATE INDEX IF NOT EXISTS "audit_logs_client_id_resource_type_resource_id_idx"
+    ON "audit_logs"("client_id", "resource_type", "resource_id");
+-- Action-pinned reads: the equality columns first, then the ORDER BY column.
+CREATE INDEX IF NOT EXISTS "audit_logs_client_id_action_resource_type_created_at_idx"
+    ON "audit_logs"("client_id", "action", "resource_type", "created_at");
+-- Serves the retention sweep.
+CREATE INDEX IF NOT EXISTS "audit_logs_created_at_idx" ON "audit_logs"("created_at");
+
+-- ⚠️ NOT CONCURRENTLY, and on a large existing trail that is a LOCK to plan
+-- for rather than a footnote: `prisma migrate deploy` wraps each migration in a
+-- transaction and `CREATE INDEX CONCURRENTLY` cannot run inside one, so each
+-- build above takes a SHARE lock on `audit_logs` — and the writer inserts into
+-- that table INSIDE every audited transaction, so those transactions block for
+-- as long as the build takes.
+--
+-- RUNBOOK for a large deployment: build them out of band FIRST, against the
+-- live database, before releasing — `CREATE INDEX CONCURRENTLY IF NOT EXISTS
+-- <name> ON "audit_logs"(…)` with the names above — and every statement here
+-- then finds its index present and is a no-op. On a fresh or small database,
+-- just let the migration build them.

package/prisma/plugin-migrations.json

@@ -28,6 +28,7 @@
     "20260812120000_add_retention_watermarks",
     "20260812150000_add_mcp_oauth_tables",
     "20260812150000_add_onboarding_states",
+    "20260813120000_add_audit_log",
     "20260813120000_add_entity_lifecycle_tables"
   ]
 }

package/prisma/schema/audit.prisma

@@ -0,0 +1,68 @@
+// @12-apps/audit (12-14) — the append-only action audit log, OWNED by the
+// package. A host adopts it with `node scripts/sync-audit-schema.mjs`, which
+// COPIES this file into the host's schema folder (never a symlink — Prisma
+// lstats a migrations folder, so a symlinked migration is silently skipped,
+// and `turbo prune` drops a partial whose owner is not a declared dependency).
+//
+// Deliberately NO foreign key into any host table (the payments/rbac doctrine):
+// `client_id`, `actor_user_id` and `on_behalf_of_user_id` are by-value scalars,
+// so the partial applies to a host whose tenant table is called anything at
+// all. A host that wants referential integrity adds the constraint in its own
+// migration — see ADOPTING.md.
+//
+// `action` and `resource_type` carry no CHECK constraint: the vocabulary is
+// HOST CONFIG (`AuditVocabulary`), validated in TypeScript at the write site,
+// so a newly instrumented feature adds an action without a migration.
+
+model AuditLog {
+  id       String  @id @default(uuid())
+  clientId String  @map("client_id")
+
+  /// The real human whose credentials authorized the write. NULL = a system
+  /// write (a provider webhook, a job). NEVER the identity an impersonated
+  /// session was rendering as — that is `onBehalfOfUserId`, below.
+  actorUserId String? @map("actor_user_id")
+  /// The role the request was AUTHORIZED under, and the scope the decision was
+  /// made in. Both describe the authorization the NAMED ACTOR used, so both are
+  /// NULL on a system write.
+  actorRole   String? @map("actor_role")
+  scope       String?
+
+  /// The identity the actor was ACTING AS (impersonation / "view as"), never
+  /// the actor themselves. Stored ALONGSIDE `actorUserId` rather than instead
+  /// of it: the trail has to answer "who really did this" and "who did the
+  /// screen claim to be" INDEPENDENTLY, and one column cannot. Conflating them
+  /// is unrecoverable after the fact — an entry that reads as though the
+  /// customer placed the order cannot later be told apart from one they really
+  /// placed, and this table is append-only, so nothing can correct it.
+  /// NULL for every ordinary write, which is why no backfill is possible.
+  onBehalfOfUserId String? @map("on_behalf_of_user_id")
+
+  action       String
+  resourceType String @map("resource_type")
+  resourceId   String @map("resource_id")
+
+  /// Allowlist-redacted state around the mutation: only the fields the
+  /// vocabulary names for this `resourceType` survive, and only flat JSON
+  /// scalars. `{}` for a pure create (no `before`).
+  before Json @default("{}")
+  after  Json @default("{}")
+
+  requestId String?  @map("request_id")
+  createdAt DateTime @default(now()) @map("created_at")
+
+  // The viewer's filters, always tenant-scoped: date (the default listing,
+  // newest first), actor, and resource.
+  @@index([clientId, createdAt])
+  @@index([clientId, actorUserId, createdAt])
+  @@index([clientId, resourceType, resourceId])
+  // Action-pinned reads (an `action_in` pill, a host's own reconciliation
+  // list): the three equality columns, then the sort column, so one index
+  // serves the page AND its count with no sort step. A rare action is the case
+  // that needs it — without the index the filtered scan reads the whole tenant
+  // partition to return an empty page, and pays it twice (findMany + count).
+  @@index([clientId, action, resourceType, createdAt])
+  // Serves the retention sweep ("entries older than N days").
+  @@index([createdAt])
+  @@map("audit_logs")
+}