@zitadel/testing 0.1.0-alpha.18 → 1.0.0-alpha.20

package/README.md

@@ -70,6 +70,24 @@ apps; the console maps the same fields to `VITE_*`/`CONSOLE_*` names instead.
 The fixtures find the instance through `ZITADEL_TESTING_HANDSHAKE`, which
 `withZitadel()` points at its handshake file.
 
+`app` is optional. Omit it when the instance itself serves the app — the
+Zitadel binary embeds the console and hosted sign-in at `/ui/console/` and
+`/ui/login/`, so a suite testing those surfaces has no second server to boot.
+Only the instance entry is generated, and `appOrigin` must then be the
+instance's own local origin:
+
+```ts
+export default defineConfig({
+  testDir: "./e2e",
+  use: { baseURL: "http://localhost:8092" },
+  ...withZitadel({
+    configDir: import.meta.dirname,
+    port: 8092,
+    appOrigin: "http://localhost:8092", // the instance is the app server
+  }),
+});
+```
+
 ### Start tests authenticated
 
 Most app tests don't want to re-test login. `authenticatedPage` seeds a user,
@@ -181,11 +199,11 @@ const z = await startLocalZitadel({
   appOrigins,    // registered as the project's preview_origins
   useCase,       // "minimal" (default) | "consumer" | "business"
   preset,        // "password-first" (default)
-  serverBinary,  // ZITADEL_SERVER_BINARY override (in-repo: dist/server/nextgen)
+  serverBinary,  // ZITADEL_SERVER_BINARY override (path to a built server binary)
   keep,          // keep the temp dir for debugging
 });
 
-z.handle;   // serializable: { baseUrl, projectId, projectSecret, schemaId, previewSecret? }
+z.handle;   // serializable: { baseUrl, projectId, projectSecret, schemaId, previewSecret?, platform? }
 z.api;      // authenticated @zitadel/api client (bearer = projectSecret)
 z.appEnv;   // { ZITADEL_URL, NEXT_PUBLIC_ZITADEL_PROJECT_ID, ZITADEL_PROJECT_SECRET }
 await z.seedUser({ email?, password?, attributes? }); // → { id, email, password }
@@ -219,9 +237,48 @@ above.
   bearer for everything else) → `POST /schemas` (server assigns the schema id)
   → `POST /flow_definitions` (default login flow pinned to that schema id).
   Templates come from `@zitadel/config/defaults`.
-- **Seeding** is `POST /users` (the body carries `$schema: <schema id>`) +
+- **Seeding** is `POST /users` (the body names the schema in `schema` and puts
+  the schema-defined content under `attributes`) +
   `PUT /users/{id}/password` with `is_change_required: false`.
 
+## Credentials: the boot contract
+
+The kit's boot contract is the sanctioned way tests and dev loops obtain
+credentials: they come from the boot contract, never from a seed default —
+the rule root ADR 053 §9 sets. The kit owns the server process and its
+database, captures each credential from provisioning
+output at the moment the server mints it, and exposes it predictably on
+`handle`:
+
+- `handle.projectSecret` — the seeded customer project's operator credential,
+  captured from `POST /projects` (the server returns it exactly once, at
+  creation). Bearer behind `z.api` and every seed op.
+- `handle.previewSecret` — the same project's browser-plane credential (the
+  publishable-key predecessor from root ADR 036).
+- `handle.platform` — the platform-plane slot (`PlatformCredentials`): the
+  reserved platform project's id and publishable key. **Stub today**: the
+  server's platform-project provisioner (Console ADR 0004 §2) has not
+  landed, so `startLocalZitadel` never populates it yet. Only the fields the
+  contract already guarantees are declared; credentials whose design is
+  still open — the platform automation principal (deferred to a future PAT /
+  service-user decision) and a boot-minted operator session — join as
+  optional fields once they exist, which is additive and churn-free.
+
+What this rules out, deliberately: there is no server `--test-mode`, no
+seed-document credential flag, and no other server-side door that mints
+deterministic credentials — and none may be added. The production seed
+contract stays credential-free; predictable test access is this kit's job,
+done entirely with what provisioning already returns. If a credential the
+kit needs is not capturable at provisioning time, the fix is to extend the
+provisioning contract the boot path drives — never a server flag, and never
+direct database writes, which would bypass the provisioner and break seed
+ops for `connectZitadel` targets.
+
+The in-repo dev loop follows the same contract: `moon run console:dev-real`
+boots, seeds, and threads `handle.projectSecret` into the console dev proxy's
+`CONSOLE_PROJECT_SECRET` itself; `--seed-only` prints the same variables for
+a separately-started dev server. Nothing to remember or export.
+
 ## Parallelism model
 
 **One instance per suite, one fresh user per test.** Emails are unique per
@@ -229,7 +286,7 @@ project, so per-test `seed.user()` calls are isolation enough for login-flow
 tests, and tests run fully parallel against the shared instance
 (demonstrated by `demo-next-e2e:e2e-real`, 2 workers).
 
-Typical timings with the SQLite local default (dev build, July 2026 — estimates, not a fresh remeasure):
+Typical timings with the SQLite local default (dated estimates from a July 2026 dev build — orders of magnitude, not a benchmark; remeasure locally before relying on them):
 
 | Operation | Time |
 | --- | --- |
@@ -259,10 +316,12 @@ Customer installs get the published server binary through `@zitadel/server`'s
 platform packages; the in-repo workspace carries no such binary, so the repo's
 own suites run `moon run server:build` and point the kit at the result via
 `ZITADEL_SERVER_BINARY` (the `withZitadel` option `zitadel.serverBinary` /
-`serverBinaryHint` exists for this). The in-repo moon tasks set
+`serverBinaryHint` exists for this). Most in-repo moon tasks set
 `NEXTGEN_SERVER_LOGIN_ENABLED=false` / `NEXTGEN_SERVER_CONSOLE_ENABLED=false`
-— the suites drive the app-embedded login, not the server-hosted `/ui/*`.
-Customer installs need none of this.
+because they drive the app-embedded login, not the server-hosted `/ui/*`; the
+exception is `console-e2e:e2e-embedded`, which keeps both surfaces on and
+omits `app` — the binary-served `/ui/*` pages are its subject. Customer
+installs need none of this.
 
 ## Known limitations
 

package/dist/{app-env-D3W0GYhA.d.mts → app-env-DlrV_ePR.d.mts}

@@ -1,13 +1,48 @@
 import { ZitadelClient } from "@zitadel/api/client";
 
 //#region src/types.d.ts
+/**
+ * Credentials of the reserved platform project, captured by the kit at
+ * provisioning time. The shape follows root ADR 053 §9 and Console ADR 0004
+ * §2 (both Proposed): bootstrap mints **no platform project secret** — the
+ * publishable key is the only default credential, and test infrastructure
+ * gets its credentials from the testkit's boot contract, not from seed
+ * defaults.
+ *
+ * Stub today: the server's platform-project provisioner does not exist yet,
+ * so `startLocalZitadel` never populates this field. Only the fields §9
+ * itself guarantees are declared. Credentials whose design is still open —
+ * the platform automation principal (deferred to a future PAT /
+ * service-user decision) and a boot-minted operator session — join as
+ * optional fields once they exist: additions are churn-free, removals are
+ * not, so nothing is pre-declared here.
+ */
+interface PlatformCredentials {
+  /** Reserved platform project id — the Console sign-in target. */
+  projectId: string;
+  /**
+   * Browser-safe publishable key. Required: it is the one credential
+   * bootstrap always provisions (sign-in needs it), so a platform block
+   * without it is malformed.
+   */
+  publishableKey: string;
+}
 /**
  * Serializable description of a bootstrapped instance + project. This is the
- * contract that crosses process boundaries (boot script -> Playwright workers).
+ * contract that crosses process boundaries (boot script -> Playwright workers)
+ * — and the credential surface of the kit: every credential the server mints
+ * during provisioning is captured here, so tests and dev loops read them from
+ * the handle instead of hand-set environment or a server-side test door (a
+ * server flag that mints deterministic credentials must not exist).
  */
 interface InstanceHandle {
   baseUrl: string;
   projectId: string;
+  /**
+   * The seeded customer project's operator credential, captured from
+   * `POST /projects` — the server returns it exactly once, at creation.
+   * Bearer for the management API (`api`) and every seed op.
+   */
   projectSecret: string;
   /**
    * First registered app origin. Flow submissions enforce the project's
@@ -16,12 +51,23 @@ interface InstanceHandle {
    */
   appOrigin?: string;
   /**
-   * Server-assigned id of the seeded user schema. User documents must
-   * reference it via their `$schema` field, so seeding needs it alongside the
-   * project credential.
+   * Server-assigned id of the seeded user schema. A user names it in `schema`
+   * and puts the schema-defined content under `attributes`, so seeding needs
+   * it alongside the project credential.
    */
   schemaId: string;
+  /**
+   * The same project's browser-plane credential (the publishable-key
+   * predecessor from root ADR 036), also captured at creation.
+   */
   previewSecret?: string;
+  /**
+   * Platform-plane credential slot. Unpopulated until the platform-project
+   * provisioner (Console ADR 0004 §2) lands server-side; see
+   * `PlatformCredentials` for what it carries, why it stays empty today, and
+   * why the still-undecided credentials are left out of it.
+   */
+  platform?: PlatformCredentials;
 }
 interface SeedUserInput {
   email?: string;
@@ -103,13 +149,19 @@ interface LocalZitadel extends ConnectedZitadel, AsyncDisposable {
 }
 //#endregion
 //#region src/app-env.d.ts
+/**
+ * Handle fields a template may reference: the flat string facts. Structured
+ * fields (e.g. `platform`) are not env-var material — consumers read those
+ * from the handle directly.
+ */
+type StringHandleField = { [K in keyof InstanceHandle]-?: InstanceHandle[K] extends string | undefined ? K : never }[keyof InstanceHandle];
 /**
  * Declarative mapping from an app's env var names to InstanceHandle fields.
  * A template (not a function) so it can cross process boundaries: the
  * Playwright config serializes it into the app-runner's environment, where it
  * is applied to the handle read from the handshake file.
  */
-type AppEnvTemplate = Record<string, keyof InstanceHandle>;
+type AppEnvTemplate = Record<string, StringHandleField>;
 /**
  * The env shape `@zitadel/sdk-next` apps read. Other frameworks pass their own
  * template — the console maps the same handle fields to `VITE_*`/`CONSOLE_*`
@@ -118,5 +170,5 @@ type AppEnvTemplate = Record<string, keyof InstanceHandle>;
 declare const nextAppEnv: AppEnvTemplate;
 declare function applyAppEnvTemplate(template: AppEnvTemplate, handle: InstanceHandle): Record<string, string>;
 //#endregion
-export { Identity as a, LocalZitadelRuntime as c, SeedUserInput as d, SeedUsersTemplate as f, ConnectedZitadel as i, MintedSession as l, SessionCookie as m, applyAppEnvTemplate as n, InstanceHandle as o, SeededUser as p, nextAppEnv as r, LocalZitadel as s, AppEnvTemplate as t, SeedSessionInput as u };
-//# sourceMappingURL=app-env-D3W0GYhA.d.mts.map
+export { Identity as a, LocalZitadelRuntime as c, SeedSessionInput as d, SeedUserInput as f, SessionCookie as h, ConnectedZitadel as i, MintedSession as l, SeededUser as m, applyAppEnvTemplate as n, InstanceHandle as o, SeedUsersTemplate as p, nextAppEnv as r, LocalZitadel as s, AppEnvTemplate as t, PlatformCredentials as u };
+//# sourceMappingURL=app-env-DlrV_ePR.d.mts.map

package/dist/app-env-DlrV_ePR.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-env-DlrV_ePR.d.mts","names":[],"sources":["../src/types.ts","../src/app-env.ts"],"mappings":";;;;;AAkBA;;;;;AAmBA;;;;;;;;;UAnBiB,mBAAA;EAmDf;EAjDA,SAAA;EAiD8B;;AAGhC;;;EA9CE,cAAA;AAAA;;;;;;AAqDF;;;UA1CiB,cAAA;EACf,OAAA;EACA,SAAA;EA2CA;;;AAIF;;EAzCE,aAAA;EA0CA;;AAKF;;;EAzCE,SAAA;EA0CA;;;;;EApCA,QAAA;EAyCI;;AAGN;;EAvCE,aAAA;EA4CqB;;;;;;EArCrB,QAAA,GAAW,mBAAA;AAAA;AAAA,UAGI,aAAA;EACf,KAAA;EACA,QAAA;;EAEA,UAAA,GAAa,MAAA;AAAA;AAAA,UAGE,UAAA;EACf,EAAA;EACA,KAAA;EACA,QAAA;AAAA;;UAIe,QAAA;EACf,KAAA;EACA,QAAA;AAAA;;UAIe,aAAA;EACf,IAAA;EACA,KAAA;EACA,QAAA;EACA,MAAA;EACA,QAAA;EACA,IAAA;AAAA;AAAA,UAGe,aAAA;EACf,IAAA,EAAM,UAAA;;EAEN,YAAA;EACA,SAAA;EACA,MAAA,EAAQ,aAAA;AAAA;AAAA,UAGO,gBAAA,SAAyB,aAAA;EAyBP;EAvBjC,IAAA,GAAO,UAAA;EAyByD;EAvBhE,kBAAA;EAyBY;;;;;EAnBZ,MAAA;AAAA;AAAA,UAGe,iBAAA;EACf,KAAA,IAAS,KAAA;EACT,QAAA,IAAY,KAAA;EACZ,UAAA,IAAc,KAAA,aAAkB,MAAA;AAAA;AAAA,UAGjB,gBAAA;EACf,MAAA,EAAQ,cAAA;EAKC;EAHT,GAAA,EAAK,aAAA;EAGoC;EADzC,MAAA,EAAQ,MAAA;EACR,QAAA,CAAS,KAAA,GAAQ,aAAA,GAAgB,OAAA,CAAQ,UAAA;EAEL;EAApC,SAAA,CAAU,KAAA,UAAe,QAAA,GAAW,iBAAA,GAAoB,OAAA,CAAQ,UAAA;EAAR;EAExD,QAAA,IAAY,QAAA;EAAZ;;;;;EAMA,WAAA,CAAY,KAAA,GAAQ,gBAAA,GAAmB,OAAA,CAAQ,aAAA;AAAA;AAAA,UAGhC,mBAAA;EACf,IAAA;EACA,GAAA;EAFkC;EAIlC,GAAA;EACA,OAAA;AAAA;AAAA,UAGe,YAAA,SAAqB,gBAAA,EAAkB,eAAA;EACtD,OAAA,EAAS,mBAAA;EACT,IAAA,IAAQ,OAAA;AAAA;;;;;AA3IV;;;KCXK,iBAAA,iBACS,cAAA,KAAmB,cAAA,CAAe,CAAA,+BAAgC,CAAA,iBACxE,cAAA;;;;;;;KAQI,cAAA,GAAiB,MAAA,SAAe,iBAAA;;;;;;cAO/B,UAAA,EAAY,cAAA;AAAA,iBAMT,mBAAA,CACd,QAAA,EAAU,cAAA,EACV,MAAA,EAAQ,cAAA,GACP,MAAA"}

package/dist/app-runner.cjs

@@ -1,4 +1,4 @@
-const require_handshake = require("./handshake-CRKcgkfN.cjs");
+const require_handshake = require("./handshake-BOsVBPtn.cjs");
 const require_orchestration = require("./orchestration-D7QBgQ0l.cjs");
 let node_child_process = require("node:child_process");
 //#region src/app-runner.ts

package/dist/app-runner.mjs

@@ -1,4 +1,4 @@
-import { i as applyAppEnvTemplate, n as waitForHandshake } from "./handshake-ClzWvG8z.mjs";
+import { i as applyAppEnvTemplate, n as waitForHandshake } from "./handshake-BnAPXC6s.mjs";
 import { i as parseAppRunnerConfig, o as requireHandshakePath, t as APP_RUNNER_CONFIG_ENV } from "./orchestration-C640_1Lg.mjs";
 import { spawn } from "node:child_process";
 //#region src/app-runner.ts

package/dist/{handshake-CRKcgkfN.cjs → handshake-BOsVBPtn.cjs}

@@ -62,8 +62,21 @@ function validateHandle(value, source) {
 		"schemaId"
 	]) if (typeof handle[field] !== "string" || handle[field].length === 0) throw new Error(`handshake file ${source} is missing "${field}"`);
 	if (!URL.canParse(handle.baseUrl)) throw new Error(`handshake file ${source} has a malformed "baseUrl": ${handle.baseUrl}`);
+	if (handle.platform !== void 0) validatePlatform(handle.platform, source);
 	return handle;
 }
+/**
+* The handshake is the cross-process contract, so a malformed platform block
+* must fail here with the field name, not later with a less actionable error.
+*/
+function validatePlatform(value, source) {
+	const fail = (detail) => {
+		throw new Error(`handshake file ${source} has a malformed "platform" block: ${detail}`);
+	};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) fail("not an object");
+	const platform = value;
+	for (const field of ["projectId", "publishableKey"]) if (typeof platform[field] !== "string" || platform[field].length === 0) fail(`"${field}" is required`);
+}
 //#endregion
 Object.defineProperty(exports, "applyAppEnvTemplate", {
 	enumerable: true,
@@ -96,4 +109,4 @@ Object.defineProperty(exports, "writeHandshake", {
 	}
 });
 
-//# sourceMappingURL=handshake-CRKcgkfN.cjs.map
+//# sourceMappingURL=handshake-BOsVBPtn.cjs.map

package/dist/handshake-BOsVBPtn.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-BOsVBPtn.cjs","names":[],"sources":["../src/app-env.ts","../src/handshake.ts"],"sourcesContent":["import type { InstanceHandle } from \"./types\";\n\n/**\n * Handle fields a template may reference: the flat string facts. Structured\n * fields (e.g. `platform`) are not env-var material — consumers read those\n * from the handle directly.\n */\ntype StringHandleField = {\n  [K in keyof InstanceHandle]-?: InstanceHandle[K] extends string | undefined ? K : never;\n}[keyof InstanceHandle];\n\n/**\n * Declarative mapping from an app's env var names to InstanceHandle fields.\n * A template (not a function) so it can cross process boundaries: the\n * Playwright config serializes it into the app-runner's environment, where it\n * is applied to the handle read from the handshake file.\n */\nexport type AppEnvTemplate = Record<string, StringHandleField>;\n\n/**\n * The env shape `@zitadel/sdk-next` apps read. Other frameworks pass their own\n * template — the console maps the same handle fields to `VITE_*`/`CONSOLE_*`\n * names, for example.\n */\nexport const nextAppEnv: AppEnvTemplate = {\n  ZITADEL_URL: \"baseUrl\",\n  NEXT_PUBLIC_ZITADEL_PROJECT_ID: \"projectId\",\n  ZITADEL_PROJECT_SECRET: \"projectSecret\",\n};\n\nexport function applyAppEnvTemplate(\n  template: AppEnvTemplate,\n  handle: InstanceHandle,\n): Record<string, string> {\n  const env: Record<string, string> = {};\n  for (const [name, field] of Object.entries(template)) {\n    const value = handle[field];\n    if (typeof value !== \"string\" || value.length === 0) {\n      // Fail instead of silently dropping the var: an app booted without one\n      // of its env vars produces a much harder-to-read failure downstream.\n      throw new Error(\n        `app env template maps \"${name}\" to handle field \"${field}\", which the instance handle does not carry`,\n      );\n    }\n    env[name] = value;\n  }\n  return env;\n}\n","import { readFileSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { setTimeout as sleep } from \"node:timers/promises\";\n\nimport type { InstanceHandle, PlatformCredentials } from \"./types\";\n\n/**\n * The handshake file carries an InstanceHandle across process boundaries:\n * written by the script that boots + bootstraps the instance, read by\n * Playwright workers (fixtures) and the app dev-server wrapper.\n */\nexport async function writeHandshake(path: string, handle: InstanceHandle): Promise<void> {\n  await mkdir(dirname(path), { recursive: true });\n  await writeFile(path, `${JSON.stringify(handle, null, 2)}\\n`, { mode: 0o600 });\n}\n\nexport function readHandshakeSync(path: string): InstanceHandle {\n  const contents = readFileSync(path, \"utf8\");\n  let value: unknown;\n  try {\n    value = JSON.parse(contents);\n  } catch (error) {\n    throw new Error(`handshake file ${path} contains invalid JSON: ${(error as Error).message}`, {\n      cause: error,\n    });\n  }\n  return validateHandle(value, path);\n}\n\nexport async function waitForHandshake(path: string, timeoutMs = 60_000): Promise<InstanceHandle> {\n  const deadline = Date.now() + timeoutMs;\n  for (;;) {\n    try {\n      return validateHandle(JSON.parse(await readFile(path, \"utf8\")), path);\n    } catch (error) {\n      if (Date.now() >= deadline) {\n        throw new Error(\n          `handshake file not readable within ${timeoutMs}ms: ${path} (${(error as Error).message})`,\n          { cause: error },\n        );\n      }\n      await sleep(250);\n    }\n  }\n}\n\nfunction validateHandle(value: unknown, source: string): InstanceHandle {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new Error(`handshake file ${source} is not an object`);\n  }\n  const handle = value as Partial<InstanceHandle>;\n  for (const field of [\"baseUrl\", \"projectId\", \"projectSecret\", \"schemaId\"] as const) {\n    if (typeof handle[field] !== \"string\" || handle[field].length === 0) {\n      throw new Error(`handshake file ${source} is missing \"${field}\"`);\n    }\n  }\n  if (!URL.canParse(handle.baseUrl as string)) {\n    throw new Error(`handshake file ${source} has a malformed \"baseUrl\": ${handle.baseUrl}`);\n  }\n  if (handle.platform !== undefined) {\n    validatePlatform(handle.platform, source);\n  }\n  return handle as InstanceHandle;\n}\n\n/**\n * The handshake is the cross-process contract, so a malformed platform block\n * must fail here with the field name, not later with a less actionable error.\n */\nfunction validatePlatform(value: unknown, source: string): void {\n  const fail = (detail: string): never => {\n    throw new Error(`handshake file ${source} has a malformed \"platform\" block: ${detail}`);\n  };\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    fail(\"not an object\");\n  }\n  const platform = value as Partial<PlatformCredentials>;\n  for (const field of [\"projectId\", \"publishableKey\"] as const) {\n    if (typeof platform[field] !== \"string\" || platform[field].length === 0) {\n      fail(`\"${field}\" is required`);\n    }\n  }\n  // Unknown extra fields pass through on purpose: future platform\n  // credentials join additively, and an older reader must not reject a\n  // newer producer's handle.\n}\n"],"mappings":";;;;;;;;;;AAwBA,MAAa,aAA6B;CACxC,aAAa;CACb,gCAAgC;CAChC,wBAAwB;CACzB;AAED,SAAgB,oBACd,UACA,QACwB;CACxB,MAAM,MAA8B,EAAE;AACtC,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,SAAS,EAAE;EACpD,MAAM,QAAQ,OAAO;AACrB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAGhD,OAAM,IAAI,MACR,0BAA0B,KAAK,qBAAqB,MAAM,6CAC3D;AAEH,MAAI,QAAQ;;AAEd,QAAO;;;;;;;;;AClCT,eAAsB,eAAe,MAAc,QAAuC;AACxF,QAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAC/C,QAAA,GAAA,iBAAA,WAAgB,MAAM,GAAG,KAAK,UAAU,QAAQ,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAO,CAAC;;AAGhF,SAAgB,kBAAkB,MAA8B;CAC9D,MAAM,YAAA,GAAA,QAAA,cAAwB,MAAM,OAAO;CAC3C,IAAI;AACJ,KAAI;AACF,UAAQ,KAAK,MAAM,SAAS;UACrB,OAAO;AACd,QAAM,IAAI,MAAM,kBAAkB,KAAK,0BAA2B,MAAgB,WAAW,EAC3F,OAAO,OACR,CAAC;;AAEJ,QAAO,eAAe,OAAO,KAAK;;AAGpC,eAAsB,iBAAiB,MAAc,YAAY,KAAiC;CAChG,MAAM,WAAW,KAAK,KAAK,GAAG;AAC9B,SACE,KAAI;AACF,SAAO,eAAe,KAAK,MAAM,OAAA,GAAA,iBAAA,UAAe,MAAM,OAAO,CAAC,EAAE,KAAK;UAC9D,OAAO;AACd,MAAI,KAAK,KAAK,IAAI,SAChB,OAAM,IAAI,MACR,sCAAsC,UAAU,MAAM,KAAK,IAAK,MAAgB,QAAQ,IACxF,EAAE,OAAO,OAAO,CACjB;AAEH,SAAA,GAAA,qBAAA,YAAY,IAAI;;;AAKtB,SAAS,eAAe,OAAgB,QAAgC;AACtE,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CACrE,OAAM,IAAI,MAAM,kBAAkB,OAAO,mBAAmB;CAE9D,MAAM,SAAS;AACf,MAAK,MAAM,SAAS;EAAC;EAAW;EAAa;EAAiB;EAAW,CACvE,KAAI,OAAO,OAAO,WAAW,YAAY,OAAO,OAAO,WAAW,EAChE,OAAM,IAAI,MAAM,kBAAkB,OAAO,eAAe,MAAM,GAAG;AAGrE,KAAI,CAAC,IAAI,SAAS,OAAO,QAAkB,CACzC,OAAM,IAAI,MAAM,kBAAkB,OAAO,8BAA8B,OAAO,UAAU;AAE1F,KAAI,OAAO,aAAa,KAAA,EACtB,kBAAiB,OAAO,UAAU,OAAO;AAE3C,QAAO;;;;;;AAOT,SAAS,iBAAiB,OAAgB,QAAsB;CAC9D,MAAM,QAAQ,WAA0B;AACtC,QAAM,IAAI,MAAM,kBAAkB,OAAO,qCAAqC,SAAS;;AAEzF,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CACrE,MAAK,gBAAgB;CAEvB,MAAM,WAAW;AACjB,MAAK,MAAM,SAAS,CAAC,aAAa,iBAAiB,CACjD,KAAI,OAAO,SAAS,WAAW,YAAY,SAAS,OAAO,WAAW,EACpE,MAAK,IAAI,MAAM,eAAe"}

package/dist/{handshake-ClzWvG8z.mjs → handshake-BnAPXC6s.mjs}

@@ -62,9 +62,22 @@ function validateHandle(value, source) {
 		"schemaId"
 	]) if (typeof handle[field] !== "string" || handle[field].length === 0) throw new Error(`handshake file ${source} is missing "${field}"`);
 	if (!URL.canParse(handle.baseUrl)) throw new Error(`handshake file ${source} has a malformed "baseUrl": ${handle.baseUrl}`);
+	if (handle.platform !== void 0) validatePlatform(handle.platform, source);
 	return handle;
 }
+/**
+* The handshake is the cross-process contract, so a malformed platform block
+* must fail here with the field name, not later with a less actionable error.
+*/
+function validatePlatform(value, source) {
+	const fail = (detail) => {
+		throw new Error(`handshake file ${source} has a malformed "platform" block: ${detail}`);
+	};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) fail("not an object");
+	const platform = value;
+	for (const field of ["projectId", "publishableKey"]) if (typeof platform[field] !== "string" || platform[field].length === 0) fail(`"${field}" is required`);
+}
 //#endregion
 export { nextAppEnv as a, applyAppEnvTemplate as i, waitForHandshake as n, writeHandshake as r, readHandshakeSync as t };
 
-//# sourceMappingURL=handshake-ClzWvG8z.mjs.map
+//# sourceMappingURL=handshake-BnAPXC6s.mjs.map

package/dist/handshake-BnAPXC6s.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake-BnAPXC6s.mjs","names":["sleep"],"sources":["../src/app-env.ts","../src/handshake.ts"],"sourcesContent":["import type { InstanceHandle } from \"./types\";\n\n/**\n * Handle fields a template may reference: the flat string facts. Structured\n * fields (e.g. `platform`) are not env-var material — consumers read those\n * from the handle directly.\n */\ntype StringHandleField = {\n  [K in keyof InstanceHandle]-?: InstanceHandle[K] extends string | undefined ? K : never;\n}[keyof InstanceHandle];\n\n/**\n * Declarative mapping from an app's env var names to InstanceHandle fields.\n * A template (not a function) so it can cross process boundaries: the\n * Playwright config serializes it into the app-runner's environment, where it\n * is applied to the handle read from the handshake file.\n */\nexport type AppEnvTemplate = Record<string, StringHandleField>;\n\n/**\n * The env shape `@zitadel/sdk-next` apps read. Other frameworks pass their own\n * template — the console maps the same handle fields to `VITE_*`/`CONSOLE_*`\n * names, for example.\n */\nexport const nextAppEnv: AppEnvTemplate = {\n  ZITADEL_URL: \"baseUrl\",\n  NEXT_PUBLIC_ZITADEL_PROJECT_ID: \"projectId\",\n  ZITADEL_PROJECT_SECRET: \"projectSecret\",\n};\n\nexport function applyAppEnvTemplate(\n  template: AppEnvTemplate,\n  handle: InstanceHandle,\n): Record<string, string> {\n  const env: Record<string, string> = {};\n  for (const [name, field] of Object.entries(template)) {\n    const value = handle[field];\n    if (typeof value !== \"string\" || value.length === 0) {\n      // Fail instead of silently dropping the var: an app booted without one\n      // of its env vars produces a much harder-to-read failure downstream.\n      throw new Error(\n        `app env template maps \"${name}\" to handle field \"${field}\", which the instance handle does not carry`,\n      );\n    }\n    env[name] = value;\n  }\n  return env;\n}\n","import { readFileSync } from \"node:fs\";\nimport { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { setTimeout as sleep } from \"node:timers/promises\";\n\nimport type { InstanceHandle, PlatformCredentials } from \"./types\";\n\n/**\n * The handshake file carries an InstanceHandle across process boundaries:\n * written by the script that boots + bootstraps the instance, read by\n * Playwright workers (fixtures) and the app dev-server wrapper.\n */\nexport async function writeHandshake(path: string, handle: InstanceHandle): Promise<void> {\n  await mkdir(dirname(path), { recursive: true });\n  await writeFile(path, `${JSON.stringify(handle, null, 2)}\\n`, { mode: 0o600 });\n}\n\nexport function readHandshakeSync(path: string): InstanceHandle {\n  const contents = readFileSync(path, \"utf8\");\n  let value: unknown;\n  try {\n    value = JSON.parse(contents);\n  } catch (error) {\n    throw new Error(`handshake file ${path} contains invalid JSON: ${(error as Error).message}`, {\n      cause: error,\n    });\n  }\n  return validateHandle(value, path);\n}\n\nexport async function waitForHandshake(path: string, timeoutMs = 60_000): Promise<InstanceHandle> {\n  const deadline = Date.now() + timeoutMs;\n  for (;;) {\n    try {\n      return validateHandle(JSON.parse(await readFile(path, \"utf8\")), path);\n    } catch (error) {\n      if (Date.now() >= deadline) {\n        throw new Error(\n          `handshake file not readable within ${timeoutMs}ms: ${path} (${(error as Error).message})`,\n          { cause: error },\n        );\n      }\n      await sleep(250);\n    }\n  }\n}\n\nfunction validateHandle(value: unknown, source: string): InstanceHandle {\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new Error(`handshake file ${source} is not an object`);\n  }\n  const handle = value as Partial<InstanceHandle>;\n  for (const field of [\"baseUrl\", \"projectId\", \"projectSecret\", \"schemaId\"] as const) {\n    if (typeof handle[field] !== \"string\" || handle[field].length === 0) {\n      throw new Error(`handshake file ${source} is missing \"${field}\"`);\n    }\n  }\n  if (!URL.canParse(handle.baseUrl as string)) {\n    throw new Error(`handshake file ${source} has a malformed \"baseUrl\": ${handle.baseUrl}`);\n  }\n  if (handle.platform !== undefined) {\n    validatePlatform(handle.platform, source);\n  }\n  return handle as InstanceHandle;\n}\n\n/**\n * The handshake is the cross-process contract, so a malformed platform block\n * must fail here with the field name, not later with a less actionable error.\n */\nfunction validatePlatform(value: unknown, source: string): void {\n  const fail = (detail: string): never => {\n    throw new Error(`handshake file ${source} has a malformed \"platform\" block: ${detail}`);\n  };\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    fail(\"not an object\");\n  }\n  const platform = value as Partial<PlatformCredentials>;\n  for (const field of [\"projectId\", \"publishableKey\"] as const) {\n    if (typeof platform[field] !== \"string\" || platform[field].length === 0) {\n      fail(`\"${field}\" is required`);\n    }\n  }\n  // Unknown extra fields pass through on purpose: future platform\n  // credentials join additively, and an older reader must not reject a\n  // newer producer's handle.\n}\n"],"mappings":";;;;;;;;;;AAwBA,MAAa,aAA6B;CACxC,aAAa;CACb,gCAAgC;CAChC,wBAAwB;CACzB;AAED,SAAgB,oBACd,UACA,QACwB;CACxB,MAAM,MAA8B,EAAE;AACtC,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,SAAS,EAAE;EACpD,MAAM,QAAQ,OAAO;AACrB,MAAI,OAAO,UAAU,YAAY,MAAM,WAAW,EAGhD,OAAM,IAAI,MACR,0BAA0B,KAAK,qBAAqB,MAAM,6CAC3D;AAEH,MAAI,QAAQ;;AAEd,QAAO;;;;;;;;;AClCT,eAAsB,eAAe,MAAc,QAAuC;AACxF,OAAM,MAAM,QAAQ,KAAK,EAAE,EAAE,WAAW,MAAM,CAAC;AAC/C,OAAM,UAAU,MAAM,GAAG,KAAK,UAAU,QAAQ,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAO,CAAC;;AAGhF,SAAgB,kBAAkB,MAA8B;CAC9D,MAAM,WAAW,aAAa,MAAM,OAAO;CAC3C,IAAI;AACJ,KAAI;AACF,UAAQ,KAAK,MAAM,SAAS;UACrB,OAAO;AACd,QAAM,IAAI,MAAM,kBAAkB,KAAK,0BAA2B,MAAgB,WAAW,EAC3F,OAAO,OACR,CAAC;;AAEJ,QAAO,eAAe,OAAO,KAAK;;AAGpC,eAAsB,iBAAiB,MAAc,YAAY,KAAiC;CAChG,MAAM,WAAW,KAAK,KAAK,GAAG;AAC9B,SACE,KAAI;AACF,SAAO,eAAe,KAAK,MAAM,MAAM,SAAS,MAAM,OAAO,CAAC,EAAE,KAAK;UAC9D,OAAO;AACd,MAAI,KAAK,KAAK,IAAI,SAChB,OAAM,IAAI,MACR,sCAAsC,UAAU,MAAM,KAAK,IAAK,MAAgB,QAAQ,IACxF,EAAE,OAAO,OAAO,CACjB;AAEH,QAAMA,WAAM,IAAI;;;AAKtB,SAAS,eAAe,OAAgB,QAAgC;AACtE,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CACrE,OAAM,IAAI,MAAM,kBAAkB,OAAO,mBAAmB;CAE9D,MAAM,SAAS;AACf,MAAK,MAAM,SAAS;EAAC;EAAW;EAAa;EAAiB;EAAW,CACvE,KAAI,OAAO,OAAO,WAAW,YAAY,OAAO,OAAO,WAAW,EAChE,OAAM,IAAI,MAAM,kBAAkB,OAAO,eAAe,MAAM,GAAG;AAGrE,KAAI,CAAC,IAAI,SAAS,OAAO,QAAkB,CACzC,OAAM,IAAI,MAAM,kBAAkB,OAAO,8BAA8B,OAAO,UAAU;AAE1F,KAAI,OAAO,aAAa,KAAA,EACtB,kBAAiB,OAAO,UAAU,OAAO;AAE3C,QAAO;;;;;;AAOT,SAAS,iBAAiB,OAAgB,QAAsB;CAC9D,MAAM,QAAQ,WAA0B;AACtC,QAAM,IAAI,MAAM,kBAAkB,OAAO,qCAAqC,SAAS;;AAEzF,KAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,MAAM,CACrE,MAAK,gBAAgB;CAEvB,MAAM,WAAW;AACjB,MAAK,MAAM,SAAS,CAAC,aAAa,iBAAiB,CACjD,KAAI,OAAO,SAAS,WAAW,YAAY,SAAS,OAAO,WAAW,EACpE,MAAK,IAAI,MAAM,eAAe"}

package/dist/index.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-DirKLqi4.cjs");
-const require_handshake = require("./handshake-CRKcgkfN.cjs");
+const require_src = require("./src-DtCJTEId.cjs");
+const require_handshake = require("./handshake-BOsVBPtn.cjs");
 exports.SESSION_COOKIE_NAME = require_src.SESSION_COOKIE_NAME;
 exports.applyAppEnvTemplate = require_handshake.applyAppEnvTemplate;
 exports.bootLocalServer = require_src.bootLocalServer;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as Identity, c as LocalZitadelRuntime, d as SeedUserInput, f as SeedUsersTemplate, i as ConnectedZitadel, l as MintedSession, m as SessionCookie, n as applyAppEnvTemplate, o as InstanceHandle, p as SeededUser, r as nextAppEnv, s as LocalZitadel, t as AppEnvTemplate, u as SeedSessionInput } from "./app-env-D3W0GYhA.mjs";
+import { a as Identity, c as LocalZitadelRuntime, d as SeedSessionInput, f as SeedUserInput, h as SessionCookie, i as ConnectedZitadel, l as MintedSession, m as SeededUser, n as applyAppEnvTemplate, o as InstanceHandle, p as SeedUsersTemplate, r as nextAppEnv, s as LocalZitadel, t as AppEnvTemplate, u as PlatformCredentials } from "./app-env-DlrV_ePR.mjs";
 import { ZitadelClient } from "@zitadel/api/client";
 import { SetupPreset, SetupUseCase } from "@zitadel/config/defaults";
 
@@ -88,5 +88,5 @@ declare function connectZitadel(handle: InstanceHandle): ConnectedZitadel;
  */
 declare function startLocalZitadel(options?: StartLocalZitadelOptions): Promise<LocalZitadel>;
 //#endregion
-export { type AppEnvTemplate, type BootServerOptions, type BootedServer, type BootstrapProjectOptions, type BootstrappedProject, type ConnectedZitadel, type Identity, type InstanceHandle, type LocalZitadel, type LocalZitadelRuntime, type MintedSession, SESSION_COOKIE_NAME, type SeedSessionInput, type SeedUserInput, type SeedUsersTemplate, type SeededUser, type SessionCookie, StartLocalZitadelOptions, applyAppEnvTemplate, bootLocalServer, bootstrapProject, connectZitadel, nextAppEnv, readHandshakeSync, startLocalZitadel, waitForHandshake, writeHandshake };
+export { type AppEnvTemplate, type BootServerOptions, type BootedServer, type BootstrapProjectOptions, type BootstrappedProject, type ConnectedZitadel, type Identity, type InstanceHandle, type LocalZitadel, type LocalZitadelRuntime, type MintedSession, type PlatformCredentials, SESSION_COOKIE_NAME, type SeedSessionInput, type SeedUserInput, type SeedUsersTemplate, type SeededUser, type SessionCookie, StartLocalZitadelOptions, applyAppEnvTemplate, bootLocalServer, bootstrapProject, connectZitadel, nextAppEnv, readHandshakeSync, startLocalZitadel, waitForHandshake, writeHandshake };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { a as nextAppEnv, i as applyAppEnvTemplate, n as waitForHandshake, r as writeHandshake, t as readHandshakeSync } from "./handshake-ClzWvG8z.mjs";
-import { a as bootstrapProject, i as bootLocalServer, n as startLocalZitadel, r as SESSION_COOKIE_NAME, t as connectZitadel } from "./src-eTcdx-ZS.mjs";
+import { a as nextAppEnv, i as applyAppEnvTemplate, n as waitForHandshake, r as writeHandshake, t as readHandshakeSync } from "./handshake-BnAPXC6s.mjs";
+import { a as bootstrapProject, i as bootLocalServer, n as startLocalZitadel, r as SESSION_COOKIE_NAME, t as connectZitadel } from "./src-Dkt0HHu8.mjs";
 export { SESSION_COOKIE_NAME, applyAppEnvTemplate, bootLocalServer, bootstrapProject, connectZitadel, nextAppEnv, readHandshakeSync, startLocalZitadel, waitForHandshake, writeHandshake };

package/dist/playwright.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_src = require("./src-DirKLqi4.cjs");
-const require_handshake = require("./handshake-CRKcgkfN.cjs");
+const require_src = require("./src-DtCJTEId.cjs");
+const require_handshake = require("./handshake-BOsVBPtn.cjs");
 const require_orchestration = require("./orchestration-D7QBgQ0l.cjs");
 let node_fs = require("node:fs");
 let node_url = require("node:url");
@@ -245,6 +245,10 @@ async function fillIfVisible(field, value) {
 * });
 * ```
 *
+* Omit `app` when the instance serves the app itself (the binary's embedded
+* `/ui/console/` and `/ui/login/` surfaces): only the boot entry is
+* generated, and `appOrigin` must be the instance's own origin.
+*
 * Also points ZITADEL_TESTING_HANDSHAKE at the handshake file so the
 * `@zitadel/testing/playwright` fixtures resolve the instance — Playwright
 * workers re-evaluate the config, which re-applies this for every process
@@ -257,9 +261,18 @@ function withZitadel(options, resolveEntry = entryPoint) {
 	if (!Number.isInteger(port) || port <= 0) throw new Error(`withZitadel: port must be a positive integer, got ${port}`);
 	const origin = URL.canParse(appOrigin) ? new URL(appOrigin) : void 0;
 	if (!origin || origin.protocol !== "http:" && origin.protocol !== "https:" || origin.pathname !== "/" || origin.search !== "" || origin.hash !== "") throw new Error(`withZitadel: appOrigin must be an origin like "http://localhost:3002", got "${appOrigin}"`);
-	if (!app.readyPath.startsWith("/")) throw new Error(`withZitadel: app.readyPath must start with "/", got "${app.readyPath}"`);
-	if (app.command.length === 0) throw new Error("withZitadel: app.command must not be empty");
-	if (!(0, node_path.isAbsolute)(app.cwd)) throw new Error(`withZitadel: app.cwd must be absolute, got "${app.cwd}"`);
+	if (app === void 0) {
+		const loopbackHosts = new Set([
+			"localhost",
+			"127.0.0.1",
+			"[::1]"
+		]);
+		if (origin.protocol !== "http:" || !loopbackHosts.has(origin.hostname) || (origin.port || "80") !== String(port)) throw new Error(`withZitadel: with no \`app\`, the instance itself serves the app, so appOrigin must be its local origin (http://localhost:${port}); got "${appOrigin}".`);
+	} else {
+		if (!app.readyPath.startsWith("/")) throw new Error(`withZitadel: app.readyPath must start with "/", got "${app.readyPath}"`);
+		if (app.command.length === 0) throw new Error("withZitadel: app.command must not be empty");
+		if (!(0, node_path.isAbsolute)(app.cwd)) throw new Error(`withZitadel: app.cwd must be absolute, got "${app.cwd}"`);
+	}
 	for (const [label, value] of [
 		["zitadel.serverBinary", options.zitadel?.serverBinary],
 		["zitadel.dir", options.zitadel?.dir],
@@ -278,13 +291,7 @@ function withZitadel(options, resolveEntry = entryPoint) {
 		preset: options.zitadel?.preset,
 		useCase: options.zitadel?.useCase
 	};
-	const appRunnerConfig = {
-		command: app.command,
-		cwd: app.cwd,
-		env: app.env,
-		handshakeTimeoutMs: app.readyTimeoutMs ?? 18e4
-	};
-	return { webServer: [{
+	const supervisorEntry = {
 		command: `node ${JSON.stringify(resolveEntry("supervisor"))}`,
 		url: `http://localhost:${port}/healthz`,
 		reuseExistingServer: false,
@@ -300,7 +307,15 @@ function withZitadel(options, resolveEntry = entryPoint) {
 			signal: "SIGTERM",
 			timeout: 3e4
 		}
-	}, {
+	};
+	if (app === void 0) return { webServer: [supervisorEntry] };
+	const appRunnerConfig = {
+		command: app.command,
+		cwd: app.cwd,
+		env: app.env,
+		handshakeTimeoutMs: app.readyTimeoutMs ?? 18e4
+	};
+	return { webServer: [supervisorEntry, {
 		command: `node ${JSON.stringify(resolveEntry("app-runner"))}`,
 		url: new URL(app.readyPath, appOrigin).toString(),
 		reuseExistingServer: false,
@@ -337,8 +352,11 @@ const test = _playwright_test.test.extend({
 	zitadel: [async ({}, use) => {
 		const handshakePath = process.env.ZITADEL_TESTING_HANDSHAKE;
 		if (!handshakePath) throw new Error("ZITADEL_TESTING_HANDSHAKE is not set. Point it at the handshake file written by the script that boots the instance (see @zitadel/testing docs).");
-		await use(require_src.connectZitadel(require_handshake.readHandshakeSync(handshakePath)));
-	}, { scope: "worker" }],
+		await use(require_src.connectZitadel(await require_handshake.waitForHandshake(handshakePath)));
+	}, {
+		scope: "worker",
+		auto: true
+	}],
 	seed: async ({ zitadel, baseURL }, use) => {
 		await use({
 			user: (input) => zitadel.seedUser(input),