@mesh-tech/mesh-cli 0.26.0 → 0.28.0

package/dist/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "8c1e961c4",
-  "builtAt": "2026-09-17T07:12:18.568Z"
+  "commit": "dd1a85628",
+  "builtAt": "2026-09-17T22:16:24.040Z"
 }

package/dist/src/commands/app-check.js

@@ -23,7 +23,8 @@ export const APP_CHECK_RULES = {
         gate: "0.2",
         title: "App registers with the Hub",
         severity: "block",
-        remediation: "end index.ts with `export const app = env.register({ description })`",
+        remediation: "end index.ts with `export const app = env.register({ displayName, description })` — " +
+            "one sentence a non-technical operator can act on; put the caveats in `operatorNote`",
         scope: "app",
     },
     CUSTOM_SESSION_AUTH: {

package/dist/src/commands/hub/index.d.ts

@@ -19,7 +19,9 @@ export interface HubDevEnvOptions {
     tenants?: string;
     uiPort: number;
     apiPort: number;
+    audience?: string;
 }
+export declare function resolveHubAudience(raw: string | undefined): "operator" | "tenant";
 export interface AssembledHubEnv {
     apiEnv: Record<string, string>;
     uiEnv: Record<string, string>;

package/dist/src/commands/hub/index.js

@@ -99,6 +99,11 @@ export function forwardedSessionVars(sessionEnv) {
     }
     return out;
 }
+export function resolveHubAudience(raw) {
+    if (raw === undefined || raw === "")
+        return "operator";
+    return raw.trim().toLowerCase() === "operator" ? "operator" : "tenant";
+}
 export function assembleHubEnv(session, sessionEnv, opts) {
     const warnings = [];
     const notes = [];
@@ -141,6 +146,7 @@ export function assembleHubEnv(session, sessionEnv, opts) {
     if (!temporalAddress) {
         throw new MeshCliError(`Dev session '${session.name}' exposes no Temporal tunnel — the Hub can't reach the stack's Temporal.`, { remediation: { command: "mesh dev  # relaunch; the session records tunnels.temporal in its state" } });
     }
+    const audienceEnv = { HUB_AUDIENCE: resolveHubAudience(opts.audience) };
     const apiEnv = {
         ...forwarded,
         PORT: String(opts.apiPort),
@@ -148,6 +154,7 @@ export function assembleHubEnv(session, sessionEnv, opts) {
         HUB_TENANT: hubTenant,
         HUB_SCOPE_ENV: scopeEnv,
         HUB_SCOPE_TENANTS: scopeTenants.join(","),
+        ...audienceEnv,
         ...(isLocalPlatform ? localPlatformEnv(sessionEnv) : {}),
     };
     const uiEnv = {
@@ -157,6 +164,7 @@ export function assembleHubEnv(session, sessionEnv, opts) {
         HUB_TENANT: hubTenant,
         DEFAULT_ORG: scopeTenants[0],
         DEFAULT_ENV: scopeEnv,
+        ...audienceEnv,
     };
     return { apiEnv, uiEnv, scope: { hubTenant, scopeEnv, scopeTenants }, temporalAddress, warnings, notes };
 }
@@ -282,7 +290,12 @@ async function hubDevAction(opts) {
         throw new MeshCliError(`Dev session '${session.name}' has a state file but no live tmux session — its tunnels and token-server are gone.`, { remediation: { command: `mesh dev  # from ${session.state.appRoot}` } });
     }
     const sessionEnv = readTmuxSessionEnv(session.name);
-    const assembled = assembleHubEnv(session, sessionEnv, { tenants: opts.tenants, uiPort, apiPort });
+    const assembled = assembleHubEnv(session, sessionEnv, {
+        tenants: opts.tenants,
+        uiPort,
+        apiPort,
+        audience: opts.audience ?? process.env.HUB_AUDIENCE,
+    });
     if (opts.printEnv) {
         console.log(chalk.bold("\nhub-api env:"));
         for (const [k, v] of Object.entries(redactEnv(assembled.apiEnv)))
@@ -308,6 +321,7 @@ async function hubDevAction(opts) {
     logInfo(`Dev session : ${session.name} (${session.state.appRoot})`);
     logInfo(`Hub source  : ${platformDir}`);
     logInfo(`Scope       : HUB_TENANT=${assembled.scope.hubTenant} HUB_SCOPE_ENV=${assembled.scope.scopeEnv} HUB_SCOPE_TENANTS=${assembled.scope.scopeTenants.join(",")}`);
+    logInfo(`Audience    : ${assembled.apiEnv.HUB_AUDIENCE} (--audience tenant for a client's view)`);
     logInfo(`Temporal    : ${assembled.temporalAddress}`);
     for (const note of assembled.notes)
         logInfo(note);
@@ -372,6 +386,7 @@ export function registerHubCommands(program) {
         .description("Launch the current-code Hub (api + ui) against a running `mesh dev` session — env auto-assembled, zero hand-set vars")
         .option("--session <name>", "dev session to observe (default: auto-detect from cwd)")
         .option("--tenants <list>", "comma-separated HUB_SCOPE_TENANTS override (default: the session's tenant)")
+        .option("--audience <who>", "who the Hub renders for: `operator` (platform staff — the default here) or `tenant` (a client's operators). Anything else reads as `tenant`")
         .option("--port <port>", `Hub UI host port (default: $MESH_HUB_DEV_PORT or ${DEFAULT_HUB_UI_PORT})`)
         .option("--api-port <port>", `Hub API port (default: ${DEFAULT_HUB_API_PORT})`)
         .option("--platform-dir <dir>", "mesh-platform checkout to run the Hub from (default: $MESH_PLATFORM_DIR or walk up from cwd)")

package/dist/src/commands/local/index.d.ts

@@ -1,10 +1,12 @@
 import { Command } from "commander";
-import { type ServiceStatus, type StackEndpoint } from "./stack.js";
+import { type OverlayState, type ServiceStatus, type StackEndpoint } from "./stack.js";
 export interface WaitForStackIo {
     probe: (endpoint: StackEndpoint) => Promise<boolean>;
     services: () => ServiceStatus[];
-    overlayServices: () => ReadonlySet<string>;
+    overlays: () => readonly OverlayState[];
 }
-export declare function waitForStack(io?: WaitForStackIo): Promise<void>;
+export declare function waitForStack(opts: {
+    idpsStarted: boolean;
+}, io?: WaitForStackIo): Promise<void>;
 export declare function startHereLines(hubRunning: boolean, up?: ReadonlyMap<string, boolean>): string[];
 export declare function registerLocalCommands(program: Command): void;

package/dist/src/commands/local/index.js

@@ -3,12 +3,13 @@ import * as path from "path";
 import chalk from "chalk";
 import { logError, logInfo, logSuccess, logWarn } from "../../utils/log.js";
 import { MeshCliError } from "../../utils/errors.js";
-import { compose, COMPOSE_PROJECT, composeStreamed, crashedServices, DEFAULT_HUB_PORT, ensureDockerAvailable, findPackageRoot, hubApiRunning, hubEndpoints, hubOverlayRunning, hubOverlayServices, hubPort, ONE_SHOT_SERVICES, probeEndpoint, STACK_ENDPOINTS, stackOwnedElsewhere, stackServices, } from "./stack.js";
+import { compose, COMPOSE_PROJECT, composeStreamed, crashedServices, DEFAULT_HUB_PORT, ensureDockerAvailable, findPackageRoot, hubApiRunning, hubEndpoints, hubOverlayServices, hubPort, idpsOverlayServices, ONE_SHOT_SERVICES, overlayRunning, probeEndpoint, STACK_ENDPOINTS, stackOwnedElsewhere, stackServices, } from "./stack.js";
 import { probeRegistryToken, REGISTRY_LOGIN_FIX } from "../../utils/auth-preflight.js";
 import { ensureHubAuthImage, ensureHubImages, buildHubImagesFromSource, readHubCompiledAuthz, hasRegistryAuth, localHubVersion, planWithHubRefresh, } from "./hub-local.js";
 import { reconcileRegistryFromZitadel } from "./auth-provision.js";
 import { LOCAL_AWS_CONFIG, localAwsEnv, seedLocalPlatform, verifyFabric } from "./seed.js";
-import { LOGIN_CONTEXT, readHubAuth, seedZitadel, TEST_USERS } from "./seed-zitadel.js";
+import { LOGIN_CONTEXT, readHubAuth, seedMockIdps, seedZitadel, TEST_USERS } from "./seed-zitadel.js";
+import { idpEndpoints, mockIdpComposeEnv, MOCK_OIDC_PORT, MOCK_SAML_PORT } from "./mock-idps.js";
 import { publishHubAuthzCatalog } from "./seed-hub-catalog.js";
 import { describePortConflicts, findPortConflicts, hostPortsOf } from "./helpers.js";
 const WAIT_TIMEOUT_MS = 180_000;
@@ -20,10 +21,13 @@ function crashError(crashed) {
         },
     });
 }
-export async function waitForStack(io = {
+export async function waitForStack(opts, io = {
     probe: probeEndpoint,
     services: stackServices,
-    overlayServices: hubOverlayServices,
+    overlays: () => [
+        { services: hubOverlayServices(), started: false },
+        { services: idpsOverlayServices(), started: opts.idpsStarted },
+    ],
 }) {
     const deadline = Date.now() + WAIT_TIMEOUT_MS;
     let pending = STACK_ENDPOINTS.filter((e) => e.probe.kind !== "none");
@@ -39,10 +43,7 @@ export async function waitForStack(io = {
             }
         }
         pending = stillDown;
-        const crashed = crashedServices(io.services(), {
-            overlayServices: io.overlayServices(),
-            overlayStarted: false,
-        });
+        const crashed = crashedServices(io.services(), { overlays: io.overlays() });
         if (crashed.length > 0)
             throw crashError(crashed);
         if (pending.length === 0)
@@ -112,6 +113,11 @@ function portMoveHints() {
             Number(hubPort()),
             "MESH_HUB_PORT=<free port> mesh start   (or mesh start --no-hub, which starts everything else)",
         ],
+        [MOCK_SAML_PORT, "mesh start   (without --with-idps — the mock identity providers are opt-in)"],
+        [
+            MOCK_OIDC_PORT,
+            "mesh start   (without --with-idps; 5556 is Dex's own default port, so a Dex of your own is the usual holder)",
+        ],
     ]);
 }
 function repoRootForHubSource() {
@@ -133,6 +139,7 @@ export function registerLocalCommands(program) {
         .option("--no-hub", "start without the Hub (API + UI)")
         .option("--with-hub", "force-refresh the Hub to the latest published @mesh-tech/hub (the Hub is included by default when its images exist or registry auth is available)")
         .option("--hub-from-source", "build the Hub images from THIS checkout's apps/hub instead of the published tarball (the only way to exercise a Hub change locally)")
+        .option("--with-idps", "also run mock SAML and OIDC identity providers, and federate the local Zitadel with both (for testing enterprise SSO without a cloud tenant or an IdP admin)", false)
         .option("--takeover", "re-own a stack that another checkout started (may recreate shared containers with THIS checkout's config)", false)
         .option("--skip-port-check", "start even though a host port the stack wants is already held (the service that loses the bind will be broken — use when the holder is something you cannot stop)", false)
         .action(async (opts) => {
@@ -151,7 +158,11 @@ export function registerLocalCommands(program) {
             logWarn(`Taking over the running stack (previously driven from ${foreign}).`);
         }
         if (!opts.skipPortCheck && !stackServices().some((s) => s.state === "running")) {
-            const ports = hostPortsOf([...STACK_ENDPOINTS, ...(opts.hub ? hubEndpoints() : [])]);
+            const ports = hostPortsOf([
+                ...STACK_ENDPOINTS,
+                ...(opts.hub ? hubEndpoints() : []),
+                ...(opts.withIdps ? idpEndpoints() : []),
+            ]);
             const conflicts = await findPortConflicts(ports, `${COMPOSE_PROJECT}-`);
             if (conflicts.length > 0) {
                 throw new MeshCliError(describePortConflicts(conflicts, portMoveHints()), {
@@ -197,9 +208,10 @@ export function registerLocalCommands(program) {
             }
         }
         logInfo("Starting the local Mesh platform (docker compose project: mesh-local)…");
-        await composeStreamed(["up", "-d"]);
+        const idpEnv = opts.withIdps ? mockIdpComposeEnv() : undefined;
+        await composeStreamed(["up", "-d"], { idps: opts.withIdps, env: idpEnv });
         compose(["restart", "prometheus", "blackbox-exporter"], { inherit: true });
-        await waitForStack();
+        await waitForStack({ idpsStarted: opts.withIdps });
         let hubAuth = readHubAuth();
         if (opts.seed) {
             logInfo("Seeding local platform (tenant registry, artifacts bucket)…");
@@ -207,6 +219,15 @@ export function registerLocalCommands(program) {
             logInfo("Seeding Zitadel (Platform project, Mesh CLI app, Hub auth, test users)…");
             const zitadel = await seedZitadel(LOCAL_AWS_CONFIG);
             hubAuth = zitadel.hubAuth;
+            if (opts.withIdps) {
+                logInfo("Federating local Zitadel with the mock SAML and OIDC identity providers…");
+                await seedMockIdps();
+                logInfo(`Mock SAML IdP: http://localhost:${MOCK_SAML_PORT}  ·  ` +
+                    `mock OIDC IdP: http://localhost:${MOCK_OIDC_PORT}/dex  ·  ` +
+                    "sign in at http://localhost:8080 and both federation buttons are offered");
+                logInfo("Both are listed in the Zitadel console under Settings → Identity Providers (owner: Instance): " +
+                    "http://localhost:8080/ui/console/org-settings?id=idp");
+            }
             if (hubVersion) {
                 const compiled = readHubCompiledAuthz(hubVersion);
                 if (compiled) {
@@ -246,19 +267,23 @@ export function registerLocalCommands(program) {
                 hubEnv.MESH_HUB_OAUTH2_CLIENT_SECRET = hubAuth.clientSecret;
                 hubEnv.MESH_HUB_OAUTH2_COOKIE_SECRET = hubAuth.cookieSecret;
             }
-            await composeStreamed(["up", "-d"], { hub: true, env: hubEnv });
+            await composeStreamed(["up", "-d"], {
+                hub: true,
+                idps: opts.withIdps,
+                env: { ...idpEnv, ...hubEnv },
+            });
             if (opts.seed) {
                 compose(["restart", "hub-api"], { hub: true, env: hubEnv });
             }
-            const overlayServices = hubOverlayServices();
+            const overlays = [
+                { services: hubOverlayServices(), started: true },
+                { services: idpsOverlayServices(), started: opts.withIdps },
+            ];
             for (const endpoint of hubEndpoints()) {
                 logInfo(`Waiting for ${endpoint.label}…`);
                 let up = await probeEndpoint(endpoint);
                 for (let i = 0; i < 60 && !up; i++) {
-                    const crashed = crashedServices(stackServices(), {
-                        overlayServices,
-                        overlayStarted: true,
-                    });
+                    const crashed = crashedServices(stackServices(), { overlays });
                     if (crashed.length > 0)
                         throw crashError(crashed);
                     await new Promise((resolve) => setTimeout(resolve, 2000));
@@ -310,11 +335,20 @@ export function registerLocalCommands(program) {
                 remediation: { command: "mesh start" },
             });
         }
-        const overlayServices = hubOverlayServices();
-        const overlayStarted = hubOverlayRunning(services, overlayServices);
-        const notStarted = (s) => !overlayStarted && overlayServices.has(s.name) && s.state === "exited";
+        const hubOverlay = hubOverlayServices();
+        const idpsOverlay = idpsOverlayServices();
+        const idpsStarted = overlayRunning(services, idpsOverlay);
+        const overlays = [
+            { services: hubOverlay, started: overlayRunning(services, hubOverlay) },
+            { services: idpsOverlay, started: idpsStarted },
+        ];
+        const notStarted = (s) => s.state === "exited" && overlays.some((o) => !o.started && o.services.has(s.name));
         const hasHub = hubApiRunning(services);
-        const endpoints = hasHub ? [...STACK_ENDPOINTS, ...hubEndpoints()] : STACK_ENDPOINTS;
+        const endpoints = [
+            ...STACK_ENDPOINTS,
+            ...(hasHub ? hubEndpoints() : []),
+            ...(idpsStarted ? idpEndpoints() : []),
+        ];
         const probes = await Promise.all(endpoints.map(async (endpoint) => ({
             service: endpoint.service,
             label: endpoint.label,
@@ -337,6 +371,7 @@ export function registerLocalCommands(program) {
                 services,
                 endpoints: probes,
                 fabric,
+                mockIdps: idpsStarted,
                 awsEnv: localAwsEnv(),
             }));
             if (fabric && !fabric.ok)
@@ -352,7 +387,7 @@ export function registerLocalCommands(program) {
             const idle = notStarted(service);
             const icon = ok || oneShotDone ? chalk.green("●") : idle ? chalk.dim("○") : chalk.red("●");
             const health = service.health ? ` (${service.health})` : "";
-            const note = idle ? chalk.dim("  (Hub not started this run)") : "";
+            const note = idle ? chalk.dim("  (not started this run)") : "";
             console.log(`  ${icon} ${service.name.padEnd(22)} ${service.state}${health}${note}`);
         }
         console.log("");
@@ -366,8 +401,11 @@ export function registerLocalCommands(program) {
             const detail = fabric.ok ? "8 KB Advanced-tier round-trip OK" : fabric.error;
             console.log(`  ${icon} ${"AWS fabric check".padEnd(34)} ${chalk.dim(detail ?? "")}`);
         }
+        if (!idpsStarted) {
+            console.log(`  ${chalk.dim("○")} ${"Mock IdPs (SAML + OIDC)".padEnd(34)} ${chalk.dim("not started — mesh start --with-idps")}`);
+        }
         const down = probes.filter((p) => !p.up);
-        const crashed = crashedServices(services, { overlayServices, overlayStarted });
+        const crashed = crashedServices(services, { overlays });
         if (fabric && !fabric.ok)
             process.exitCode = 1;
         if (down.length > 0 || crashed.length > 0) {

package/dist/src/commands/local/mock-idps.d.ts

@@ -0,0 +1,48 @@
+import type { StackEndpoint } from "./stack.js";
+export declare const MOCK_SAML_PORT = 4569;
+export declare const MOCK_OIDC_PORT = 5556;
+export declare const idpEndpoints: () => StackEndpoint[];
+export declare const MOCK_SAML_IDP_NAME = "Mock SAML (local)";
+export declare const MOCK_OIDC_IDP_NAME = "Mock OIDC (local)";
+export declare const mockSamlMetadataUrl: () => string;
+export declare const mockOidcEndpoints: () => {
+    authorization: string;
+    token: string;
+    user: string;
+};
+export declare function ensureMockSamlSigningKey(): {
+    publicKeyB64: string;
+    privateKeyB64: string;
+};
+export declare const mockIdpComposeEnv: () => Record<string, string>;
+export declare const buildMockSamlIdpBody: (metadataXml: string) => {
+    name: string;
+    metadataXml: string;
+    binding: string;
+    withSignedRequest: boolean;
+    providerOptions: {
+        isLinkingAllowed: boolean;
+        isCreationAllowed: boolean;
+        isAutoCreation: boolean;
+        isAutoUpdate: boolean;
+        autoLinking: string;
+    };
+};
+export declare const buildMockOauthIdpBody: () => {
+    name: string;
+    clientId: string;
+    clientSecret: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    userEndpoint: string;
+    scopes: string[];
+    idAttribute: string;
+    providerOptions: {
+        isLinkingAllowed: boolean;
+        isCreationAllowed: boolean;
+        isAutoCreation: boolean;
+        isAutoUpdate: boolean;
+        autoLinking: string;
+    };
+};
+export declare const missingLoginPolicyIdps: (attached: readonly string[], wanted: readonly string[]) => string[];

package/dist/src/commands/local/mock-idps.js

@@ -0,0 +1,119 @@
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { meshCacheDir } from "../../utils/cache-home.js";
+import { MeshCliError } from "../../utils/errors.js";
+export const MOCK_SAML_PORT = 4569;
+export const MOCK_OIDC_PORT = 5556;
+const MOCK_OIDC_SERVICE = "mock-oidc";
+export const idpEndpoints = () => [
+    {
+        service: "mock-saml",
+        label: "Mock SAML IdP",
+        url: `http://localhost:${MOCK_SAML_PORT}`,
+        probe: { kind: "http", url: mockSamlMetadataUrl() },
+        hint: "sign in as any email you type; federation metadata at /api/saml/metadata",
+    },
+    {
+        service: MOCK_OIDC_SERVICE,
+        label: "Mock OIDC IdP",
+        url: `http://localhost:${MOCK_OIDC_PORT}/dex`,
+        probe: {
+            kind: "http",
+            url: `http://localhost:${MOCK_OIDC_PORT}/dex/.well-known/openid-configuration`,
+        },
+        hint: "dev@local.mesh or ops@local.mesh / password",
+    },
+];
+export const MOCK_SAML_IDP_NAME = "Mock SAML (local)";
+export const MOCK_OIDC_IDP_NAME = "Mock OIDC (local)";
+const MOCK_OIDC_CLIENT_ID = "mesh-local";
+const MOCK_OIDC_CLIENT_SECRET = "mesh-local-secret";
+export const mockSamlMetadataUrl = () => `http://localhost:${MOCK_SAML_PORT}/api/saml/metadata`;
+export const mockOidcEndpoints = () => ({
+    authorization: `http://localhost:${MOCK_OIDC_PORT}/dex/auth`,
+    token: `http://${MOCK_OIDC_SERVICE}:${MOCK_OIDC_PORT}/dex/token`,
+    user: `http://${MOCK_OIDC_SERVICE}:${MOCK_OIDC_PORT}/dex/userinfo`,
+});
+const keyDir = () => path.join(meshCacheDir("mesh-local"), "mock-idp");
+export function ensureMockSamlSigningKey() {
+    const dir = keyDir();
+    const certPath = path.join(dir, "cert.pem");
+    const keyPath = path.join(dir, "key.pem");
+    if (!fs.existsSync(certPath) || !fs.existsSync(keyPath)) {
+        fs.mkdirSync(dir, { recursive: true });
+        try {
+            execFileSync("openssl", [
+                "req",
+                "-x509",
+                "-newkey",
+                "rsa:2048",
+                "-keyout",
+                keyPath,
+                "-out",
+                certPath,
+                "-days",
+                "3650",
+                "-nodes",
+                "-subj",
+                "/CN=mesh-local-mock-saml",
+            ], { stdio: "ignore" });
+        }
+        catch (cause) {
+            throw new MeshCliError("Could not generate the mock SAML signing key.", {
+                remediation: {
+                    command: "openssl version   # openssl must be on PATH for --with-idps",
+                },
+                cause,
+            });
+        }
+    }
+    return {
+        publicKeyB64: fs.readFileSync(certPath).toString("base64"),
+        privateKeyB64: fs.readFileSync(keyPath).toString("base64"),
+    };
+}
+export const mockIdpComposeEnv = () => {
+    const { publicKeyB64, privateKeyB64 } = ensureMockSamlSigningKey();
+    return {
+        MESH_MOCK_SAML_PUBLIC_KEY: publicKeyB64,
+        MESH_MOCK_SAML_PRIVATE_KEY: privateKeyB64,
+    };
+};
+export const buildMockSamlIdpBody = (metadataXml) => ({
+    name: MOCK_SAML_IDP_NAME,
+    metadataXml: Buffer.from(metadataXml, "utf-8").toString("base64"),
+    binding: "SAML_BINDING_POST",
+    withSignedRequest: true,
+    providerOptions: {
+        isLinkingAllowed: true,
+        isCreationAllowed: true,
+        isAutoCreation: true,
+        isAutoUpdate: true,
+        autoLinking: "AUTO_LINKING_OPTION_EMAIL",
+    },
+});
+export const buildMockOauthIdpBody = () => {
+    const endpoints = mockOidcEndpoints();
+    return {
+        name: MOCK_OIDC_IDP_NAME,
+        clientId: MOCK_OIDC_CLIENT_ID,
+        clientSecret: MOCK_OIDC_CLIENT_SECRET,
+        authorizationEndpoint: endpoints.authorization,
+        tokenEndpoint: endpoints.token,
+        userEndpoint: endpoints.user,
+        scopes: ["openid", "profile", "email"],
+        idAttribute: "sub",
+        providerOptions: {
+            isLinkingAllowed: true,
+            isCreationAllowed: true,
+            isAutoCreation: true,
+            isAutoUpdate: true,
+            autoLinking: "AUTO_LINKING_OPTION_EMAIL",
+        },
+    };
+};
+export const missingLoginPolicyIdps = (attached, wanted) => {
+    const have = new Set(attached);
+    return [...new Set(wanted)].filter((id) => !have.has(id));
+};

package/dist/src/commands/local/seed-zitadel.d.ts

@@ -73,4 +73,10 @@ export interface ZitadelSeedResult {
     hubAuth: HubAuthConfig;
 }
 export declare function seedZitadel(awsConfig: object): Promise<ZitadelSeedResult>;
+export declare const IDP_SEARCH_PATH = "/admin/v1/idps/templates/_search";
+export declare const pickIdpIdByName: (searchResult: any, name: string) => string | undefined;
+export declare function seedMockIdps(): Promise<{
+    samlIdpId: string;
+    oidcIdpId: string;
+}>;
 export {};

package/dist/src/commands/local/seed-zitadel.js

@@ -8,6 +8,7 @@ import { writeContextConfig } from "../login.js";
 import { compose, hubPort, DEFAULT_HUB_PORT } from "./stack.js";
 import { LOCAL_TENANT, LOCAL_ENV } from "./seed.js";
 import { meshCacheDir } from "../../utils/cache-home.js";
+import { buildMockOauthIdpBody, buildMockSamlIdpBody, missingLoginPolicyIdps, MOCK_OIDC_IDP_NAME, MOCK_SAML_IDP_NAME, mockSamlMetadataUrl, } from "./mock-idps.js";
 export const ZITADEL_ISSUER = "http://localhost:8080";
 export const LOGIN_CONTEXT = "local";
 export const PLATFORM_ORG = "mesh";
@@ -441,3 +442,78 @@ export async function seedZitadel(awsConfig) {
     logSuccess(`Login context '${LOGIN_CONTEXT}' configured → try: mesh login ${LOGIN_CONTEXT}`);
     return { projectId, cliClientId, hubAuth };
 }
+async function fetchMockSamlMetadata() {
+    const url = mockSamlMetadataUrl();
+    let lastError = "no attempt made";
+    for (let attempt = 0; attempt < 30; attempt++) {
+        try {
+            const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
+            const body = await res.text();
+            if (res.ok && body.includes("EntityDescriptor")) {
+                if (/<ds:X509Certificate\s*\/>|<ds:X509Certificate>\s*<\/ds:X509Certificate>/.test(body)) {
+                    throw new MeshCliError("The mock SAML IdP served metadata with an empty signing certificate.", {
+                        remediation: {
+                            command: "rm -rf ~/.cache/mesh/mesh-local/mock-idp && mesh stop && mesh start --with-idps",
+                        },
+                    });
+                }
+                return body;
+            }
+            lastError = `HTTP ${res.status}`;
+        }
+        catch (cause) {
+            if (cause instanceof MeshCliError)
+                throw cause;
+            lastError = String(cause);
+        }
+        await new Promise((resolve) => setTimeout(resolve, 2_000));
+    }
+    throw new MeshCliError(`Could not read mock SAML metadata from ${url} (${lastError}).`, {
+        remediation: { command: "mesh status   # is mock-saml running?" },
+    });
+}
+async function attachedLoginPolicyIdps(pat) {
+    const res = await api(pat, "POST", "/admin/v1/policies/login/idps/_search", {});
+    return (res?.result ?? []).map((idp) => String(idp.idpId ?? idp.id)).filter(Boolean);
+}
+export const IDP_SEARCH_PATH = "/admin/v1/idps/templates/_search";
+export const pickIdpIdByName = (searchResult, name) => {
+    const hit = (searchResult?.result ?? []).find((idp) => idp?.name === name);
+    return hit?.id ? String(hit.id) : undefined;
+};
+async function findIdpByName(pat, name) {
+    return pickIdpIdByName(await api(pat, "POST", IDP_SEARCH_PATH, {}), name);
+}
+export async function seedMockIdps() {
+    const pat = readSeederPat();
+    const metadataXml = await fetchMockSamlMetadata();
+    let samlIdpId = await findIdpByName(pat, MOCK_SAML_IDP_NAME);
+    if (!samlIdpId) {
+        const created = await api(pat, "POST", "/admin/v1/idps/saml", buildMockSamlIdpBody(metadataXml));
+        samlIdpId = String(created.id);
+    }
+    logSuccess(`Mock SAML IdP ready (${MOCK_SAML_IDP_NAME}, id ${samlIdpId})`);
+    let oidcIdpId = await findIdpByName(pat, MOCK_OIDC_IDP_NAME);
+    if (!oidcIdpId) {
+        const created = await api(pat, "POST", "/admin/v1/idps/oauth", buildMockOauthIdpBody());
+        oidcIdpId = String(created.id);
+    }
+    logSuccess(`Mock OIDC IdP ready (${MOCK_OIDC_IDP_NAME}, id ${oidcIdpId})`);
+    const policy = await api(pat, "GET", "/admin/v1/policies/login");
+    if (policy?.policy?.allowExternalIdp !== true) {
+        await api(pat, "PUT", "/admin/v1/policies/login", {
+            ...policy.policy,
+            allowExternalIdp: true,
+        });
+        logInfo("Instance login policy: allowExternalIdp turned on (federation buttons were hidden)");
+    }
+    const attached = await attachedLoginPolicyIdps(pat);
+    const toAttach = missingLoginPolicyIdps(attached, [samlIdpId, oidcIdpId]);
+    for (const idpId of toAttach) {
+        await api(pat, "POST", "/admin/v1/policies/login/idps", { idpId, ownerType: "IDP_OWNER_TYPE_SYSTEM" });
+    }
+    const finalIdps = await attachedLoginPolicyIdps(pat);
+    logSuccess(`Login policy carries ${finalIdps.length} federation(s) — both mocks attached, ` +
+        "which is the state a login-policy change has to preserve");
+    return { samlIdpId, oidcIdpId };
+}

package/dist/src/commands/local/stack.d.ts

@@ -29,20 +29,25 @@ export declare function hubPort(): string;
 export declare function hubEndpoints(): StackEndpoint[];
 export declare function findPackageRoot(startDir?: string): string;
 export declare function stackDir(): string;
+export declare const BASE_COMPOSE_FILE = "docker-compose.yml";
 export declare const HUB_OVERLAY_FILE = "docker-compose.hub.yml";
+export declare const IDPS_OVERLAY_FILE = "docker-compose.idps.yml";
 export declare function parseComposeServiceNames(yamlText: string): string[];
 export declare function hubOverlayServices(): ReadonlySet<string>;
+export declare function idpsOverlayServices(): ReadonlySet<string>;
 export declare function stackOwnedElsewhere(): string | undefined;
 export declare function ensureDockerAvailable(): void;
 export declare function compose(args: string[], opts?: {
     inherit?: boolean;
     hub?: boolean;
+    idps?: boolean;
     env?: Record<string, string>;
 }): string;
 export declare function summarizeComposeFailure(output: string): string;
 export declare function composeLogPath(op: string): string;
 export declare function composeStreamed(args: string[], opts?: {
     hub?: boolean;
+    idps?: boolean;
     env?: Record<string, string>;
 }): Promise<void>;
 export interface ServiceStatus {
@@ -53,10 +58,13 @@ export interface ServiceStatus {
 export declare function parseComposePs(output: string): ServiceStatus[];
 export declare function stackServices(): ServiceStatus[];
 export declare const ONE_SHOT_SERVICES: Set<string>;
+export interface OverlayState {
+    services: ReadonlySet<string>;
+    started: boolean;
+}
 export declare function crashedServices(services: ServiceStatus[], opts: {
-    overlayServices: ReadonlySet<string>;
-    overlayStarted: boolean;
+    overlays: readonly OverlayState[];
 }): ServiceStatus[];
-export declare function hubOverlayRunning(services: ServiceStatus[], overlayServices: ReadonlySet<string>): boolean;
+export declare function overlayRunning(services: ServiceStatus[], overlayServices: ReadonlySet<string>): boolean;
 export declare function hubApiRunning(services: ServiceStatus[]): boolean;
 export declare function probeEndpoint(endpoint: StackEndpoint): Promise<boolean>;