@wtfalch/foundry 0.8.0 → 0.10.0

package/dist/plan/zitadel-system-api.d.ts

@@ -0,0 +1,64 @@
+/**
+ * #283: foundry's way into a brand-new ZITADEL instance. ZITADEL's system API
+ * (`POST /system/v1/instances/_create`, permission `system.instance.write`,
+ * https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
+ * creates the instance with a machine owner (IAM_OWNER of that instance) and
+ * returns that owner's personal access token (`pat`) once, inline. foundry
+ * authenticates to the system API with a short-lived RS256 JWT signed by a
+ * keypair it generates: the public half goes into the container as a system
+ * API user, the private half stays in memory for one run. The calls follow
+ * ZITADEL's source and proto and have not been run against a live instance.
+ */
+/** The system API user's name; it is the JWT's `iss` and `sub`. */
+export declare const SYSTEM_API_USER_NAME = "foundry";
+/** A fresh RSA keypair: the public key (PEM) for ZITADEL, the private key (PKCS#8 PEM) for signing. */
+export declare function generateSystemApiKeypair(): {
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * The value of `ZITADEL_SYSTEMAPIUSERS`: JSON in ZITADEL's `SystemAPIUsers`
+ * shape (`cmd/defaults.yaml`), `KeyData` being the base64 of the public key
+ * PEM. With no `Memberships` ZITADEL grants exactly System/SYSTEM_OWNER.
+ */
+export declare function systemApiUsersEnv(publicKeyPem: string): string;
+/** A 1-minute RS256 JWT for the system API: `iss` = `sub` = the user name, `aud` = the instance URL. */
+export declare function signSystemApiJwt(privateKeyPem: string, audience: string, nowMs: number): string;
+/**
+ * How a create failed. `rejected`: ZITADEL refused it for good before doing
+ * anything (bad key, bad request), so nothing exists. `exists`: an instance
+ * for the domain already exists. `uncertain`: the request may have reached
+ * ZITADEL (timeout, network error, 5xx, an unreadable answer), so an instance
+ * may exist. The caller records a marker for the last two.
+ */
+export declare class CreateInstanceError extends Error {
+    readonly kind: 'rejected' | 'exists' | 'uncertain';
+    constructor(kind: 'rejected' | 'exists' | 'uncertain', message: string);
+}
+/** What a person does when an instance exists without a delivered bearer. Nothing is deleted automatically. */
+export declare function instanceWithoutBearerMessage(hostname: string, detail: string): string;
+export interface CreateInstanceRuntime {
+    fetch?: typeof fetch;
+    now: () => number;
+    /** Fetch timeout for the one create call (default 30s). */
+    timeoutMs?: number;
+}
+/**
+ * Creates the platform's ZITADEL instance on `customDomain` with one machine
+ * owner and returns its id and the owner's PAT. Sends exactly one request,
+ * never retries, and signs a fresh 60-second JWT for it. The PAT is returned
+ * to the caller only, never logged or put in an error.
+ */
+export declare function createZitadelInstance(input: {
+    customDomain: string;
+    privateKey: string;
+    instanceName: string;
+    firstOrgName: string;
+    owner: {
+        userName: string;
+        name: string;
+    };
+}, runtime: CreateInstanceRuntime): Promise<{
+    instanceId: string;
+    pat: string;
+}>;

package/dist/plan/zitadel-system-api.js

@@ -0,0 +1,125 @@
+import { createSign, generateKeyPairSync } from 'node:crypto';
+/**
+ * #283: foundry's way into a brand-new ZITADEL instance. ZITADEL's system API
+ * (`POST /system/v1/instances/_create`, permission `system.instance.write`,
+ * https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
+ * creates the instance with a machine owner (IAM_OWNER of that instance) and
+ * returns that owner's personal access token (`pat`) once, inline. foundry
+ * authenticates to the system API with a short-lived RS256 JWT signed by a
+ * keypair it generates: the public half goes into the container as a system
+ * API user, the private half stays in memory for one run. The calls follow
+ * ZITADEL's source and proto and have not been run against a live instance.
+ */
+/** The system API user's name; it is the JWT's `iss` and `sub`. */
+export const SYSTEM_API_USER_NAME = 'foundry';
+/** A fresh RSA keypair: the public key (PEM) for ZITADEL, the private key (PKCS#8 PEM) for signing. */
+export function generateSystemApiKeypair() {
+    return generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+}
+/**
+ * The value of `ZITADEL_SYSTEMAPIUSERS`: JSON in ZITADEL's `SystemAPIUsers`
+ * shape (`cmd/defaults.yaml`), `KeyData` being the base64 of the public key
+ * PEM. With no `Memberships` ZITADEL grants exactly System/SYSTEM_OWNER.
+ */
+export function systemApiUsersEnv(publicKeyPem) {
+    return JSON.stringify({
+        [SYSTEM_API_USER_NAME]: { KeyData: Buffer.from(publicKeyPem).toString('base64') },
+    });
+}
+const b64url = (input) => Buffer.from(input).toString('base64url');
+/** A 1-minute RS256 JWT for the system API: `iss` = `sub` = the user name, `aud` = the instance URL. */
+export function signSystemApiJwt(privateKeyPem, audience, nowMs) {
+    const iat = Math.floor(nowMs / 1000);
+    const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+    const body = b64url(JSON.stringify({
+        iss: SYSTEM_API_USER_NAME,
+        sub: SYSTEM_API_USER_NAME,
+        aud: audience,
+        iat,
+        exp: iat + 60,
+    }));
+    const signature = createSign('RSA-SHA256').update(`${head}.${body}`).sign(privateKeyPem);
+    return `${head}.${body}.${b64url(signature)}`;
+}
+/**
+ * How a create failed. `rejected`: ZITADEL refused it for good before doing
+ * anything (bad key, bad request), so nothing exists. `exists`: an instance
+ * for the domain already exists. `uncertain`: the request may have reached
+ * ZITADEL (timeout, network error, 5xx, an unreadable answer), so an instance
+ * may exist. The caller records a marker for the last two.
+ */
+export class CreateInstanceError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'CreateInstanceError';
+    }
+}
+/** What a person does when an instance exists without a delivered bearer. Nothing is deleted automatically. */
+export function instanceWithoutBearerMessage(hostname, detail) {
+    return `platform:auth: a ZITADEL instance may already exist for ${hostname} without a delivered bearer (${detail}). To recover, delete the instance with the system API (DELETE /system/v1/instances/{id}) or redeploy the ZITADEL database, remove the recorded key zitadel_platform_instance_undelivered, then apply again`;
+}
+/**
+ * Creates the platform's ZITADEL instance on `customDomain` with one machine
+ * owner and returns its id and the owner's PAT. Sends exactly one request,
+ * never retries, and signs a fresh 60-second JWT for it. The PAT is returned
+ * to the caller only, never logged or put in an error.
+ */
+export async function createZitadelInstance(input, runtime) {
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const url = `https://${input.customDomain}`;
+    let response;
+    try {
+        response = await fetchImpl(`${url}/system/v1/instances/_create`, {
+            method: 'POST',
+            signal: AbortSignal.timeout(runtime.timeoutMs ?? 30_000),
+            headers: {
+                authorization: `Bearer ${signSystemApiJwt(input.privateKey, url, runtime.now())}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                instanceName: input.instanceName,
+                firstOrgName: input.firstOrgName,
+                customDomain: input.customDomain,
+                machine: {
+                    userName: input.owner.userName,
+                    name: input.owner.name,
+                    personalAccessToken: {
+                        expirationDate: new Date(runtime.now() + 10 * 365 * 86_400_000).toISOString(),
+                    },
+                },
+            }),
+        });
+    }
+    catch {
+        throw new CreateInstanceError('uncertain', instanceWithoutBearerMessage(input.customDomain, 'the create request timed out or failed'));
+    }
+    if (response.status === 401) {
+        throw new CreateInstanceError('rejected', 'platform:auth: system API key rejected (HTTP 401); nothing was created');
+    }
+    if (response.status === 409) {
+        throw new CreateInstanceError('exists', instanceWithoutBearerMessage(input.customDomain, 'ZITADEL answered 409, already exists'));
+    }
+    if (!response.ok) {
+        // A 4xx is a refusal before anything was created; a 5xx may not be.
+        throw new CreateInstanceError(response.status < 500 ? 'rejected' : 'uncertain', response.status < 500
+            ? `platform:auth: ZITADEL refused to create the instance (HTTP ${response.status}); nothing was created`
+            : instanceWithoutBearerMessage(input.customDomain, `ZITADEL answered HTTP ${response.status}`));
+    }
+    let body = {};
+    try {
+        body = (await response.json());
+    }
+    catch {
+        // Handled below.
+    }
+    if (!body.instanceId || !body.pat) {
+        throw new CreateInstanceError('uncertain', instanceWithoutBearerMessage(input.customDomain, 'the answer had no instance id or token'));
+    }
+    return { instanceId: body.instanceId, pat: body.pat };
+}

package/dist/platform.d.ts

@@ -4,7 +4,7 @@ import type { OrgId } from './org.js';
  * {@link DeclaredPlatform}. `enabled` turns the service's own provisioning
  * on; `hostname` is where it is served (default `<service>.<apex>`,
  * {@link defaultPlatformHostname}); `gitRef` is the release it runs, the
- * same "declared, not discovered" shape `HostingConfig.gitBranch` uses for
+ * same "declared, not discovered" shape `HostingEntry.branch` uses for
  * an org's own app (`org.ts`).
  */
 export interface PlatformService {

package/dist/store/postgres.js

@@ -1,5 +1,6 @@
 import { asc, eq, sql } from 'drizzle-orm';
-import { DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, validateBuyerIdentity, validateDomain, validateHosting, validateMail, validateOwner, validateSite, } from '../org.js';
+import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, validateBuyerIdentity, validateDomain, validateHosting, validateMail, validateOwner, validateSite, } from '../org.js';
+import { lockedHostnames } from '../plan/locked-hostnames.js';
 import { validatePlatform } from '../platform.js';
 import { RequestedChangeError, classifyChange } from '../requested-changes.js';
 import { validateSlug } from '../slug.js';
@@ -79,13 +80,13 @@ function rowToOrg(row) {
         hosting: {
             enabled: row.hostingEnabled,
             usesDomain: row.hostingUsesDomain,
-            database: row.hostingDatabase,
             tunnel: row.hostingTunnel,
-            gitBranch: row.hostingGitBranch,
-            buildPack: row.hostingBuildPack,
             issuerApps: row.hostingIssuerApps,
-            accessEmails: row.hostingAccessEmails,
-            appEnv: row.hostingAppEnv,
+            // Migration 0030's default for an entry stored before `hostnames`.
+            entries: row.hostingEntries.map((entry) => ({
+                ...entry,
+                hostnames: entry.hostnames ?? (entry.key === APP_ENTRY_KEY && row.hostingUsesDomain ? ['@'] : []),
+            })),
         },
         sso: { enabled: row.ssoEnabled },
         guests: { enabled: row.guestsEnabled },
@@ -122,13 +123,9 @@ function orgToRow(org) {
         siteUsesDomain: org.site.usesDomain,
         hostingEnabled: org.hosting.enabled,
         hostingUsesDomain: org.hosting.usesDomain,
-        hostingDatabase: org.hosting.database,
         hostingTunnel: org.hosting.tunnel,
-        hostingGitBranch: org.hosting.gitBranch,
-        hostingBuildPack: org.hosting.buildPack,
         hostingIssuerApps: org.hosting.issuerApps,
-        hostingAccessEmails: org.hosting.accessEmails,
-        hostingAppEnv: org.hosting.appEnv ?? {},
+        hostingEntries: org.hosting.entries,
         ssoEnabled: org.sso.enabled,
         guestsEnabled: org.guests.enabled,
         soloEnabled: org.solo.enabled,
@@ -257,7 +254,10 @@ export function createPostgresDeclaredOrgStore(db) {
     // #71: same place `requireValidBuyer` checks the buyer identity (#67), on
     // both `create` and the merged result of `update`.
     function requireValidHosting(org) {
-        const reason = validateHosting(org.hosting);
+        const reason = validateHosting(org.hosting, {
+            domain: org.domain,
+            locked: lockedHostnames(org, []),
+        });
         if (reason)
             throw new DeclaredOrgError(`hosting invalid: ${reason} (#71)`);
     }

package/dist/store/schema.d.ts

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

package/dist/store/schema.js

@@ -43,11 +43,17 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     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.
+    // values the plan already mints; empty by default. Read only by migration
+    // 0029, which copies it into `hostingEntries`.
     hostingAppEnv: jsonb('hosting_app_env')
         .notNull()
         .default({})
         .$type(),
+    // HostingConfig.entries (org.ts): one entry per app. Replaces the flat
+    // hosting_database, hosting_git_branch, hosting_build_pack,
+    // hosting_access_emails and hosting_app_env columns, which stay for an older
+    // reader and are no longer written.
+    hostingEntries: jsonb('hosting_entries').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.8.0",
+  "version": "0.10.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",