@wtfalch/foundry 0.4.0 → 0.6.0

package/dist/plan/platform-sfu.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The platform's `sfu` step (#170): the shared calls SFU (LiveKit +
+ * cloudflared, `../calls-sfu.ts`) applied from `applyPlatform` instead of by
+ * hand running `scripts/calls-sfu-deploy.mjs`. Mirrors #167's
+ * `platform-providers.ts` shape -- narrow ports, a host (archon) supplies the
+ * real implementation -- for the two things this step needs beyond
+ * `applyCallsSfu` itself:
+ *
+ * - {@link CallsSfuConnectionPort}: the SFU VM's address, SSH credentials and
+ *   host key fingerprint. A human stores these as held keys ahead of time
+ *   (#170's "Human steps") -- this package only ever reads them back, the
+ *   same way #122's original script did from the environment.
+ * - {@link CallsSfuKeysPort}: a LiveKit API key/secret pair *per org*, as of
+ *   #152 ("one shared LiveKit SFU, kept apart by per-company keys", estate
+ *   DECISIONS.md 2026-09-28). `applyCallsSfuPlatformStep` takes the list of
+ *   org slugs with calls enabled -- `platform-providers.ts`'s `executeSfu`
+ *   builds it from `DeclaredOrgStore.list()` -- and, for each one, mints a
+ *   pair the first time and delivers it to held keys; every apply after that
+ *   reads the same pair back rather than minting a second one. A slug no
+ *   longer in the list simply contributes no line to the next apply's
+ *   `keys:` map (`../calls-sfu.ts`'s `livekitConfigYaml`) -- its held pair is
+ *   left stored, not deleted, the same "park, don't delete" rule the rest of
+ *   this planner follows. `executor.ts`'s `CallsSfuPort.resolveCredentials`
+ *   (the org-level calls-service step) reads a specific org's own held pair
+ *   back, by that org's slug. {@link PLATFORM_LIVEKIT_KEY_SLUG}'s own pair is
+ *   always included too, even with zero orgs enabled, so `keys:` is never
+ *   empty (round 2 of #152's review, finding 2).
+ *
+ * {@link CallsSfuSshConnector} is the third port: opening the actual SSH
+ * session. The real one is `calls-sfu-ssh-client.ts`'s `connectCallsSfuSsh`
+ * (over `ssh2`); a host passes it as `ssh`. {@link CallsSfuConnectionPort} and
+ * {@link CallsSfuKeysPort} stay host-implemented on purpose: they read and
+ * write held keys (`@wtfalch/keys`), which only the host (archon) can reach,
+ * the same way `CoolifyPort`/`CloudflarePort`/`ZitadelPort`'s real clients
+ * live outside this package. `calls-sfu-ssh-adapter.ts`'s {@link CallsSfuSshSession} is the narrow shape
+ * a test fakes instead.
+ */
+import { type LivekitCredentials } from '../calls-sfu-keys.js';
+import { type CallsSfuSshSession } from '../calls-sfu-ssh-adapter.js';
+/** The SFU VM's own address, SSH credentials and host key fingerprint -- held keys a human stored ahead of time. */
+export interface CallsSfuConnection {
+    address: string;
+    sshUser: string;
+    sshPort: number;
+    sshPrivateKey: string;
+    /** `SHA256:...`, `hostKeyFingerprint`'s own format -- checked by `toCallsSfuHostPort`/`applyCallsSfuOverSession`. */
+    sshHostFingerprint: string;
+    /** #127's own held key, read back here rather than minted -- unrelated to the LiveKit pair this step mints. */
+    cloudflaredTunnelToken: string;
+}
+/**
+ * Read-only: `null` before a human has stored the SFU VM's connection
+ * details as held keys (#170's "Human steps"). This step never invents an
+ * address or a private key.
+ */
+export interface CallsSfuConnectionPort {
+    resolveConnection(): Promise<CallsSfuConnection | null>;
+}
+/**
+ * Where this step mints and stores each org's own LiveKit API key/secret
+ * pair, as held keys, keyed by the org's slug (#152). `resolveLivekitKeys`
+ * returns `null` for a slug with no pair stored yet; `deliverLivekitKeys` is
+ * called exactly once per slug, the first time that slug's pair comes back
+ * `null` -- mirrors `FoundryStepExecutorPorts.deliverSecret`'s own "mint
+ * once, deliver, never re-mint" shape (`zitadel:app`'s
+ * `createApiApp`/`deliverSecret` pair in `executor.ts`).
+ *
+ * `deliverLivekitKeys` must be create-if-absent at the store: the first
+ * write for a slug wins and a later one is a no-op, not an overwrite. Two
+ * concurrent applies can both see `resolveLivekitKeys` return `null` for the
+ * same new slug and each mint a different pair; create-if-absent is what
+ * lets {@link applyCallsSfuPlatformStep}'s post-deliver re-read (round 2 of
+ * #152's review) converge both applies on whichever pair the store actually
+ * kept, rather than each one writing its own locally-minted pair into
+ * `livekit.yaml`.
+ */
+export interface CallsSfuKeysPort {
+    resolveLivekitKeys(orgSlug: string): Promise<LivekitCredentials | null>;
+    deliverLivekitKeys(orgSlug: string, pair: LivekitCredentials): Promise<void>;
+}
+/**
+ * The key id the platform's own LiveKit pair is held under, alongside every
+ * org's own pair, in the same {@link CallsSfuKeysPort} (#152 round 2 review:
+ * a `keys:` map with no entries at all makes LiveKit refuse to start outside
+ * dev mode, so an estate with no org's calls turned on yet still needs one
+ * live key). `oikos` is reserved and can never be a real org's own slug
+ * (`../slug.ts`'s `RESERVED_SLUGS`), so this can never collide with an org's
+ * pair.
+ */
+export declare const PLATFORM_LIVEKIT_KEY_SLUG = "oikos";
+/** Opens the actual SSH session; `connectCallsSfuSsh` is the real implementation. */
+export interface CallsSfuSshConnector {
+    connect(options: {
+        address: string;
+        sshUser: string;
+        sshPort: number;
+        sshPrivateKey: string;
+        /** Verified inside the handshake, before authentication; the connector refuses a mismatch. */
+        sshHostFingerprint: string;
+    }): Promise<CallsSfuSshSession & {
+        close(): void;
+    }>;
+}
+export declare class MissingCallsSfuConnectionError extends Error {
+    constructor();
+}
+export interface CallsSfuPlatformDeps {
+    connection: CallsSfuConnectionPort;
+    keys: CallsSfuKeysPort;
+    ssh: CallsSfuSshConnector;
+    /** Overridable so a test never needs a real CSPRNG call to assert on the minted pair. */
+    mintLivekitCredentials?: () => LivekitCredentials;
+}
+/**
+ * Runs the platform's `sfu` step: resolve the connection, mint each enabled
+ * org's own LiveKit pair the first time (read it back on every apply after
+ * that), open the SSH session, and apply. `orgSlugs` is every org with calls
+ * enabled, in no required order -- sorted here, alongside the always-present
+ * {@link PLATFORM_LIVEKIT_KEY_SLUG}, so a re-run with the same set mints
+ * nothing new and builds the identical `keys:` map (`../calls-sfu.ts`'s
+ * `livekitConfigYaml` sorts it again regardless, but sorting before minting
+ * keeps this function's own behaviour independent of the order its caller
+ * happens to list orgs in). Every part of this is safe to re-run -- minting
+ * only happens once a given slug's stored pair comes back `null`, and
+ * `applyCallsSfuOverSession` is itself idempotent -- so a second apply with
+ * the same held keys and the same org list changes nothing.
+ */
+export declare function applyCallsSfuPlatformStep(deps: CallsSfuPlatformDeps, orgSlugs?: readonly string[]): Promise<void>;

package/dist/plan/platform-sfu.js

@@ -0,0 +1,142 @@
+/**
+ * The platform's `sfu` step (#170): the shared calls SFU (LiveKit +
+ * cloudflared, `../calls-sfu.ts`) applied from `applyPlatform` instead of by
+ * hand running `scripts/calls-sfu-deploy.mjs`. Mirrors #167's
+ * `platform-providers.ts` shape -- narrow ports, a host (archon) supplies the
+ * real implementation -- for the two things this step needs beyond
+ * `applyCallsSfu` itself:
+ *
+ * - {@link CallsSfuConnectionPort}: the SFU VM's address, SSH credentials and
+ *   host key fingerprint. A human stores these as held keys ahead of time
+ *   (#170's "Human steps") -- this package only ever reads them back, the
+ *   same way #122's original script did from the environment.
+ * - {@link CallsSfuKeysPort}: a LiveKit API key/secret pair *per org*, as of
+ *   #152 ("one shared LiveKit SFU, kept apart by per-company keys", estate
+ *   DECISIONS.md 2026-09-28). `applyCallsSfuPlatformStep` takes the list of
+ *   org slugs with calls enabled -- `platform-providers.ts`'s `executeSfu`
+ *   builds it from `DeclaredOrgStore.list()` -- and, for each one, mints a
+ *   pair the first time and delivers it to held keys; every apply after that
+ *   reads the same pair back rather than minting a second one. A slug no
+ *   longer in the list simply contributes no line to the next apply's
+ *   `keys:` map (`../calls-sfu.ts`'s `livekitConfigYaml`) -- its held pair is
+ *   left stored, not deleted, the same "park, don't delete" rule the rest of
+ *   this planner follows. `executor.ts`'s `CallsSfuPort.resolveCredentials`
+ *   (the org-level calls-service step) reads a specific org's own held pair
+ *   back, by that org's slug. {@link PLATFORM_LIVEKIT_KEY_SLUG}'s own pair is
+ *   always included too, even with zero orgs enabled, so `keys:` is never
+ *   empty (round 2 of #152's review, finding 2).
+ *
+ * {@link CallsSfuSshConnector} is the third port: opening the actual SSH
+ * session. The real one is `calls-sfu-ssh-client.ts`'s `connectCallsSfuSsh`
+ * (over `ssh2`); a host passes it as `ssh`. {@link CallsSfuConnectionPort} and
+ * {@link CallsSfuKeysPort} stay host-implemented on purpose: they read and
+ * write held keys (`@wtfalch/keys`), which only the host (archon) can reach,
+ * the same way `CoolifyPort`/`CloudflarePort`/`ZitadelPort`'s real clients
+ * live outside this package. `calls-sfu-ssh-adapter.ts`'s {@link CallsSfuSshSession} is the narrow shape
+ * a test fakes instead.
+ */
+import { redactSecrets } from '../calls-sfu-deploy-support.js';
+import { mintLivekitCredentials } from '../calls-sfu-keys.js';
+import { applyCallsSfuOverSession } from '../calls-sfu-ssh-adapter.js';
+/**
+ * The key id the platform's own LiveKit pair is held under, alongside every
+ * org's own pair, in the same {@link CallsSfuKeysPort} (#152 round 2 review:
+ * a `keys:` map with no entries at all makes LiveKit refuse to start outside
+ * dev mode, so an estate with no org's calls turned on yet still needs one
+ * live key). `oikos` is reserved and can never be a real org's own slug
+ * (`../slug.ts`'s `RESERVED_SLUGS`), so this can never collide with an org's
+ * pair.
+ */
+export const PLATFORM_LIVEKIT_KEY_SLUG = 'oikos';
+export class MissingCallsSfuConnectionError extends Error {
+    constructor() {
+        super('No SSH connection details are held for the calls SFU. Store the SFU VM’s ' +
+            'SSH key and host key fingerprint as held keys before applying the ' +
+            'platform’s sfu step (#170’s "Human steps").');
+        this.name = 'MissingCallsSfuConnectionError';
+    }
+}
+/**
+ * Runs the platform's `sfu` step: resolve the connection, mint each enabled
+ * org's own LiveKit pair the first time (read it back on every apply after
+ * that), open the SSH session, and apply. `orgSlugs` is every org with calls
+ * enabled, in no required order -- sorted here, alongside the always-present
+ * {@link PLATFORM_LIVEKIT_KEY_SLUG}, so a re-run with the same set mints
+ * nothing new and builds the identical `keys:` map (`../calls-sfu.ts`'s
+ * `livekitConfigYaml` sorts it again regardless, but sorting before minting
+ * keeps this function's own behaviour independent of the order its caller
+ * happens to list orgs in). Every part of this is safe to re-run -- minting
+ * only happens once a given slug's stored pair comes back `null`, and
+ * `applyCallsSfuOverSession` is itself idempotent -- so a second apply with
+ * the same held keys and the same org list changes nothing.
+ */
+export async function applyCallsSfuPlatformStep(deps, orgSlugs = []) {
+    const connection = await deps.connection.resolveConnection();
+    if (!connection)
+        throw new MissingCallsSfuConnectionError();
+    // Every value below can echo back in an error (remote stdout/stderr, an
+    // ssh2 connect error), and the message reaches the platform audit row, so
+    // it is redacted before it leaves this function.
+    const secrets = [connection.sshPrivateKey, connection.cloudflaredTunnelToken];
+    try {
+        const livekitKeys = {};
+        const slugs = new Set([PLATFORM_LIVEKIT_KEY_SLUG, ...orgSlugs]);
+        for (const orgSlug of [...slugs].sort()) {
+            let pair = await deps.keys.resolveLivekitKeys(orgSlug);
+            if (!pair) {
+                const minted = (deps.mintLivekitCredentials ?? mintLivekitCredentials)();
+                // Pushed before the delivery call below (not after): a delivery
+                // that throws with the freshly minted secret in its message must
+                // still find it in this list to redact it (round 2 of #152's
+                // review, finding 1).
+                secrets.push(minted.apiKey, minted.apiSecret);
+                await deps.keys.deliverLivekitKeys(orgSlug, minted);
+                // `deliverLivekitKeys` is create-if-absent (this interface's own
+                // doc comment), so a concurrent apply that minted first may already
+                // have won the write for this slug. Re-read rather than trusting
+                // the locally minted pair, so this apply's own `livekit.yaml`
+                // always matches whatever the store actually kept (round 2's
+                // finding 3).
+                pair = (await deps.keys.resolveLivekitKeys(orgSlug)) ?? minted;
+                if (pair !== minted)
+                    secrets.push(pair.apiKey, pair.apiSecret);
+            }
+            else {
+                secrets.push(pair.apiKey, pair.apiSecret);
+            }
+            livekitKeys[pair.apiKey] = pair.apiSecret;
+        }
+        const session = await deps.ssh.connect({
+            address: connection.address,
+            sshUser: connection.sshUser,
+            sshPort: connection.sshPort,
+            sshPrivateKey: connection.sshPrivateKey,
+            sshHostFingerprint: connection.sshHostFingerprint,
+        });
+        try {
+            const config = {
+                address: connection.address,
+                livekitKeys,
+                cloudflaredTunnelToken: connection.cloudflaredTunnelToken,
+            };
+            await applyCallsSfuOverSession(session, config, connection.sshHostFingerprint);
+        }
+        finally {
+            session.close();
+        }
+    }
+    catch (error) {
+        throw redactedError(error, secrets);
+    }
+}
+function redactedError(error, secrets) {
+    const original = error instanceof Error ? error : new Error(String(error));
+    const message = redactSecrets(original.message, secrets);
+    const stack = redactSecrets(original.stack ?? message, secrets);
+    if (message === original.message && stack === original.stack)
+        return original;
+    const clean = new Error(message);
+    clean.name = original.name;
+    clean.stack = stack;
+    return clean;
+}

package/dist/plan/providers-readers.js

@@ -130,6 +130,26 @@ async function withLogVolumeConfig(client, resource, recorded) {
         return resource;
     }
 }
+/**
+ * #164: the org's own recorded Agora app's live `AGORA_*` env vars, as
+ * `config.env`, so `diff.ts`'s `planAgora` can compare them with what
+ * `executor.ts` would write. Gated on `recorded` mapping this exact uuid onto
+ * the `agora` kind, like {@link withLogVolumeConfig}. Unlike that read, a
+ * failure here is not swallowed: a plan that cannot see the live config must
+ * fail, not report it as missing.
+ */
+async function withAgoraEnvConfig(client, resource, recorded) {
+    if (resource.kind !== 'application' || !recorded[resource.key]?.startsWith('agora:')) {
+        return resource;
+    }
+    const envs = await client.listEnvs(resource.key);
+    const env = {};
+    for (const e of envs) {
+        if (!e.is_preview && e.key.startsWith('AGORA_'))
+            env[e.key] = e.value;
+    }
+    return { ...resource, config: { ...resource.config, env } };
+}
 /** `@wtfalch/providers`' own `LiveResource` (`resource.ts`) has no `system` field — foundry's adds it at this boundary. */
 function toFoundryResources(system, resources) {
     return resources.map((r) => ({ system, kind: r.kind, key: r.key, config: r.config }));
@@ -157,7 +177,8 @@ export class ProvidersCoolifyReader {
             this.resolveRecordedIds(orgId),
         ]);
         const withLogConfig = await Promise.all(toFoundryResources('coolify', resources).map((r) => withLogVolumeConfig(this.client, r, recorded)));
-        return applyRecordedIds(withLogConfig, recorded);
+        const withAgoraConfig = await Promise.all(withLogConfig.map((r) => withAgoraEnvConfig(this.client, r, recorded)));
+        return applyRecordedIds(withAgoraConfig, recorded);
     }
 }
 /**

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

@@ -0,0 +1,83 @@
+import type { ZitadelPort } from './executor.js';
+/**
+ * #168: the real {@link ZitadelPort.mintAdminMachineUser}/
+ * {@link ZitadelPort.mintLoginClientMachineUser}. `@wtfalch/providers` has no
+ * machine-user support, so this speaks ZITADEL's v1 management and admin APIs
+ * directly, with the same request shape as providers' `ZitadelClient.call`
+ * (bearer token, JSON in and out, `x-zitadel-orgid` for the target org,
+ * optional instance-host headers, a typed error on a non-ok response). The
+ * calls follow ZITADEL's published API reference and have not been run
+ * against a live instance.
+ *
+ *  1. `POST /management/v1/users/_search` finds the machine user by user name.
+ *  2. `POST /management/v1/users/machine` creates it when absent.
+ *  3. #216: for the login-client role on an *existing* user, `POST
+ *     /admin/v1/members/_search` reads its currently granted IAM roles, and
+ *     refuses (rather than reusing) a user that holds anything other than
+ *     exactly `IAM_LOGIN_CLIENT` -- see {@link ZitadelLoginClientRoleConflictError}.
+ *  4. `POST /admin/v1/members` grants the role (409 means already granted).
+ *  5. #216: for the login-client role on an existing user, `POST
+ *     /management/v1/users/{id}/pats/_search` (round 2 of the second PR
+ *     review: ZITADEL lists PATs with a POST and a JSON body, `{}` here --
+ *     not the `GET` this file used until then, which a live instance
+ *     rejects before the revoke sweep ever runs) lists every PAT it already
+ *     holds, and `DELETE /management/v1/users/{id}/pats/{patId}` removes
+ *     each one --
+ *     before the new PAT is requested, so a rerun (a crash between a prior
+ *     mint and the caller recording it, or every delivery retry failing)
+ *     always leaves exactly one live token, never two. The admin role's PAT
+ *     is never revoked this way, unchanged from before #216: nothing here
+ *     decrypts with a stale admin PAT the way ZITADEL's own masterkey
+ *     protects data encrypted under it, but this file still only revokes
+ *     what the caller (`platform-providers.ts`) actually asked for. #216
+ *     round 3: a 404 on one of these deletes (two concurrent mints listing
+ *     and deleting the same already-gone PAT) is treated as already done,
+ *     not an error -- the sweep's goal, that PAT is gone, already holds.
+ *  6. `POST /management/v1/users/{id}/pats` adds a token, which ZITADEL
+ *     returns once, alongside the new PAT's own id (`tokenId`) -- #216
+ *     round 2: {@link ZitadelPort.mintLoginClientMachineUser} returns that
+ *     id (`patId`) so the caller can re-list PATs after delivery and detect
+ *     a concurrent apply that revoked or replaced it (see
+ *     {@link ZitadelPort.listLoginClientPats}'s own doc comment). The admin
+ *     role's mint drops it before returning, unchanged from before #216
+ *     round 2 -- nothing reads it there.
+ *
+ * `token` is the bearer for the new instance, so it must belong to a caller
+ * allowed to create users and instance members (for example the instance's
+ * bootstrap machine user). The minted token is returned to the caller and
+ * never logged or put in an error.
+ */
+export declare class ZitadelHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * #216: thrown by {@link createZitadelAdminMinter}'s `mintLoginClientMachineUser`
+ * when a `foundry-login-client` user already exists but holds an IAM role
+ * other than exactly `IAM_LOGIN_CLIENT` -- for example `IAM_OWNER`. That user
+ * was not created by this method; granting it an additional role, or handing
+ * its PAT out as the login-client token, would widen access nobody asked
+ * for. Never caught and retried -- a human has to resolve the conflicting
+ * user by hand.
+ *
+ * #216 round 2: a user with *no* role at all is never refused this way --
+ * see `mintMachineUser`'s own `roles.length > 0 && ...` check. That is the
+ * crash window between `POST /management/v1/users/machine` creating the user
+ * and `POST /admin/v1/members` granting it the role; refusing it would turn
+ * an ordinary crash-and-rerun into a permanent, human-only block, which is
+ * exactly the bug class #216 exists to close.
+ */
+export declare class ZitadelLoginClientRoleConflictError 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;
+    /** Bearer token allowed to create users and add instance members there. */
+    token: string;
+    fetchImpl?: typeof fetch;
+    instanceHost?: string;
+}
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats'>;

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

@@ -0,0 +1,238 @@
+/**
+ * #168: the real {@link ZitadelPort.mintAdminMachineUser}/
+ * {@link ZitadelPort.mintLoginClientMachineUser}. `@wtfalch/providers` has no
+ * machine-user support, so this speaks ZITADEL's v1 management and admin APIs
+ * directly, with the same request shape as providers' `ZitadelClient.call`
+ * (bearer token, JSON in and out, `x-zitadel-orgid` for the target org,
+ * optional instance-host headers, a typed error on a non-ok response). The
+ * calls follow ZITADEL's published API reference and have not been run
+ * against a live instance.
+ *
+ *  1. `POST /management/v1/users/_search` finds the machine user by user name.
+ *  2. `POST /management/v1/users/machine` creates it when absent.
+ *  3. #216: for the login-client role on an *existing* user, `POST
+ *     /admin/v1/members/_search` reads its currently granted IAM roles, and
+ *     refuses (rather than reusing) a user that holds anything other than
+ *     exactly `IAM_LOGIN_CLIENT` -- see {@link ZitadelLoginClientRoleConflictError}.
+ *  4. `POST /admin/v1/members` grants the role (409 means already granted).
+ *  5. #216: for the login-client role on an existing user, `POST
+ *     /management/v1/users/{id}/pats/_search` (round 2 of the second PR
+ *     review: ZITADEL lists PATs with a POST and a JSON body, `{}` here --
+ *     not the `GET` this file used until then, which a live instance
+ *     rejects before the revoke sweep ever runs) lists every PAT it already
+ *     holds, and `DELETE /management/v1/users/{id}/pats/{patId}` removes
+ *     each one --
+ *     before the new PAT is requested, so a rerun (a crash between a prior
+ *     mint and the caller recording it, or every delivery retry failing)
+ *     always leaves exactly one live token, never two. The admin role's PAT
+ *     is never revoked this way, unchanged from before #216: nothing here
+ *     decrypts with a stale admin PAT the way ZITADEL's own masterkey
+ *     protects data encrypted under it, but this file still only revokes
+ *     what the caller (`platform-providers.ts`) actually asked for. #216
+ *     round 3: a 404 on one of these deletes (two concurrent mints listing
+ *     and deleting the same already-gone PAT) is treated as already done,
+ *     not an error -- the sweep's goal, that PAT is gone, already holds.
+ *  6. `POST /management/v1/users/{id}/pats` adds a token, which ZITADEL
+ *     returns once, alongside the new PAT's own id (`tokenId`) -- #216
+ *     round 2: {@link ZitadelPort.mintLoginClientMachineUser} returns that
+ *     id (`patId`) so the caller can re-list PATs after delivery and detect
+ *     a concurrent apply that revoked or replaced it (see
+ *     {@link ZitadelPort.listLoginClientPats}'s own doc comment). The admin
+ *     role's mint drops it before returning, unchanged from before #216
+ *     round 2 -- nothing reads it there.
+ *
+ * `token` is the bearer for the new instance, so it must belong to a caller
+ * allowed to create users and instance members (for example the instance's
+ * bootstrap machine user). The minted token is returned to the caller and
+ * never logged or put in an error.
+ */
+export class ZitadelHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'ZitadelHttpError';
+    }
+}
+/**
+ * #216: thrown by {@link createZitadelAdminMinter}'s `mintLoginClientMachineUser`
+ * when a `foundry-login-client` user already exists but holds an IAM role
+ * other than exactly `IAM_LOGIN_CLIENT` -- for example `IAM_OWNER`. That user
+ * was not created by this method; granting it an additional role, or handing
+ * its PAT out as the login-client token, would widen access nobody asked
+ * for. Never caught and retried -- a human has to resolve the conflicting
+ * user by hand.
+ *
+ * #216 round 2: a user with *no* role at all is never refused this way --
+ * see `mintMachineUser`'s own `roles.length > 0 && ...` check. That is the
+ * crash window between `POST /management/v1/users/machine` creating the user
+ * and `POST /admin/v1/members` granting it the role; refusing it would turn
+ * an ordinary crash-and-rerun into a permanent, human-only block, which is
+ * exactly the bug class #216 exists to close.
+ */
+export class ZitadelLoginClientRoleConflictError extends Error {
+    userId;
+    roles;
+    constructor(userId, roles) {
+        super(`ZITADEL machine user ${userId} already exists with role(s) [${roles.join(', ') || 'none'}], not [IAM_LOGIN_CLIENT] -- refusing to reuse it as foundry's login-client user`);
+        this.userId = userId;
+        this.roles = roles;
+        this.name = 'ZitadelLoginClientRoleConflictError';
+    }
+}
+export function createZitadelAdminMinter(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    async function call(method, path, body, orgId) {
+        const response = await fetchImpl(`${options.url}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                'content-type': 'application/json',
+                ...(options.instanceHost
+                    ? {
+                        'x-zitadel-instance-host': options.instanceHost,
+                        'x-forwarded-host': options.instanceHost,
+                        'x-forwarded-proto': 'https',
+                    }
+                    : {}),
+                ...(orgId ? { 'x-zitadel-orgid': orgId } : {}),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            // Never echo the body: on a PAT call it could hold the token.
+            throw new ZitadelHttpError(response.status, `non-JSON response from ${path}`);
+        }
+        if (!response.ok) {
+            throw new ZitadelHttpError(response.status, String(data.message ?? response.statusText));
+        }
+        return data;
+    }
+    /**
+     * #216 round 2: every live PAT id on a machine user, for both the
+     * revoke-before-mint sweep below and {@link ZitadelPort.listLoginClientPats}
+     * -- one call, one place that reads it.
+     *
+     * #216 (second PR review, round 2): ZITADEL lists a user's PATs with `POST
+     * /management/v1/users/{id}/pats/_search` and a JSON body (`{}` -- no
+     * filter narrows the search), not `GET` on the plain collection route this
+     * function used until this fix. A `GET` here 404s/405s before the
+     * revoke-before-mint sweep below ever runs on a live instance, so a re-mint
+     * on an existing login-client user never got as far as revoking its old
+     * PAT; `authLoginClientDrifted` (`platform-providers.ts`) then swallowed
+     * that failure as "unknown, not drifted" (its own `try`/`catch`), silently
+     * masking the break.
+     */
+    async function listPats(orgId, userId) {
+        const pats = await call('POST', `/management/v1/users/${userId}/pats/_search`, {}, orgId);
+        return (pats.result ?? [])
+            .map((p) => p.id)
+            .filter((id) => Boolean(id));
+    }
+    /**
+     * Shared by `mintAdminMachineUser` (`role: 'IAM_OWNER'`) and
+     * `mintLoginClientMachineUser` (`role: 'IAM_LOGIN_CLIENT'`) -- find or
+     * create the machine user by `userName`, grant `role`, then mint a fresh
+     * PAT. See this file's own top doc comment for the numbered call sequence
+     * and which of the `#216` steps (3 and 5) apply only to the login-client
+     * role, on an existing user, to keep the admin path's own behaviour
+     * unchanged.
+     */
+    async function mintMachineUser(orgId, input, role) {
+        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');
+        // #216: only the login-client role checks an existing user's roles
+        // before reusing it -- see this function's own doc comment for why the
+        // admin path stays as it was.
+        if (existing && role === 'IAM_LOGIN_CLIENT') {
+            const members = await call('POST', '/admin/v1/members/_search', {
+                queries: [{ userIdQuery: { userId } }],
+            });
+            const roles = (members.result ?? [])
+                .filter((m) => m.userId === userId)
+                .flatMap((m) => m.roles ?? []);
+            if (roles.length > 0 && !(roles.length === 1 && roles[0] === role)) {
+                throw new ZitadelLoginClientRoleConflictError(userId, roles);
+            }
+        }
+        try {
+            await call('POST', '/admin/v1/members', { userId, roles: [role] });
+        }
+        catch (e) {
+            if (!(e instanceof ZitadelHttpError && e.status === 409))
+                throw e;
+        }
+        // #216 (third PR review): true exactly when a live PAT existed on this
+        // user and this sweep revoked it -- never true on a first-ever mint
+        // (`existing` false, or an admin-role mint, which never revokes). The
+        // caller (`provisionPlatformAuth`) uses this to word a delivery-failure
+        // error correctly: revoking-then-failing leaves the apps with no live
+        // token at all, where a first mint that fails to deliver never had one.
+        let revokedPriorPat = false;
+        if (existing && role === 'IAM_LOGIN_CLIENT') {
+            // #216: revoke every PAT already on the user before minting a new one
+            // -- ZITADEL shows a PAT's value once, so a crash or a failed
+            // delivery between a prior mint and the caller recording it would
+            // otherwise leave that lost token live forever, and a rerun would
+            // mint a second one alongside it rather than replacing it.
+            const existingPats = await listPats(orgId, userId);
+            revokedPriorPat = existingPats.length > 0;
+            for (const patId of existingPats) {
+                try {
+                    await call('DELETE', `/management/v1/users/${userId}/pats/${patId}`, undefined, orgId);
+                }
+                catch (e) {
+                    // #216 round 3: two concurrent mints can both list the same
+                    // existing PAT and both try to delete it -- the second DELETE
+                    // finds it already gone. That is the outcome this sweep wants,
+                    // not a failure; only a non-404 error (ZITADEL unreachable, a
+                    // permissions problem) should still abort the mint.
+                    if (!(e instanceof ZitadelHttpError && e.status === 404))
+                        throw e;
+                }
+            }
+        }
+        const pat = await call('POST', `/management/v1/users/${userId}/pats`, {}, orgId);
+        if (typeof pat.token !== 'string' || pat.token === '') {
+            throw new Error(`ZITADEL returned no token for machine user ${userId}`);
+        }
+        const patId = typeof pat.tokenId === 'string' && pat.tokenId !== '' ? pat.tokenId : undefined;
+        // Only the login-client role's caller ever reads `patId` (the round-2
+        // concurrent-apply guard) -- the admin path never required a PAT id
+        // before #216 round 2 and still does not, so this never turns a response
+        // the admin path already accepted into a new failure.
+        if (role === 'IAM_LOGIN_CLIENT' && !patId) {
+            throw new Error(`ZITADEL returned no token id for machine user ${userId}`);
+        }
+        return { userId, token: pat.token, patId: patId ?? '', revokedPriorPat };
+    }
+    return {
+        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
+        // delivering a freshly minted token, that it is still live and alone on
+        // the user -- see `ZitadelPort.listLoginClientPats`'s own doc comment for
+        // the race this closes.
+        listLoginClientPats: (orgId, userId) => listPats(orgId, userId),
+    };
+}

package/dist/plan.d.ts

@@ -35,6 +35,12 @@ export interface PlanStep {
  */
 export interface UnmanagedItem {
     description: string;
+    /**
+     * Set on a platform service that is blocked, not planned: the service's name
+     * (`auth`, `mail`, `integrations`, `files`, `ai`, `jobs`, `archon`, `sfu`).
+     * Absent on a live-but-undeclared resource.
+     */
+    key?: string;
 }
 /**
  * The diff between a {@link DeclaredOrg} and live reality, computed by the