@wtfalch/authz-store 0.2.1 → 0.3.0

package/migrations/0004_credential_keys_issued_id.sql

@@ -0,0 +1,33 @@
+-- authz#95 (decision 2), wave 7: mint and revoke credentials through
+-- @wtfalch/keys/issued instead of this package's own sha256 `wtfk_...`
+-- scheme (credential-secret.ts stays, for rows minted before this).
+--
+-- `secret_hash` is loosened, not dropped: a credential minted from here on
+-- carries no hash of its own (its secret is checked against the
+-- Worker-signed `keys_issued_credentials` row `@wtfalch/keys` owns, not
+-- against a column on this table), and the old rows keep the column and
+-- their history rather than losing it outright. NOT NULL DROP is additive
+-- under a rolling deploy: an old container still inserts a hash, a new one
+-- inserts none, and neither reads the other's row shape.
+--
+-- `keys_issued_id` is the matching `keys_issued_credentials.id`, so
+-- `revokeCredential` can revoke a credential there too, not only mark this
+-- package's own row revoked. Null on a pre-cutover row, which `revoked_at`
+-- on this same table already refuses regardless of what the (now
+-- unreachable, clean-cut) old secret scheme would have said.
+alter table credentials alter column secret_hash drop not null;
+--> statement-breakpoint
+alter table credentials add column if not exists keys_issued_id text;
+--> statement-breakpoint
+
+-- `credentials_secret_prefix_check` (0001_baseline.sql) bounded
+-- `secret_prefix` to 16 characters, sized for the old scheme's 8 raw hex
+-- characters. A `@wtfalch/keys/issued` `keyPrefix` is a host's own split-
+-- secret prefix plus an 8-character public id -- longer than 16 already, and
+-- longer still if a host's prefix grows -- so the bound widens to the same
+-- 64 `@wtfalch/keys` itself allows on `keys_issued_credentials.key_prefix`.
+alter table credentials drop constraint if exists credentials_secret_prefix_check;
+--> statement-breakpoint
+alter table credentials
+  add constraint credentials_secret_prefix_check
+  check (secret_prefix is null or length(secret_prefix) between 1 and 64);

package/migrations/0005_activations.sql

@@ -0,0 +1,71 @@
+-- ADR 0016 ("No standing authority"): storage for time-boxed permission
+-- activations, ported from Boule's drizzle/0014_activations.sql (authz#83
+-- wave 11b). authz_roles.updated_by and the widened authz_assignments
+-- source check (that file's other two changes, plus the six activation.*
+-- names in authz_events_action_check from drizzle/0020_activation_events.sql)
+-- are already in 0001_baseline.sql, so only the two new tables land here.
+--
+-- No FK from principal_id/approver_id to a host's own person table
+-- (`profiles` in Boule): the store never imports a host table, the same as
+-- 0001_baseline.sql's break_glass_sessions.operator_id, left to each host.
+-- Boule's client-side `\if`/`\gset` guard (for its pre/post authz-v2-cutover
+-- databases) does not apply here: every store database has authz_roles and
+-- authz_assignments already, from 0001_baseline.sql, before this file runs.
+
+CREATE TABLE "authz_activations" (
+  "id"              uuid        PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "tenant_id"       uuid        NOT NULL,
+  "application_id"  text        NOT NULL,
+  "platform_id"     text        NOT NULL,
+  "principal_id"    text        NOT NULL,
+  "principal_class" text        NOT NULL,
+  "permissions"     text[]      NOT NULL,
+  "reason"          text        NOT NULL,
+  "reference"       text        NOT NULL,
+  "status"          text        NOT NULL DEFAULT 'pending',
+  "requested_at"    timestamp with time zone NOT NULL DEFAULT now(),
+  "starts_at"       timestamp with time zone NOT NULL,
+  "expires_at"      timestamp with time zone NOT NULL,
+  "role_id"         uuid        NOT NULL,
+  "ended_at"        timestamp with time zone,
+  "ended_by"        text,
+  CONSTRAINT "authz_activations_tenant_id_fkey" FOREIGN KEY ("tenant_id") REFERENCES "tenants"("id") ON DELETE RESTRICT,
+  -- The non-primary authz_roles row minted with exactly the requested
+  -- entries, the same indirection break_glass_sessions.role_id uses.
+  CONSTRAINT "authz_activations_role_fk" FOREIGN KEY ("tenant_id", "role_id") REFERENCES "authz_roles"("tenant_id", "id"),
+  CONSTRAINT "authz_activations_principal_class_check" CHECK ("principal_class" = 'human'),
+  CONSTRAINT "authz_activations_permissions_check" CHECK (cardinality("permissions") BETWEEN 1 AND 100),
+  CONSTRAINT "authz_activations_reason_check" CHECK (length("reason") BETWEEN 1 AND 512),
+  CONSTRAINT "authz_activations_reference_check" CHECK (length("reference") BETWEEN 1 AND 512),
+  CONSTRAINT "authz_activations_status_check" CHECK ("status" IN ('pending', 'active', 'denied', 'expired', 'revoked')),
+  CONSTRAINT "authz_activations_window_check" CHECK ("expires_at" > "starts_at"),
+  CONSTRAINT "authz_activations_ended_check" CHECK ("ended_at" IS NULL OR "ended_at" >= "requested_at")
+);
+--> statement-breakpoint
+-- "does this principal already have an open request", and an approver's own
+-- queue of what is waiting, both scoped by tenant the same way bg_active_idx
+-- and bg_tenant_idx scope break_glass_sessions.
+CREATE INDEX "authz_activations_pending_idx" ON "authz_activations" ("tenant_id", "principal_id") WHERE "status" = 'pending';
+--> statement-breakpoint
+CREATE INDEX "authz_activations_tenant_idx" ON "authz_activations" ("tenant_id", "requested_at" DESC);
+--> statement-breakpoint
+CREATE TABLE "authz_activation_approvals" (
+  "id"              uuid        PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+  "activation_id"   uuid        NOT NULL,
+  "approver_id"     text        NOT NULL,
+  "approver_class"  text        NOT NULL,
+  "decision"        text        NOT NULL,
+  "reason"          text,
+  "decided_at"      timestamp with time zone NOT NULL DEFAULT now(),
+  CONSTRAINT "authz_activation_approvals_activation_id_fkey" FOREIGN KEY ("activation_id") REFERENCES "authz_activations"("id") ON DELETE RESTRICT,
+  CONSTRAINT "authz_activation_approvals_approver_class_check" CHECK ("approver_class" = 'human'),
+  CONSTRAINT "authz_activation_approvals_decision_check" CHECK ("decision" IN ('approved', 'denied')),
+  CONSTRAINT "authz_activation_approvals_reason_check" CHECK ("reason" IS NULL OR length("reason") <= 512)
+);
+--> statement-breakpoint
+-- Every decision recorded against one activation, most recent first -- what
+-- approve/selfApprove reads to count Aged-and-Independent approvers and to
+-- refuse a same-principal approval.
+CREATE INDEX "authz_activation_approvals_activation_idx" ON "authz_activation_approvals" ("activation_id", "decided_at" DESC);
+--> statement-breakpoint
+CREATE INDEX "authz_activation_approvals_approver_idx" ON "authz_activation_approvals" ("approver_id");

package/migrations/0006_erase_person.sql

@@ -0,0 +1,134 @@
+-- Erasure (D9, X6 M3, authz#83 wave 11d): the one sanctioned write to
+-- `authz_events`, plus the store's own scrub of `invitations.email`.
+--
+-- Boule's `drizzle/0008_erasure_and_boot.sql` also updated `profiles` (a
+-- host table) and called `reporting_erase_person` (the host's reporting
+-- package's own function); neither belongs to this migration. Both move to
+-- the `ErasureHost` port `src/erase.ts` takes instead, so this function
+-- touches only what the store owns: `authz_events` and `invitations`.
+--
+-- Additive, per every other file in this directory: never edit this file
+-- once shipped, a change is a new numbered one.
+
+-- ------------------------------------------------------- erase_person(...)
+-- The single sanctioned write to `authz_events` (D9, M3).
+--
+-- Two walls stand between the running app and its own audit log, and this
+-- function is the one door through both. 0001's grants give the runtime
+-- role no UPDATE on `authz_events` at all, and 0001's `authz_events_guard`
+-- trigger refuses any UPDATE on that table touching a column outside
+-- `actor_display`, `before`, `after` and `erased_at`, and refuses DELETE and
+-- TRUNCATE outright. A `SECURITY DEFINER` function owned by the migration
+-- role runs with that role's privileges, so it passes the first wall, and it
+-- is written to touch only those four columns (plus `invitations.email`, a
+-- different table the same trigger does not guard), so it passes the second
+-- rather than going around it. The trigger stays the backstop: if this
+-- function is ever edited to touch a fifth `authz_events` column, the
+-- trigger refuses it and the erasure fails loudly.
+--
+-- What it does, and what it deliberately does not. `actor_id` stays, so
+-- "someone with this id did this" survives every row; `actor_display`
+-- becomes a stable pseudonym derived from the id, so "who that was" does
+-- not. Row counts do not change: nothing is deleted, and an erased row is
+-- still an ordered part of the trail. `before` and `after` are rewritten
+-- wholesale rather than field by field, because they are free-form JSON
+-- written by many call sites and a list of personal keys to scrub would be
+-- a list to keep in step forever; what a row meant is in `action`,
+-- `target_*` and `reason`, none of which this touches.
+--
+-- `search_path` is pinned. A SECURITY DEFINER function that resolves an
+-- unqualified name through the caller's `search_path` runs whatever they put
+-- in front of it, with the owner's privileges, which is the standard way
+-- this feature becomes a privilege escalation.
+CREATE OR REPLACE FUNCTION "erase_person"("subject" text, "pseudonym" text, "subject_email" text)
+RETURNS integer
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = pg_catalog, public
+AS $$
+DECLARE
+  touched integer;
+BEGIN
+  IF "subject" IS NULL OR length("subject") = 0 THEN
+    RAISE EXCEPTION 'erase_person: a subject id is required';
+  END IF;
+  IF "pseudonym" IS NULL OR length("pseudonym") = 0 OR length("pseudonym") > 256 THEN
+    RAISE EXCEPTION 'erase_person: a pseudonym of 1 to 256 characters is required';
+  END IF;
+
+  -- Rows this person WROTE, and rows written ABOUT them.
+  --
+  -- Only the first was ever swept in Boule's own history, and it is the
+  -- smaller half. Almost every payload carrying somebody's personal data was
+  -- written by somebody else: `invitation.sent` puts the invitee's email in
+  -- the inviter's own row, and the invitee never becomes an actor on it.
+  -- Erasing by actor id alone therefore leaves the address that prompted the
+  -- request sitting in the log, which is the one outcome erasure exists to
+  -- prevent. Matching the email inside `before`/`after` catches those rows,
+  -- because the email is the only personal field these payloads ever carry:
+  -- everything else in them is a role key, an id or a count.
+  UPDATE "authz_events"
+     SET "actor_display" = CASE
+           WHEN "actor_id" = "subject" THEN "pseudonym"
+           ELSE "actor_display"
+         END,
+         "before" = CASE WHEN "before" IS NULL THEN NULL ELSE '{"erased":true}'::jsonb END,
+         "after" = CASE WHEN "after" IS NULL THEN NULL ELSE '{"erased":true}'::jsonb END,
+         "erased_at" = now()
+   WHERE "erased_at" IS NULL
+     AND (
+       "actor_id" = "subject"
+       OR (
+         "subject_email" IS NOT NULL
+         AND (
+           lower("before" ->> 'email') = "subject_email"
+           OR lower("after" ->> 'email') = "subject_email"
+         )
+       )
+     );
+  GET DIAGNOSTICS touched = ROW_COUNT;
+
+  -- The invitation rows themselves. `invitations.email` is a plain NOT NULL
+  -- column, not a payload, and no other path ever clears it, so an export
+  -- taken after an erasure handed the address straight back. Replaced with a
+  -- value derived from the same pseudonym: lower case, so the table's own
+  -- CHECK still holds, and at `.invalid`, which RFC 2606 reserves precisely
+  -- so that nothing can ever route to it.
+  --
+  -- No `profiles` UPDATE here, unlike Boule's own function: `profiles` is a
+  -- host table, out of reach of a package migration. `erasePerson`
+  -- (src/erase.ts) calls the host's own `ErasureHost.eraseHostRecords` for
+  -- that, after this function returns and before the `person.erased` audit
+  -- row is written.
+  IF "subject_email" IS NOT NULL THEN
+    UPDATE "invitations"
+       SET "email" = "pseudonym" || '@invalid'
+     WHERE "email" = "subject_email";
+  END IF;
+
+  RETURN touched;
+END
+$$;
+--> statement-breakpoint
+
+-- EXECUTE on a definer function is not UPDATE on what it touches, so the
+-- runtime role may be handed this one without gaining any other access to
+-- the table. Revoked from PUBLIC first, since Postgres grants EXECUTE on a
+-- new function to PUBLIC by default.
+REVOKE ALL ON FUNCTION "erase_person"(text, text, text) FROM PUBLIC;
+--> statement-breakpoint
+
+-- The store has no runtime-role convention of its own, unlike Boule's fixed
+-- `<database>_rt`, granted unconditionally. A host whose runtime role
+-- happens to be named that way gets EXECUTE for free; a host with no such
+-- role gets nothing granted here and grants EXECUTE itself, rather than
+-- this migration failing outright for naming a role that does not exist.
+DO $$
+DECLARE
+  rt text := current_database() || '_rt';
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = rt) THEN
+    EXECUTE format('GRANT EXECUTE ON FUNCTION "erase_person"(text, text, text) TO %I', rt);
+  END IF;
+END
+$$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/authz-store",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Persistence and lifecycle for @wtfalch/authz: the storage a host would otherwise write itself.",
   "type": "module",
   "files": [
@@ -16,8 +16,10 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
-    "@wtfalch/authz": "^0.15.0",
-    "drizzle-orm": ">=0.39.0 <1.0.0"
+    "@wtfalch/authz": "^0.16.0",
+    "@wtfalch/db": "0.4.0",
+    "drizzle-orm": ">=0.39.3 <1.0.0",
+    "zod": "^4.1.13"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -29,12 +31,15 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@wtfalch/db": "0.4.0",
+    "@wtfalch/keys": "0.4.2",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.39.0",
     "fast-check": "^4.9.0",
     "postgres": "^3.4.5",
     "typescript": "^5.9.0",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.6",
+    "zod": "^4.5.4"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",