@govcore/schema 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @govcore/schema
+
+## 0.1.0
+
+### Minor Changes
+
+- f2f3743: Add `@govcore/schema`: the platform schema (identity, tenancy, auth, audit) in a
+  dedicated `govcore` Postgres schema, with the `orgScoped` tenancy-column helper
+  and `CORE_SCHEMA_VERSION`. Roles are `text` (app-defined via `@govcore/rbac`),
+  not a fixed enum.
+
+  Also adds federation (`org_connections`, `cross_org_links`), support access
+  (`break_glass_sessions`, `act_as_sessions`), and instance config
+  (`instance_settings`, `platform_config`).
+
+  Ships authored migrations (`0000_platform_init`, `0001_platform_security` —
+  append-only audit trigger + Row-Level Security with `FORCE ROW LEVEL SECURITY`;
+  `0002_platform_federation_support` — federation tables with a both-participant
+  RLS check) and the `govcore-migrate` runner (separate, non-edge `./migrate`
+  entrypoint; tracked in `govcore.__govcore_migrations`; runs as the owner/DDL role).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Allred
+
+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

@@ -0,0 +1,60 @@
+# @govcore/schema
+
+Platform table definitions, enums, the authored migrations, and the
+`govcore-migrate` runner. All platform tables live in the `govcore` Postgres
+schema. See the design doc §5 and §13.1–§13.2.
+
+## Two entrypoints
+
+- **`@govcore/schema`** — table definitions + `orgScoped` + `CORE_SCHEMA_VERSION`.
+  Edge-safe (only `drizzle-orm/pg-core`); importable into Next middleware.
+- **`@govcore/schema/migrate`** — the migration runner (`postgres` + `node:fs`).
+  **Not** edge-safe; server-only.
+
+## Migrations
+
+Authored SQL in [`migrations/`](./migrations), applied in lexical order by
+`govcore-migrate`, each in its own transaction, tracked in
+`govcore.__govcore_migrations` (separate from an app's own Drizzle journal).
+
+| File | Contents |
+|---|---|
+| `0000_platform_init.sql` | identity/tenancy/auth/audit tables, FKs, indexes |
+| `0001_platform_security.sql` | append-only `audit_log` trigger; RLS + `FORCE ROW LEVEL SECURITY` on `users` / memberships / `audit_log` |
+| `0002_platform_federation_support.sql` | federation (`org_connections`, `cross_org_links`), support (`break_glass_sessions`, `act_as_sessions`), instance config (`instance_settings`, `platform_config`); federation RLS (both-participant check). Support/instance tables are app-authorized, not under org-GUC RLS |
+
+> Core **owns** this DDL (design §5). It must stay in sync with
+> [`src/schema.ts`](./src/schema.ts). A schema-conformance test is a follow-up.
+
+## Two-role database (design §13.2)
+
+- **`govcore-migrate`** runs as the **owner / DDL** role:
+  set `GOVCORE_MIGRATE_DATABASE_URL` (falls back to `DATABASE_URL`).
+- The **app runtime** connects as a separate **non-owner** role, which RLS binds.
+
+## Tenant isolation (design §13.1)
+
+RLS policies key off `current_setting('app.current_org')`. The runtime sets it
+**transaction-locally** per request — `select set_config('app.current_org', $org, true)`
+— inside the tenant transaction (the `@govcore/server` `tenantAction`, later phase).
+Unset GUC ⇒ all rows hidden (deny by default).
+
+## Roles are `text`, not an enum
+
+Per-org and per-user `role` columns are `text`, not a fixed `pgEnum` — GovCore
+ships no role vocabulary. The app defines valid roles via `@govcore/rbac`'s
+`createRbac`.
+
+## Usage
+
+```ts
+// app schema: re-export core tables, add domain tables scoped to the tenant
+export * from '@govcore/schema'
+import { organizations, orgScoped } from '@govcore/schema'
+export const permits = pgTable('permits', { ...orgScoped(organizations), title: text('title') })
+```
+
+```jsonc
+// app package.json — platform migrations run before the app's own
+"db:migrate": "govcore-migrate && drizzle-kit migrate"
+```

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+export * from './schema';
+/**
+ * A Drizzle Postgres database **or** transaction handle. Functions in the
+ * tenancy/audit packages accept this so callers inject their own client (the
+ * app's `postgres-js` db, or a `tx` inside a transaction — which extends it).
+ */
+export type GovcoreDb = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * Bumped whenever the platform schema changes. Written to instance settings on
+ * boot for observability ("this instance runs platform schema vN", design §5),
+ * and stamped into backup archives (design §13.5). Not load-bearing for
+ * correctness — the migrations are — but useful for diagnostics.
+ */
+export declare const CORE_SCHEMA_VERSION = "0.0.0";
+//# 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":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AAEvE,cAAc,UAAU,CAAA;AAExB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,gBAAgB,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// @govcore/schema — platform table definitions + schema version.
+// Edge-safe entrypoint (no DB client). The migrate runner is ./migrate.
+export * from './schema';
+/**
+ * Bumped whenever the platform schema changes. Written to instance settings on
+ * boot for observability ("this instance runs platform schema vN", design §5),
+ * and stamped into backup archives (design §13.5). Not load-bearing for
+ * correctness — the migrations are — but useful for diagnostics.
+ */
+export const CORE_SCHEMA_VERSION = '0.0.0';

package/dist/migrate.d.ts

@@ -0,0 +1,11 @@
+export interface MigrateOptions {
+    /** Connection string for the owner/DDL role. Defaults to env. */
+    connectionString?: string;
+    /** Optional logger; defaults to console.log. */
+    log?: (message: string) => void;
+}
+/** Apply all pending platform migrations. Idempotent — already-applied files are skipped. */
+export declare function migrate(options?: MigrateOptions): Promise<{
+    applied: string[];
+}>;
+//# sourceMappingURL=migrate.d.ts.map

package/dist/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../src/migrate.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,gDAAgD;IAChD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC;AAED,6FAA6F;AAC7F,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAiD1F"}

package/dist/migrate.js

@@ -0,0 +1,64 @@
+// @govcore/schema/migrate — the govcore-migrate runner.
+//
+// NOT edge-safe (uses node:fs + a postgres client). Applies the authored
+// platform migrations in ../migrations in lexical order, each in its own
+// transaction, tracked in `govcore.__govcore_migrations` — kept separate from
+// the app's own Drizzle journal so the two migration streams never overlap
+// (design §5).
+//
+// Runs as the OWNER / DDL role (design §13.2): set GOVCORE_MIGRATE_DATABASE_URL
+// to the owning role's connection string; falls back to DATABASE_URL. The app
+// runtime connects as a separate NON-OWNER role, which RLS binds.
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import postgres from 'postgres';
+const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'migrations');
+/** Apply all pending platform migrations. Idempotent — already-applied files are skipped. */
+export async function migrate(options = {}) {
+    const connectionString = options.connectionString ??
+        process.env.GOVCORE_MIGRATE_DATABASE_URL ??
+        process.env.DATABASE_URL;
+    if (!connectionString) {
+        throw new Error('govcore-migrate: set GOVCORE_MIGRATE_DATABASE_URL (owner role) or DATABASE_URL');
+    }
+    const log = options.log ?? ((m) => console.log(m));
+    const sql = postgres(connectionString, { max: 1 });
+    const applied = [];
+    try {
+        await sql.unsafe('CREATE SCHEMA IF NOT EXISTS govcore');
+        await sql.unsafe(`CREATE TABLE IF NOT EXISTS govcore.__govcore_migrations (
+         name text PRIMARY KEY,
+         applied_at timestamptz NOT NULL DEFAULT now()
+       )`);
+        const done = new Set((await sql `SELECT name FROM govcore.__govcore_migrations`).map((r) => r.name));
+        const files = readdirSync(MIGRATIONS_DIR)
+            .filter((f) => f.endsWith('.sql'))
+            .sort();
+        for (const file of files) {
+            if (done.has(file))
+                continue;
+            const ddl = readFileSync(join(MIGRATIONS_DIR, file), 'utf8');
+            await sql.begin(async (tx) => {
+                await tx.unsafe(ddl);
+                await tx `INSERT INTO govcore.__govcore_migrations (name) VALUES (${file})`;
+            });
+            applied.push(file);
+            log(`govcore-migrate: applied ${file}`);
+        }
+        log(applied.length
+            ? `govcore-migrate: applied ${applied.length} migration(s)`
+            : 'govcore-migrate: already up to date');
+        return { applied };
+    }
+    finally {
+        await sql.end();
+    }
+}
+// Run when invoked as the `govcore-migrate` bin.
+if (process.argv[1] && import.meta.url === `file://${process.argv[1]}`) {
+    migrate().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}