@wtfalch/foundry 0.42.1 → 0.44.0

package/dist/plan/executor.d.ts

@@ -1,7 +1,8 @@
 import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/postmaster';
 import { type CallsSfuUrls } from '../calls-sfu.js';
-import type { DeclaredOrg, HostingBuildPack } from '../org.js';
+import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
+import { type BlueGreenServer, type BlueGreenSubject } from './blue-green.js';
 import { type BrokerPort } from './broker-entries.js';
 import { type DeployHealthRuntime } from './deploy-health.js';
 import { type StepAction } from './diff.js';
@@ -16,6 +17,9 @@ import { type OwnServicesPort } from './own-services.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 import type { EdgePortName } from './platform-org.js';
 import type { RequestHeaderPort } from './platform-providers.js';
+import { type ReleaseContext, type ReleaseHost } from './release-host.js';
+import type { WorkerAppDatabasePort } from './worker-app-database.js';
+import { type KeysCustodyPort, type WorkerAppPort } from './worker-app.js';
 export declare function coolifyProjectMark(org: Pick<DeclaredOrg, 'id'>): string;
 /**
  * The Coolify calls this executor makes, shaped to match
@@ -103,6 +107,8 @@ export interface CoolifyPort {
      */
     getApplication(uuid: string): Promise<{
         uuid: string;
+        /** Coolify's name for the app; a blue/green entry's recorded app is its blue copy only when this is the blue name. */
+        name?: string;
         status?: string;
         custom_labels?: string | null;
         settings?: {
@@ -831,6 +837,8 @@ export interface ZitadelPort {
         appType: 'web' | 'native';
         redirectUris: string[];
         postLogoutRedirectUris: string[];
+        /** `jwt` for an entry with `uses.auth.mcp` (providers 0.11.0). Omitted: opaque. */
+        accessTokenType?: 'jwt' | 'opaque';
     }): Promise<{
         appId: string;
         clientId: string;
@@ -1116,6 +1124,25 @@ export interface ZitadelPort {
      * reports no longer live is never attempted at all.
      */
     listLoginClientPats(orgId: string, userId: string): Promise<string[]>;
+    /**
+     * C3: mints a read-only directory credential for one ZITADEL organisation (the company's
+     * customers): a machine user with only the read-only organisation role, and a fresh PAT.
+     * Idempotent on the user by `userName`; every PAT the user already holds is revoked before the
+     * new one is minted, so a rerun leaves exactly one live token (like
+     * {@link mintLoginClientMachineUser}). The caller holds the token and writes it to Boule's env;
+     * it never reaches an error, a log or a recorded id. Optional: a host without it gets the
+     * customers directory reported blocked. `zitadel-machine-user.ts` is the real implementation.
+     */
+    mintOrgDirectoryReader?(orgId: string, input: {
+        userName: string;
+        name: string;
+    }): Promise<{
+        userId: string;
+        token: string;
+        patId: string;
+    }>;
+    /** C3: revokes every PAT of the directory reader, so a company that turns customers off leaves no live credential. A PAT already gone is not an error. */
+    revokeOrgDirectoryReader?(orgId: string, userId: string): Promise<void>;
     /**
      * #267: adds the org's own company login host to the ZITADEL instance's
      * trusted domains (`@wtfalch/providers`' `ZitadelClient.ensureTrustedDomain`)
@@ -1173,6 +1200,21 @@ export interface ZitadelPort {
      * `createOidcApp` and `createOidcAppWithSecret` send it on themselves.
      */
     updateOidcAppIdTokenUserinfoAssertion?(orgId: string, projectId: string, appId: string): Promise<boolean>;
+    /**
+     * Auth ADR 0002: an existing sign-in app issues JWT access tokens and holds
+     * every `redirectUris` entry (`@wtfalch/providers` 0.11.0). Resolves `true`
+     * when it wrote, `false` when nothing differed. Optional, with
+     * {@link ZitadelPort.ensureAccessTokenLifetime}: a host whose client lacks
+     * either gets every `uses.auth.mcp` reported blocked
+     * (`FoundryPlanApplyOptions.zitadelMcp`).
+     */
+    ensureOidcAppMcpAccess?(orgId: string, projectId: string, appId: string, want: {
+        redirectUris: string[];
+    }): Promise<boolean>;
+    /** The instance-wide access-token lifetime, in seconds. Resolves `{ changed }`. */
+    ensureAccessTokenLifetime?(seconds: number): Promise<{
+        changed: boolean;
+    }>;
 }
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
@@ -1536,6 +1578,11 @@ export interface PlatformOrgPortSource {
     /** The platform's shared sign-in host, or `null` when none is declared. */
     authHostname?(): Promise<string | null>;
 }
+/**
+ * C3: mints the Archon credential for one org's Boule and returns the secret. Every call rotates the
+ * org's credential (the old secret stays valid one more hour) or issues the first.
+ */
+export type BouleArchonCredentialMinter = (orgId: OrgId) => Promise<string>;
 export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
     /**
@@ -1662,6 +1709,29 @@ export interface FoundryStepExecutorPorts {
      * sets `FoundryPlanApplyOptions.edgeWorkers`).
      */
     workers?: WorkersPort;
+    /**
+     * ADR 0002: deploys and routes an entry's `workerApp` -- see
+     * {@link WorkerAppPort}. Optional the same way `workers` is: without it the
+     * plan reports each Worker app blocked (the host also sets
+     * `FoundryPlanApplyOptions.workerApps`).
+     */
+    workerApps?: WorkerAppPort;
+    /** ADR 0002: the keys custody Worker, for a `keysCustody` secret of a Worker app. */
+    workerAppKeys?: KeysCustodyPort;
+    /**
+     * C3: mints the credential an org's Boule reaches Archon with (org-scoped; `orgs:request` and
+     * `orgs:read` for that org). Archon implements it. Every call rotates the credential (the old secret
+     * stays valid one more hour) and credentials expire after 365 days, so foundry calls it only when none
+     * was pushed or the recorded push time is 335 days old. It reaches Boule's env as `ARCHON_CREDENTIAL` and nowhere else. Without it the host
+     * writes no Archon credential and the plan says so.
+     */
+    mintBouleArchonCredential?: BouleArchonCredentialMinter;
+    /**
+     * C2: the Hyperdrive config, the release's `migrations.json` and the SQL runner behind the tunnel,
+     * for a Worker app with `workerApp.database`. Without it the plan reports that entry blocked
+     * (the host also sets `FoundryPlanApplyOptions.workerAppDatabase`).
+     */
+    workerAppDatabase?: WorkerAppDatabasePort;
     /**
      * Hands a just-minted, one-time secret (today: an API app's
      * `clientSecret`) to the host, immediately after the provider returns it
@@ -1843,6 +1913,10 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private executeScoped;
     /** Whether `ensureOwnAuthMailToken` can mint: the same two inputs it blocks on. */
     ownMailKeyMintable(): boolean;
+    /** C3: whether the ZITADEL port can mint and revoke a customers directory credential. */
+    customersDirectoryAvailable(): boolean;
+    /** C3: whether the host supplied `mintBouleArchonCredential`. */
+    bouleArchonCredentialAvailable(): boolean;
     /** Whether the held keys can store a new company's sign-in database CA and certificate (#746). */
     ownSigninDbKeysPuttable(): boolean;
     /** Whether the host supplies the backup bucket the sign-in database dumps into (#746). */
@@ -1944,6 +2018,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * "Declared changes apply" nothing is marked done until the
      * live state actually matches it.
      */
+    private workerAppDeps;
     private cloudflareWorker;
     /**
      * Makes the no-Worker routes recorded for an entry match `patterns`: deletes
@@ -2003,6 +2078,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * nothing: the next apply finds the account by username and mints a new code.
      */
     private zitadelOwner;
+    /** `plan/mcp.ts`: the entry's MCP audience project. */
+    private zitadelMcpProject;
+    /** `plan/mcp.ts`: JWT access tokens and the broker's callback on the entry's app. */
+    private zitadelMcpAccess;
+    /** `plan/mcp.ts`: the instance access-token lifetime. */
+    private zitadelAccessTokenLifetime;
     /**
      * Switches on "user info inside the ID token" for each live sign-in app
      * the planner named. An app's marker (its ZITADEL app id) is recorded and
@@ -2096,7 +2177,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     /**
      * `plan/diff.ts`'s `planCustomers` (plan gap A9): the org's customers sign
      * in through a second ZITADEL org, `<slug> customers`, with
-     * self-registration on and a grant to the org's app project. Staff stay in
+     * self-registration as `customers.signUp` says (off by default) and a grant to the org's app project. Staff stay in
      * the org's own invite-only ZITADEL org. The space keeps the name apart from
      * every issuer org, which is named by a slug and a slug has no spaces. Every call here is idempotent, so
      * a re-run after a crash finishes the job.
@@ -2141,6 +2222,34 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * actually be created on.
      */
     private resolveServer;
+    /**
+     * Contract C3: every usable, reachable Coolify server, the org's primary first. The primary is
+     * {@link resolveServer}'s (databases and single-copy services stay on it, unchanged). A server that is
+     * down is named in `down` and left out of `servers`; it is not an error.
+     */
+    resolveServers(org: DeclaredOrg, context: StepExecutionContext): Promise<{
+        primary: {
+            uuid: string;
+        };
+        servers: Array<{
+            uuid: string;
+        }>;
+        down: string[];
+    }>;
+    /**
+     * The release runner's outside calls for one blue/green entry (`plan/release-host.ts`), or `null` while its
+     * blue copy is not recorded. The health token is only read here, never minted.
+     */
+    releaseHost(org: DeclaredOrg, subject: BlueGreenSubject, context: ReleaseContext, renew: () => Promise<void>): ReleaseHost | null;
+    /** Every server Coolify lists with whether it is usable and reachable, for the planner. */
+    blueGreenServers(): Promise<BlueGreenServer[]>;
+    /**
+     * The blue/green steps (`plan/blue-green.ts`): `bluegreen` makes the apps and the balancer on one server,
+     * `bluegreen-lb` only writes the balancer's weights, `bluegreen-connector` runs the tunnel's connector on a
+     * server. A server that went down since the plan is skipped by `bluegreen-connector`'s caller, not here:
+     * a step for it fails, which the next plan reports instead.
+     */
+    private coolifyBlueGreen;
     private coolifyApp;
     /**
      * #75: mounts a persistent volume at {@link LOG_DIR} on the app, unless one
@@ -2891,6 +3000,27 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
+    /**
+     * C3: the Archon credential of an org's Boule. Archon's mint rotates on every call, so it is called only
+     * when none was pushed or the recorded push time (no secret) is 335 days old. Otherwise the held value is
+     * written again unchanged. The secret is held first; the caller records `pushedAt` only after the env write
+     * succeeded, so a failed hold or a failed push is mended by the next apply minting again. Errors name no secret.
+     */
+    private ensureBouleArchonCredential;
+    /**
+     * C3: the read-only credential for the company's customers organisation. Held first. Minting revokes every
+     * earlier token of the machine user, so a hold that failed is repaired by the next apply minting again and
+     * leaves one live token. `null` while the customers organisation is not recorded yet.
+     */
+    private ensureCustomersDirectoryCredential;
+    /** `put`, tried up to {@link BOULE_CREDENTIAL_ATTEMPTS} times; true once one attempt succeeds. The cause is dropped. */
+    private holdWithRetry;
+    /**
+     * C3: customers switched off. Revokes the directory credential's tokens first, then removes the customers
+     * env from Boule, then forgets the held value and the user id. Each step is repeated safely, so a run that
+     * died halfway is finished by the next. Returns true when Boule's env changed.
+     */
+    private dropCustomersCredential;
     /**
      * Gives Boule `LETTERMINT_API_TOKEN`: the platform's held key for an org on
      * the platform's own apex, else the org's `<slug>-app` token through the
@@ -3009,6 +3139,8 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private ownSfu;
     private jobsRegistration;
+    /** The blue/green database route (`plan/remote-database.ts`). */
+    private remoteDatabaseRoute;
     /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
     private deliverWithRetry;
     private cloudflareTunnel;