@wtfalch/foundry 0.15.0 → 0.16.1

package/dist/plan/executor.d.ts

@@ -84,6 +84,7 @@ export interface CoolifyPort {
     getApplication(uuid: string): Promise<{
         uuid: string;
         status?: string;
+        custom_labels?: string | null;
     }>;
     createGithubAppApplication(input: {
         project_uuid: string;
@@ -457,6 +458,8 @@ export interface CloudflarePort {
         content: string;
         proxied?: boolean;
         ttl?: number;
+        /** Required by Cloudflare for an `MX` record. */
+        priority?: number;
     }): Promise<{
         id: string;
         name: string;
@@ -468,6 +471,7 @@ export interface CloudflarePort {
         content: string;
         proxied?: boolean;
         ttl?: number;
+        priority?: number;
     }): Promise<{
         id: string;
         name: string;
@@ -800,6 +804,24 @@ export interface ZitadelPort {
         userId: string;
         created: boolean;
     }>;
+    /**
+     * Adds a role to a project. Idempotent: a role that already exists is not
+     * an error. `@wtfalch/providers`' `ZitadelClient` has no project-role API,
+     * so `zitadel-project-roles.ts` is the real implementation.
+     */
+    ensureProjectRole(orgId: string, projectId: string, role: {
+        key: string;
+        displayName: string;
+    }): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * Grants a user (in `orgId`) project roles. Idempotent: roles the user
+     * already holds on the project are kept and the missing ones added.
+     */
+    grantProjectRoles(orgId: string, userId: string, projectId: string, roleKeys: string[]): Promise<{
+        changed: boolean;
+    }>;
     /** Lets anyone sign up to the org (plan gap A9). Idempotent. */
     allowSelfRegistration(orgId: string): Promise<{
         changed: boolean;
@@ -1008,6 +1030,9 @@ export interface FilesOrganisationPort {
         ceilingBytes: string | null;
         ceilingMicros: string | null;
         shareHost?: string | null;
+        /** F6b: with `owner`, files creates the organisation's owner membership, which its own key is minted below. */
+        name?: string;
+        owner?: string;
     }): Promise<{
         organisationId: string;
         ceilingBytes: string | null;
@@ -1018,10 +1043,65 @@ export interface FilesOrganisationPort {
         suspended: boolean;
         shareHost: string | null;
         created: boolean;
+        /**
+         * F6b: files' service key for Agora, returned once on a 201 that passed
+         * `name` and `owner` (the SDK's `agoraKey`). `filesOrganisation` delivers it.
+         */
+        agoraKey?: {
+            id: string;
+            secret: string;
+        };
     }>;
     /** #27, #177: the org's own spend limit on Files -- see this interface's own doc comment for why `organisationId` is explicit here. */
     setQuota(organisationId: string, limitBytes: string | null): Promise<unknown>;
     setBudget(organisationId: string, limitMicros: string | null): Promise<unknown>;
+    /**
+     * F6b: mints the organisation's own key, matching files'
+     * `POST /v1/manage/organisations/:organisationId/keys` (SDK
+     * `issueOrganisationKey`, wtfalch/files#121). `issuer` is a live human
+     * member the key's permissions are copied from. The secret comes back
+     * once; `filesRootKey` hands it to `deliverSecret` and returns only the id.
+     */
+    issueOrganisationKey(organisationId: string, input: {
+        name: string;
+        kind: 'api_key' | 'agent' | 'service';
+        issuer: string;
+        permissions: string[];
+        expiresDays: number;
+    }): Promise<{
+        id: string;
+        secret: string;
+        expiresAt: string;
+    }>;
+    /**
+     * F6b: mints an entry's key below the organisation's own key without that
+     * key's secret, matching `POST /v1/manage/organisations/:organisationId/
+     * keys/:minterId/keys` (SDK `issueKeyBelow`, wtfalch/files#127).
+     * `permissions` is a subset of the minter's, and files refuses an expiry
+     * past the minter's. The secret comes back once; `filesEntryKey` hands it
+     * to `bulkUpsertEnvs` and returns only the id.
+     */
+    issueKeyBelow(organisationId: string, minterId: string, input: {
+        name: string;
+        kind: 'api_key' | 'agent' | 'service';
+        permissions: string[];
+        expiresDays: number;
+    }): Promise<{
+        id: string;
+        secret: string;
+        expiresAt: string;
+    }>;
+    /** F6b: revokes the key and every key it minted (SDK `revokeOrganisationKey`); a second call is a no-op. */
+    revokeOrganisationKey(organisationId: string, keyId: string): Promise<{
+        id: string;
+        revoked: string[];
+    }>;
+    /** F6b: the organisation's collection of that name, created when missing (SDK `ensureCollection`, wtfalch/files#127). */
+    ensureCollection(organisationId: string, name: string): Promise<{
+        id: string;
+        name: string;
+        created: boolean;
+    }>;
 }
 /**
  * Provisions one org's organisation on AI and switches its AI use on (#80),
@@ -1077,6 +1157,45 @@ export interface AiOrganisationPort {
         id: string;
         secret: string;
     }>;
+    /**
+     * F6a: mints an entry's key below the org's own key, matching ai's
+     * `POST /v1/keys` (wtfalch/ai#162, SDK `mintKey`), which the management key
+     * calls with `minter` set to `minterKeyId` (the recorded id of
+     * `ai:key:<orgId>`). `permissions` is a subset of the minter's. ai clamps
+     * the expiry to the minter's, so the returned `expiresAt` can be sooner
+     * than `expiresDays`; `aiEntryKey` records that value. The child's issuer
+     * is the minter, so revoking the org key reaches it. The secret comes back
+     * once; `aiEntryKey` hands it to `bulkUpsertEnvs` and returns only the id.
+     */
+    mintNestedKey(input: {
+        organisationId: string;
+        minterKeyId: string;
+        name: string;
+        expiresDays: number;
+        permissions: string[];
+    }): Promise<{
+        organisationId: string;
+        id: string;
+        secret: string;
+        expiresAt: string;
+    }>;
+    /**
+     * F6a: registers `address` as the org's webhook, matching `PUT /v1/webhooks`
+     * (`setWebhookAddress`). `secret` is present only when ai created the
+     * webhook; an address change on an existing one returns none.
+     */
+    setWebhookAddress(organisationId: string, address: string): Promise<{
+        address: string;
+        secret?: string;
+    }>;
+    /**
+     * REVOKE SEAM (wtfalch/ai#157, A1b, not built): revokes one key and its
+     * credential row. Optional until that route exists; while a port has none,
+     * a replaced entry key stays live until it expires and its id is recorded
+     * under `entryAiUnrevokedScopeKey` for the plan to list. Nothing else
+     * depends on it.
+     */
+    revokeKey?(organisationId: string, keyId: string): Promise<void>;
     /**
      * #27, #177: the org's own budget on AI, matching
      * `ai/packages/sdk/src/client.ts:94-101`'s `updateBudget` (`UpdateBudget`
@@ -1207,8 +1326,8 @@ export interface FoundryStepExecutorPorts {
 }
 /**
  * Thrown by name for a step this executor deliberately does not implement:
- * chat (no admin API exists yet), plus moving the issuer onto or off the
- * org's domain (built, but not in v1 — domain verification and passkey
+ * moving chat or the issuer onto or off the org's domain (chat's re-key is
+ * not built; the issuer's is built, but not in v1 — domain verification and passkey
  * invalidation need their own design). Never carries a token, secret or key
  * (task brief: "errors carry the step and the provider's status only").
  */
@@ -1278,7 +1397,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `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>`, which is exactly what makes the next
+     * under `zitadel:owner:<orgId>:<email>`, which is exactly what makes the next
      * `plan()` call idempotent (`planOwner` plans nothing once that key is
      * recorded).
      */
@@ -1441,9 +1560,9 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `zitadel:issuer` (`AUTH_ORGANIZATION_ID`), `zitadel:owner`
      * (`OWNER_USER_ID`, gap P3) and every `zitadel:app` step
      * (`AUTH_CLIENT_ID`), all ordered before `coolify:app` for exactly this
-     * reason. `AUTH_APP_KEY` (#206 -- which broker an org's app registers with
-     * is its own design question, left out of #204's own "How" rather than
-     * guessed) is out of scope here (task brief). `DATABASE_URL_OWNER`/
+     * reason. `AUTH_APP_KEY` is pushed here too, for an entry that declares
+     * `uses: [auth]` (`ensureAuthAppKey`); the host's `BrokerPort` decides which
+     * broker the org's app registers with (#206). `DATABASE_URL_OWNER`/
      * `DATABASE_URL` are pushed by `pushDatabaseUrl` instead, not here --
      * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
@@ -1753,6 +1872,31 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * so an existing one is always re-written.
      */
     private ensureCallsFileStorage;
+    /**
+     * Creates the `chat.admin` role on the org's messaging project and grants
+     * it to each owner whose invite is recorded (`zitadel:owner:<orgId>:<email>`,
+     * email lowercased).
+     */
+    private ensureChatAdmins;
+    /**
+     * `plan/diff.ts`'s `planChat`: the org's chat stack at level 1 -- three
+     * Coolify-managed Postgres databases (Synapse, MAS, chat), Synapse with the
+     * `wtfalch_chat_gate` module and MAS (both with a config file this step
+     * writes, `chat-matrix.ts`), and the chat service. All four apps are
+     * internal: Agora is the one public origin and proxies to them
+     * (`AGORA_CHAT_UPSTREAM`, `AGORA_MATRIX_UPSTREAM`, `AGORA_MAS_UPSTREAM`).
+     * It also finds or creates the org's ZITADEL messaging project, the
+     * audience the chat service requires, and records its id for Agora.
+     *
+     * Idempotent: every resource is found by name or recorded id before it is
+     * created, minted secrets are read back from the MAS app's envs, and an app
+     * is deployed when it is new, its config was freshly minted, or it is not running. A
+     * recorded chat resource means the stack already exists, so a second
+     * `coolify:chat` step for it is a re-key (onto the company domain, or back)
+     * and neither is built: both are refused by name, before anything is touched.
+     * No secret reaches an error: errors name the org and the missing input only.
+     */
+    private coolifyChat;
     /**
      * `plan/diff.ts`'s `planCallsService`: the org's own calls service --
      * `wtfalch/calls`'s `packages/service`, wired to the calls Matrix stack
@@ -1821,10 +1965,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * `AGORA_FILES_UPSTREAM` are pushed once the platform's own mail/files
      * hosts are on and applied (#177's `platform-org.ts`'s
      * `agoraHostValuesFromPlatform`, read by `plan-apply.ts` when no host
-     * `agora` port overrides it) -- absent otherwise. The chat upstreams are
-     * still never pushed: chat has no admin API yet
-     * (https://github.com/wtfalch/chat/issues/40). Agora answers 502 on those
-     * routes rather than serving anything wrong. `AGORA_CALLS_UPSTREAM` is
+     * `agora` port overrides it) -- absent otherwise. `AGORA_CHAT_UPSTREAM`,
+     * `AGORA_MATRIX_UPSTREAM` and `AGORA_MAS_UPSTREAM` are pushed together once
+     * chat is on and `coolifyChat` has recorded that its apps carry their
+     * internal names (`CHAT_SERVICE_URL_SCOPE_KEY`); absent otherwise, and Agora
+     * answers 502 on those routes rather than serving anything wrong.
+     * `messagingProjectId` falls back to the project `coolifyChat` recorded. `AGORA_CALLS_UPSTREAM` is
      * pushed once calls are on and this org's calls service app carries its
      * internal name (`desiredAgoraEnv` reads that marker from the recorded ids,
      * not the host values).
@@ -2018,7 +2164,7 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * when the org has no owner yet, when no address is declared yet
      * (`plan/diff.ts`'s `planMail` reports that case as blocked, not planned,
      * so this step's own mode/domain work still runs), or once
-     * {@link MAIL_OWNER_MAILBOX_SCOPE_KEY} is already recorded -- checked last
+     * `mail_owner_mailbox` is already recorded -- checked last
      * so a second apply never calls `MailPort.createMailbox` again, rather
      * than relying on that port method's own duplicate refusal.
      */
@@ -2045,13 +2191,32 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private deleteStaleLettermintDomain;
     /**
-     * Upserts each DNS record `applyOrgMail` says foundry must publish, found
-     * by an exact name+type match (`CloudflarePort.findDnsRecord`'s own doc
-     * comment) so update never mistakes a stale record of a different type for
-     * a match. A `DKIM` record can be absent on the first call, since Stalwart
-     * mints the key on a background task; the next apply publishes it.
+     * Upserts each DNS record `applyOrgMail` says foundry must publish through
+     * {@link upsertMailDnsRecord}. A `DKIM` record can be absent on the first
+     * call, since Stalwart mints the key on a background task; the next apply
+     * publishes it.
      */
     private publishMailDnsRecords;
+    /**
+     * Creates or updates one mail record (Stalwart's or Lettermint's).
+     *
+     * Always DNS-only: Cloudflare proxies only `A`, `AAAA` and `CNAME`, and a
+     * proxied `CNAME` answers with Cloudflare's own addresses instead of its
+     * target, so Lettermint's return-path and DKIM names would stop resolving
+     * to Lettermint. `@wtfalch/providers`' `createDnsRecord` proxies by
+     * default, so `proxied: false` is sent on every write, update included, so
+     * a record someone proxied by hand is put back. An `MX` record carries the
+     * priority it was given, which Cloudflare requires.
+     *
+     * Found by an exact name+type match (`CloudflarePort.findDnsRecord`'s own
+     * doc comment) so a stale record of a different type is never taken for a
+     * match. A name can hold several `TXT` records (an apex often holds a site
+     * verification beside SPF), so a `TXT` record only replaces one that
+     * starts with the same tag (`v=spf1`, `v=DKIM1`); with none, it is added
+     * beside them. Before this, the first `TXT` on the name was overwritten,
+     * whatever it was.
+     */
+    private upsertMailDnsRecord;
     /**
      * Parking mail (2026-09-28 lettermint-org-mail swap, "Core rule": "Parking
      * mail deletes the org's projects and then the domain itself, so no
@@ -2096,6 +2261,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * idempotent by find-or-create, not by checking `recordedIds` first.
      */
     private filesOrganisation;
+    /**
+     * Files onboards Agora when it provisions an organisation with an owner and
+     * returns Agora's service key once. Foundry holds no other files key for
+     * Agora, so this is the only one: its secret goes straight to
+     * `deliverSecret`, its id is recorded as undelivered first, and a delivery
+     * that fails revokes the key again instead of leaving a live key nobody holds.
+     */
+    private deliverFilesAgoraKey;
     private filesStorage;
     /**
      * #80: provisions the org's own organisation on AI and switches its AI use
@@ -2116,6 +2289,61 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * way to check for an already-minted key.
      */
     private aiKey;
+    /**
+     * F6a: mints, renews, finishes, re-writes or retires one entry's ai key.
+     *
+     * Order keeps the app on a valid key throughout: the new key is minted below
+     * the org's key, its id is recorded and persisted as undelivered, the env is
+     * written (up to three tries), that write is recorded, the app is restarted,
+     * and only then is the old key revoked. A failed write keeps the old key in
+     * use and the planner blocks instead of minting again. A failed restart
+     * after the write plans `finish`, which restarts and records, minting
+     * nothing. The webhook secret, which ai shows once, is written the same way
+     * before the mint. A secret reaches `bulkUpsertEnvs` and nothing else:
+     * errors name ids, never the cause, which can echo one.
+     */
+    private aiEntryKey;
+    /**
+     * REVOKE SEAM (ai#157): revokes through `revokeKey` when the port has one.
+     * Without it, or when it fails, the id joins the entry's list of keys left
+     * live, which the plan shows, and the step goes on: the app already has its
+     * new key.
+     */
+    private revokeEntryKey;
+    /**
+     * F6b: mints or renews the org's own files key, or revokes the ones a
+     * renewal replaced. The key is minted below the files organisation's owner
+     * (the member `files_org_owner` records) and its one-time secret goes
+     * straight to {@link FoundryStepExecutorPorts.deliverSecret}. The id is
+     * recorded as undelivered first, so a delivery that fails never leads to a
+     * second mint. Entries are minted below it with `issueKeyBelow`, which needs
+     * no secret.
+     *
+     * A renewal keeps the old key live: its id goes to `files_key_previous`, the
+     * entries are re-minted below the new key by their own steps, and
+     * `revoke-previous` revokes the old key only when every entry holds a key
+     * below the new one. A failed revoke is listed, not retried.
+     */
+    private filesRootKey;
+    /**
+     * F6b: mints, renews, finishes, re-writes or retires one entry's files key.
+     *
+     * Same order as the ai entry key: the collections are ensured first (they
+     * hold no secret and can be repeated), the new key is minted below the
+     * org's own key, its id is recorded and persisted as undelivered, the env
+     * is written (up to three tries), that write is recorded, the app is
+     * restarted, and only then is the old key revoked. A failed write keeps the
+     * old key in use and the planner blocks instead of minting again. A failed
+     * restart after the write plans `finish`, which restarts and records,
+     * minting nothing. A secret reaches `bulkUpsertEnvs` and nothing else.
+     */
+    private filesEntryKey;
+    /**
+     * Revokes one entry key. When the call fails the id joins the entry's list
+     * of keys left live, which the plan shows, and the step goes on: the app
+     * already has its new key.
+     */
+    private revokeFilesEntryKey;
     /**
      * {@link StepDestroyer.destroy}: deletes the one resource
      * `FoundryPlanApply.destroy` names. A provider 404 (already gone) counts as