@zitadel/config 0.1.0-alpha.14 → 0.1.0-alpha.16

package/defaults/README-flows.md

@@ -5,6 +5,11 @@ which fields the user sees at each step, which credentials are checked,
 and how one step transitions to the next. The Zitadel flow engine runs
 these on the platform; the widget renders whatever the engine emits.
 
+Flows and schemas work together: the user schema in
+`.zitadel/schemas/` defines **what** data exists, the flow defines
+**when and where** users are asked to provide it. If you add a property
+to the schema, users won't see a new field until a flow step lists it.
+
 ## What's in a flow file
 
 - `purposes` — entry step for each purpose (`login`, `register`, …). A
@@ -16,22 +21,74 @@ these on the platform; the widget renders whatever the engine emits.
 - `user_schema` — pins the flow to one specific user-schema revision.
 - `audience` (optional) — scopes the flow to specific apps or teams.
 
-## What you can do
+## Making changes
+
+The common workflow:
+
+1. Edit the flow (and, if it needs new data, the schema in
+   `.zitadel/schemas/` first).
+2. Run `zitadel plan` to preview the change.
+3. Run `zitadel apply` to publish it.
+
+Typical edits:
 
-- **Add or remove a step** — extend `steps[]`.
 - **Change which fields a step collects** — edit `steps[].fields[]`.
   Values must be properties of the pinned schema (or reserved credential
   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.
 - **Add another flow** — drop a new JSON file with its own `purposes`
-  and `audience` (e.g. a per-team login).
+  and a distinct `name` (e.g. a per-team login). See
+  [Multiple flows](#multiple-flows) for how it gets selected at runtime.
+
+## Multiple flows
+
+All files in this folder sync on `apply`, but the widget runs exactly
+one flow per sign-in. Which one:
+
+- **By name** — give the flow a distinct `name` and pass it as
+  `flowName` on `ZitadelLogin` (the `flow-name` attribute on
+  `<zitadel-login>`). The platform resolves that definition directly;
+  an unknown name or wrong purpose surfaces as a startup error in the
+  widget.
+- **By audience** — omit `flowName` and scope the flow with
+  `audience.app_ids` / `audience.team_ids`. A start request hinting one
+  of those ids gets the scoped flow (app match beats team match); all
+  other requests get the newest flow without an `audience`.
+
+A flow scoped to an app or team never captures the project default —
+requests that don't identify that audience fall back to the unscoped
+flow.
+
+The flip side: a **new active flow without an `audience` becomes the
+newest unscoped definition, i.e. the default**, the moment it applies.
+`plan` calls this out with a `# warning:` line on the create so an
+experiment can't silently take over `/login` — scope it or pin
+`flow-name` in the widget if that isn't the intent.
+
+## Presets
+
+`zitadel setup` scaffolds this folder from a preset (`--preset
+password-first` 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.
+
+## Presets
+
+`zitadel setup` scaffolds this folder from a preset (`--preset
+password-first` 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.
 
-## Applying changes
+## Schema revisions
 
-`zitadel plan` previews the change; `zitadel apply` PUTs the updated
-flow to the platform. When the pinned user-schema is edited, the flow
-stays pinned to the old revision — `apply` prints the new revision id so
-you can copy it into `user_schema` (and update `steps[].fields[]` for
-any added/removed properties) when you're ready to adopt it.
+Editing a schema publishes a new immutable revision. When you `apply` a
+schema edit, the CLI rewrites `user_schema` in the flow files pinned to
+the old revision and updates the flows in the same run — the plan
+announces the re-pin beforehand, and the rewrite shows up in your git
+diff. Remember to update `steps[].fields[]` yourself when the edit
+added or removed properties the flow should collect.

package/defaults/README-schemas.md

@@ -1,32 +1,141 @@
 # `.zitadel/schemas/`
 
-User-schema files. Each JSON file describes one editable user type — the
-shape of the user records the platform stores and the login/register
-flows collect (email, name, phoneNumber, custom claims, etc.). A project
-can hold as many schemas as you need (e.g. one for end users, one for
-internal admins).
-
-## What's in a schema file
-
-- `objectType` — groups revisions of the same logical user type. Do not
-  rename it after the first `apply`; the platform correlates history by
-  this key.
-- `properties` / `required` — the user's attributes and which of them
-  must be present on every user.
-- `x-auth-methods` — which credentials this user type supports
-  (password, passkey, …).
-
-## What you can do
-
-- **Add or edit a property** — extend `properties`, mark it `required`
-  if it must be present on every user.
-- **Enable or disable an auth method** — flip an `x-auth-methods` entry.
-- **Add another user type** — drop a new JSON file next to this one.
-
-## Applying changes
-
-`zitadel plan` previews the change; `zitadel apply` publishes it. Editing
-a schema publishes a **new immutable revision** — existing users keep
-validating against the previous revision. Flows that reference this
-schema stay pinned to the old revision until you re-pin them; see
-`.zitadel/flows/README.md`.
+This folder contains your project's user schemas.
+
+A user schema defines **what information is stored about a user** and
+**how that type of user can authenticate**.
+
+You can have as many schemas as you need. For example:
+
+-   `customer.json`
+-   `employee.json`
+-   `admin.json`
+
+Here's a simplified example:
+
+``` json
+{
+  "objectType": "customer",
+  "properties": {
+    "firstName": {
+      "type": "string"
+    },
+    "company": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "firstName"
+  ],
+  "x-auth-methods": {
+    "password": { "enabled": true, "position": 1 },
+    "passkey": { "enabled": true, "position": 2 }
+  }
+}
+```
+
+Each schema is made up of four main sections:
+
+## `objectType`
+
+Identifies this type of user.
+
+Once you've applied a schema for the first time, don't rename it.
+Zitadel uses it to recognise future revisions of the same user type.
+
+## `properties`
+
+Defines the information stored for users of this type.
+
+For example:
+
+-   First name
+-   Last name
+-   Company
+-   Phone number
+-   Custom attributes
+
+Every property becomes available to the rest of the identity system,
+including login and registration flows.
+
+## `required`
+
+Lists which properties every user must provide.
+
+Properties that aren't listed here are optional.
+
+## `x-auth-methods`
+
+Controls how users of this type can authenticate.
+
+For example:
+
+-   Password
+-   Passkeys
+-   Social login
+
+------------------------------------------------------------------------
+
+# Making changes
+
+The most common workflow looks like this:
+
+1.  Update your schema.
+2.  If you've added, removed or renamed fields, update the corresponding
+    login flow in `.zitadel/flows/`.
+3.  Run `zitadel plan` to preview the changes.
+4.  Run `zitadel apply` to publish them.
+
+## Why do I need to update the login flow?
+
+The schema defines **what data exists**.
+
+The login flow defines **when and where users are asked to provide that
+data**.
+
+For example, if you add a `company` property to your schema, users won't
+see a new field on the registration form until you also update the
+registration flow.
+
+Likewise, if you remove or rename a property, you'll usually need to
+update any login flows that reference it.
+
+------------------------------------------------------------------------
+
+# Common changes
+
+## Add a new field
+
+Add it under `properties`.
+
+If every user must provide it, also add it to `required`.
+
+Finally, update the login flow if users should be able to enter it.
+
+## Make a field optional
+
+Remove it from `required`.
+
+## Enable passkeys
+
+Set `"passkey": { "enabled": true }` in `x-auth-methods`.
+
+## Create another user type
+
+Create another JSON file in this directory.
+
+## Start from a different preset
+
+`zitadel setup` scaffolds this folder from a preset (`--preset
+password-first` or `--preset passkey-first`). The preset only decides the
+starting point — everything in it is editable afterwards.
+
+------------------------------------------------------------------------
+
+## Next step
+
+Once you've updated your schema, continue with:
+
+    .zitadel/flows/
+
+to update your login and registration flows.

package/defaults/default-login.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "../meta/flow-definition.json",
   "name": "default-login",
   "status": "active",
   "user_schema": "${USER_SCHEMA_URL}",

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

@@ -0,0 +1,46 @@
+{
+  "title": "DefaultHumanUserSchema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "metaSchema": "${SERVER_URL}/user-schema.json",
+  "$id": "${USER_SCHEMA_URL}",
+  "objectType": "human-user",
+  "kind": "user-schema",
+  "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
+    }
+  },
+  "required": [
+    "email"
+  ],
+  "properties": {
+    "email": {
+      "type": "string",
+      "format": "email",
+      "x-unique": "project",
+      "description": "The user's email address."
+    },
+    "givenName": {
+      "type": "string",
+      "maxLength": 50,
+      "description": "The user's given (first) name."
+    },
+    "familyName": {
+      "type": "string",
+      "maxLength": 50,
+      "description": "The user's family (last) name."
+    },
+    "dateOfBirth": {
+      "type": "string",
+      "format": "date",
+      "description": "The user's date of birth (ISO 8601, YYYY-MM-DD)."
+    }
+  }
+}

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

@@ -0,0 +1,161 @@
+{
+  "$schema": "../meta/flow-definition.json",
+  "name": "default-login",
+  "status": "active",
+  "user_schema": "${USER_SCHEMA_URL}",
+  "purposes": {
+    "login": "passkey-first",
+    "register": "register"
+  },
+  "steps": [
+    {
+      "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"
+        }
+      ],
+      "transitions": {
+        "passkey": {
+          "target": "done"
+        },
+        "email_fallback": {
+          "target": "identifier"
+        },
+        "user_not_found": {
+          "target": "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"
+        }
+      ],
+      "transitions": {
+        "submit": {
+          "target": "password"
+        },
+        "passkey": {
+          "target": "done"
+        },
+        "user_not_found": {
+          "target": "register"
+        }
+      }
+    },
+    {
+      "name": "password",
+      "fields": [
+        "x-auth-methods#password"
+      ],
+      "actions": [
+        {
+          "name": "submit",
+          "kind": "submit",
+          "primary": true,
+          "text_key": "password.action.signin"
+        },
+        {
+          "name": "passkey",
+          "kind": "passkey",
+          "primary": false,
+          "text_key": "password.action.passkey"
+        }
+      ],
+      "transitions": {
+        "submit": {
+          "target": "done"
+        },
+        "passkey": {
+          "target": "done"
+        }
+      }
+    },
+    {
+      "name": "register",
+      "fields": [
+        "email",
+        "givenName",
+        "familyName",
+        "dateOfBirth"
+      ],
+      "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"
+        }
+      ],
+      "transitions": {
+        "passkey_register": {
+          "target": "done"
+        },
+        "submit": {
+          "target": "register-password"
+        },
+        "user_already_exists": {
+          "target": "password"
+        }
+      }
+    },
+    {
+      "name": "register-password",
+      "fields": [
+        "x-auth-methods#password"
+      ],
+      "actions": [
+        {
+          "name": "submit",
+          "kind": "submit",
+          "primary": true,
+          "text_key": "register-password.action.submit"
+        }
+      ],
+      "on_success": "create_user",
+      "transitions": {
+        "submit": {
+          "target": "done"
+        },
+        "user_already_exists": {
+          "target": "password"
+        }
+      }
+    },
+    {
+      "name": "done",
+      "complete": "show"
+    }
+  ]
+}