@zitadel/config 0.1.0-alpha.18 → 0.1.0-alpha.19

package/README.md

@@ -0,0 +1,27 @@
+# @zitadel/config
+
+Versioned Zitadel local config schemas and defaults — the contract behind the
+`.zitadel/` directory that `zitadel setup` scaffolds into your project.
+
+## What's in here
+
+| Import                                             | What it carries                                                                                           |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `@zitadel/config/schemas`                          | Zod schemas for the local config files (`schemaConfigSchema`, `flowConfigSchema`, `brandingConfigSchema`) |
+| `@zitadel/config/branding-url`                     | Canonical loopback HTTP URL predicate shared by config and browser render gates                           |
+| `@zitadel/config/validate`                         | Validation entry points the CLI runs on `plan`/`apply`                                                    |
+| `@zitadel/config/normalize`                        | Normalization used to compare local files against server state                                            |
+| `@zitadel/config/defaults`                         | The versioned default user schema, login flow, and branding designs                                       |
+| `@zitadel/config/meta-schemas`                     | The JSON meta-schemas the defaults pin                                                                    |
+| `@zitadel/config/template`                         | Liquid template helpers                                                                                   |
+| `@zitadel/config/defaults/default-login.json`      | The default login flow — the authority for flow step shape                                                |
+| `@zitadel/config/defaults/default-human-user.json` | The default user schema                                                                                   |
+
+## The customer-facing part
+
+`zitadel setup` copies the defaults into your repo as
+`.zitadel/{schemas,flows,branding}/`, each with a README explaining how to
+edit it (`defaults/README-schemas.md`, `README-flows.md`,
+`README-branding.md` in this package become those files). Those files are
+yours to edit; `zitadel plan` / `zitadel apply` reconcile them with the
+server, and edits publish new revisions rather than mutating state in place.

package/defaults/README-branding.md

@@ -6,7 +6,7 @@ and asset URLs) plus `login.liquid`, the LiquidJS template the
 
 ## Workflow
 
-1. Edit `login.liquid` (and `branding.json` for logo/font/hero URLs).
+1. Edit `login.liquid` (and `branding.json` for logo/hero URLs).
 2. `zitadel plan` — validates the template (LiquidJS parse, banned patterns,
    the required `{% mandatory_gates %}` tag) and shows the pending revision.
 3. `zitadel apply` — publishes an immutable branding revision. The login UI
@@ -27,6 +27,40 @@ by re-applying an earlier template.
 
 ## Make it yours
 
+- Brand asset URLs go in `branding.json` and must use `https://`. Each template
+  decides which fields it renders: `centered` and `hero` use `logo_url`; `split`
+  and `split-right` use both `logo_url` and `hero_url`; `minimal` uses neither
+  until you add them to `login.liquid`. The `hero` design's brand pane is
+  editable markup rather than a `hero_url` background. Custom fonts are not
+  configurable here yet; load them from the embedding page.
+
+  ```json
+  {
+    "$schema": "../meta/branding.json",
+    "layout": "split",
+    "liquid_template_file": "./login.liquid",
+    "logo_url": "https://example.com/logo.svg",
+    "hero_url": "https://example.com/hero.jpg"
+  }
+  ```
+
+  A well-formed URL that serves nothing is the one branding mistake nothing
+  else catches — it passes validation, publishes a revision, and then renders
+  as an invisible image. So `zitadel plan` probes each asset URL and warns
+  (never fails) when it is unreachable, bodyless, or not an image, and the
+  login UI hides an asset that fails to load, restoring the shipped design's
+  no-asset content rather than leaving a gap. If the host is only
+  reachable from where the login page renders — or you are offline — set
+  `ZITADEL_SKIP_ASSET_PROBE=1` to skip the check. The probe contacts public
+  HTTPS destinations only and re-checks redirects; loopback/private/internal
+  targets are left to the browser-side fallback instead of being requested by
+  the machine running `plan`.
+
+  `layout` is the degrade preset (`centered` or `split`), **not** the complete
+  design catalog. All named designs (`centered`, `split`, `split-right`, `hero`,
+  `minimal`) are delivered as templates and map onto those two values. Switch
+  designs with `zitadel branding eject --design <name>`, don't edit `layout`.
+
 - In the split-family designs (`split`, `split-right`, `hero`) the
   `.zl-split__brand` pane is yours: structural HTML plus inline `style=""`
   attributes are allowed; `button`, `input`, and `form` tags are stripped —
@@ -38,7 +72,7 @@ by re-applying an earlier template.
 - The split chrome is tunable from your template root's `style` attribute
   (`--zl-split-columns`, `--zl-split-align`, `--zl-split-brand-mobile`), and
   `zl-split--right` on the wrapper mirrors the panes. Knob reference:
-  `docs/design/branding/templates.md` in the Zitadel repo.
+  [`docs/design/branding/templates.md`](https://github.com/zitadel/nextgen/blob/main/docs/design/branding/templates.md).
 - The "Secured with Zitadel" attribution is licence-gated and on by default.
 - Back-navigation: the engine injects a `kind: "back"` action on steps
   that can return to their predecessor, and the browser's back gesture

package/defaults/README-flows.md

@@ -37,8 +37,25 @@ Typical edits:
   tokens).
 - **Add or remove a step** — extend `steps[]`.
 - **Rewire transitions** — edit `steps[].transitions` to point at a
-  different next step, or use `action: switch` / `pivot` to jump to
-  another flow.
+  different next step. Cross-flow jumps (`action: switch` / `pivot`)
+  validate in a definition but are **not yet executed by the runtime** —
+  submitting through one fails with a 400 (`code: "flow.unsupported"`);
+  keep transitions within one flow, using a purpose switch (next bullet)
+  for login ↔ register navigation.
+- **Offer a purpose switch in the card** — pair a `kind: navigate`
+  action with a transition that declares a local `purpose`. The default
+  login flow ships this in both directions:
+
+  ```json
+  "register": { "target": "register", "purpose": "register" }
+  ```
+
+  Navigation skips field validation (an empty email box can't block the
+  link), and the declared purpose is what makes the landing leg run with
+  the right semantics — register creates the user instead of trying to
+  verify one. Rules: the purpose must be one this flow's `purposes`
+  serves, the target must be that purpose's entry step, and `purpose`
+  never combines with `action` (which targets another flow instead).
 - **Add another flow** — drop a new JSON file with its own `purposes`
   and a distinct `name` (e.g. a per-team login). See
   [Multiple flows](#multiple-flows) for how it gets selected at runtime.
@@ -70,8 +87,8 @@ experiment can't silently take over `/login` — scope it or pin
 
 ## Presets
 
-`zitadel setup` scaffolds this folder from a preset (`--preset
-password-first` or `--preset passkey-first`). The passkey-first flow
+`zitadel setup` scaffolds this folder from a preset: `password-first` (the
+default root files) or `--preset passkey-first`. The passkey-first flow
 enters login on a fields-less passkey step with an email → password
 fallback path. The preset only decides the starting point — edit
 anything here afterwards.

package/defaults/README-schemas.md

@@ -28,8 +28,8 @@ Here's a simplified example:
     "firstName"
   ],
   "x-auth-methods": {
-    "password": { "enabled": true, "position": 1 },
-    "passkey": { "enabled": true, "position": 2 }
+    "password": { "enabled": true },
+    "passkey": { "enabled": true }
   }
 }
 ```

package/defaults/branding/hero/login.liquid

@@ -19,7 +19,8 @@
         <nav class="zl-hero__nav">
           <span class="zl-hero__brand">
             {% if branding.logo_url %}
-              <img class="zl-hero__brand-logo" src="{{ branding.logo_url }}" alt="" />
+              <img class="zl-hero__brand-logo" src="{{ branding.logo_url }}" alt="" data-zl-asset-fallback />
+              <span class="zl-hero__brand-mark" aria-hidden="true" hidden data-zl-asset-fallback-content></span>
             {% else %}
               <span class="zl-hero__brand-mark" aria-hidden="true"></span>
             {% endif %}
@@ -54,7 +55,8 @@
     </aside>
     <section class="zl-split__form">
     {% if branding.logo_url %}
-      <img class="zl-split__compact" src="{{ branding.logo_url }}" alt="" />
+      <img class="zl-split__compact" src="{{ branding.logo_url }}" alt="" data-zl-asset-fallback />
+      <p class="zl-split__compact zl-hero__compact-brand" hidden data-zl-asset-fallback-content>Your brand</p>
     {% else %}
       <p class="zl-split__compact zl-hero__compact-brand">Your brand</p>
     {% endif %}

package/defaults/branding/split/login.liquid

@@ -7,6 +7,11 @@
       {% if branding.hero_url %}
         <img class="zl-split__hero" src="{{ branding.hero_url }}" alt="" />
       {% endif %}
+      {% unless branding.logo_url or branding.hero_url %}
+        {% comment %} Until branding.json names an asset, a decorative panel
+           keeps the split composition readable. {% endcomment %}
+        <div class="zl-split__placeholder" aria-hidden="true"></div>
+      {% endunless %}
     </aside>
     <section class="zl-split__form">
     {% if branding.logo_url %}

package/defaults/branding/split-right/login.liquid

@@ -7,6 +7,11 @@
       {% if branding.hero_url %}
         <img class="zl-split__hero" src="{{ branding.hero_url }}" alt="" />
       {% endif %}
+      {% unless branding.logo_url or branding.hero_url %}
+        {% comment %} Until branding.json names an asset, a decorative panel
+           keeps the split composition readable. {% endcomment %}
+        <div class="zl-split__placeholder" aria-hidden="true"></div>
+      {% endunless %}
     </aside>
     <section class="zl-split__form">
     {% if branding.logo_url %}

package/defaults/default-human-user.json

@@ -9,12 +9,10 @@
   "description": "The default editable schema for human users.",
   "x-auth-methods": {
     "password": {
-      "enabled": true,
-      "position": 1
+      "enabled": true
     },
     "passkey": {
-      "enabled": true,
-      "position": 2
+      "enabled": true
     }
   },
   "required": [

package/defaults/default-login.json

@@ -25,6 +25,12 @@
           "kind": "passkey",
           "primary": false,
           "text_key": "identifier.action.passkey"
+        },
+        {
+          "name": "register",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "identifier.action.register.link"
         }
       ],
       "transitions": {
@@ -36,6 +42,10 @@
         },
         "user_not_found": {
           "target": "register"
+        },
+        "register": {
+          "target": "register",
+          "purpose": "register"
         }
       }
     },
@@ -84,6 +94,12 @@
           "kind": "passkey_register",
           "primary": false,
           "text_key": "register.action.passkey"
+        },
+        {
+          "name": "sign_in",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "register.action.sign_in.link"
         }
       ],
       "transitions": {
@@ -95,6 +111,10 @@
         },
         "user_already_exists": {
           "target": "password"
+        },
+        "sign_in": {
+          "target": "identifier",
+          "purpose": "login"
         }
       }
     },

package/defaults/presets/passkey-first/human-user.json

@@ -9,12 +9,10 @@
   "description": "The default editable schema for human users (passkey-first sign-in).",
   "x-auth-methods": {
     "passkey": {
-      "enabled": true,
-      "position": 1
+      "enabled": true
     },
     "password": {
-      "enabled": true,
-      "position": 2
+      "enabled": true
     }
   },
   "required": [

package/defaults/presets/passkey-first/login.json

@@ -23,6 +23,12 @@
           "kind": "navigate",
           "primary": false,
           "text_key": "passkey-first.action.email_fallback"
+        },
+        {
+          "name": "register",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "identifier.action.register.link"
         }
       ],
       "transitions": {
@@ -34,6 +40,10 @@
         },
         "user_not_found": {
           "target": "register"
+        },
+        "register": {
+          "target": "register",
+          "purpose": "register"
         }
       }
     },
@@ -54,6 +64,12 @@
           "kind": "passkey",
           "primary": false,
           "text_key": "identifier.action.passkey"
+        },
+        {
+          "name": "register",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "identifier.action.register.link"
         }
       ],
       "transitions": {
@@ -65,6 +81,10 @@
         },
         "user_not_found": {
           "target": "register"
+        },
+        "register": {
+          "target": "register",
+          "purpose": "register"
         }
       }
     },
@@ -113,6 +133,12 @@
           "kind": "submit",
           "primary": false,
           "text_key": "register.action.password"
+        },
+        {
+          "name": "sign_in",
+          "kind": "navigate",
+          "primary": false,
+          "text_key": "register.action.sign_in.link"
         }
       ],
       "transitions": {
@@ -124,6 +150,10 @@
         },
         "user_already_exists": {
           "target": "password"
+        },
+        "sign_in": {
+          "target": "passkey-first",
+          "purpose": "login"
         }
       }
     },

package/dist/branding-url.d.mts

@@ -0,0 +1,14 @@
+//#region src/branding-url.d.ts
+/**
+ * Reports whether value is an absolute HTTP URL using one of the canonical
+ * loopback spellings shared by the config and component gates.
+ *
+ * The raw-pattern check deliberately runs before WHATWG URL normalisation so
+ * shorthand, integer, hexadecimal, leading-zero, and userinfo forms cannot
+ * become a loopback host in one JavaScript layer while the Go save gate rejects
+ * them.
+ */
+declare function isCanonicalLoopbackHttpUrl(value: string): boolean;
+//#endregion
+export { isCanonicalLoopbackHttpUrl };
+//# sourceMappingURL=branding-url.d.mts.map

package/dist/branding-url.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branding-url.d.mts","names":[],"sources":["../src/branding-url.ts"],"mappings":";;AAYA;;;;;;;;iBAAgB,0BAAA,CAA2B,KAAA"}

package/dist/branding-url.mjs

@@ -0,0 +1,23 @@
+//#region src/branding-url.ts
+const CANONICAL_LOOPBACK_HTTP_URL = /^http:\/\/(?:localhost|127\.(?:0|[1-9][0-9]{0,2})\.(?:0|[1-9][0-9]{0,2})\.(?:0|[1-9][0-9]{0,2})|\[::1\])(?::[0-9]+)?(?:[/?#]|$)/i;
+/**
+* Reports whether value is an absolute HTTP URL using one of the canonical
+* loopback spellings shared by the config and component gates.
+*
+* The raw-pattern check deliberately runs before WHATWG URL normalisation so
+* shorthand, integer, hexadecimal, leading-zero, and userinfo forms cannot
+* become a loopback host in one JavaScript layer while the Go save gate rejects
+* them.
+*/
+function isCanonicalLoopbackHttpUrl(value) {
+	if (!CANONICAL_LOOPBACK_HTTP_URL.test(value)) return false;
+	try {
+		return new URL(value).protocol === "http:";
+	} catch {
+		return false;
+	}
+}
+//#endregion
+export { isCanonicalLoopbackHttpUrl };
+
+//# sourceMappingURL=branding-url.mjs.map

package/dist/branding-url.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"branding-url.mjs","names":[],"sources":["../src/branding-url.ts"],"sourcesContent":["const CANONICAL_LOOPBACK_HTTP_URL =\n  /^http:\\/\\/(?:localhost|127\\.(?:0|[1-9][0-9]{0,2})\\.(?:0|[1-9][0-9]{0,2})\\.(?:0|[1-9][0-9]{0,2})|\\[::1\\])(?::[0-9]+)?(?:[/?#]|$)/i;\n\n/**\n * Reports whether value is an absolute HTTP URL using one of the canonical\n * loopback spellings shared by the config and component gates.\n *\n * The raw-pattern check deliberately runs before WHATWG URL normalisation so\n * shorthand, integer, hexadecimal, leading-zero, and userinfo forms cannot\n * become a loopback host in one JavaScript layer while the Go save gate rejects\n * them.\n */\nexport function isCanonicalLoopbackHttpUrl(value: string): boolean {\n  if (!CANONICAL_LOOPBACK_HTTP_URL.test(value)) return false;\n  try {\n    return new URL(value).protocol === \"http:\";\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";AAAA,MAAM,8BACJ;;;;;;;;;;AAWF,SAAgB,2BAA2B,OAAwB;AACjE,KAAI,CAAC,4BAA4B,KAAK,MAAM,CAAE,QAAO;AACrD,KAAI;AACF,SAAO,IAAI,IAAI,MAAM,CAAC,aAAa;SAC7B;AACN,SAAO"}

package/dist/{defaults-CXTnFMHj.mjs → defaults-eiGHyI5Y.mjs}

@@ -11,14 +11,8 @@ var default_human_user_default = {
 	type: "object",
 	description: "The default editable schema for human users.",
 	"x-auth-methods": {
-		"password": {
-			"enabled": true,
-			"position": 1
-		},
-		"passkey": {
-			"enabled": true,
-			"position": 2
-		}
+		"password": { "enabled": true },
+		"passkey": { "enabled": true }
 	},
 	required: ["email"],
 	properties: { "email": {
@@ -43,21 +37,34 @@ var default_login_default = {
 		{
 			"name": "identifier",
 			"fields": ["email"],
-			"actions": [{
-				"name": "submit",
-				"kind": "submit",
-				"primary": true,
-				"text_key": "identifier.action.continue"
-			}, {
-				"name": "passkey",
-				"kind": "passkey",
-				"primary": false,
-				"text_key": "identifier.action.passkey"
-			}],
+			"actions": [
+				{
+					"name": "submit",
+					"kind": "submit",
+					"primary": true,
+					"text_key": "identifier.action.continue"
+				},
+				{
+					"name": "passkey",
+					"kind": "passkey",
+					"primary": false,
+					"text_key": "identifier.action.passkey"
+				},
+				{
+					"name": "register",
+					"kind": "navigate",
+					"primary": false,
+					"text_key": "identifier.action.register.link"
+				}
+			],
 			"transitions": {
 				"submit": { "target": "password" },
 				"passkey": { "target": "done" },
-				"user_not_found": { "target": "register" }
+				"user_not_found": { "target": "register" },
+				"register": {
+					"target": "register",
+					"purpose": "register"
+				}
 			}
 		},
 		{
@@ -82,21 +89,34 @@ var default_login_default = {
 		{
 			"name": "register",
 			"fields": ["email"],
-			"actions": [{
-				"name": "submit",
-				"kind": "submit",
-				"primary": true,
-				"text_key": "register.action.password"
-			}, {
-				"name": "passkey_register",
-				"kind": "passkey_register",
-				"primary": false,
-				"text_key": "register.action.passkey"
-			}],
+			"actions": [
+				{
+					"name": "submit",
+					"kind": "submit",
+					"primary": true,
+					"text_key": "register.action.password"
+				},
+				{
+					"name": "passkey_register",
+					"kind": "passkey_register",
+					"primary": false,
+					"text_key": "register.action.passkey"
+				},
+				{
+					"name": "sign_in",
+					"kind": "navigate",
+					"primary": false,
+					"text_key": "register.action.sign_in.link"
+				}
+			],
 			"transitions": {
 				"submit": { "target": "register-password" },
 				"passkey_register": { "target": "done" },
-				"user_already_exists": { "target": "password" }
+				"user_already_exists": { "target": "password" },
+				"sign_in": {
+					"target": "identifier",
+					"purpose": "login"
+				}
 			}
 		},
 		{
@@ -132,14 +152,8 @@ var human_user_default = {
 	type: "object",
 	description: "The default editable schema for human users (passkey-first sign-in).",
 	"x-auth-methods": {
-		"passkey": {
-			"enabled": true,
-			"position": 1
-		},
-		"password": {
-			"enabled": true,
-			"position": 2
-		}
+		"passkey": { "enabled": true },
+		"password": { "enabled": true }
 	},
 	required: ["email"],
 	properties: { "email": {
@@ -164,41 +178,67 @@ var login_default = {
 		{
 			"name": "passkey-first",
 			"fields": [],
-			"actions": [{
-				"name": "passkey",
-				"kind": "passkey",
-				"primary": true,
-				"text_key": "passkey-first.action.passkey"
-			}, {
-				"name": "email_fallback",
-				"kind": "navigate",
-				"primary": false,
-				"text_key": "passkey-first.action.email_fallback"
-			}],
+			"actions": [
+				{
+					"name": "passkey",
+					"kind": "passkey",
+					"primary": true,
+					"text_key": "passkey-first.action.passkey"
+				},
+				{
+					"name": "email_fallback",
+					"kind": "navigate",
+					"primary": false,
+					"text_key": "passkey-first.action.email_fallback"
+				},
+				{
+					"name": "register",
+					"kind": "navigate",
+					"primary": false,
+					"text_key": "identifier.action.register.link"
+				}
+			],
 			"transitions": {
 				"passkey": { "target": "done" },
 				"email_fallback": { "target": "identifier" },
-				"user_not_found": { "target": "register" }
+				"user_not_found": { "target": "register" },
+				"register": {
+					"target": "register",
+					"purpose": "register"
+				}
 			}
 		},
 		{
 			"name": "identifier",
 			"fields": ["email"],
-			"actions": [{
-				"name": "submit",
-				"kind": "submit",
-				"primary": true,
-				"text_key": "identifier.action.continue"
-			}, {
-				"name": "passkey",
-				"kind": "passkey",
-				"primary": false,
-				"text_key": "identifier.action.passkey"
-			}],
+			"actions": [
+				{
+					"name": "submit",
+					"kind": "submit",
+					"primary": true,
+					"text_key": "identifier.action.continue"
+				},
+				{
+					"name": "passkey",
+					"kind": "passkey",
+					"primary": false,
+					"text_key": "identifier.action.passkey"
+				},
+				{
+					"name": "register",
+					"kind": "navigate",
+					"primary": false,
+					"text_key": "identifier.action.register.link"
+				}
+			],
 			"transitions": {
 				"submit": { "target": "password" },
 				"passkey": { "target": "done" },
-				"user_not_found": { "target": "register" }
+				"user_not_found": { "target": "register" },
+				"register": {
+					"target": "register",
+					"purpose": "register"
+				}
 			}
 		},
 		{
@@ -223,21 +263,34 @@ var login_default = {
 		{
 			"name": "register",
 			"fields": ["email"],
-			"actions": [{
-				"name": "passkey_register",
-				"kind": "passkey_register",
-				"primary": true,
-				"text_key": "register.action.passkey"
-			}, {
-				"name": "submit",
-				"kind": "submit",
-				"primary": false,
-				"text_key": "register.action.password"
-			}],
+			"actions": [
+				{
+					"name": "passkey_register",
+					"kind": "passkey_register",
+					"primary": true,
+					"text_key": "register.action.passkey"
+				},
+				{
+					"name": "submit",
+					"kind": "submit",
+					"primary": false,
+					"text_key": "register.action.password"
+				},
+				{
+					"name": "sign_in",
+					"kind": "navigate",
+					"primary": false,
+					"text_key": "register.action.sign_in.link"
+				}
+			],
 			"transitions": {
 				"passkey_register": { "target": "done" },
 				"submit": { "target": "register-password" },
-				"user_already_exists": { "target": "password" }
+				"user_already_exists": { "target": "password" },
+				"sign_in": {
+					"target": "passkey-first",
+					"purpose": "login"
+				}
 			}
 		},
 		{
@@ -513,4 +566,4 @@ function trimTrailingSlash(value) {
 //#endregion
 export { brandingReadmeContent as _, DEFAULT_BUILTIN_SCHEMA_BASE as a, DEFAULT_SCHEMA_CONFIG_PATH as c, SETUP_PRESETS as d, SETUP_USE_CASES as f, getDefaultLoginFlow as g, getDefaultHumanUserSchema as h, DEFAULT_BRANDING_TEMPLATE_PATH as i, DEFAULT_SETUP_PRESET as l, getDefaultBrandingConfig as m, DEFAULT_BRANDING_CONFIG_PATH as n, DEFAULT_FLOW_CONFIG_PATH as o, defaultHumanUserSchemaUrl as p, DEFAULT_BRANDING_DESIGN as r, DEFAULT_FLOW_SCHEMA_URI as s, BRANDING_DESIGNS as t, DEFAULT_SETUP_USE_CASE as u, flowsReadmeContent as v, schemasReadmeContent as y };
 
-//# sourceMappingURL=defaults-CXTnFMHj.mjs.map
+//# sourceMappingURL=defaults-eiGHyI5Y.mjs.map