@wtfalch/foundry 0.32.0 → 0.34.0

package/dist/plan/executor.d.ts

@@ -12,8 +12,10 @@ import { type EdgePlatformTunnels, type TunnelPort } from './edge-tunnels.js';
 import { type EdgePlatformZones, type ZonePort } from './edge-zones.js';
 import { type LoginHostBindingsPort } from './login-host.js';
 import { type MailCopyPort } from './mail-copy.js';
+import { type OwnServicesPort } from './own-services.js';
 import type { DestroyTarget, StepDestroyer, StepExecutionContext, StepExecutor } from './plan-apply.js';
 import type { EdgePortName } from './platform-org.js';
+export declare function coolifyProjectMark(org: Pick<DeclaredOrg, 'id'>): string;
 /**
  * The Coolify calls this executor makes, shaped to match
  * `@wtfalch/providers/coolify`'s `CoolifyClient` method-for-method — a real
@@ -36,6 +38,12 @@ export interface CoolifyPort {
         name: string;
         description?: string | null;
     } | null>;
+    /** A project's environments (`CoolifyClient.listEnvironments`), read-only. */
+    listEnvironments(projectUuid: string): Promise<Array<{
+        id: number;
+        uuid: string;
+        name: string;
+    }>>;
     createProject(name: string, description?: string): Promise<{
         uuid: string;
     }>;
@@ -100,6 +108,9 @@ export interface CoolifyPort {
         custom_network_aliases?: string | null;
         health_check_enabled?: boolean;
         ports_exposes?: string;
+        /** Coolify's own record of the resource limits (`plan/own-limits.ts`). */
+        limits_memory?: string;
+        limits_cpus?: string;
     }>;
     createGithubAppApplication(input: {
         project_uuid: string;
@@ -155,6 +166,8 @@ export interface CoolifyPort {
         uuid: string;
         internal_db_url?: string;
         status?: string;
+        limits_memory?: string;
+        limits_cpus?: string;
     }>;
     /**
      * Every database Coolify holds. `coolifyDatabase` finds its own by name and
@@ -878,10 +891,22 @@ export interface ZitadelPort {
         givenName: string;
         familyName: string;
         email: string;
-    }, urlTemplate?: string): Promise<{
+        username?: string;
+    }, urlTemplate?: string, returnCode?: boolean): Promise<{
         userId: string;
         created: boolean;
+        inviteCode?: string;
     }>;
+    /** Adds a domain to the org. Idempotent: a domain already on the org is a no-op. */
+    addOrgDomain(orgId: string, domain: string): Promise<void>;
+    /** Makes a domain already on the org its primary one. Idempotent: no-op when it already is. */
+    setPrimaryOrgDomain(orgId: string, domain: string): Promise<void>;
+    setUserMetadata(orgId: string, userId: string, key: string, value: string): Promise<void>;
+    getUserMetadata(orgId: string, userId: string, key: string): Promise<string | null>;
+    findUserByEmail(orgId: string, email: string): Promise<{
+        userId: string;
+        state: string;
+    } | null>;
     /**
      * Adds a role to a project. Idempotent: a role that already exists is not
      * an error. `@wtfalch/providers`' `ZitadelClient` has no project-role API,
@@ -1125,6 +1150,16 @@ export interface ZitadelListAppsRawApp {
  * an operator's `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` pins.
  */
 export interface FilesOrganisationPort {
+    /**
+     * An own files host's R2 storage key, sent to that host once (the files route
+     * `PUT /v1/manage/r2-credentials`). Absent on a port that cannot: the own R2 key step is then
+     * blocked by name. The same pair may be sent again after a failed send.
+     */
+    storeR2Credentials?(input: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        tokenId: string;
+    }): Promise<void>;
     provisionOrganisation(input: {
         organisationId: string;
         ceilingBytes: string | null;
@@ -1428,6 +1463,12 @@ export interface PlatformOrgPortSource {
 }
 export interface FoundryStepExecutorPorts {
     coolify: CoolifyPort;
+    /**
+     * Ports for the instances an own org (`services.own`) runs itself. Without
+     * it, a step for an own org is refused rather than run against the shared
+     * services, and the planner reports the org's own services blocked.
+     */
+    ownServices?: OwnServicesPort;
     zitadel: ZitadelPort;
     mail: MailPort;
     lettermint: LettermintPort;
@@ -1456,6 +1497,16 @@ export interface FoundryStepExecutorPorts {
      * compilation over one dependency nothing else needs.
      */
     mailCopy?: MailCopyPort;
+    /**
+     * Mails an owner's first-sign-in link to their personal address. The link
+     * carries the one-time invite code `inviteOrgOwner` returned, so an error
+     * from `send` must not repeat `link`. Optional: without it the planner
+     * reports each owner's invite as blocked, because the owner's work address
+     * is not a mailbox they can open yet.
+     */
+    ownerInviteMail?: {
+        send(to: string, link: string): Promise<void>;
+    };
     /**
      * #463: the cross-homeserver copy chat's forward re-key needs -- see
      * {@link ChatRekeyPort}'s own doc comment. Optional the same way
@@ -1661,12 +1712,36 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private edgeRateLimits;
     private edgeZones;
     private edgeWriteSlot;
+    /** Secrets this executor minted or was handed; see `StepExecutor.secretsHandled`. */
+    private readonly handledSecrets;
     constructor(ports: FoundryStepExecutorPorts);
+    secretsHandled(): readonly string[];
+    /**
+     * An own org's step runs on a copy of this executor whose ZITADEL, mail,
+     * broker, files, jobs and calls ports are the org's own. A port the org has
+     * not got yet is absent or throws, never the shared one.
+     */
+    private executeScoped;
+    /** Whether `ensureOwnAuthMailToken` can mint: the same two inputs it blocks on. */
+    ownMailKeyMintable(): boolean;
+    /** What the executor's own files dependencies supply, for the planner's blocked lines. */
+    ownFilesDeps(): {
+        keys: boolean;
+        bucket: boolean;
+    };
+    /** Which ports the own files storage key step needs this executor has, for the planner's blocked line. */
+    ownFilesR2Ports(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<{
+        r2Keys: boolean;
+        storeR2Credentials: boolean;
+    }>;
+    /** Whether the host's scoped ports for this own org include a files-organisation port. A held key still missing counts as no port. */
+    ownFilesOrganisationPort(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): Promise<boolean>;
     /** #555: the edge-routed ports this executor was built with itself (they win over edge). */
     ownEdgePorts(): Partial<Record<EdgePortName, boolean>>;
     execute(action: StepAction, context: StepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
+    private run;
     /**
      * `plan/diff.ts`'s `planAccess` (#246): puts a `hosting.access` rule's
      * hostname behind a Cloudflare Access app named
@@ -1765,12 +1840,30 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private teardownWorker;
     private zitadelIssuer;
     /**
-     * `plan/diff.ts`'s `planOwner`: invites the org's owner into its ZITADEL
-     * org by email. Never logs, returns or throws the email itself -- only the
-     * invited user id, handed back as `resourceId` so `runSteps` records it
-     * under `zitadel:owner:<orgId>:<email>`, which is exactly what makes the next
-     * `plan()` call idempotent (`planOwner` plans nothing once that key is
-     * recorded).
+     * `plan/diff.ts`'s `planOrgRegistrationClosed`: closes self-registration on
+     * the recorded ZITADEL org, for an org made before foundry did this or whose
+     * close failed in the issuer step. Recorded only after the close returned.
+     */
+    private zitadelRegistrationClosed;
+    /**
+     * `plan/diff.ts`'s `planOrgDomain`: registers the org's sign-in domain on
+     * its recorded ZITADEL org and makes it primary, for an org whose ZITADEL
+     * org was made before foundry did this. Records the domain only after both
+     * calls succeeded.
+     */
+    private zitadelDomain;
+    /**
+     * `plan/diff.ts`'s `planOwners`: makes the owner's account in the org's
+     * ZITADEL org and mails the first-sign-in link to their personal address.
+     * The account's username is the local part of `mailboxAddress` and its email
+     * is `mailboxAddress`, so the owner signs in as `name@<org domain>`; the
+     * personal address is kept as the `personal_email` metadata. The invite code
+     * ZITADEL returns goes only into that mail. Nothing here logs, returns or
+     * throws the personal address or the code -- only the invited user id, handed
+     * back as `resourceId` so `runSteps` records it under
+     * `zitadel:owner:<orgId>:<email>`, which is exactly what makes the next
+     * `plan()` call idempotent. A failure after the account exists records
+     * nothing: the next apply finds the account by username and mints a new code.
      */
     private zitadelOwner;
     /**
@@ -1992,6 +2085,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
     private bouleBrokerEntry;
     /** The shared tail of both broker-entry steps: read the app's key, write the entry, record what was written. */
     private writeAppBrokerEntry;
+    /**
+     * `null` once the app already has `AUTHZ_PEER_PASSWORD_OPERATOR`: minted only
+     * the first time and never rotated, like {@link ensureAuthCookieSecret}.
+     */
+    private ensurePeerPassword;
+    /** Same rule for the secret Archon's invite form sends to Boule. */
+    private ensureBridgeSecret;
+    private mintIfAbsent;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a
@@ -2131,6 +2232,22 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * (which must never delete the platform's own project) change.
      */
     private ensureOrgLettermintRelay;
+    /**
+     * The company's own sign-in mail token: a Lettermint project `<slug>-auth`
+     * whose token goes to `orgTarget(org).refs.brokerMailKey`, where the broker
+     * and ZITADEL's SMTP settings read it. The platform-wide Lettermint key
+     * stays with the executor and never reaches a company. A held ref is left
+     * alone. Otherwise the mint rule of {@link ensureOrgAppMailToken}: create
+     * the project, restrict the domain, deliver its token, and only then
+     * delete every other `<slug>-auth` project (a token cannot be read back,
+     * so a project without a held token is a leftover). The restriction comes
+     * before the delivery so a failure there leaves no held ref: the next run
+     * starts over instead of skipping it. A failure before the delivery leaves
+     * that project for the next run to delete. Every Lettermint call is
+     * bounded; the token is registered for redaction before anything can throw
+     * with it.
+     */
+    private ensureOwnAuthMailToken;
     /**
      * Deletes a just-minted project from inside a `catch`. A failed delete is
      * dropped so it never replaces the error being rethrown; the orphan is
@@ -2626,6 +2743,54 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private zonePort;
     private jobsPort;
+    /**
+     * `plan/own-diff.ts`'s `planOwnJobs`: the org's own scheduler, in the org's
+     * own project, with the names and the held-key ref of `orgTarget(org)`. The
+     * admin token goes to `jobs:org:<slug>:adminToken` and nowhere else.
+     */
+    private ownJobs;
+    /**
+     * `plan/own-diff.ts`'s `planOwnFiles`: the org's own files host in the
+     * org's own project, trusting the company's issuer `https://auth.<domain>`.
+     * Its ZITADEL project `<slug>-files` and introspection app are made in the
+     * company's instance (`ownServices.zitadelFor`), never the shared one. The
+     * bucket comes from the host's bucket port under the target's name. The
+     * management key goes to `files:org:<slug>:managementKey` and the
+     * introspection secret to `zitadel:org:<slug>:files:introspection`, both
+     * once, and neither is recorded or returned.
+     */
+    private ownFiles;
+    /**
+     * `plan/own-diff.ts`'s `planOwnFilesR2`: the storage key of the org's own files bucket. A token
+     * recorded as undelivered is deleted first (its secret cannot be read back, so it can never be
+     * finished), then one is minted, registered as a secret, recorded by id as undelivered and
+     * persisted, and only then sent to the files host, the same pair on every retry. The secret is
+     * never recorded and never written to a Coolify env. The id is recorded once the host has it.
+     */
+    private ownFilesR2;
+    /**
+     * `plan/own-diff.ts`'s `planOwnAuth`: the org's own sign-in at
+     * `auth.<domain>`, in the org's own project, through the org's own edge
+     * routed DNS and tunnel ports. The instance owner token goes to
+     * `zitadel:org:<slug>:instanceBearer` and is never recorded. A changed
+     * declared auth ref patches both git apps' branch and redeploys them; the
+     * applied marker comes last, so a run that died halfway is planned again.
+     */
+    private ownAuth;
+    /**
+     * `plan/own-diff.ts`'s `planOwnMail`: the org's own Stalwart in the org's own
+     * project, with no host port (the shared relay reaches it by internal name)
+     * and a directory that trusts the org's own sign-in. The admin key goes to
+     * `orgTarget(org).refs.mailAdminKey` and nowhere else. The address the relay
+     * routes to is recorded last, and the step's marker after it.
+     */
+    private ownMail;
+    /**
+     * `plan/own-diff.ts`'s `planOwnSfu`: the org's own LiveKit server in the
+     * org's project, on the ports of its slot. The company's key pair goes to
+     * `livekit:org:<slug>:keys` and the app's env, nowhere else.
+     */
+    private ownSfu;
     private jobsRegistration;
     /** `deliverSecret`, tried up to {@link JOBS_DELIVERY_ATTEMPTS} times; true once one attempt succeeds. */
     private deliverWithRetry;
@@ -2879,6 +3044,11 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * #491: when `mailDomain` is the platform's own apex, this must never
      * delete the platform's own project (the delete loop skips it by id) or
      * the platform's own domain (returns before the domain lookup/delete).
+     *
+     * An org whose own sign-in is applied keeps its `<slug>-auth` project, and
+     * keeps the Lettermint domain when that is the domain the sign-in sends
+     * from. Every other org deletes `<slug>-auth` too, which only a failed
+     * first sign-in run can have left behind.
      */
     private parkLettermintMail;
     /**