@wtfalch/foundry 0.43.0 → 0.44.1

package/dist/plan/zitadel-machine-user.d.ts

@@ -76,6 +76,18 @@ export declare class ZitadelLoginClientRoleConflictError extends Error {
     readonly roles: readonly string[];
     constructor(userId: string, roles: readonly string[]);
 }
+/** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
+export declare const ORG_DIRECTORY_READER_ROLE = "ORG_OWNER_VIEWER";
+/**
+ * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
+ * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
+ * would widen access nobody asked for. A person resolves it by hand.
+ */
+export declare class ZitadelDirectoryRoleConflictError extends Error {
+    readonly userId: string;
+    readonly roles: readonly string[];
+    constructor(userId: string, roles: readonly string[]);
+}
 export interface ZitadelMinterOptions {
     /** The new instance's base URL, e.g. `https://auth.companyincluded.com`. */
     url: string;
@@ -84,4 +96,4 @@ export interface ZitadelMinterOptions {
     fetchImpl?: typeof fetch;
     instanceHost?: string;
 }
-export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName'>;
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'mintOrgDirectoryReader' | 'revokeOrgDirectoryReader'>;

package/dist/plan/zitadel-machine-user.js

@@ -84,6 +84,23 @@ export class ZitadelLoginClientRoleConflictError extends Error {
         this.name = 'ZitadelLoginClientRoleConflictError';
     }
 }
+/** The read-only organisation role a directory reader holds. It lists the organisation's users and changes nothing. */
+export const ORG_DIRECTORY_READER_ROLE = 'ORG_OWNER_VIEWER';
+/**
+ * C3: thrown by `mintOrgDirectoryReader` when the user already exists with an organisation role other
+ * than the read-only one. That user was not made by foundry; granting it more or handing out its PAT
+ * would widen access nobody asked for. A person resolves it by hand.
+ */
+export class ZitadelDirectoryRoleConflictError extends Error {
+    userId;
+    roles;
+    constructor(userId, roles) {
+        super(`ZITADEL machine user ${userId} already exists with organisation role(s) [${roles.join(', ') || 'none'}], not only [${ORG_DIRECTORY_READER_ROLE}] -- refusing to reuse it as a directory reader`);
+        this.userId = userId;
+        this.roles = roles;
+        this.name = 'ZitadelDirectoryRoleConflictError';
+    }
+}
 export function createZitadelAdminMinter(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     async function call(method, path, body, orgId) {
@@ -263,7 +280,70 @@ export function createZitadelAdminMinter(options) {
         }
         return { userId };
     }
+    /**
+     * C3: a machine user inside one ZITADEL organisation with the read-only org role
+     * {@link ORG_DIRECTORY_READER_ROLE} and nothing else, plus a fresh PAT. Every PAT it already holds is
+     * revoked first, so a rerun leaves exactly one live token. An existing user that holds any other
+     * org role is refused, not reused. The calls follow ZITADEL's published v1 management API and have
+     * not been run against a live instance.
+     */
+    async function mintOrgDirectoryReader(orgId, input) {
+        const found = await call('POST', '/management/v1/users/_search', {
+            queries: [
+                { userNameQuery: { userName: input.userName, method: 'TEXT_QUERY_METHOD_EQUALS' } },
+            ],
+        }, orgId);
+        const existing = found.result?.[0]?.id;
+        let userId = existing;
+        if (!userId) {
+            const created = await call('POST', '/management/v1/users/machine', {
+                userName: input.userName,
+                name: input.name,
+                accessTokenType: 'ACCESS_TOKEN_TYPE_BEARER',
+            }, orgId);
+            userId = typeof created.userId === 'string' ? created.userId : undefined;
+        }
+        if (!userId)
+            throw new Error('ZITADEL did not return the machine user id');
+        if (existing) {
+            const members = await call('POST', '/management/v1/orgs/me/members/_search', { queries: [{ userIdQuery: { userId } }] }, orgId);
+            const roles = (members.result ?? [])
+                .filter((m) => m.userId === userId)
+                .flatMap((m) => m.roles ?? []);
+            if (roles.some((role) => role !== ORG_DIRECTORY_READER_ROLE)) {
+                throw new ZitadelDirectoryRoleConflictError(userId, roles);
+            }
+        }
+        try {
+            await call('POST', '/management/v1/orgs/me/members', { userId, roles: [ORG_DIRECTORY_READER_ROLE] }, orgId);
+        }
+        catch (e) {
+            if (!(e instanceof ZitadelHttpError && e.status === 409))
+                throw e;
+        }
+        await revokeAllPats(orgId, userId);
+        const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, orgId);
+        const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
+        if (typeof pat.token !== 'string' || pat.token === '' || !patId) {
+            throw new Error(`ZITADEL returned no token for machine user ${userId}`);
+        }
+        return { userId, token: pat.token, patId };
+    }
+    /** Deletes every PAT of a user; a PAT already gone (404) is the outcome wanted. */
+    async function revokeAllPats(orgId, userId) {
+        for (const patId of await listPats(orgId, userId)) {
+            try {
+                await call('DELETE', `/management/v1/users/${userId}/pats/${patId}`, undefined, orgId);
+            }
+            catch (e) {
+                if (!(e instanceof ZitadelHttpError && e.status === 404))
+                    throw e;
+            }
+        }
+    }
     return {
+        mintOrgDirectoryReader,
+        revokeOrgDirectoryReader: revokeAllPats,
         mintAdminMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_OWNER').then(({ userId, token }) => ({ userId, token })),
         mintLoginClientMachineUser: (orgId, input) => mintMachineUser(orgId, input, 'IAM_LOGIN_CLIENT'),
         // #216 round 2: lets the caller (`platform-providers.ts`) re-check, after

package/dist/requested-changes.d.ts

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, MailMode, OrgId } from './org.js';
+import { type DeclaredOrg, type MailMode, type OrgId } from './org.js';
 import type { PlanDetail } from './plan/diff.js';
 /**
  * The whitelist of `DeclaredOrg` fields a company's own Boule can request a
@@ -15,13 +15,22 @@ import type { PlanDetail } from './plan/diff.js';
  * lowering or leaving a limit unchanged -- raising either one needs
  * approval too, until a billing field exists to say what the raise costs.
  */
-export type RequestableField = 'calls' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier';
+export type RequestableField = 'calls' | 'customers' | 'storageLimit' | 'aiLimit' | 'domain' | 'mailTier';
 export declare const REQUESTABLE_FIELDS: readonly RequestableField[];
 /** Turn the org's own calls Matrix stack (`org.ts`'s `CallsConfig.enabled`) on or off. */
 export interface CallsChange {
     field: 'calls';
     enabled: boolean;
 }
+/**
+ * Turn the org's customers on or off and let them register themselves
+ * (`org.ts`'s `CustomersConfig`). `signUp` needs `enabled`: the request is refused otherwise.
+ */
+export interface CustomersChange {
+    field: 'customers';
+    enabled: boolean;
+    signUp: boolean;
+}
 /** Change the org's own spend limit on Files (`org.ts`'s `StorageConfig`). */
 export interface StorageLimitChange {
     field: 'storageLimit';
@@ -48,7 +57,7 @@ export interface MailTierChange {
  * {@link RequestableField}. `classifyChange` and the store both switch on
  * `.field`.
  */
-export type RequestedChangeValue = CallsChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange;
+export type RequestedChangeValue = CallsChange | CustomersChange | StorageLimitChange | AiLimitChange | DomainChange | MailTierChange;
 /**
  * `auto`: nothing further is required -- archon may carry the request
  * straight into a plan and apply it. `approval`: a human must approve the

package/dist/requested-changes.js

@@ -1,5 +1,7 @@
+import { validateCustomers } from './org.js';
 export const REQUESTABLE_FIELDS = [
     'calls',
+    'customers',
     'storageLimit',
     'aiLimit',
     'domain',
@@ -27,6 +29,8 @@ function applyRequestedChange(org, change) {
     switch (change.field) {
         case 'calls':
             return { ...org, calls: { ...org.calls, enabled: change.enabled } };
+        case 'customers':
+            return { ...org, customers: { enabled: change.enabled, signUp: change.signUp } };
         case 'storageLimit':
             return {
                 ...org,
@@ -69,6 +73,15 @@ function isLimitRaise(before, after) {
         return true;
     return BigInt(after) > BigInt(before);
 }
+/** Throws {@link RequestedChangeError} unless both switches are booleans and sign-up comes with customers on. */
+function validateCustomersChange(change) {
+    if (typeof change.enabled !== 'boolean' || typeof change.signUp !== 'boolean') {
+        throw new RequestedChangeError('customers needs enabled and signUp, both true or false');
+    }
+    if (change.signUp && !change.enabled) {
+        throw new RequestedChangeError('customers.signUp needs customers.enabled');
+    }
+}
 /**
  * `auto` when `change` is small and safe (`calls`, and `storageLimit`/
  * `aiLimit` in the lowering or unchanged direction), the plan it causes has
@@ -102,6 +115,14 @@ export function classifyChange(org, change, plan) {
     if (!REQUESTABLE_FIELDS.includes(change.field)) {
         throw new RequestedChangeError(`'${change.field}' is not a requestable field`);
     }
+    if (change.field === 'customers') {
+        validateCustomersChange(change);
+        // The org after the change must still pass the rule apply checks, for example open registration
+        // on a hosting entry needs customers on; otherwise the request is stored and fails at apply.
+        const invalid = validateCustomers(applyRequestedChange(org, change));
+        if (invalid)
+            throw new RequestedChangeError(invalid);
+    }
     if (plan?.plannedSteps.some((planned) => planned.step.destroys || planned.step.migrates)) {
         return 'approval';
     }
@@ -110,6 +131,7 @@ export function classifyChange(org, change, plan) {
         return 'approval';
     switch (change.field) {
         case 'calls':
+        case 'customers':
             return 'auto';
         case 'storageLimit':
             return isLimitRaise(org.storage.limitBytes, change.limitBytes) ||

package/dist/store/postgres.js

@@ -1,6 +1,6 @@
 import { and, asc, desc, eq, inArray, isNull, ne, sql } from 'drizzle-orm';
-import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, validateBlueGreen, validateBuyerIdentity, validateCalls, validateDomain, validateDomainClaim, validateHosting, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, } from '../org.js';
-import { lockedHostnames } from '../plan/locked-hostnames.js';
+import { APP_ENTRY_KEY, DEFAULT_MAIL_APPS, DEFAULT_NO_REPLY_LOCAL_PART, validateBlueGreen, validateBuyerIdentity, validateCalls, validateCustomers, validateDomain, validateDomainClaim, validateHosting, validateMail, validateOwners, validateServices, validateSignIn, validateSite, validateVersionPin, } from '../org.js';
+import { hostingNames } from '../plan/locked-hostnames.js';
 import { findNameClashes, nameClashMessage } from '../plan/org-names.js';
 import { validatePlatform } from '../platform.js';
 import { releaseActionSchema } from '../release/state.js';
@@ -149,6 +149,10 @@ function rowToOrg(row) {
             : {}),
         // Omitted while off.
         ...(row.signInInApp ? { signIn: { inApp: true } } : {}),
+        // Omitted while off.
+        ...(row.customersEnabled || row.customersSignUp
+            ? { customers: { enabled: row.customersEnabled, signUp: row.customersSignUp } }
+            : {}),
         // Omitted while unset. Validated on read: a stored value is not trusted.
         ...(row.versionPin ? { versionPin: readVersionPin(row) } : {}),
         site: { enabled: row.siteEnabled, usesDomain: row.siteUsesDomain },
@@ -202,6 +206,8 @@ function orgToRow(org) {
         callsVersionPinMas: org.calls.versionPin?.mas ?? null,
         issuerUsesDomain: org.issuer.usesDomain,
         signInInApp: org.signIn?.inApp ?? false,
+        customersEnabled: org.customers?.enabled ?? false,
+        customersSignUp: org.customers?.signUp ?? false,
         servicesOwn: org.services?.own ?? false,
         servicesSfuSlot: org.services?.sfuSlot ?? null,
         versionPin: org.versionPin && Object.keys(org.versionPin).length > 0 ? org.versionPin : null,
@@ -351,10 +357,7 @@ 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, {
-            domain: org.domain,
-            locked: lockedHostnames(org, []),
-        });
+        const reason = validateHosting(org.hosting, hostingNames(org, []));
         if (reason)
             throw new DeclaredOrgError(`hosting invalid: ${reason} (#71)`);
     }
@@ -408,6 +411,9 @@ export function createPostgresDeclaredOrgStore(db) {
         const signInReason = validateSignIn(org);
         if (signInReason)
             throw new DeclaredOrgError(`signIn invalid: ${signInReason}`);
+        const customersReason = validateCustomers(org);
+        if (customersReason)
+            throw new DeclaredOrgError(`customers invalid: ${customersReason}`);
         const slot = org.services?.sfuSlot ?? null;
         if (slot === null)
             return;

package/dist/store/schema.d.ts

@@ -372,6 +372,40 @@ export declare const declaredOrgs: import("drizzle-orm/pg-core").PgTableWithColu
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        customersEnabled: import("drizzle-orm/pg-core").PgColumn<{
+            name: "customers_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;
+        }, {}, {}>;
+        customersSignUp: import("drizzle-orm/pg-core").PgColumn<{
+            name: "customers_sign_up";
+            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;
+        }, {}, {}>;
         versionPin: import("drizzle-orm/pg-core").PgColumn<{
             name: "version_pin";
             tableName: "foundry_declared_orgs";

package/dist/store/schema.js

@@ -40,6 +40,9 @@ export const declaredOrgs = pgTable('foundry_declared_orgs', {
     servicesSfuSlot: integer('services_sfu_slot'),
     // SignInConfig.inApp (org.ts); migrations/0054.
     signInInApp: boolean('signin_in_app').notNull().default(false),
+    // CustomersConfig (org.ts); migrations/0057.
+    customersEnabled: boolean('customers_enabled').notNull().default(false),
+    customersSignUp: boolean('customers_sign_up').notNull().default(false),
     // VersionPin (org.ts): null follows the platform. `migrations/0053_org_version_pin.sql`.
     versionPin: jsonb('version_pin').$type(),
     // SiteConfig (org.ts, T10). A brand new org has no cms site.

package/dist/worker-app-config.d.ts

@@ -0,0 +1,151 @@
+import type { HostingConfig, HostingEntry } from './org.js';
+/**
+ * A hosting entry that runs as a Cloudflare Worker with Durable Objects and,
+ * optionally, Containers (foundry ADR 0002, `docs/adr/0002-worker-app-hosting-option.md`).
+ * The entry has no Coolify app, no volumes and no gate. The org's repo CI builds
+ * the module and the image; foundry fetches the module, checks its sha256 and
+ * uploads it, and never builds or checks out source.
+ */
+export interface WorkerAppConfig {
+    /** Built module (https URL) and its sha256, as in `WorkerConfig`. */
+    artifactUrl: string;
+    artifactSha256: string;
+    /** Defaults to `WORKER_COMPATIBILITY_DATE`. Flags come from an allowlist in foundry. */
+    compatibilityDate?: string;
+    compatibilityFlags?: 'nodejs_compat'[];
+    durableObjects: {
+        /** Binding name -> exported class. */
+        classes: Record<string, string>;
+        /** Append-only. Foundry sends only tags not yet applied. */
+        migrations: {
+            tag: string;
+            newSqliteClasses?: string[];
+            deletedClasses?: string[];
+            renamedClasses?: {
+                from: string;
+                to: string;
+            }[];
+        }[];
+    };
+    containers?: {
+        /** Must be a durable object class above. */
+        className: string;
+        /** Image pushed by the app's CI to the platform registry, pinned by digest. */
+        image: {
+            repository: string;
+            digest: `sha256:${string}`;
+        };
+        instanceType: 'lite' | 'basic' | 'standard-1' | 'standard-2' | 'standard-3' | 'standard-4';
+        maxInstances: number;
+    }[];
+    /**
+     * Name -> source. Delivered as Worker secrets. `keysCustody` (named
+     * `KEYS_CREDENTIAL`, at most one) delivers a keys custody Worker credential
+     * for the app's own host id (`workerAppHostId`), with `KEYS_URL` as a var.
+     * `keys` (an issued API key) is refused: custody does not accept one.
+     */
+    secrets?: Record<string, {
+        from: 'generated';
+    } | {
+        from: 'keysCustody';
+    }>;
+    /** True delivers the entry's sign-in env as Worker vars. Needs `uses.auth`. */
+    authEnv?: boolean;
+    /**
+     * A Postgres database in the org's Coolify database, reached by the Worker
+     * through a Hyperdrive config bound as `HYPERDRIVE` (connect as `<db>_rt`).
+     * The release may carry `migrations.json` (`[{ id, sql }]`, ordered); foundry
+     * applies the unapplied ids before the Worker deploys. `appendOnly` names
+     * tables the runtime role may insert into and read but never update, delete
+     * or truncate. `migrationsSha256` (64 lowercase hex) pins the release's
+     * `migrations.json`: required when the release has one, and foundry refuses
+     * to parse bytes whose sha256 differs. Omit it only for a release with no
+     * `migrations.json`; one that has the file is then refused.
+     */
+    database?: {
+        appendOnly?: string[];
+        migrationsSha256?: string;
+    };
+    /** Plain vars. Never secrets. */
+    vars?: Record<string, string>;
+    /** Host label: '@' for the apex, else a label. Exact host, never a wildcard. */
+    host: string;
+}
+/** The compatibility flags a Worker app may ask for. */
+export declare const WORKER_APP_COMPATIBILITY_FLAGS: ReadonlySet<string>;
+export declare const WORKER_APP_INSTANCE_TYPES: ReadonlySet<string>;
+/** The most instances one container class may scale to. */
+export declare const WORKER_APP_MAX_INSTANCES = 100;
+/** The secret that carries a `keysCustody` source: the custody Worker credential. */
+export declare const WORKER_APP_KEYS_SECRET = "KEYS_CREDENTIAL";
+export declare const WORKER_APP_KEYS_URL_VAR = "KEYS_URL";
+/**
+ * Names foundry writes into a Worker app's environment itself, so a
+ * declaration may not use them as a binding, secret or var.
+ */
+export declare const WORKER_APP_RESERVED_NAMES: RegExp;
+/** True when the entry needs the org's Postgres database: a Coolify app with `database`, or a Worker app with `workerApp.database`. */
+export declare const entryHasDatabase: (entry: {
+    database: boolean;
+    workerApp?: {
+        database?: unknown;
+    } | undefined;
+}) => boolean;
+/** The Hyperdrive binding of a Worker app with `database`. */
+export declare const WORKER_APP_HYPERDRIVE_BINDING = "HYPERDRIVE";
+/** The most tables `database.appendOnly` may name, and the shape of one name (`table` or `schema.table`). */
+export declare const WORKER_APP_APPEND_ONLY_MAX = 100;
+/** Hex characters of the org id's sha256 in a host id. */
+export declare const WORKER_APP_HOST_ID_HASH_LENGTH = 12;
+/**
+ * The custody host id of a Worker app: `app-<12 hex of sha256(org id)>-<entry key>`.
+ * It derives from the org id, never the slug, so a slug rename keeps it, and
+ * two orgs cannot share one (their hashes differ). The entry key is unique
+ * within an org. Null when the result breaks the custody pattern
+ * `^app-[a-z0-9]+(-[a-z0-9]+)*$`, 64 characters, or ends in `-next`.
+ */
+export declare function workerAppHostId(orgId: string, entryKey: string): string | null;
+/** The script name ends in this; the entry key's budget against Cloudflare's 63 characters follows from it. */
+export declare const WORKER_APP_NAME_SUFFIX = "-app";
+/**
+ * Checks an artifact reference: an https URL with no userinfo, query or
+ * fragment (those end up verbatim in recorded scope ids) and a lowercase hex
+ * sha256. Shared by `worker` and `workerApp`.
+ */
+export declare function validateArtifact(at: string, artifactUrl: string, sha256: string, repo?: string | null): string | null;
+/**
+ * The one exact name a Worker app is served at: `<host>.<domain>` or the apex
+ * on the org's own domain, else `<slug>-<key>.oikos.host` (one label under
+ * `oikos.host`, so the free Universal certificate covers it), and
+ * `<slug>.oikos.host` for the entry keyed `app`.
+ */
+export declare function workerAppHostnameOf(org: {
+    slug: string;
+    domain: string | null;
+    usesDomain: boolean;
+}, key: string, host: string): string;
+/**
+ * The Durable Object classes the migrations leave behind, folded in order:
+ * created, then removed, then renamed. A rename of a class that does not exist
+ * at that point is an error.
+ */
+export declare function foldMigrationClasses(migrations: WorkerAppConfig['durableObjects']['migrations']): {
+    classes: Set<string>;
+} | {
+    error: string;
+};
+/**
+ * `workerApp`: exclusive with `worker` and a Coolify repo, no Coolify-only
+ * setting, a Durable Object and container declaration Cloudflare will accept,
+ * names that cannot clash with what foundry delivers, and one exact host.
+ * `null` when valid. Whether a migration was already applied is a fact of the
+ * live system; the planner checks that (`plan/worker-app.ts`).
+ */
+export declare function validateEntryWorkerApp(entry: HostingEntry, hosting: HostingConfig, names?: {
+    domain: string | null;
+    locked: ReadonlySet<string>;
+    /** Without it the domain-less host `<slug>-<key>.oikos.host` cannot be checked. */
+    slug?: string;
+    /** True when the site is served at the apex of the org's domain. */
+    siteOwnsApex?: boolean;
+}): string | null;