@wtfalch/foundry 0.6.0 → 0.8.0

package/dist/store/audit.js

@@ -1,44 +1,125 @@
-import { foundryAuditEvents } from './schema.js';
+import { createLedger, ledgerVocabulary } from '@wtfalch/audit';
 /**
- * foundry's own {@link AuditLog}, one row per plan, apply or destroy in
- * `foundry_audit_events` (#85). The CLI uses it before any archon exists; an
- * attached archon reads the same table. It only inserts.
+ * foundry's own closed vocabulary (#232): one event per `AuditLog` method,
+ * `outcome` carrying how it went rather than the action name repeating it
+ * (the same split `@wtfalch/audit`'s own "service with no tenant database"
+ * example uses: `action: 'plan.applied'`, `outcome: 'refused'`). `actor`
+ * has one class, `'operator'`, because `AuditActor` (`plan-apply.ts`) does
+ * not distinguish a human from a service caller -- nothing here guesses
+ * one. `'recorded'` sorts first so it is the default outcome
+ * `plan.computed` rows get (`recordPlan` has no outcome of its own to pass).
  */
-export function createPostgresAuditLog(db) {
+const FOUNDRY_LEDGER_VOCABULARY = ledgerVocabulary({
+    events: {
+        'plan.computed': { tenantVisible: false },
+        'apply.recorded': { tenantVisible: false },
+        'destroy.recorded': { tenantVisible: false },
+    },
+    actorClasses: ['operator'],
+    contexts: ['operator'],
+    outcomes: ['recorded', 'applied', 'destroyed', 'refused', 'failed'],
+});
+/**
+ * The ledger table's CHECKs (migration 0024): reason <= 512 chars, `after`
+ * <= 65536 bytes as jsonb text, actor_display 1-256 chars. A write that
+ * breaks one throws and would hide the apply error being recorded, so each
+ * value is bounded here. Postgres' jsonb text adds a space after every `:`
+ * and `,`, so the plan is measured against half the limit.
+ */
+const MAX_REASON = 512;
+const MAX_AFTER_BYTES = 32768;
+const MAX_DISPLAY = 256;
+function boundReason(reason) {
+    return reason === undefined ? null : reason.slice(0, MAX_REASON);
+}
+function boundDisplay(actor) {
+    return (actor.display || actor.id).slice(0, MAX_DISPLAY);
+}
+function boundPlan(plan) {
+    return Buffer.byteLength(JSON.stringify(plan)) <= MAX_AFTER_BYTES
+        ? plan
+        : { truncated: true, steps: plan.steps.length, unmanaged: plan.unmanaged.length };
+}
+/**
+ * foundry's own {@link AuditLog}, backed by `@wtfalch/audit`'s ledger
+ * (#232) instead of the hand-rolled `foundry_audit_events` table
+ * (`migrations/0012_audit.sql`) this replaces. Every row: `tenantId: null`
+ * (foundry has no tenant of its own -- the org a plan is *for* is the
+ * `target`, not a tenant), `hashChain` on so a changed or deleted row is
+ * detectable (`verifyChain`), through migrations 0024-0028
+ * (`src/migrations/`, copied from `@wtfalch/audit` 0.6.0's own
+ * `migrations/0001-0005`, the same files its own `audit-migrations` CLI
+ * would copy into a host that has a `drizzle/` journal -- foundry does not,
+ * so they are hand-placed at the next free numbers instead).
+ *
+ * The `AuditLog` interface this satisfies is unchanged (`plan-apply.ts`),
+ * so `bootstrap.ts` and `redactingAudit` need no change either.
+ *
+ * Decide (#232, open): whether `foundry_audit_events`' existing rows are
+ * copied into the ledger or left as a closed, separate trail. Left as-is
+ * here -- the simpler default, and the one that forecloses nothing: a
+ * backfill can still be written later, where discarding the old rows
+ * outright could not be undone.
+ *
+ * `checkRuntimeRole` defaults to `true`, `createLedger`'s own default. The
+ * connection must be a restricted role: not a superuser, no BYPASSRLS, and no
+ * UPDATE, DELETE or TRUNCATE on `audit_events`. A call through the owner
+ * connection throws `UnsafeRuntimeRoleError`. The check reads attributes of
+ * the connected role, not its name.
+ *
+ * The host provides that role. After it migrates with the owner URL, it calls
+ * `ensureRuntimeRole` from `@wtfalch/db/runtime-role` with
+ * `appendOnly: ['audit_events']` and the four audit functions in `grants`
+ * (README, "Foundry's own Postgres"), then connects the server as the runtime
+ * role. A test fixture without that split (PGlite's one user is a superuser)
+ * passes `checkRuntimeRole: false`. Options, not a second positional argument
+ * (`CLAUDE.md` rule 7).
+ */
+export function createPostgresAuditLog(db, options = {}) {
+    const ledger = createLedger({
+        vocabulary: FOUNDRY_LEDGER_VOCABULARY,
+        hashChain: true,
+        checkRuntimeRole: options.checkRuntimeRole,
+    });
+    const targetFor = (orgId, target) => ({
+        type: target === 'platform' ? 'platform' : 'org',
+        id: orgId,
+    });
     return {
         async recordPlan({ actor, orgId, plan, target, at }) {
-            await db.insert(foundryAuditEvents).values({
-                at,
-                kind: 'plan',
-                actorId: actor.id,
-                actorDisplay: actor.display,
-                orgId,
-                plan,
-                target: target ?? null,
+            await ledger.sign(db, {
+                action: 'plan.computed',
+                tenantId: null,
+                actor: { class: 'operator', id: actor.id, display: boundDisplay(actor) },
+                context: 'operator',
+                target: targetFor(orgId, target),
+                after: boundPlan(plan),
+                occurredAt: at,
             });
         },
         async recordApply({ actor, orgId, plan, outcome, reason, target, at }) {
-            await db.insert(foundryAuditEvents).values({
-                at,
-                kind: 'apply',
-                actorId: actor.id,
-                actorDisplay: actor.display,
-                orgId,
+            await ledger.sign(db, {
+                action: 'apply.recorded',
+                tenantId: null,
+                actor: { class: 'operator', id: actor.id, display: boundDisplay(actor) },
+                context: 'operator',
+                target: targetFor(orgId, target),
                 outcome,
-                reason: reason ?? null,
-                plan,
-                target: target ?? null,
+                reason: boundReason(reason),
+                after: boundPlan(plan),
+                occurredAt: at,
             });
         },
         async recordDestroy({ actor, orgId, outcome, reason, at }) {
-            await db.insert(foundryAuditEvents).values({
-                at,
-                kind: 'destroy',
-                actorId: actor.id,
-                actorDisplay: actor.display,
-                orgId,
+            await ledger.sign(db, {
+                action: 'destroy.recorded',
+                tenantId: null,
+                actor: { class: 'operator', id: actor.id, display: boundDisplay(actor) },
+                context: 'operator',
+                target: targetFor(orgId),
                 outcome,
-                reason: reason ?? null,
+                reason: boundReason(reason),
+                occurredAt: at,
             });
         },
     };

package/dist/store/postgres.d.ts

@@ -7,6 +7,20 @@ import type { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from '../s
  * connection itself.
  */
 export type FoundryStoreDb = PgDatabase<PgQueryResultHKT, any, any>;
+/**
+ * The Postgres unique-violation constraint name, however the driver hands the
+ * error back -- directly (PGlite in this package's own tests) or wrapped in
+ * drizzle-orm's own `DrizzleQueryError`, whose `cause` carries the raw driver
+ * error (postgres-js in a host) -- or `undefined` when this is not a unique
+ * violation. Checked by Postgres error code, never by message text, since
+ * message text is not a contract. Same code-check pattern as
+ * `../runner/runner.ts`'s own `isUniqueViolation` -- kept as a local copy
+ * here rather than shared, since neither module depends on the other; this
+ * one additionally reads the constraint name (`constraint` under node-postgres and PGlite, `constraint_name` under postgres-js) so `create`/`update` can tell a slug
+ * collision from a domain collision (#131) rather than reporting both the
+ * same way.
+ */
+export declare function uniqueViolationConstraint(error: unknown): string | undefined;
 /**
  * Thrown by `create` and `update` when the store refuses a write: an id
  * that already exists, an id that does not, a slug that fails

package/dist/store/postgres.js

@@ -19,17 +19,22 @@ const NON_NEGATIVE_INTEGER = /^(0|[1-9]\d*)$/;
  * message text is not a contract. Same code-check pattern as
  * `../runner/runner.ts`'s own `isUniqueViolation` -- kept as a local copy
  * here rather than shared, since neither module depends on the other; this
- * one additionally reads `constraint` so `create`/`update` can tell a slug
+ * one additionally reads the constraint name (`constraint` under node-postgres and PGlite, `constraint_name` under postgres-js) so `create`/`update` can tell a slug
  * collision from a domain collision (#131) rather than reporting both the
  * same way.
  */
-function uniqueViolationConstraint(error) {
-    const direct = error;
-    if (direct?.code === UNIQUE_VIOLATION)
-        return direct.constraint;
-    const cause = error?.cause;
-    if (cause?.code === UNIQUE_VIOLATION)
-        return cause.constraint;
+export function uniqueViolationConstraint(error) {
+    // Walk `cause`: drizzle-orm wraps the driver error, and how deep differs by version. Bounded so a cyclic `cause` ends.
+    let current = error;
+    for (let depth = 0; depth < 5 && current !== null && typeof current === 'object'; depth += 1) {
+        const e = current;
+        if (e.code === UNIQUE_VIOLATION) {
+            // node-postgres spells it `constraint`; postgres-js spells it `constraint_name`.
+            const name = e.constraint ?? e.constraint_name;
+            return typeof name === 'string' ? name : undefined;
+        }
+        current = e.cause;
+    }
     return undefined;
 }
 /**
@@ -67,7 +72,7 @@ function rowToOrg(row) {
             mailApps: row.mailApps,
             roleMailboxes: row.roleMailboxes,
         },
-        chat: { usesDomain: row.chatUsesDomain },
+        chat: { enabled: row.chatEnabled, usesDomain: row.chatUsesDomain },
         calls: { enabled: row.callsEnabled, usesDomain: row.callsUsesDomain },
         issuer: { usesDomain: row.issuerUsesDomain },
         site: { enabled: row.siteEnabled, usesDomain: row.siteUsesDomain },
@@ -80,6 +85,7 @@ function rowToOrg(row) {
             buildPack: row.hostingBuildPack,
             issuerApps: row.hostingIssuerApps,
             accessEmails: row.hostingAccessEmails,
+            appEnv: row.hostingAppEnv,
         },
         sso: { enabled: row.ssoEnabled },
         guests: { enabled: row.guestsEnabled },
@@ -107,6 +113,7 @@ function orgToRow(org) {
         noReplyLocalPart: org.mail.noReplyLocalPart ?? DEFAULT_NO_REPLY_LOCAL_PART,
         mailApps: org.mail.mailApps ?? [...DEFAULT_MAIL_APPS],
         roleMailboxes: org.mail.roleMailboxes ?? [],
+        chatEnabled: org.chat.enabled,
         chatUsesDomain: org.chat.usesDomain,
         callsEnabled: org.calls.enabled,
         callsUsesDomain: org.calls.usesDomain,
@@ -121,6 +128,7 @@ function orgToRow(org) {
         hostingBuildPack: org.hosting.buildPack,
         hostingIssuerApps: org.hosting.issuerApps,
         hostingAccessEmails: org.hosting.accessEmails,
+        hostingAppEnv: org.hosting.appEnv ?? {},
         ssoEnabled: org.sso.enabled,
         guestsEnabled: org.guests.enabled,
         soloEnabled: org.solo.enabled,

package/dist/store/schema.d.ts

@@ -1,4 +1,4 @@
-import type { IssuerApp } from '../org.js';
+import type { AppEnvSource, IssuerApp } from '../org.js';
 import type { Plan } from '../plan.js';
 import type { Checkpoint } from '../state.js';
 /**
@@ -185,6 +185,23 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
         }, {}, {
             $type: string[];
         }>;
+        chatEnabled: import("drizzle-orm/pg-core").PgColumn<{
+            name: "chat_enabled";
+            tableName: "foundry_declared_orgs";
+            dataType: "boolean";
+            columnType: "PgBoolean";
+            data: boolean;
+            driverParam: boolean;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         chatUsesDomain: import("drizzle-orm/pg-core").PgColumn<{
             name: "chat_uses_domain";
             tableName: "foundry_declared_orgs";
@@ -427,6 +444,25 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
         }, {}, {
             $type: string[];
         }>;
+        hostingAppEnv: import("drizzle-orm/pg-core").PgColumn<{
+            name: "hosting_app_env";
+            tableName: "foundry_declared_orgs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: Record<string, AppEnvSource>;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: Record<string, AppEnvSource>;
+        }>;
         ssoEnabled: import("drizzle-orm/pg-core").PgColumn<{
             name: "sso_enabled";
             tableName: "foundry_declared_orgs";

package/dist/store/schema.js

@@ -25,6 +25,7 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     // MailConfig.roleMailboxes (org.ts, #230). Local parts of the role mailboxes
     // pre-created on the org's mail domain; empty by default.
     roleMailboxes: jsonb('role_mailboxes').notNull().default([]).$type(),
+    chatEnabled: boolean('chat_enabled').notNull().default(false),
     chatUsesDomain: boolean('chat_uses_domain').notNull().default(false),
     callsEnabled: boolean('calls_enabled').notNull().default(false),
     callsUsesDomain: boolean('calls_uses_domain').notNull().default(false),
@@ -41,6 +42,12 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     hostingBuildPack: text('hosting_build_pack').notNull().default('nixpacks'),
     hostingIssuerApps: jsonb('hosting_issuer_apps').notNull().default([]).$type(),
     hostingAccessEmails: jsonb('hosting_access_emails').notNull().default([]).$type(),
+    // HostingConfig.appEnv (org.ts, #243). Maps the app's own env var names to
+    // values the plan already mints; empty by default.
+    hostingAppEnv: jsonb('hosting_app_env')
+        .notNull()
+        .default({})
+        .$type(),
     ssoEnabled: boolean('sso_enabled').notNull().default(false),
     guestsEnabled: boolean('guests_enabled').notNull().default(false),
     soloEnabled: boolean('solo_enabled').notNull().default(false),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",
@@ -9,12 +9,16 @@
   },
   "license": "MIT",
   "type": "module",
-  "files": ["dist"],
+  "files": ["dist", "versions.json"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./migrations-dir": {
+      "types": "./dist/migrations-dir.d.ts",
+      "default": "./dist/migrations-dir.js"
+    },
     "./migrations/*.sql": "./dist/migrations/*.sql",
     "./package.json": "./package.json"
   },
@@ -30,23 +34,24 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "db:provision": "node scripts/foundry-db-provision.mjs",
-    "db:migrate": "node scripts/foundry-db-migrate.mjs",
     "calls-sfu:deploy": "node scripts/calls-sfu-deploy.mjs"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.45.2"
   },
   "dependencies": {
+    "@wtfalch/audit": "0.6.0",
     "@wtfalch/auth": "0.16.0",
     "@wtfalch/email": "0.15.0",
     "@wtfalch/providers": "0.6.0",
-    "ssh2": "1.17.0"
+    "ssh2": "1.17.0",
+    "zod": "4.6.5"
   },
   "devDependencies": {
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@wtfalch/db": "0.5.2",
     "drizzle-orm": "0.45.2",
-    "postgres": "3.4.9",
     "typescript": "^5.9.0",
     "vitest": "^4.1.6"
   }

package/versions.json

@@ -0,0 +1,8 @@
+{
+  "zitadel": "v4.17.3",
+  "synapse": "v1.161.0",
+  "mas": "1.24.0",
+  "livekit": "v1.13.7",
+  "cloudflared": "2026.9.3",
+  "stalwart": "v0.16.24"
+}

package/dist/migrate.d.ts

@@ -1,38 +0,0 @@
-/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
-export declare const MIGRATIONS_DIR: string;
-/**
- * The one capability `migrate` needs from a driver: run SQL text (one
- * statement or several) and run a callback inside a transaction. Deliberately
- * not a drizzle `PgDatabase` or a concrete driver type -- drizzle's own
- * `.execute()` routes a multi-statement string through a single prepared
- * query on PGlite, which rejects it, so a migration file's raw text has to
- * reach the driver's own multi-statement path (`postgres`'s `.unsafe()`,
- * PGlite's `.exec()`) instead. Same "narrow port, no concrete client type"
- * shape `plan/executor.ts`'s `CoolifyPort` uses, for the same reason: a real
- * driver satisfies this structurally, with a few lines of adapter at the
- * call site (see `scripts/foundry-db-migrate.mjs` and `migrate.test.ts`).
- */
-export interface MigrateSql {
-    /** Run SQL text and discard any result -- the tracking table's own DDL, and each migration file's contents. */
-    exec(text: string): Promise<void>;
-    /**
-     * Run one literal SELECT and return its rows. Only ever called here with
-     * fixed text this module builds itself (the tracking table's name, and a
-     * migration filename already checked against `/^\d{4}_.+\.sql$/`), so
-     * there is no external input to inject.
-     */
-    query<T = Record<string, unknown>>(text: string): Promise<T[]>;
-    /** Run `fn` inside one transaction, handing it a `MigrateSql` scoped to it; rolled back if `fn` throws. */
-    transaction<T>(fn: (tx: MigrateSql) => Promise<T>): Promise<T>;
-}
-export interface MigrationResult {
-    /** Names of the migration files applied this run, in filename order -- empty when the database was already current. */
-    applied: string[];
-}
-/**
- * Applies every migration file in `dir` (default: this package's own
- * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
- * filename order, one transaction per file. Safe to call repeatedly: a file
- * already recorded is never re-read, let alone re-run.
- */
-export declare function migrate(sql: MigrateSql, dir?: string): Promise<MigrationResult>;

package/dist/migrate.js

@@ -1,47 +0,0 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-// #R2 (map gap: foundry's own Postgres, two commands): a tracked, idempotent
-// migration runner. `./test/db.ts` and `./runner/test/db.ts` already read
-// and sort this same directory to build one concatenated blob for a fresh
-// PGlite -- fine for a test fixture that always starts empty, wrong for a
-// real host that must apply only what a `foundry_schema_migrations` table
-// does not yet list. `migrationFiles` below is that same discovery, reused
-// rather than re-implemented, kept per-file instead of concatenated.
-const here = dirname(fileURLToPath(import.meta.url));
-/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
-export const MIGRATIONS_DIR = join(here, 'migrations');
-const TRACKING_TABLE = 'foundry_schema_migrations';
-function migrationFiles(dir) {
-    return readdirSync(dir)
-        .filter((f) => /^\d{4}_.+\.sql$/.test(f))
-        .sort()
-        .map((name) => ({ name, path: join(dir, name) }));
-}
-/**
- * Applies every migration file in `dir` (default: this package's own
- * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
- * filename order, one transaction per file. Safe to call repeatedly: a file
- * already recorded is never re-read, let alone re-run.
- */
-export async function migrate(sql, dir = MIGRATIONS_DIR) {
-    await sql.exec(`create table if not exists ${TRACKING_TABLE} (name text primary key, applied_at timestamptz not null default now())`);
-    const appliedRows = await sql.query(`select name from ${TRACKING_TABLE}`);
-    const applied = new Set(appliedRows.map((row) => row.name));
-    const pending = migrationFiles(dir).filter((file) => !applied.has(file.name));
-    const done = [];
-    for (const file of pending) {
-        const text = readFileSync(file.path, 'utf8');
-        await sql.transaction(async (tx) => {
-            await tx.exec(text);
-            // `file.name` is drawn from `migrationFiles`' own regex-filtered
-            // `readdirSync`, never from outside this module -- see `MigrateSql`'s
-            // doc comment. Quotes are still escaped, so an oddly-named future
-            // migration file cannot break the statement.
-            const escaped = file.name.replace(/'/g, "''");
-            await tx.exec(`insert into ${TRACKING_TABLE} (name) values ('${escaped}')`);
-        });
-        done.push(file.name);
-    }
-    return { applied: done };
-}