@wtfalch/authz-store 0.5.0 → 0.6.0

package/README.md

@@ -128,7 +128,8 @@ same helper otf already used, in place of the `(error as {code?}).code ===
 '23505'` duck-typing Boule's and archon's copies both wrote — declared as a
 peer dependency, matching `drizzle-orm`'s role (a host-supplied instance),
 pinned exact at `0.4.0` (the estate's `@wtfalch/*` pin rule), plus a matching
-exact `devDependency` for this package's own build and test.
+exact `devDependency` for this package's own build and test. From 0.6.0 the
+peer is the range `>=0.5.2 <0.6.0` and the `devDependency` is exact `0.5.2`.
 
 Wave 7 (authz#83, authz#95 decision 2, authz#98) moves `credentials.ts`
 (`mintCredential`, `revokeCredential`, `credentialsFor`) and `bootstrap.ts`
@@ -375,7 +376,7 @@ are: each genuinely needs the secret/keys column it names (an export row's
 0.4.0 also renames the SQL function `migrations/0006_erase_person.sql`
 creates, from `erase_person` to `authz_erase_person`. The old name collided
 with each host's own erasure function of the same name and signature, which
-also scrubs a host's `profiles`; `migrateStore`'s `CREATE OR REPLACE FUNCTION`
+also scrubs a host's `profiles`; the migration's `CREATE OR REPLACE FUNCTION`
 replaced a host's function outright, silently dropping that scrub. 0.3.0
 published an hour before this fix and no persistent database had applied
 0006 yet, so this is a same-file rename, not a new numbered migration.
@@ -392,10 +393,13 @@ have `expires_at`. Chat reads this to act on expiry; see
 https://github.com/wtfalch/authz/issues/42.
 
 Tests run against a real Postgres — PGlite, compiled to wasm and started in the
-test process — so no container, service or network is needed. Most tests build
-the tables from the drizzle definitions. `src/migrate.test.ts` applies the
-shipped SQL instead and fails when the two disagree on a column, a type,
-nullability or an index name.
+test process — so no container, service or network is needed. Every test applies
+the shipped SQL through `@wtfalch/db`'s `runMigrationSources`, and
+`src/migrate.test.ts` fails when that SQL and the drizzle definitions disagree on
+a column, a type, nullability or an index name. Set `TEST_DATABASE_URL` to run the
+same suite on a real Postgres, each test file in its own uniquely named schema,
+dropped afterwards; roles, grants and the nested-transaction savepoint path are
+tested only there.
 
 ## 0.4.0
 
@@ -422,8 +426,8 @@ constraint as-is).
 `StoreBinding`, `PolicyData` and `PolicyRoleTemplate`, and nothing else, for a
 client component that only needs the policy catalogue for permission labels.
 The main entry (`.`) still exports everything it does today — this is
-additive — but it also drags in `migrateStore`, which imports
-`node:fs/promises` and breaks a production client build; `./policy`'s import
+additive — but it also drags in `node:crypto` and `drizzle-orm`, which break
+a production client build; `./policy`'s import
 graph is proved free of any `node:` module, `drizzle-orm` or a database handle
 by `scripts/tests/package-contract.test.mjs`. 0.4.0 also exports the five
 membership row helpers from `src/membership-rows.ts` off the main entry —
@@ -436,11 +440,87 @@ passed, exactly as before.
 
 ## Migrations
 
-The package ships its own SQL in `migrations/`, and `migrateStore(db)` applies
-it. Run it before the app's own migrations, so every table the package owns
-exists before an app migration references it. Each file runs once, in one
-transaction, and is recorded in `authz_store_migrations`. Never edit a shipped
-file; a change is a new numbered one.
+The package ships its own SQL in `migrations/` and applies none of it: the host
+does, with `runMigrationSources` from `@wtfalch/db/migrate` (0.5.2 or later), before its
+own migrations, so every table the package owns exists before a host migration
+references it. The directory comes from the subpath
+`@wtfalch/authz-store/migrations-dir`, which imports only `node:url`, so a
+migration image or a bundler never loads the main entry for it:
+
+```ts
+import { runMigrationSources } from '@wtfalch/db/migrate';
+import { migrationsDir } from '@wtfalch/authz-store/migrations-dir';
+
+const ownerUrl = process.env.DATABASE_URL_OWNER;
+if (!ownerUrl) throw new Error('DATABASE_URL_OWNER is required');
+
+await runMigrationSources({
+  url: ownerUrl,
+  schema: 'myservice',
+  sources: [
+    { name: 'authz-store', dir: migrationsDir },
+    { name: 'app', dir: 'drizzle' },
+  ],
+});
+```
+
+Each file runs once, in one transaction, and is recorded with its checksum in
+`_migrations_sources` in the host's schema. Never edit a shipped file; a change
+is a new numbered one. The SQL names no schema: the host's `schema` decides
+where the tables land. The runtime connection puts that schema on its
+`search_path`, and `ensureRuntimeRole({ schemas: ['myservice'] })` covers it.
+`authz_erase_person` is a `SECURITY DEFINER` function that pins the
+`search_path` of the migration run; the runtime role needs EXECUTE on it, which
+the host grants (see below). Migrate with `@wtfalch/db` 0.5.2 or later: 0.5.0
+and 0.5.1 let a temp table shadow the store's tables inside that function.
+
+### Moving from 0.5
+
+Before, `migrateStore(db)` applied the SQL on the host's one database and
+recorded it in `authz_store_migrations`, and the host ran a grant for
+`authz_erase_person` (or named its runtime role `<database>_rt`):
+
+```ts
+import { migrateStore } from '@wtfalch/authz-store';
+
+await migrateStore(db);
+```
+
+After, with the owner credential, a schema, the store's source first, and the
+grant on `ensureRuntimeRole`:
+
+```ts
+import { runMigrationSources } from '@wtfalch/db/migrate';
+import { ensureRuntimeRole } from '@wtfalch/db/runtime-role';
+import { migrationsDir } from '@wtfalch/authz-store/migrations-dir';
+
+const ownerUrl = process.env.DATABASE_URL_OWNER;
+const runtimeUrl = process.env.DATABASE_URL;
+if (!ownerUrl || !runtimeUrl) throw new Error('DATABASE_URL_OWNER and DATABASE_URL are required');
+
+await runMigrationSources({
+  url: ownerUrl,
+  schema: 'myservice',
+  sources: [
+    { name: 'authz-store', dir: migrationsDir },
+    { name: 'app', dir: 'drizzle' },
+  ],
+});
+await ensureRuntimeRole({
+  ownerUrl,
+  runtimeUrl,
+  schemas: ['myservice'],
+  grants: ['myservice.authz_erase_person(text,text,text)'],
+});
+// Runtime connection: createDatabase({ url, searchPath: ['myservice', 'public'] })
+```
+
+`migrateStore` and its `authz_store_migrations` table are gone; a database that
+used them keeps a stale table that nothing reads and nothing adopts. 0.6.0
+assumes databases are recreated empty. Pass the native Drizzle handle,
+`withDrizzle(...).orm` or `tx.orm`, to every function, with no cast. Install
+`@wtfalch/db` `>=0.5.2 <0.6.0` yourself: it is a peer dependency (the runtime
+code imports `sqlState` from it).
 
 `0001_baseline.sql` is every store table as manage's live schema had it on
 2026-09-22. Three things stay with each app, because each lists something the
@@ -453,7 +533,7 @@ app owns:
 The baseline is for a new database. An existing host must verify its schema
 and migration history before adopting it. Its reconciliation brings the
 schema to the baseline before recording `0001_baseline.sql` in
-`authz_store_migrations`; it must preserve runtime-role privileges and the
+`_migrations_sources`; it must preserve runtime-role privileges and the
 host-specific constraints above. The historical map records OTF's missing
 `authz_roles.updated_by` and `'activation'` assignment source; verify these
 against the host being migrated rather than assuming that snapshot is current.

package/dist/index.d.ts

@@ -4,7 +4,6 @@ export { policyActivationApprovals, policyActivations, policyAssignments, policy
 export { accessTeamMembers, accessTeams, type AppRolePermission, } from './resource-schema.js';
 export { attachProposals, authzEvents, breakGlassSessions, credentials, invitations, memberships, tenants, type AttachProposal, type AuthzEvent, type BreakGlassSession, type Credential, type Invitation, type Membership, type NewAttachProposal, type NewAuthzEvent, type NewBreakGlassSession, type NewCredential, type NewInvitation, type NewMembership, type NewTenant, type Tenant, } from './schema.js';
 export { ownerCoverage, ownerSeatCovered, principalIsReachable, type OwnerCoverage, type OwnerCoverageOptions, type PolicyBinding, } from './owners.js';
-export { migrateStore } from './migrate.js';
 export { guestGrants, policyGrants, type GrantStatus, type GuestGrant } from './grants.js';
 export { permissionOf, type StoreBinding, type HostResourceResolver, type ResourceTarget, } from './binding.js';
 export { isCustomRoleKey } from './role-keys.js';

package/dist/index.js

@@ -4,7 +4,6 @@ export { policyActivationApprovals, policyActivations, policyAssignments, policy
 export { accessTeamMembers, accessTeams, } from './resource-schema.js';
 export { attachProposals, authzEvents, breakGlassSessions, credentials, invitations, memberships, tenants, } from './schema.js';
 export { ownerCoverage, ownerSeatCovered, principalIsReachable, } from './owners.js';
-export { migrateStore } from './migrate.js';
 export { guestGrants, policyGrants } from './grants.js';
 export { permissionOf, } from './binding.js';
 export { isCustomRoleKey } from './role-keys.js';

package/dist/migrations-dir.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Absolute path of the directory holding this package's numbered `.sql`
+ * migrations. The host passes it to `runMigrationSources` as
+ * `{ name: 'authz-store', dir: migrationsDir }`.
+ *
+ * Its own subpath (`@wtfalch/authz-store/migrations-dir`) and no other
+ * imports: a migration image imports this without Drizzle and authz, and a
+ * bundler never meets this file's `import.meta.url` through the main entry.
+ * `migrations/` sits next to `dist/` in the package and next to `src/` in
+ * this repository, so one relative path is right in both.
+ */
+export declare const migrationsDir: string;

package/dist/migrations-dir.js

@@ -0,0 +1,13 @@
+import { fileURLToPath } from 'node:url';
+/**
+ * Absolute path of the directory holding this package's numbered `.sql`
+ * migrations. The host passes it to `runMigrationSources` as
+ * `{ name: 'authz-store', dir: migrationsDir }`.
+ *
+ * Its own subpath (`@wtfalch/authz-store/migrations-dir`) and no other
+ * imports: a migration image imports this without Drizzle and authz, and a
+ * bundler never meets this file's `import.meta.url` through the main entry.
+ * `migrations/` sits next to `dist/` in the package and next to `src/` in
+ * this repository, so one relative path is right in both.
+ */
+export const migrationsDir = fileURLToPath(new URL('../migrations/', import.meta.url));

package/dist/policy-entry.d.ts

@@ -1,7 +1,7 @@
 /**
  * `@wtfalch/authz-store/policy` — a client-safe subpath for `definePolicy` and the types its
- * signature needs. The main entry (`.`) re-exports `migrateStore`, which imports
- * `node:fs/promises`, so a client component that only reads the policy catalogue for permission
+ * signature needs. The main entry (`.`) imports `node:crypto` and
+ * `drizzle-orm`, so a client component that only reads the policy catalogue for permission
  * labels cannot import from `.` without pulling Node into a production browser build
  * (https://github.com/wtfalch/boule/pull/162). Nothing this module imports, directly or
  * transitively, may import a `node:` module, `drizzle-orm`, or a database handle — proved by

package/dist/policy-entry.js

@@ -1,7 +1,7 @@
 /**
  * `@wtfalch/authz-store/policy` — a client-safe subpath for `definePolicy` and the types its
- * signature needs. The main entry (`.`) re-exports `migrateStore`, which imports
- * `node:fs/promises`, so a client component that only reads the policy catalogue for permission
+ * signature needs. The main entry (`.`) imports `node:crypto` and
+ * `drizzle-orm`, so a client component that only reads the policy catalogue for permission
  * labels cannot import from `.` without pulling Node into a production browser build
  * (https://github.com/wtfalch/boule/pull/162). Nothing this module imports, directly or
  * transitively, may import a `node:` module, `drizzle-orm`, or a database handle — proved by

package/dist/tenants.js

@@ -111,7 +111,9 @@ export async function createTenant(principal, db, policy, config, profiles, opti
             return refused('slug_taken', 'That address is already taken.');
         let tenantRow;
         try {
-            [tenantRow] = await tx
+            // A savepoint: a unique violation aborts a Postgres transaction, and the rest of this
+            // function runs in it. Rolling back to the savepoint lets the catch below return normally.
+            [tenantRow] = await tx.transaction((sp) => sp
                 .insert(tenants)
                 .values({
                 kind: 'customer',
@@ -121,7 +123,7 @@ export async function createTenant(principal, db, policy, config, profiles, opti
                 selfDenied: [],
                 createdBy: principal.id,
             })
-                .returning({ id: tenants.id });
+                .returning({ id: tenants.id }));
         }
         catch (error) {
             if (isUniqueViolation(error))
@@ -197,10 +199,11 @@ export async function renameTenant(access, db, scopeColumn, options) {
                 return refused('slug_taken', 'That address is already taken.');
         }
         try {
-            await tx
+            // A savepoint, for the same reason as in `createTenant`.
+            await tx.transaction((sp) => sp
                 .update(tenants)
                 .set({ name: nextName, slug: nextSlug, updatedAt: new Date() })
-                .where(eq(tenants.id, tenantRow.id));
+                .where(eq(tenants.id, tenantRow.id)));
         }
         catch (error) {
             if (isUniqueViolation(error))
@@ -611,7 +614,8 @@ export async function createTenantAsOperator(operatorAccess, db, scopeColumn, po
             }
             let tenantRow;
             try {
-                [tenantRow] = await tx
+                // A savepoint, for the same reason as in `createTenant`.
+                [tenantRow] = await tx.transaction((sp) => sp
                     .insert(tenants)
                     .values({
                     kind: 'customer',
@@ -621,7 +625,7 @@ export async function createTenantAsOperator(operatorAccess, db, scopeColumn, po
                     selfDenied: [],
                     createdBy: currentAccess.actor.id,
                 })
-                    .returning({ id: tenants.id });
+                    .returning({ id: tenants.id }));
             }
             catch (error) {
                 if (isUniqueViolation(error))

package/migrations/0006_erase_person.sql

@@ -12,12 +12,17 @@
 --
 -- 0.4.0 note: this function was originally named `erase_person`, the same
 -- name and signature as each host's own erasure function (the one that also
--- scrubs `profiles`). `migrateStore` replaces a same-named function outright,
+-- scrubs `profiles`). `CREATE OR REPLACE FUNCTION` replaces a same-named function outright,
 -- so applying this migration silently dropped a host's own `profiles` scrub.
 -- Renamed here to `authz_erase_person` before any persistent database ever
 -- applied it: 0.3.0 published an hour before this fix, and no host had run
 -- this migration against a real database yet, so this is a same-file rename,
 -- not a new numbered migration.
+--
+-- 0.6.0 note: edited in place, again before any persistent database applied
+-- it (databases were recreated empty when migrations moved to the host's
+-- runner, in the host's own schema). The function now pins the `search_path`
+-- of the session that creates it, and the runtime-role grant moved to the host.
 
 -- ----------------------------------------------- authz_erase_person(...)
 -- The single sanctioned write to `authz_events` (D9, M3).
@@ -45,15 +50,17 @@
 -- 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.
+-- `search_path` is pinned to the one the host's migration run set, which is
+-- the host's schema first, so the unqualified names below resolve there. 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 "authz_erase_person"("subject" text, "pseudonym" text, "subject_email" text)
 RETURNS integer
 LANGUAGE plpgsql
 SECURITY DEFINER
-SET search_path = pg_catalog, public
+SET search_path FROM CURRENT
 AS $$
 DECLARE
   touched integer;
@@ -126,18 +133,3 @@ $$;
 -- new function to PUBLIC by default.
 REVOKE ALL ON FUNCTION "authz_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 "authz_erase_person"(text, text, text) TO %I', rt);
-  END IF;
-END
-$$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/authz-store",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Persistence and lifecycle for @wtfalch/authz: the storage a host would otherwise write itself.",
   "type": "module",
   "files": [
@@ -17,11 +17,15 @@
       "types": "./dist/policy-entry.d.ts",
       "default": "./dist/policy-entry.js"
     },
+    "./migrations-dir": {
+      "types": "./dist/migrations-dir.d.ts",
+      "default": "./dist/migrations-dir.js"
+    },
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "@wtfalch/authz": "^0.17.0",
-    "@wtfalch/db": "0.4.0",
+    "@wtfalch/db": ">=0.5.2 <0.6.0",
     "drizzle-orm": ">=0.39.3 <1.0.0",
     "zod": "^4.1.13"
   },
@@ -35,12 +39,10 @@
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
-    "@wtfalch/db": "0.4.0",
+    "@wtfalch/db": "0.5.2",
     "@wtfalch/keys": "0.4.2",
-    "drizzle-kit": "^0.31.10",
-    "drizzle-orm": "^0.39.0",
+    "drizzle-orm": "0.39.3",
     "fast-check": "^4.9.0",
-    "postgres": "^3.4.5",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6",
     "zod": "^4.5.4"

package/dist/migrate.d.ts

@@ -1,9 +0,0 @@
-import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
-type HostDb = PgDatabase<PgQueryResultHKT, any, any>;
-/**
- * Applies the package's migrations that `authz_store_migrations` has no row for, in file-name
- * order, one transaction per file. Returns the names it applied. The host runs this before its own
- * migrations, so everything the package owns exists before a host migration references it.
- */
-export declare function migrateStore(db: HostDb): Promise<string[]>;
-export {};

package/dist/migrate.js

@@ -1,52 +0,0 @@
-import { readFile, readdir } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { sql } from 'drizzle-orm';
-/**
- * The shipped SQL, next to `dist/` in the package and next to `src/` in this repository. Computed
- * lazily inside `migrateStore` rather than as a module-level `new URL('../migrations/',
- * import.meta.url)`: Turbopack resolves that literal statically when an app imports the package
- * barrel, and fails with "Can't resolve '../migrations/'" because the directory holds no importable
- * module.
- */
-function migrationsDir() {
-    return join(dirname(fileURLToPath(import.meta.url)), '..', 'migrations');
-}
-/** Files split on this line, the marker drizzle-kit writes, so any driver can run them one statement at a time. */
-const BREAKPOINT = '--> statement-breakpoint';
-/** One key for every host, so two containers starting at once apply each file once between them. */
-const LOCK = 7_310_422_001;
-/**
- * Applies the package's migrations that `authz_store_migrations` has no row for, in file-name
- * order, one transaction per file. Returns the names it applied. The host runs this before its own
- * migrations, so everything the package owns exists before a host migration references it.
- */
-export async function migrateStore(db) {
-    const dir = migrationsDir();
-    const names = (await readdir(dir)).filter((n) => n.endsWith('.sql')).sort();
-    const applied = [];
-    for (const name of names) {
-        const text = await readFile(join(dir, name), 'utf8');
-        const ran = await db.transaction(async (tx) => {
-            await tx.execute(sql `select pg_advisory_xact_lock(${LOCK})`);
-            // Created under the lock: two runners creating it at once collide in pg_type.
-            await tx.execute(sql `create table if not exists authz_store_migrations (name text primary key, applied_at timestamptz not null default now())`);
-            const done = await tx.execute(sql `select 1 from authz_store_migrations where name = ${name}`);
-            if (rowsOf(done).length > 0)
-                return false;
-            for (const statement of text.split(BREAKPOINT)) {
-                if (statement.trim())
-                    await tx.execute(sql.raw(statement));
-            }
-            await tx.execute(sql `insert into authz_store_migrations (name) values (${name})`);
-            return true;
-        });
-        if (ran)
-            applied.push(name);
-    }
-    return applied;
-}
-/** postgres-js returns the rows as the result; node-postgres and PGlite wrap them in `rows`. */
-function rowsOf(result) {
-    return Array.isArray(result) ? result : (result.rows ?? []);
-}