@wtfalch/foundry 0.5.0 → 0.6.0

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

@@ -10,12 +10,21 @@
  *   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}: the LiveKit API key/secret pair. Unlike the
- *   connection details, this step *mints* the pair itself, the first time,
- *   and delivers it to held keys -- every apply after that reads the same
- *   pair back rather than minting a second one. `executor.ts`'s
- *   `CallsSfuPort.resolveCredentials` (the org-level calls-matrix step) reads
- *   the same held-keys entry this delivers.
+ * - {@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`
@@ -48,17 +57,37 @@ export interface CallsSfuConnectionPort {
     resolveConnection(): Promise<CallsSfuConnection | null>;
 }
 /**
- * Where this step mints and stores the LiveKit API key/secret pair, as held
- * keys. `resolveLivekitKeys` returns `null` before the first apply;
- * `deliverLivekitKeys` is called exactly once, the first time this step
- * finds nothing stored -- mirrors `FoundryStepExecutorPorts.deliverSecret`'s
- * own "mint once, deliver, never re-mint" shape (`zitadel:app`'s
+ * 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(): Promise<LivekitCredentials | null>;
-    deliverLivekitKeys(pair: LivekitCredentials): Promise<void>;
+    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: {
@@ -83,11 +112,17 @@ export interface CallsSfuPlatformDeps {
     mintLivekitCredentials?: () => LivekitCredentials;
 }
 /**
- * Runs the platform's `sfu` step: resolve the connection, mint the LiveKit
- * pair the first time (read it back on every apply after that), open the
- * SSH session, and apply. Every part of this is safe to re-run -- minting
- * only happens once the stored pair comes back `null`, and
+ * 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 changes nothing.
+ * the same held keys and the same org list changes nothing.
  */
-export declare function applyCallsSfuPlatformStep(deps: CallsSfuPlatformDeps): Promise<void>;
+export declare function applyCallsSfuPlatformStep(deps: CallsSfuPlatformDeps, orgSlugs?: readonly string[]): Promise<void>;

package/dist/plan/platform-sfu.js

@@ -10,12 +10,21 @@
  *   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}: the LiveKit API key/secret pair. Unlike the
- *   connection details, this step *mints* the pair itself, the first time,
- *   and delivers it to held keys -- every apply after that reads the same
- *   pair back rather than minting a second one. `executor.ts`'s
- *   `CallsSfuPort.resolveCredentials` (the org-level calls-matrix step) reads
- *   the same held-keys entry this delivers.
+ * - {@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`
@@ -29,6 +38,16 @@
 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 ' +
@@ -38,14 +57,20 @@ export class MissingCallsSfuConnectionError extends Error {
     }
 }
 /**
- * Runs the platform's `sfu` step: resolve the connection, mint the LiveKit
- * pair the first time (read it back on every apply after that), open the
- * SSH session, and apply. Every part of this is safe to re-run -- minting
- * only happens once the stored pair comes back `null`, and
+ * 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 changes nothing.
+ * the same held keys and the same org list changes nothing.
  */
-export async function applyCallsSfuPlatformStep(deps) {
+export async function applyCallsSfuPlatformStep(deps, orgSlugs = []) {
     const connection = await deps.connection.resolveConnection();
     if (!connection)
         throw new MissingCallsSfuConnectionError();
@@ -54,14 +79,32 @@ export async function applyCallsSfuPlatformStep(deps) {
     // it is redacted before it leaves this function.
     const secrets = [connection.sshPrivateKey, connection.cloudflaredTunnelToken];
     try {
-        let pair = await deps.keys.resolveLivekitKeys();
-        if (!pair) {
-            pair = (deps.mintLivekitCredentials ?? mintLivekitCredentials)();
-            secrets.push(pair.apiKey, pair.apiSecret);
-            await deps.keys.deliverLivekitKeys(pair);
-        }
-        else {
-            secrets.push(pair.apiKey, pair.apiSecret);
+        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,
@@ -73,8 +116,7 @@ export async function applyCallsSfuPlatformStep(deps) {
         try {
             const config = {
                 address: connection.address,
-                livekitApiKey: pair.apiKey,
-                livekitApiSecret: pair.apiSecret,
+                livekitKeys,
                 cloudflaredTunnelToken: connection.cloudflaredTunnelToken,
             };
             await applyCallsSfuOverSession(session, config, connection.sshHostFingerprint);

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

@@ -1,18 +1,46 @@
 import type { ZitadelPort } from './executor.js';
 /**
- * #168: the real {@link ZitadelPort.mintAdminMachineUser}. `@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.
+ * #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. `POST /admin/v1/members` grants `IAM_OWNER` (409 means already granted).
- *  4. `POST /management/v1/users/{id}/pats` adds a token, which ZITADEL
- *     returns once.
+ *  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
@@ -23,6 +51,27 @@ 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;
@@ -31,4 +80,4 @@ export interface ZitadelMinterOptions {
     fetchImpl?: typeof fetch;
     instanceHost?: string;
 }
-export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser'>;
+export declare function createZitadelAdminMinter(options: ZitadelMinterOptions): Pick<ZitadelPort, 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats'>;

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

@@ -1,17 +1,45 @@
 /**
- * #168: the real {@link ZitadelPort.mintAdminMachineUser}. `@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.
+ * #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. `POST /admin/v1/members` grants `IAM_OWNER` (409 means already granted).
- *  4. `POST /management/v1/users/{id}/pats` adds a token, which ZITADEL
- *     returns once.
+ *  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
@@ -26,6 +54,32 @@ export class ZitadelHttpError extends Error {
         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) {
@@ -59,37 +113,126 @@ export function createZitadelAdminMinter(options) {
         }
         return data;
     }
-    return {
-        async mintAdminMachineUser(orgId, input) {
-            const found = await call('POST', '/management/v1/users/_search', {
-                queries: [
-                    { userNameQuery: { userName: input.userName, method: 'TEXT_QUERY_METHOD_EQUALS' } },
-                ],
+    /**
+     * #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);
-            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');
-            try {
-                await call('POST', '/admin/v1/members', { userId, roles: ['IAM_OWNER'] });
-            }
-            catch (e) {
-                if (!(e instanceof ZitadelHttpError && e.status === 409))
-                    throw e;
+            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);
             }
-            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}`);
+        }
+        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;
+                }
             }
-            return { userId, token: pat.token };
-        },
+        }
+        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/requested-changes.d.ts

@@ -11,7 +11,9 @@ import type { PlanDetail } from './plan/diff.js';
  * and safe; `domain` and `mailTier` are full self-service too, but both are
  * migrating steps (`plan/diff.ts`'s `planMail` moves live mail between
  * modes; a domain move is at least as disruptive) and always need approval,
- * never auto.
+ * never auto. #184 narrows `storageLimit`/`aiLimit`'s "small and safe" to
+ * 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 declare const REQUESTABLE_FIELDS: readonly RequestableField[];
@@ -85,12 +87,20 @@ export declare class RequestedChangeError extends Error {
     constructor(message: string);
 }
 /**
- * `auto` when `change` is small and safe (`calls`, `storageLimit`,
- * `aiLimit`), the plan it causes has no destructive or migrating step, and
- * it causes no price change on `org`'s own billing fields; `approval`
- * otherwise -- every `domain` or `mailTier` change classifies `approval`
- * unconditionally, since #178 "Decide" calls both migrating steps that
- * always need approval, whatever direction the change moves.
+ * `auto` when `change` is small and safe (`calls`, and `storageLimit`/
+ * `aiLimit` in the lowering or unchanged direction), the plan it causes has
+ * no destructive or migrating step, and it causes no price change on
+ * `org`'s own billing fields; `approval` otherwise -- every `domain` or
+ * `mailTier` change classifies `approval` unconditionally, since #178
+ * "Decide" calls both migrating steps that always need approval, whatever
+ * direction the change moves.
+ *
+ * A `storageLimit` or `aiLimit` change that *raises* either limit
+ * ({@link isLimitRaise} against `org`'s current value) classifies
+ * `approval`, decided in #184: "a raise of the storage or AI limit
+ * classifies `approval` until billing fields exist. A lowering stays
+ * `auto`." `storageLimit` carries two independent limits (`limitBytes`,
+ * `limitMicros`); a raise on either one is enough.
  *
  * `plan` is the {@link PlanDetail} `change` causes -- the caller's own diff
  * against live reality, from the same `computePlanDetail` (`plan/diff.ts`)