From c7013be2f00e64bc6f47f54501391eded37fd7f5 Mon Sep 17 00:00:00 2001 From: lilleman Date: Tue, 18 Aug 2026 23:12:13 +0200 Subject: [PATCH] Give a plugin a Postgres database of its own --- AGENTS.md | 24 +++- README-dockerhub.md | 3 +- README.md | 106 +++++++++++++--- compose.override.yml | 6 + compose.yml | 22 +++- examples/plugins/scheduling/shifts.test.ts | 2 +- ory/postgres/init/init.sql | 3 +- package-lock.json | 16 ++- package.json | 3 +- src/auth/bootstrap.ts | 17 ++- src/compose.test.ts | 19 ++- src/config.test.ts | 12 +- src/config.ts | 17 +++ src/plugin-host/discovery.test.ts | 13 +- src/plugin-host/discovery.ts | 10 ++ src/plugin-host/hooks.test.ts | 7 +- src/plugin-host/hooks.ts | 12 +- src/plugin-host/plugin-api.ts | 5 +- src/plugin-host/plugin.ts | 11 +- src/plugin-host/storage.test.ts | 137 +++++++++++++++++++++ src/plugin-host/storage.ts | 104 ++++++++++++++++ src/postgres.test.ts | 5 +- src/server.ts | 14 ++- todo.md | 4 + 24 files changed, 524 insertions(+), 48 deletions(-) create mode 100644 src/plugin-host/storage.test.ts create mode 100644 src/plugin-host/storage.ts diff --git a/AGENTS.md b/AGENTS.md index 7ed9948..c3a6b14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,11 +36,13 @@ branch, create a PR and merge it when the CI/CD turns green. ## Project priorities (do not erode) 1. **Simplicity** — prefer the solution that is easiest to understand, smallest, and most readable. -2. **Few dependencies** — runtime deps stay minimal (today `ejs`, `lucide-static`, `@larvit/log`). - Prefer the Node standard library; justify any new dependency; do not add frameworks. The app is - **stateless — no database**. Auth/identity/OAuth are **Ory sidecar services** reached over their - REST APIs with built-in `fetch` — no SDK. New capabilities ship as **plugin folders** under - `plugins/` that fetch their data from upstream services, not as core code. +2. **Few dependencies** — runtime deps stay minimal (today `ejs`, `lucide-static`, `@larvit/log`, + `postgres`). Prefer the Node standard library; justify any new dependency; do not add frameworks. + The **host is stateless — it owns no schema and stores nothing of its own**; a plugin may own a + Postgres database, which the host provisions and never reads or writes. Auth/identity/OAuth are + **Ory sidecar services** reached over their REST APIs with built-in `fetch` — no SDK. New + capabilities ship as **plugin folders** under `plugins/` that get their data from an upstream + service or their own database, not as core code. 3. **Strict TypeScript** — `tsconfig.json` is strict (incl. `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `verbatimModuleSyntax`). Keep it that way. Prefer exact types; limit nullable and multi-option types. @@ -79,7 +81,17 @@ Revisit only if the stated reason stops holding. it into `/node_modules`, above every plugin scope. Never let a copy reach a plugin's own `node_modules`: two instances of the barrel break `instanceof` across the boundary, which `plugin-api.test.ts` guards by asserting both paths reach one module. - - **`config/` is still a plain dir — no `package.json` of its own**, or `#menu-config` resolves + - **Plugin storage hands over credentials, not a client** (README → Plugin storage). The host takes + `postgres` to run the provisioning DDL in `bootstrap` and nothing else: it is never re-exported + through the barrel, so no driver shape enters the contract and a plugin depends on whichever client + it likes. Three properties hold the design together, so don't trade one away in isolation: + passwords are `HMAC-SHA256(PLUGIN_DB_SECRET, id)` rather than stored, which is what keeps the host + stateless; the superuser DSN reaches `bootstrap` only, because plugin code runs inside `web` and + can read that process' environment (`src/compose.test.ts` guards the split); and provisioning + never drops anything, so uninstalling a plugin cannot destroy data. Because the host's copy sits in + the ambient `/node_modules`, a plugin can `import "postgres"` without declaring it — that is + incidental, not a packaging promise, and a plugin must still depend on its own driver. +- **`config/` is still a plain dir — no `package.json` of its own**, or `#menu-config` resolves against that instead and boot fails loud. An operator's menu override has no use for dependencies; if that changes, it needs the same package treatment. - **A plugin `package.json` without `"type": "module"` is refused, not warned.** Allowing it costs a diff --git a/README-dockerhub.md b/README-dockerhub.md index 3daac1a..cad8ec2 100644 --- a/README-dockerhub.md +++ b/README-dockerhub.md @@ -2,7 +2,8 @@ A self-hostable foundation for server-rendered web apps — public or gated pages from a zero-JS design system, with a config-driven menu and auth/permissions (Ory) baked in. -Every domain feature is a drop-in plugin folder; the app is stateless, no build step. +Every domain feature is a drop-in plugin folder, with a Postgres database of its own if it wants +one; the host itself is stateless, and there is no build step. **Source, docs & issues: ** ([GitHub mirror](https://github.com/larvit/plainpages)) diff --git a/README.md b/README.md index 076486f..5dc4708 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,7 @@ From here, render real pages against the app shell and fetch upstream data — s - [hooks](#hooks) - [where they live & mounting](#where-plugins-live-and-how-to-mount-them) - [dependencies](#plugin-dependencies) + - [storage](#plugin-storage) - [local dev & test](#local-dev--test-story) - [The menu system](#the-menu-system) - [Building blocks](#building-blocks) @@ -106,7 +107,7 @@ From here, render real pages against the app shell and fetch upstream data — s - [security model](#security-model) - [Email](#email) - [Architecture](#architecture) - - [Stateless](#stateless) + - [Stateless core](#stateless-core) - [Testing](#testing) - [end-to-end](#end-to-end-playwright) - [the full gate](#the-full-gate-one-command) @@ -380,6 +381,7 @@ folder-derived `id` to produce the loaded `Plugin`. | `permissions` | no | Permissions this plugin gates on. See [Nav & permission gates](#nav--permission-gates). | | `routes` | no | See [Routes & handlers](#routes--handlers). | | `hooks` | no | See [Hooks](#hooks). | +| `storage` | no | `true` ⇒ the host provisions a Postgres database and login role for this plugin and hands the credentials to `onBoot`. See [Plugin storage](#plugin-storage). | A plugin may be routes-only, nav-only, or hooks-only — every collection field is optional. @@ -432,8 +434,8 @@ export async function listThings(ctx: RequestContext) { `requireSession(ctx)`, `can(ctx, permission)` (coarse JWT-claim check, zero I/O), and `check(keto, ctx, {namespace, object, relation})` (a live Keto check; anonymous ⇒ denied). Throw `new GuardError(403, …)` after a failed `can`/`check` to render the 403 page. -- The handler **fetches its own data** from upstream; plugins hold no state (see - [Stateless](#stateless)). +- The handler **fetches its own data** — from upstream, or from the plugin's own + [storage](#plugin-storage); the host holds none of it (see [Stateless core](#stateless-core)). - Default status: `200` for `view`/`html`/`json`, `303` for `redirect`. #### Escaping & the trust boundary @@ -632,10 +634,13 @@ Optional, for reacting to system actions. A plugin's `hooks` may implement: | Hook | When | May | | --- | --- | --- | -| `onBoot()` | after discovery, before the server listens | warm caches, validate upstream config | +| `onBoot(host)` | after discovery, before the server listens | warm caches, validate upstream config, open a [storage](#plugin-storage) connection | | `onRequest(ctx)` | before route matching | inspect, or **short-circuit** by returning a `RouteResult` | | `onResponse(ctx, result)` | after the handler | observe/log; cannot change the response | +`onBoot`'s `host` is a `BootContext`, carrying `storage` for a plugin that declared it. A hook +written without a parameter stays valid. + Hooks run in **discovery order** (plugins sorted by id). `onRequest` fires on every request that reaches routing (static assets bypass it); the **first** hook to return a `RouteResult` short-circuits — later hooks and the route handler are skipped, and that result renders against its own plugin's @@ -653,7 +658,7 @@ getting its folder there. bind-mounts the whole tree (`compose.override.yml`: `.:/app`), so a restart picks it up. **2. A plugin kept in its own repo, or added to a prebuilt image.** Bind-mount the plugin -folder onto `/app/plugins/` with a small compose override. Plugins are stateless, so +folder onto `/app/plugins/` with a small compose override. A plugin folder is code, not data — mount it read-only: ```yaml @@ -724,6 +729,67 @@ barrel's types on disk: typecheck it mounted under the host tree, or vendor a ty `node_modules`** and point tsconfig `paths` at it — a stub inside is the shadowing copy discovery refuses, and it would travel with the folder you mount. +### Plugin storage + +A plugin that needs to keep data sets `storage: true`. The host then provisions a Postgres +**database and login role of its own** — both named `plugin_` — and hands the credentials to +`onBoot`: + +```ts +import postgres from "postgres"; // your dependency, not the host's +import { definePlugin, type StorageCredentials } from "@plainpages/plugin-api"; + +let sql: ReturnType; + +export default definePlugin({ + apiVersion: "1.0.0", + storage: true, + hooks: { + onBoot: async (host) => { + if (!host.storage) throw new Error("things: storage was not provisioned"); + sql = postgres(host.storage.url); + await sql`CREATE TABLE IF NOT EXISTS things (id uuid PRIMARY KEY, name text NOT NULL)`; + }, + }, +}); +``` + +`host.storage` is a `StorageCredentials` — `database`, `host`, `password`, `port`, `user`, and `url`, +the same values pre-assembled as a DSN, which most clients take directly. + +**Credentials, not a client.** The host has no opinion on how you reach Postgres: depend on +`postgres`, `pg`, a query builder or an ORM ([Plugin dependencies](#plugin-dependencies)). No driver +is part of the contract, so upgrading yours is yours alone to time. + +**The schema is yours.** The host creates the database empty and never reads or writes inside it. +Create your tables in `onBoot`: it runs before the server listens, so a failure aborts boot instead +of surfacing later as a broken page. + +What the host does guarantee: + +- **One database and one role per plugin.** `CONNECT` is revoked from `PUBLIC`, so another installed + plugin's role cannot reach your database. +- **Provisioning is idempotent and runs every boot**, so a plugin dropped in later is picked up by + the next `docker compose up -d` — the same rule as permission seeding. +- **Your data is never dropped.** Removing a plugin folder leaves its database untouched; deleting it + is a deliberate act by an operator. + +**Passwords are derived, never stored** — each is `HMAC-SHA256(PLUGIN_DB_SECRET, )`, so +`bootstrap` and `web` compute the same value independently and nothing has to be written down. +Rotate every plugin's password by changing `PLUGIN_DB_SECRET` and running `docker compose up -d`, +which re-applies each role's password and leaves the data alone. + +**Only `bootstrap` holds superuser credentials.** It alone gets `PLUGIN_DB_ADMIN_URL`, the DSN that +may `CREATE DATABASE`/`CREATE ROLE`. `web` gets `PLUGIN_DB_URL`, which names the server and carries +no credentials — so plugin code, which runs inside `web`, cannot read a superuser password out of its +own environment. Set both, plus `PLUGIN_DB_SECRET` ([Configuration](#configuration)); the dev stack +sets them for you. + +Storage stays off until `PLUGIN_DB_URL` is set, and a plugin declaring it while that is unset +**aborts boot** naming itself — rather than serving pages without its data. One naming limit: a +storage plugin's folder may be at most **56 characters**, so `plugin_` fits Postgres' 63-byte +identifier. + ### Local dev & test story A plugin is a normal folder of TypeScript, tested the same way the core is — everything in Docker. @@ -936,7 +1002,7 @@ The app is **environment-agnostic**: no `NODE_ENV`, every behaviour its own expl | `PORT` | `3000` | web listen port | | `CACHE_TEMPLATES` | `false` | cache compiled EJS templates (`true` in prod) | | `SECURE_COOKIES` | `false` | mark our session/CSRF cookies `Secure` (`true` in prod https; off in dev http) | -| `REQUIRE_SECURE_SECRETS` | `false` | when `true`, `CSRF_SECRET` must be supplied and differ from the dev throwaway | +| `REQUIRE_SECURE_SECRETS` | `false` | when `true`, `CSRF_SECRET` — and `PLUGIN_DB_SECRET` once storage is configured — must be supplied and differ from the dev throwaway | | `LOG_LEVEL` | `info` | min severity logged: `error`/`warn`/`info`/`verbose`/`debug`/`silly`/`none` | | `LOG_FORMAT` | `text` | log line format: `text` (human-readable, dev) or `json` (structured, prod) | | `SERVICE_NAME` | `plainpages` | OTLP `service.name` on every log + span — brand it as your own deployment | @@ -952,6 +1018,9 @@ The app is **environment-agnostic**: no `NODE_ENV`, every behaviour its own expl | `REVOCATION_DENYLIST` | `false` | when `true`, enable the optional [instant permission/session revoke denylist](#instant-revoke-the-optional-denylist) | | `REVOCATION_TTL_SEC` | `900` | how long a revoke entry lives; keep ≥ tokenizer TTL (10m) + clock skew | | `CSRF_SECRET` | dev throwaway | signs our double-submit CSRF token; enforced by `REQUIRE_SECURE_SECRETS` | +| `PLUGIN_DB_URL` | _unset_ (dev: `postgres://postgres:5432`) | credential-free Postgres base URL for [plugin storage](#plugin-storage); unset ⇒ storage off, and a plugin declaring it aborts boot | +| `PLUGIN_DB_ADMIN_URL` | _unset_ (dev: the bundled superuser) | the DSN that provisions each plugin's database and role — read by the one-shot `bootstrap` service **only**, never by `web` | +| `PLUGIN_DB_SECRET` | dev throwaway | derives each plugin's database password; enforced by `REQUIRE_SECURE_SECRETS` once `PLUGIN_DB_URL` is set | ### Canonical host (one public URL) @@ -1082,8 +1151,8 @@ records that subject as revoked-now; the hot path then rejects every token for i the revoke and forces a re-mint — which re-reads permissions from Keto, or clears a dead session. A fresh re-login passes, so a downgrade lands immediately without locking the account. -It is an in-memory, auto-evicting map — no database, so it stays inside the stateless model — and -the check is pure CPU, keeping Keto off the hot path. Entries self-evict after `REVOCATION_TTL_SEC` +It is an in-memory, auto-evicting map — host-owned state would break the [stateless +core](#stateless-core) — and the check is pure CPU, keeping Keto off the hot path. Entries self-evict after `REVOCATION_TTL_SEC` (default 900s ≥ the 10m token TTL + skew). Two bounds: it is instant only on the **single instance** that handled the revoke (elsewhere the guarantee falls back to the token TTL — back it with a shared store for hard multi-instance revoke), and a **group** membership change is transitive across many @@ -1198,18 +1267,21 @@ of it over their **REST APIs using Node's built-in `fetch`** — no SDK dependen In **dev** the host-facing Ory ports are published — Kratos public `4433` and Hydra public `4444`; prod keeps them internal. -Runtime deps stay tiny and pinned: **`ejs`**, **`lucide-static`**, and **`@larvit/log`**. Auth, -sessions, SSO and OAuth2 add *services*, not npm packages. +Runtime deps stay tiny and pinned: **`ejs`**, **`lucide-static`**, **`@larvit/log`**, and +**`postgres`** — the last one has no sub-dependencies of its own and is used in a single module, to +provision [plugin storage](#plugin-storage) at boot. Auth, sessions, SSO and OAuth2 add *services*, +not npm packages. -### Stateless +### Stateless core -Plainpages holds **no state of its own**. The only database in the stack is **Postgres**, used by -Ory; the `web` app never connects to it. +The host holds **no state of its own**: it owns no schema and keeps nothing between requests. The +stack's **Postgres** backs Ory, and gives every plugin that asks for one a database of its own +([Plugin storage](#plugin-storage)) — which the host provisions but never reads or writes. -A plugin reads and writes state by **calling an upstream service** from its route handler — a REST -API, an ERP, a plant historian, the customer's own backend — and renders the response with the -building blocks. That keeps `web` trivially scalable and crash-safe: any instance can serve any -request, because the session lives in Kratos and the data lives upstream. +So a plugin gets its data one of two ways: by **calling an upstream service** from its route handler +— a REST API, an ERP, a plant historian, the customer's own backend — or from **its own database**. +Either keeps `web` trivially scalable and crash-safe: any instance can serve any request, because the +session lives in Kratos and the data lives outside the process. ## Testing diff --git a/compose.override.yml b/compose.override.yml index f4d0176..e70a741 100644 --- a/compose.override.yml +++ b/compose.override.yml @@ -13,6 +13,9 @@ services: CACHE_TEMPLATES: "false" LOG_FORMAT: "text" # human-readable logs in dev (base sets json for prod log pipelines) LOG_LEVEL: "debug" # verbose by default while developing (base defaults to info) + # Point plugin storage at the bundled Postgres, so a dropped-in plugin declaring `storage` + # works with no further config; the secret falls back to the dev throwaway (config.ts). + PLUGIN_DB_URL: postgres://postgres:5432 REQUIRE_SECURE_SECRETS: "false" SECURE_COOKIES: "false" # dev serves http — Secure cookies wouldn't be sent SCHEDULING_UPSTREAM: "http://shifts-upstream:4000" # backs the reference plugin once you copy it into plugins/ @@ -29,6 +32,9 @@ services: # It belongs here and not in the base file, where it would desynchronise prod and collide with the # e2e stacks, which bind individual plugins *inside* /app/plugins. bootstrap: + # Provisions the plugin databases web connects to above, as the dev superuser. + environment: + PLUGIN_DB_ADMIN_URL: postgres://${POSTGRES_USER:-ory}:${POSTGRES_PASSWORD:-ory}@postgres:5432/ory volumes: - .:/app diff --git a/compose.yml b/compose.yml index 959745f..ce48b74 100644 --- a/compose.yml +++ b/compose.yml @@ -17,10 +17,16 @@ services: CACHE_TEMPLATES: "true" CSRF_SECRET: ${CSRF_SECRET:-dev-insecure-csrf-secret} LOG_FORMAT: "json" # structured logs for prod pipelines; set OTLP_ENDPOINT to also export to a collector + # Per-plugin Postgres storage. Explicit toggle: unset ⇒ off, and a plugin declaring `storage` + # refuses to boot rather than run without its data. The URL carries no credentials — each + # plugin's own password is derived from the secret (README → Plugin storage). + PLUGIN_DB_SECRET: ${PLUGIN_DB_SECRET:-} + PLUGIN_DB_URL: ${PLUGIN_DB_URL:-} REQUIRE_SECURE_SECRETS: "true" SECURE_COOKIES: "true" # prod serves https — mark session/CSRF cookies Secure # Wait for the services the app talks to (kratos + keto + hydra for the OAuth2 login/ - # consent handler) + the one-shot bootstrap (admin + JWKS seed). + # consent handler) + the one-shot bootstrap (admin + JWKS seed). Postgres too: a plugin that + # declares `storage` opens its connection in onBoot, before the server listens. depends_on: bootstrap: condition: service_completed_successfully @@ -30,14 +36,17 @@ services: condition: service_healthy hydra: condition: service_healthy + postgres: + condition: service_healthy # verifier reads the same tokenizer JWKS Kratos signs with (config.ts JWKS_URL). # Read-only — bootstrap is the only writer. volumes: - ./ory/kratos/tokenizer:/etc/config/kratos/tokenizer:ro restart: unless-stopped - # Ory's storage only (Kratos/Keto/Hydra) — the web app never connects here. - # init/init.sql creates one database per service. Dev defaults below; supply + # The stack's storage: one database per Ory service (init/init.sql), plus one per plugin that + # declares `storage` — bootstrap creates those at boot, since only it holds superuser credentials. + # A plugin connects as its own role from inside web. Dev defaults below; supply # POSTGRES_USER/PASSWORD via env in production. postgres: image: postgres:18.6-alpine3.23 @@ -127,6 +136,8 @@ services: condition: service_healthy keto: condition: service_healthy + postgres: + condition: service_healthy environment: ADMIN_EMAIL: ${ADMIN_EMAIL:-admin@plainpages.local} ADMIN_PASSWORD: ${ADMIN_PASSWORD:-admin} @@ -137,6 +148,11 @@ services: JWKS_FILE: /etc/config/kratos/tokenizer/jwks.json KETO_WRITE_URL: http://keto:4467 KRATOS_ADMIN_URL: http://kratos:4434 + # The superuser DSN that creates each plugin's database and role lives ONLY here — never in + # web, so plugin code cannot read it out of its own environment. Unset ⇒ a plugin declaring + # `storage` fails the seed loudly. The secret must match web's; both derive the same passwords. + PLUGIN_DB_ADMIN_URL: ${PLUGIN_DB_ADMIN_URL:-} + PLUGIN_DB_SECRET: ${PLUGIN_DB_SECRET:-} volumes: - ./ory/kratos/tokenizer:/etc/config/kratos/tokenizer command: node src/auth/bootstrap.ts diff --git a/examples/plugins/scheduling/shifts.test.ts b/examples/plugins/scheduling/shifts.test.ts index 50441fc..e641b66 100644 --- a/examples/plugins/scheduling/shifts.test.ts +++ b/examples/plugins/scheduling/shifts.test.ts @@ -51,7 +51,7 @@ test("the manifest's onBoot hook validates SCHEDULING_UPSTREAM (the binding, not try { const manifest = (await import("./plugin.ts")).default; assert.equal(typeof manifest.hooks?.onBoot, "function"); - assert.throws(() => manifest.hooks!.onBoot!(), /SCHEDULING_UPSTREAM/); // bad upstream → boot fails loud + assert.throws(() => manifest.hooks!.onBoot!({}), /SCHEDULING_UPSTREAM/); // bad upstream → boot fails loud } finally { if (prev === undefined) delete process.env["SCHEDULING_UPSTREAM"]; else process.env["SCHEDULING_UPSTREAM"] = prev; diff --git a/ory/postgres/init/init.sql b/ory/postgres/init/init.sql index e058258..83cd64b 100644 --- a/ory/postgres/init/init.sql +++ b/ory/postgres/init/init.sql @@ -1,6 +1,7 @@ -- Runs once on first boot (docker-entrypoint-initdb.d), as the POSTGRES_USER. -- One database per Ory service: each owns its schema and runs its own migrations, --- so they never collide. The web app never connects here (stateless — see README). +-- so they never collide. A plugin's database does not belong here: bootstrap provisions those on +-- every boot, so one dropped in later is picked up too (README → Plugin storage). CREATE DATABASE kratos; CREATE DATABASE keto; CREATE DATABASE hydra; diff --git a/package-lock.json b/package-lock.json index c7a90d5..5ac0dd4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,7 +10,8 @@ "dependencies": { "@larvit/log": "2.3.0", "ejs": "6.0.1", - "lucide-static": "1.31.0" + "lucide-static": "1.31.0", + "postgres": "3.4.9" }, "devDependencies": { "@types/ejs": "3.1.5", @@ -405,6 +406,19 @@ "integrity": "sha512-XFX9NO+gcLsOkXISmeQZYGJa2siGWZc/lgT/BK1b83h9RdOiz3cj1eQP5nWhELiB1KhW5ryk0nmMopOgm/CuSA==", "license": "ISC" }, + "node_modules/postgres": { + "version": "3.4.9", + "resolved": "https://registry.npmjs.org/postgres/-/postgres-3.4.9.tgz", + "integrity": "sha512-GD3qdB0x1z9xgFI6cdRD6xu2Sp2WCOEoe3mtnyB5Ee0XrrL5Pe+e4CCnJrRMnL1zYtRDZmQQVbvOttLnKDLnaw==", + "license": "Unlicense", + "engines": { + "node": ">=12" + }, + "funding": { + "type": "individual", + "url": "https://github.com/sponsors/porsager" + } + }, "node_modules/typescript": { "version": "7.0.2", "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz", diff --git a/package.json b/package.json index 9e046d1..b730149 100644 --- a/package.json +++ b/package.json @@ -19,7 +19,8 @@ "dependencies": { "@larvit/log": "2.3.0", "ejs": "6.0.1", - "lucide-static": "1.31.0" + "lucide-static": "1.31.0", + "postgres": "3.4.9" }, "devDependencies": { "@types/ejs": "3.1.5", diff --git a/src/auth/bootstrap.ts b/src/auth/bootstrap.ts index c7088bd..b65389d 100644 --- a/src/auth/bootstrap.ts +++ b/src/auth/bootstrap.ts @@ -8,8 +8,10 @@ // Then prints a first-run banner; fails loud on any unexpected upstream error. import { existsSync, writeFileSync } from "node:fs"; import { fileURLToPath } from "node:url"; +import { resolvePluginDbSecret } from "../config.ts"; import { discoverPlugins } from "../plugin-host/discovery.ts"; import { declaredPermissions, isValidPermissionName } from "../plugin-host/plugin.ts"; +import { provisionStorage } from "../plugin-host/storage.ts"; import { generateJwks, type JwkSet } from "./gen-jwks.ts"; import { createLogger, runWithLog, tracedFetch } from "../logger.ts"; @@ -151,9 +153,22 @@ async function main() { await runWithLog(log, async () => { if (ensureJwks(env["JWKS_FILE"] ?? "/etc/config/kratos/tokenizer/jwks.json")) log.info("generated a JWKS signing key"); + const plugins = await discoverPlugins(); + + // A database and login role for each plugin that asked for one. It happens here because + // bootstrap holds the stack's only superuser credentials — web derives the same password from + // PLUGIN_DB_SECRET and connects as the plugin's own role, never as a superuser. + const storagePlugins = plugins.filter((plugin) => plugin.storage).map((plugin) => plugin.id); + if (storagePlugins.length > 0) { + const adminUrl = env["PLUGIN_DB_ADMIN_URL"]; + if (!adminUrl) throw new Error(`bootstrap: PLUGIN_DB_ADMIN_URL must be set — these plugins declare storage: ${storagePlugins.join(", ")}`); + const provisioned = await provisionStorage({ adminUrl, pluginIds: storagePlugins, secret: resolvePluginDbSecret(env) }); + log.info("plugin storage provisioned", { databases: provisioned.join(", ") }); + } + // Seed every discovered plugin's declared permission names (plus any ADMIN_PERMISSIONS), so the // shipped example — and any dropped-in plugin — works for the demo admin without a host edit. - const declared = declaredPermissions(await discoverPlugins()).map((decl) => decl.name); + const declared = declaredPermissions(plugins).map((decl) => decl.name); const { ignored, permissions } = seedPermissions(env["ADMIN_PERMISSIONS"], declared); if (ignored.length > 0) { log.warn("ignoring ADMIN_PERMISSIONS entries that are not :", { ignored: ignored.join(", ") }); diff --git a/src/compose.test.ts b/src/compose.test.ts index 1a355c1..6542ce5 100644 --- a/src/compose.test.ts +++ b/src/compose.test.ts @@ -44,10 +44,11 @@ test("long-running Ory services declare readiness healthchecks", () => { `${svc} probes :${port}/health/ready`); }); -test("web waits for kratos, keto and hydra to be healthy before starting", () => { +test("web waits for kratos, keto, hydra and postgres to be healthy before starting", () => { assert.match(webBlock, /depends_on:/, "web declares dependencies"); - // hydra: the OAuth2 login/consent handler talks to its admin API. - for (const svc of ["kratos", "keto", "hydra"]) + // hydra: the OAuth2 login/consent handler talks to its admin API. postgres: a plugin declaring + // `storage` opens its connection in onBoot, before the server listens. + for (const svc of ["kratos", "keto", "hydra", "postgres"]) assert.match(webBlock, new RegExp(`${svc}:\\s*\\n\\s*condition:\\s*service_healthy`), `web waits for ${svc} healthy`); }); @@ -78,6 +79,18 @@ test("prod base supplies the app secret via env and mounts no source; dev overri assert.match(compose, /POSTGRES_PASSWORD:\s*\$\{POSTGRES_PASSWORD\b/, "postgres password via env"); }); +test("the provisioning superuser DSN reaches bootstrap only, never web", () => { + // web runs plugin code, which can read its own environment — so the credentials that may CREATE + // DATABASE/ROLE must never be there. web gets the credential-free base URL and derives each + // plugin's own password from the shared secret instead. + const boot = compose.slice(compose.indexOf("\n bootstrap:")); + const overrideWeb = override.slice(override.indexOf("\n web:"), override.indexOf("\n bootstrap:")); + assert.match(boot, /PLUGIN_DB_ADMIN_URL:/, "bootstrap is given the superuser DSN"); + for (const [name, block] of [["base", webBlock], ["dev override", overrideWeb]] as const) + assert.doesNotMatch(block, /PLUGIN_DB_ADMIN_URL/, `${name} web never sees it`); + assert.match(webBlock, /PLUGIN_DB_URL:\s*\$\{PLUGIN_DB_URL/, "base wires web's base URL from env"); +}); + test("a one-shot bootstrap seeds the stack before web starts", () => { // MVP bar: `bootstrap` runs after kratos+keto are healthy, seeds the admin + // JWKS, then exits; web waits for it to complete. Live seeding is boot-verified. diff --git a/src/config.test.ts b/src/config.test.ts index 62ec8ce..982e450 100644 --- a/src/config.test.ts +++ b/src/config.test.ts @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import { test } from "node:test"; -import { loadConfig } from "./config.ts"; +import { loadConfig, resolvePluginDbSecret } from "./config.ts"; // Explicit secure-secret enforcement (no environment sniffing): secrets are the only // thing a hardened deploy must supply. @@ -9,6 +9,16 @@ const secureEnv = { REQUIRE_SECURE_SECRETS: "true", }; +// web reads the secret through loadConfig and bootstrap through resolvePluginDbSecret; the two +// deriving different passwords is invisible until a plugin's connection is refused at boot. Compose +// passes an unset variable through as "", which is the case that actually drifted. +test("web and bootstrap resolve the same plugin storage secret", () => { + for (const env of [{}, { PLUGIN_DB_SECRET: "" }, { PLUGIN_DB_SECRET: "a-real-secret" }]) { + assert.equal(loadConfig(env).pluginDbSecret, resolvePluginDbSecret(env), `for ${JSON.stringify(env)}`); + } + assert.match(resolvePluginDbSecret({ PLUGIN_DB_SECRET: "" }), /dev-insecure/); // empty is unset, not a secret +}); + test("loads dev defaults when the environment is empty", () => { const c = loadConfig({}); assert.equal(c.port, 3000); diff --git a/src/config.ts b/src/config.ts index 137fff7..f971e1c 100644 --- a/src/config.ts +++ b/src/config.ts @@ -6,6 +6,15 @@ export const LOG_LEVELS = ["error", "warn", "info", "verbose", "debug", "silly", "none"] as const; export type LogLevel = (typeof LOG_LEVELS)[number]; +const DEV_PLUGIN_DB_SECRET = "dev-insecure-plugin-db-secret"; + +// bootstrap resolves the plugin-storage secret through this, web through loadConfig — and the two +// must agree exactly or web connects with a password the role was never given. Compose passes an +// unset variable through as "", so empty means throwaway here as it does in readSecret. +export function resolvePluginDbSecret(env: Env): string { + return env["PLUGIN_DB_SECRET"] || DEV_PLUGIN_DB_SECRET; +} + export interface Config { appUrl: string | undefined; // canonical public URL; set ⇒ off-host visitors are redirected here. Unset ⇒ no redirect (explicit toggle) cacheTemplates: boolean; @@ -24,6 +33,8 @@ export interface Config { oryTimeoutSec: number; // per-call timeout for outbound Kratos/Keto/Hydra fetches (bounds a hung Ory) otlpEndpoint: string | undefined; // OTLP/HTTP collector base URI; unset ⇒ console-only (no export) otlpProtocol: "http/json" | "http/protobuf"; // OTLP wire format (protobuf for json-averse collectors) + pluginDbSecret: string; // derives each plugin's database password (src/plugin-host/storage.ts) + pluginDbUrl: string | undefined; // credential-free Postgres base URL; unset ⇒ plugin storage is off port: number; revocationDenylist: boolean; // enable the optional instant permission/session revoke denylist revocationTtlSec: number; // how long a revoke entry lives; keep ≥ tokenizer TTL + clock skew @@ -150,6 +161,12 @@ export function loadConfig(env: Env = process.env): Config { oryTimeoutSec: readPosInt(env, "ORY_TIMEOUT_SEC", 5), otlpEndpoint: readOptionalUrl(env, "OTLP_ENDPOINT"), otlpProtocol: readEnum(env, "OTLP_PROTOCOL", ["http/json", "http/protobuf"] as const, "http/json"), + // Per-plugin storage. PLUGIN_DB_URL carries the server and its connection parameters but no + // credentials: the superuser DSN that provisions stays in bootstrap, so a plugin cannot read it + // out of web's environment. Unset ⇒ storage is off and a plugin declaring it fails loud at boot, + // which is also why the secret is only enforced once a URL is configured. + pluginDbSecret: readSecret(env, "PLUGIN_DB_SECRET", DEV_PLUGIN_DB_SECRET, requireSecure && Boolean(env["PLUGIN_DB_URL"])), + pluginDbUrl: readOptionalUrl(env, "PLUGIN_DB_URL"), port: readPort(env), // Optional instant-revoke, off by default. When on, an admin deactivate/delete or permission // change revokes the subject's live tokens at once; the entry lives ttl seconds (≥ the 10m diff --git a/src/plugin-host/discovery.test.ts b/src/plugin-host/discovery.test.ts index 8bdca5a..91966db 100644 --- a/src/plugin-host/discovery.test.ts +++ b/src/plugin-host/discovery.test.ts @@ -27,13 +27,19 @@ test("a missing plugins/ dir means zero plugins, not an error (clean clone)", as }); test("discovers each folder's manifest, sorted, id derived from the folder name", async (t) => { - const dir = scaffold(t, { "beta/plugin.ts": full("beta"), "alpha/plugin.ts": full("alpha") }); + const dir = scaffold(t, { + "beta/plugin.ts": full("beta"), + "alpha/plugin.ts": full("alpha"), + "gamma/plugin.ts": `export default { apiVersion: "1.0.0", storage: true };`, + }); const plugins = await discoverPlugins({ dir }); - assert.deepEqual(plugins.map((p) => p.id), ["alpha", "beta"]); // deterministic order + assert.deepEqual(plugins.map((p) => p.id), ["alpha", "beta", "gamma"]); // deterministic order assert.equal(plugins[0]?.apiVersion, "1.0.0"); assert.equal(plugins[0]?.nav?.[0]?.label, "alpha"); assert.equal(typeof plugins[0]?.routes?.[0]?.handler, "function"); // handlers survive import + assert.equal(plugins[0]?.storage, undefined); // storage is opt-in, never assumed + assert.equal(plugins[2]?.storage, true); }); // Every per-plugin problem and every error-level conflict aborts boot with a message naming it. @@ -48,6 +54,9 @@ const badCases: Array<{ name: string; files: Record; match: RegE { name: "non-array routes", files: { "weird/plugin.ts": `export default { apiVersion: "1.0.0", routes: "nope" };` }, match: /weird.*routes.*array/s }, { name: "non-function home", files: { "weirdhome/plugin.ts": `export default { apiVersion: "1.0.0", home: "nope" };` }, match: /weirdhome.*home.*function/s }, { name: "non-function dashboard", files: { "weirddash/plugin.ts": `export default { apiVersion: "1.0.0", dashboard: "nope" };` }, match: /weirddash.*dashboard.*function/s }, + { name: "non-boolean storage", files: { "weirdstore/plugin.ts": `export default { apiVersion: "1.0.0", storage: "postgres://db" };` }, match: /weirdstore.*storage.*boolean/s }, + // The folder name becomes a Postgres identifier, which truncates past 63 bytes. + { name: "a storage plugin whose folder name overflows a Postgres identifier", files: { [`${"a".repeat(57)}/plugin.ts`]: `export default { apiVersion: "1.0.0", storage: true };` }, match: /storage.*56 characters/s }, { name: "reserved dashboard id shadows the gated dashboard", files: { "dashboard/plugin.ts": full("dashboard") }, match: /dashboard.*reserved/s }, { name: "duplicate nav id across plugins", files: { "a/plugin.ts": full("a").replace("a:root", "dup"), "b/plugin.ts": full("b").replace("b:root", "dup") }, match: /nav id "dup"/ }, { name: "a route marked public AND permission is contradictory", files: { "contra/plugin.ts": `export default { apiVersion: "1.0.0", routes: [{ method: "GET", path: "/", public: true, permission: "x:read", handler: () => ({ html: "x" }) }] };` }, match: /contra.*public.*permission/s }, diff --git a/src/plugin-host/discovery.ts b/src/plugin-host/discovery.ts index fd36dd7..ba32562 100644 --- a/src/plugin-host/discovery.ts +++ b/src/plugin-host/discovery.ts @@ -8,6 +8,7 @@ import { existsSync, readdirSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { checkApiVersion, findConflicts, isValidPermissionName, isValidPluginId, RESERVED_PLUGIN_IDS, type Plugin, type PluginManifest } from "./plugin.ts"; +import { isValidStoragePluginId, MAX_STORAGE_PLUGIN_ID } from "./storage.ts"; const rootDir = join(dirname(fileURLToPath(import.meta.url)), "..", ".."); @@ -66,6 +67,13 @@ export async function discoverPlugins(options: DiscoverOptions = {}): Promise { const calls: string[] = []; + const scoped: string[] = []; // each hook is handed a context built for its own plugin + const bootContextFor = (built: Plugin) => { scoped.push(built.id); return {}; }; await runBootHooks([ plugin("a", { onBoot: () => void calls.push("a") }), plugin("b", {}), // no onBoot → skipped plugin("c", { onBoot: async () => void calls.push("c") }), - ]); + ], bootContextFor); assert.deepEqual(calls, ["a", "c"]); + assert.deepEqual(scoped, ["a", "c"]); // and built only for the plugins that have one - await assert.rejects(runBootHooks([plugin("x", { onBoot: () => { throw new Error("boom"); } })]), /boom/); + await assert.rejects(runBootHooks([plugin("x", { onBoot: () => { throw new Error("boom"); } })], () => ({})), /boom/); }); test("runRequestHooks short-circuits on the first RouteResult (with its plugin); later hooks skipped", async () => { diff --git a/src/plugin-host/hooks.ts b/src/plugin-host/hooks.ts index 04fd1c6..0c6cd77 100644 --- a/src/plugin-host/hooks.ts +++ b/src/plugin-host/hooks.ts @@ -4,11 +4,15 @@ // entirely when no plugin declares the hook, so the no-hooks hot path stays free. import type { RequestContext } from "../http/context.ts"; -import type { Plugin, RouteResult } from "./plugin.ts"; +import type { BootContext, Plugin, RouteResult } from "./plugin.ts"; -// After discovery, before the server listens. A throw aborts boot. -export async function runBootHooks(plugins: Plugin[]): Promise { - for (const plugin of plugins) await plugin.hooks?.onBoot?.(); +// After discovery, before the server listens. A throw aborts boot. Each hook gets a context built +// for its own plugin, so one plugin is never handed another's storage credentials. +export async function runBootHooks(plugins: Plugin[], bootContextFor: (plugin: Plugin) => BootContext): Promise { + for (const plugin of plugins) { + const onBoot = plugin.hooks?.onBoot; + if (onBoot) await onBoot(bootContextFor(plugin)); + } } // Before route matching. The first hook to return a RouteResult short-circuits the request — its diff --git a/src/plugin-host/plugin-api.ts b/src/plugin-host/plugin-api.ts index b2a7bd7..1777480 100644 --- a/src/plugin-host/plugin-api.ts +++ b/src/plugin-host/plugin-api.ts @@ -5,7 +5,10 @@ // a plugin should import from here, never reach into deeper modules. See README.md → Building plugins. export { definePlugin, isValidPermissionName } from "./plugin.ts"; -export type { HttpMethod, Plugin, PluginHooks, PluginManifest, PermissionDecl, Route, RouteHandler, RouteResult } from "./plugin.ts"; +export type { BootContext, HttpMethod, Plugin, PluginHooks, PluginManifest, PermissionDecl, Route, RouteHandler, RouteResult } from "./plugin.ts"; +// A plugin's own database, handed to onBoot when the manifest sets `storage`. Credentials, not a +// client — the plugin depends on whichever driver it prefers (README → Plugin storage). +export type { StorageCredentials } from "./storage.ts"; export type { RequestContext, User } from "../http/context.ts"; export type { PageChrome } from "../ui/chrome.ts"; export type { NavNode } from "../ui/nav.ts"; diff --git a/src/plugin-host/plugin.ts b/src/plugin-host/plugin.ts index 9b3d9de..18151af 100644 --- a/src/plugin-host/plugin.ts +++ b/src/plugin-host/plugin.ts @@ -6,6 +6,7 @@ import type { RequestContext } from "../http/context.ts"; import type { NavNode } from "../ui/nav.ts"; +import type { StorageCredentials } from "./storage.ts"; // Bump major on a breaking manifest/handler change, minor on an additive one. export const HOST_API_VERSION = "1.0.0"; @@ -60,9 +61,14 @@ export function declaredPermissions(plugins: Plugin[]): PermissionDecl[] { return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)); } +// What onBoot receives. A hook declaring no parameter stays valid, so this may grow additively. +export interface BootContext { + storage?: StorageCredentials; // this plugin's own database; present iff the manifest declared `storage` +} + // Optional hooks on system actions. Crash-isolation is a non-goal — a throwing hook fails loud. export interface PluginHooks { - onBoot?: () => Promise | void; // after discovery, before the server listens + onBoot?: (host: BootContext) => Promise | void; // after discovery, before the server listens onRequest?: (ctx: RequestContext) => Promise | RouteResult | void; // may short-circuit onResponse?: (ctx: RequestContext, result: RouteResult | null) => Promise | void; } @@ -80,6 +86,9 @@ export interface PluginManifest { nav?: NavNode[]; // fragment merged into the menu (composeNav); node `icon` is a Lucide sprite id (src/ui/icons.ts), node ids must be globally unique permissions?: PermissionDecl[]; routes?: Route[]; + // Ask for a Postgres database of this plugin's own; its credentials arrive on onBoot's BootContext. + // The host provisions and locks it down but owns no schema inside it, and never drops it. + storage?: boolean; } // A discovered plugin: the manifest plus the `id` the host read from the folder name. Mounted diff --git a/src/plugin-host/storage.test.ts b/src/plugin-host/storage.test.ts new file mode 100644 index 0000000..8ff9fa4 --- /dev/null +++ b/src/plugin-host/storage.test.ts @@ -0,0 +1,137 @@ +// Guards the per-plugin storage rules: the shared database/role name, the derived password, the DSN +// a plugin receives and the provisioning statements. The integration test runs only when a superuser +// DSN is supplied, so the unit suite needs no Postgres. +import { test } from "node:test"; +import assert from "node:assert/strict"; +import postgres from "postgres"; +import { + buildCredentials, + derivePassword, + isValidStoragePluginId, + MAX_STORAGE_PLUGIN_ID, + provisionSql, + provisionStorage, + quoteIdentifier, + quoteLiteral, + storageName, +} from "./storage.ts"; + +const SECRET = "a-test-secret"; + +test("the database and the role share one plugin_-prefixed name", () => { + assert.equal(storageName("things"), "plugin_things"); + assert.equal(storageName("my-plugin"), "plugin_my-plugin"); +}); + +test("a storage plugin's id must leave the identifier under Postgres' 63 bytes", () => { + assert.equal(MAX_STORAGE_PLUGIN_ID, 56); // 63 - "plugin_" + assert.ok(isValidStoragePluginId("a".repeat(MAX_STORAGE_PLUGIN_ID))); + assert.ok(!isValidStoragePluginId("a".repeat(MAX_STORAGE_PLUGIN_ID + 1))); +}); + +test("the password is derived, so the same one is reachable without storing it", () => { + const derived = derivePassword(SECRET, "things"); + assert.equal(derived, derivePassword(SECRET, "things")); + assert.notEqual(derived, derivePassword(SECRET, "other")); + assert.notEqual(derived, derivePassword("a-rotated-secret", "things")); + assert.match(derived, /^[A-Za-z0-9_-]{43}$/); // base64url of 32 bytes — needs no escaping in a DSN +}); + +test("credentials name the plugin's own database, user and password", () => { + const credentials = buildCredentials("postgres://postgres:5432", "things", SECRET); + assert.deepEqual(credentials, { + database: "plugin_things", + host: "postgres", + password: derivePassword(SECRET, "things"), + port: 5432, + url: `postgres://plugin_things:${derivePassword(SECRET, "things")}@postgres:5432/plugin_things`, + user: "plugin_things", + }); +}); + +test("the base URL's connection parameters survive into the DSN", () => { + const credentials = buildCredentials("postgres://db.example?sslmode=require", "things", SECRET); + assert.equal(credentials.port, 5432); // absent ⇒ Postgres' default, never NaN + assert.equal(credentials.host, "db.example"); + assert.match(credentials.url, /@db\.example\/plugin_things\?sslmode=require$/); +}); + +test("quoting doubles an embedded quote", () => { + assert.equal(quoteIdentifier('we"ird'), '"we""ird"'); + assert.equal(quoteLiteral("we'ird"), "'we''ird'"); +}); + +test("provisioning creates the role and the database when neither exists", () => { + assert.deepEqual(provisionSql("plugin_things", "pw", { databaseExists: false, roleExists: false }), [ + `CREATE ROLE "plugin_things" LOGIN PASSWORD 'pw'`, + `CREATE DATABASE "plugin_things" OWNER "plugin_things"`, + `REVOKE ALL ON DATABASE "plugin_things" FROM PUBLIC`, + `GRANT ALL PRIVILEGES ON DATABASE "plugin_things" TO "plugin_things"`, + ]); +}); + +test("re-provisioning re-sets the password and creates nothing twice", () => { + assert.deepEqual(provisionSql("plugin_things", "rotated", { databaseExists: true, roleExists: true }), [ + `ALTER ROLE "plugin_things" WITH LOGIN PASSWORD 'rotated'`, + `REVOKE ALL ON DATABASE "plugin_things" FROM PUBLIC`, + `GRANT ALL PRIVILEGES ON DATABASE "plugin_things" TO "plugin_things"`, + ]); +}); + +// --- Integration: the statements above, against a real Postgres ----------------------- +// Opt-in via PLUGIN_DB_ADMIN_URL (a superuser DSN); the unit gate runs no Postgres. What the unit +// tests cannot prove lives here: the owner may create tables, and a peer role is locked out. + +const ADMIN_URL = process.env["PLUGIN_DB_ADMIN_URL"] ?? ""; +const integration = ADMIN_URL ? {} : { skip: "set PLUGIN_DB_ADMIN_URL to a superuser DSN to run" }; + +function baseUrlOf(adminUrl: string): string { + const url = new URL(adminUrl); + url.username = ""; + url.password = ""; + url.pathname = ""; + return url.href; +} + +async function queryAs(url: string, statement: string): Promise { + const sql = postgres(url, { connect_timeout: 10, max: 1, onnotice: () => {} }); + try { + return await sql.unsafe(statement); + } finally { + await sql.end(); + } +} + +test("provisions a database its plugin can use and a peer plugin cannot reach", integration, async () => { + const ids = ["storage-itest-a", "storage-itest-b"]; + const base = baseUrlOf(ADMIN_URL); + const admin = postgres(ADMIN_URL, { connect_timeout: 10, max: 1, onnotice: () => {} }); + try { + await provisionStorage({ adminUrl: ADMIN_URL, pluginIds: ids, secret: SECRET }); + + const owner = buildCredentials(base, "storage-itest-a", SECRET); + await queryAs(owner.url, "CREATE TABLE IF NOT EXISTS notes (body text)"); + await queryAs(owner.url, "INSERT INTO notes (body) VALUES ('persisted')"); + const rows = (await queryAs(owner.url, "SELECT body FROM notes")) as { body: string }[]; + assert.deepEqual(rows.map((row) => row.body), ["persisted"]); + + // A peer holds valid credentials for its OWN database and still cannot reach this one. + const peer = new URL(buildCredentials(base, "storage-itest-b", SECRET).url); + peer.pathname = `/${storageName("storage-itest-a")}`; + await assert.rejects(queryAs(peer.href, "SELECT 1"), /permission denied|not permitted/i); + + // Re-running is idempotent, and a rotated secret lands on the existing role. + await provisionStorage({ adminUrl: ADMIN_URL, pluginIds: ids, secret: "a-rotated-secret" }); + const rotated = buildCredentials(base, "storage-itest-a", "a-rotated-secret"); + const kept = (await queryAs(rotated.url, "SELECT body FROM notes")) as { body: string }[]; + assert.deepEqual(kept.map((row) => row.body), ["persisted"]); // rotating the secret keeps the data + await assert.rejects(queryAs(owner.url, "SELECT 1"), /password authentication failed/i); + } finally { + for (const id of ids) { + const name = quoteIdentifier(storageName(id)); + await admin.unsafe(`DROP DATABASE IF EXISTS ${name} WITH (FORCE)`); + await admin.unsafe(`DROP ROLE IF EXISTS ${name}`); + } + await admin.end(); + } +}); diff --git a/src/plugin-host/storage.ts b/src/plugin-host/storage.ts new file mode 100644 index 0000000..6847e0d --- /dev/null +++ b/src/plugin-host/storage.ts @@ -0,0 +1,104 @@ +// Per-plugin Postgres storage (README → Plugin storage). Only bootstrap provisions, because only it +// is given superuser credentials; web derives the same passwords and never sees them. + +import { createHmac } from "node:crypto"; +import postgres from "postgres"; + +// Database and role share one name, so reconnecting needs nothing looked up. The prefix also keeps +// a plugin id from ever naming an Ory database. +const NAME_PREFIX = "plugin_"; + +// Postgres truncates an identifier at 63 bytes, which would silently collide two long ids. +export const MAX_STORAGE_PLUGIN_ID = 63 - NAME_PREFIX.length; + +// `url` pre-assembles the other fields as a DSN, which most drivers take directly. +export interface StorageCredentials { + database: string; + host: string; + password: string; + port: number; + url: string; + user: string; +} + +export function storageName(pluginId: string): string { + return `${NAME_PREFIX}${pluginId}`; +} + +export function isValidStoragePluginId(pluginId: string): boolean { + return pluginId.length <= MAX_STORAGE_PLUGIN_ID; +} + +// Derived, never stored — which is what keeps the host free of state it would have to persist. +export function derivePassword(secret: string, pluginId: string): string { + return createHmac("sha256", secret).update(pluginId).digest("base64url"); +} + +// `baseUrl` names the server and its connection parameters, and carries no credentials of its own. +export function buildCredentials(baseUrl: string, pluginId: string, secret: string): StorageCredentials { + const name = storageName(pluginId); + const password = derivePassword(secret, pluginId); + const url = new URL(baseUrl); + url.username = name; + url.password = password; + url.pathname = `/${name}`; + return { database: name, host: url.hostname, password, port: Number(url.port) || 5432, url: url.href, user: name }; +} + +// CREATE ROLE/DATABASE bind no parameters, so the name and password are quoted into the statement. +export function quoteIdentifier(name: string): string { + return `"${name.replaceAll('"', '""')}"`; +} + +export function quoteLiteral(value: string): string { + return `'${value.replaceAll("'", "''")}'`; +} + +export interface ProvisionState { + databaseExists: boolean; + roleExists: boolean; +} + +// One plugin's full plan, in order. The password is re-set on every run so rotating the secret needs +// no separate step, and PUBLIC loses CONNECT so no other plugin's role can reach this database. +export function provisionSql(name: string, password: string, state: ProvisionState): string[] { + const identifier = quoteIdentifier(name); + const secret = quoteLiteral(password); + return [ + state.roleExists + ? `ALTER ROLE ${identifier} WITH LOGIN PASSWORD ${secret}` + : `CREATE ROLE ${identifier} LOGIN PASSWORD ${secret}`, + ...(state.databaseExists ? [] : [`CREATE DATABASE ${identifier} OWNER ${identifier}`]), + `REVOKE ALL ON DATABASE ${identifier} FROM PUBLIC`, + `GRANT ALL PRIVILEGES ON DATABASE ${identifier} TO ${identifier}`, + ]; +} + +export interface ProvisionOptions { + adminUrl: string; // superuser DSN — the rights to create a database and a role + pluginIds: string[]; + secret: string; +} + +// Idempotent, and it drops nothing: an uninstalled plugin keeps its data until an operator removes +// it deliberately. +export async function provisionStorage(options: ProvisionOptions): Promise { + const sql = postgres(options.adminUrl, { connect_timeout: 10, max: 1, onnotice: () => {} }); + try { + const names: string[] = []; + for (const pluginId of options.pluginIds) { + const name = storageName(pluginId); + const [role] = await sql`SELECT 1 FROM pg_roles WHERE rolname = ${name}`; + const [database] = await sql`SELECT 1 FROM pg_database WHERE datname = ${name}`; + const plan = provisionSql(name, derivePassword(options.secret, pluginId), { + databaseExists: database !== undefined, + roleExists: role !== undefined, + }); + for (const statement of plan) await sql.unsafe(statement); // provisionSql quotes what it interpolates + names.push(name); + } + return names; + } finally { + await sql.end(); + } +} diff --git a/src/postgres.test.ts b/src/postgres.test.ts index 3ec70b3..0cbc543 100644 --- a/src/postgres.test.ts +++ b/src/postgres.test.ts @@ -8,9 +8,12 @@ import { readFileSync } from "node:fs"; const read = (p: string) => readFileSync(new URL(`../${p}`, import.meta.url), "utf8"); const ORY_DATABASES = ["hydra", "keto", "kratos"]; // one DB per Ory service -test("init SQL gives each Ory service its own database", () => { +test("init SQL gives each Ory service its own database, and leaves plugin databases to bootstrap", () => { const sql = read("ory/postgres/init/init.sql"); for (const db of ORY_DATABASES) { assert.match(sql, new RegExp(`CREATE DATABASE ${db}\\b`, "i"), `creates ${db}`); } + // This file runs once, on an empty data dir — a plugin database added here would never appear for + // a plugin dropped in later. bootstrap provisions them on every boot instead. + assert.doesNotMatch(sql, /plugin_/i, "no plugin database is seeded here"); }); diff --git a/src/server.ts b/src/server.ts index d8d38f6..960284d 100644 --- a/src/server.ts +++ b/src/server.ts @@ -13,6 +13,7 @@ import { createKratosAdmin } from "./auth/kratos-admin.ts"; import { createKratosPublic } from "./auth/kratos-public.ts"; import { createLogger, tracedFetch } from "./logger.ts"; import { loadMenuConfig } from "./ui/menu-config.ts"; +import { buildCredentials } from "./plugin-host/storage.ts"; const config = loadConfig(); // validates the env (incl. enforced secrets) — fails loud at boot // App-level logger: structured, OTLP-capable when OTLP_ENDPOINT is set. The hot path clones it @@ -44,7 +45,18 @@ log.info("plugins discovered", { count: plugins.length, ids: plugins.map((p) => const i18n = createI18n(await loadI18n({ logger: log, pluginIds: plugins.map((p) => p.id) })); log.info("locales loaded", { locales: i18n.available.join(", ") }); -await runBootHooks(plugins); // plugin onBoot — after discovery, before listen; a throw aborts boot +// A plugin's database credentials are derived, never stored — so the only thing that can be missing +// is the server itself. Refuse at boot rather than at that plugin's first query, hours later. +const pluginDbUrl = config.pluginDbUrl; +const declaresStorage = plugins.filter((plugin) => plugin.storage).map((plugin) => plugin.id); +if (declaresStorage.length > 0 && pluginDbUrl === undefined) { + throw new Error(`config: PLUGIN_DB_URL must be set — these plugins declare storage: ${declaresStorage.join(", ")}`); +} + +// plugin onBoot — after discovery, before listen; a throw aborts boot. +await runBootHooks(plugins, (plugin) => + plugin.storage && pluginDbUrl !== undefined ? { storage: buildCredentials(pluginDbUrl, plugin.id, config.pluginDbSecret) } : {}, +); const server = createApp({ // Canonical-host redirect target (off-host GET/HEAD visitors are sent here). Opt-in: omitted unless diff --git a/todo.md b/todo.md index e624651..085a04a 100644 --- a/todo.md +++ b/todo.md @@ -3,6 +3,9 @@ ## Unfinnished work - [ ] Add a way to configure plugins directly when installing. **Decided: the manifest declares it, not an `.env`** — a declared schema is validatable at boot, so a missing or mistyped setting fails loud and named the way a stray `package.json` now does, and the picker/docs can be generated from the declaration. Open: where the operator *supplies* the values (env var per key, a `config/` file, or both), and whether a secret may be declared at all. +- [ ] A provisioned plugin database is invisible and unremovable. Nothing lists what exists, so an operator cannot see that `plugin_` is there, nor that its plugin is gone — and uninstalling never drops it (deliberately, so data survives), leaving orphans with no supported way to clean them. Same shape as the uninstalled-plugin grant gap above. Sketch: a read-only "provisioned, but no installed plugin claims it" list plus a documented drop procedure. +- [ ] Decide who owns the connection ceiling for plugin storage. Each storage plugin opens its own pool against one Postgres, whose default `max_connections` is 100, and nothing warns as plugins are added. Either state a per-plugin pool ceiling in README → Plugin storage or record that the plugin owns it. +- [ ] E2E that a plugin's data actually survives a restart. `storage.test.ts` proves provisioning against a real Postgres (opt-in via `PLUGIN_DB_ADMIN_URL`), but no Playwright flow writes through a plugin page and reads it back after `docker compose restart web`. - [ ] Rename the plugin "admin" to something less generic, like "auth-admin" or "users-groups-admin". - [ ] Guard the group paths against self-lockout, or accept them explicitly. The self-revoke guard covers only your own *direct* grants on the Users screen; unticking a permission on a group you belong to, removing yourself from that group, or deleting it can all still strip your own effective access with no warning. Recorded in AGENTS.md as a known gap — the robust fix is a "last effective holder" check, which needs a reverse Keto query. - [ ] The permission picker has no concurrency baseline, so two operators editing the same user/group silently discard each other's change. Sketch: post the rendered set as a hidden baseline; if it no longer matches Keto, re-render with "this changed while you had the page open" rather than applying. @@ -36,6 +39,7 @@ Prioritized. Overall verdict: architecture is sound; these are refinements. ## Finnished work +- [x] Give a plugin persistent storage: `storage: true` provisions a Postgres database + login role named `plugin_`, credentials arrive on `onBoot`, passwords are derived from `PLUGIN_DB_SECRET` rather than stored. - [x] Refuse a stray `package.json`/`node_modules` in `config/` by name, as plugin folders already are. - [x] Let Renovate reach the example plugins' manifests (`ignorePaths` overrides `config:recommended`). - [x] The seeded admin is granted each permission once — `seedPermissions` dedupes and the grant PUT is idempotent.