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

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,32 @@ 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).
 
-## 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,135 @@
 # `.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.
+
+------------------------------------------------------------------------
+
+## Next step
+
+Once you've updated your schema, continue with:
+
+    .zitadel/flows/
+
+to update your login and registration flows.

package/dist/index.d.mts

@@ -1,3 +1,4 @@
 import { a as DefaultConfigRenderOptions, c as getDefaultLoginFlow, i as DEFAULT_SCHEMA_CONFIG_PATH, l as flowsReadmeContent, n as DEFAULT_FLOW_CONFIG_PATH, o as defaultHumanUserSchemaUrl, r as DEFAULT_FLOW_SCHEMA_URI, s as getDefaultHumanUserSchema, t as DEFAULT_BUILTIN_SCHEMA_BASE, u as schemasReadmeContent } from "./defaults-DzfOT2_7.mjs";
+import { USER_PROPERTY_DEFAULTS, normalizeFlowBody, normalizeSchemaBody } from "./normalize.mjs";
 import { createFlowDefinitionRequestSchema, flowConfigSchema, schemaConfigSchema } from "./schemas.mjs";
-export { DEFAULT_BUILTIN_SCHEMA_BASE, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, DefaultConfigRenderOptions, createFlowDefinitionRequestSchema, defaultHumanUserSchemaUrl, flowConfigSchema, flowsReadmeContent, getDefaultHumanUserSchema, getDefaultLoginFlow, schemaConfigSchema, schemasReadmeContent };
+export { DEFAULT_BUILTIN_SCHEMA_BASE, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, DefaultConfigRenderOptions, USER_PROPERTY_DEFAULTS, createFlowDefinitionRequestSchema, defaultHumanUserSchemaUrl, flowConfigSchema, flowsReadmeContent, getDefaultHumanUserSchema, getDefaultLoginFlow, normalizeFlowBody, normalizeSchemaBody, schemaConfigSchema, schemasReadmeContent };

package/dist/index.mjs

@@ -1,3 +1,4 @@
 import { a as defaultHumanUserSchemaUrl, c as flowsReadmeContent, i as DEFAULT_SCHEMA_CONFIG_PATH, l as schemasReadmeContent, n as DEFAULT_FLOW_CONFIG_PATH, o as getDefaultHumanUserSchema, r as DEFAULT_FLOW_SCHEMA_URI, s as getDefaultLoginFlow, t as DEFAULT_BUILTIN_SCHEMA_BASE } from "./defaults-B2iIPSSl.mjs";
+import { USER_PROPERTY_DEFAULTS, normalizeFlowBody, normalizeSchemaBody } from "./normalize.mjs";
 import { createFlowDefinitionRequestSchema, flowConfigSchema, schemaConfigSchema } from "./schemas.mjs";
-export { DEFAULT_BUILTIN_SCHEMA_BASE, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, createFlowDefinitionRequestSchema, defaultHumanUserSchemaUrl, flowConfigSchema, flowsReadmeContent, getDefaultHumanUserSchema, getDefaultLoginFlow, schemaConfigSchema, schemasReadmeContent };
+export { DEFAULT_BUILTIN_SCHEMA_BASE, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, USER_PROPERTY_DEFAULTS, createFlowDefinitionRequestSchema, defaultHumanUserSchemaUrl, flowConfigSchema, flowsReadmeContent, getDefaultHumanUserSchema, getDefaultLoginFlow, normalizeFlowBody, normalizeSchemaBody, schemaConfigSchema, schemasReadmeContent };

package/dist/normalize.d.mts

@@ -0,0 +1,40 @@
+//#region src/normalize.d.ts
+/**
+ * Canonical-form normalizers for the two repo-config resource kinds.
+ *
+ * The sync engine compares `.zitadel/**` files against server responses;
+ * the server echoes fields the author never wrote (an empty `audience`
+ * on flows) and the meta-schema declares defaults an author may or may
+ * not spell out (`x-editable` et al on schema properties). Normalizing
+ * both sides before hashing or diffing keeps a one-field edit rendering
+ * as a one-field diff.
+ *
+ * Normalized bodies are for COMPARISON. Never upload them, and never
+ * write a normalized schema body to a file: the server stores schema
+ * bytes verbatim without materializing meta-schema defaults, so a
+ * stripped `"x-editable": true` would vanish from the next published
+ * revision. (Flow write-back may reuse {@link normalizeFlowBody} —
+ * everything it strips is pure transport noise.)
+ */
+/**
+ * Property-level defaults declared by the user-property meta-schema
+ * (`api/openapi/endpoints/schemas/user-property.json`). A property that
+ * spells one of these out is semantically identical to one that omits it.
+ */
+declare const USER_PROPERTY_DEFAULTS: Readonly<Record<string, boolean>>;
+/**
+ * Return a deep copy of a bare flow-definition body with server-echoed
+ * noise removed: an empty `audience` and any detail-envelope keys.
+ */
+declare function normalizeFlowBody(body: object): object;
+/**
+ * Return a deep copy of a user-schema body with meta-schema property
+ * defaults stripped: a property carrying `"x-editable": true` (or the
+ * other {@link USER_PROPERTY_DEFAULTS}) normalizes to one omitting it.
+ * Only exact default values are removed; `$id` and every other field
+ * pass through untouched.
+ */
+declare function normalizeSchemaBody(body: object): object;
+//#endregion
+export { USER_PROPERTY_DEFAULTS, normalizeFlowBody, normalizeSchemaBody };
+//# sourceMappingURL=normalize.d.mts.map

package/dist/normalize.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.mts","names":[],"sources":["../src/normalize.ts"],"mappings":";;AAuBA;;;;;AAqCA;;;;;AAkBA;;;;;;;;;;;cAvDa,sBAAA,EAAwB,QAAA,CAAS,MAAA;;;;;iBAqC9B,iBAAA,CAAkB,IAAA;;;;;;;;iBAkBlB,mBAAA,CAAoB,IAAA"}

package/dist/normalize.mjs

@@ -0,0 +1,82 @@
+//#region src/normalize.ts
+/**
+* Canonical-form normalizers for the two repo-config resource kinds.
+*
+* The sync engine compares `.zitadel/**` files against server responses;
+* the server echoes fields the author never wrote (an empty `audience`
+* on flows) and the meta-schema declares defaults an author may or may
+* not spell out (`x-editable` et al on schema properties). Normalizing
+* both sides before hashing or diffing keeps a one-field edit rendering
+* as a one-field diff.
+*
+* Normalized bodies are for COMPARISON. Never upload them, and never
+* write a normalized schema body to a file: the server stores schema
+* bytes verbatim without materializing meta-schema defaults, so a
+* stripped `"x-editable": true` would vanish from the next published
+* revision. (Flow write-back may reuse {@link normalizeFlowBody} —
+* everything it strips is pure transport noise.)
+*/
+/**
+* Property-level defaults declared by the user-property meta-schema
+* (`api/openapi/endpoints/schemas/user-property.json`). A property that
+* spells one of these out is semantically identical to one that omits it.
+*/
+const USER_PROPERTY_DEFAULTS = {
+	"x-editable": true,
+	"x-sensitive": false,
+	"x-mfa": false
+};
+/**
+* Keys of the flow-definition detail envelope. `fetch` in the flow syncer
+* already unwraps the envelope; stripping them here as well makes the
+* normalizer safe on raw detail responses.
+*/
+const FLOW_ENVELOPE_KEYS = [
+	"id",
+	"project_id",
+	"schema_uri",
+	"created_at",
+	"updated_at"
+];
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* An `audience` counts as empty when it scopes nothing: no keys, or only
+* `team_ids`/`app_ids` that are null or empty arrays. Unknown keys keep
+* the audience — better a noisy diff than a silently dropped scope.
+*/
+function isEmptyAudience(value) {
+	if (!isPlainObject(value)) return false;
+	return Object.entries(value).every(([key, entry]) => (key === "team_ids" || key === "app_ids") && (entry === null || entry === void 0 || Array.isArray(entry) && entry.length === 0));
+}
+/**
+* Return a deep copy of a bare flow-definition body with server-echoed
+* noise removed: an empty `audience` and any detail-envelope keys.
+*/
+function normalizeFlowBody(body) {
+	const result = structuredClone(body);
+	for (const key of FLOW_ENVELOPE_KEYS) delete result[key];
+	if ("audience" in result && isEmptyAudience(result.audience)) delete result.audience;
+	return result;
+}
+/**
+* Return a deep copy of a user-schema body with meta-schema property
+* defaults stripped: a property carrying `"x-editable": true` (or the
+* other {@link USER_PROPERTY_DEFAULTS}) normalizes to one omitting it.
+* Only exact default values are removed; `$id` and every other field
+* pass through untouched.
+*/
+function normalizeSchemaBody(body) {
+	const result = structuredClone(body);
+	if (!isPlainObject(result.properties)) return result;
+	for (const property of Object.values(result.properties)) {
+		if (!isPlainObject(property)) continue;
+		for (const [key, defaultValue] of Object.entries(USER_PROPERTY_DEFAULTS)) if (property[key] === defaultValue) delete property[key];
+	}
+	return result;
+}
+//#endregion
+export { USER_PROPERTY_DEFAULTS, normalizeFlowBody, normalizeSchemaBody };
+
+//# sourceMappingURL=normalize.mjs.map

package/dist/normalize.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.mjs","names":[],"sources":["../src/normalize.ts"],"sourcesContent":["/**\n * Canonical-form normalizers for the two repo-config resource kinds.\n *\n * The sync engine compares `.zitadel/**` files against server responses;\n * the server echoes fields the author never wrote (an empty `audience`\n * on flows) and the meta-schema declares defaults an author may or may\n * not spell out (`x-editable` et al on schema properties). Normalizing\n * both sides before hashing or diffing keeps a one-field edit rendering\n * as a one-field diff.\n *\n * Normalized bodies are for COMPARISON. Never upload them, and never\n * write a normalized schema body to a file: the server stores schema\n * bytes verbatim without materializing meta-schema defaults, so a\n * stripped `\"x-editable\": true` would vanish from the next published\n * revision. (Flow write-back may reuse {@link normalizeFlowBody} —\n * everything it strips is pure transport noise.)\n */\n\n/**\n * Property-level defaults declared by the user-property meta-schema\n * (`api/openapi/endpoints/schemas/user-property.json`). A property that\n * spells one of these out is semantically identical to one that omits it.\n */\nexport const USER_PROPERTY_DEFAULTS: Readonly<Record<string, boolean>> = {\n  \"x-editable\": true,\n  \"x-sensitive\": false,\n  \"x-mfa\": false,\n};\n\n/**\n * Keys of the flow-definition detail envelope. `fetch` in the flow syncer\n * already unwraps the envelope; stripping them here as well makes the\n * normalizer safe on raw detail responses.\n */\nconst FLOW_ENVELOPE_KEYS = [\"id\", \"project_id\", \"schema_uri\", \"created_at\", \"updated_at\"];\n\nfunction isPlainObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * An `audience` counts as empty when it scopes nothing: no keys, or only\n * `team_ids`/`app_ids` that are null or empty arrays. Unknown keys keep\n * the audience — better a noisy diff than a silently dropped scope.\n */\nfunction isEmptyAudience(value: unknown): boolean {\n  if (!isPlainObject(value)) {\n    return false;\n  }\n  return Object.entries(value).every(\n    ([key, entry]) =>\n      (key === \"team_ids\" || key === \"app_ids\") &&\n      (entry === null || entry === undefined || (Array.isArray(entry) && entry.length === 0)),\n  );\n}\n\n/**\n * Return a deep copy of a bare flow-definition body with server-echoed\n * noise removed: an empty `audience` and any detail-envelope keys.\n */\nexport function normalizeFlowBody(body: object): object {\n  const result = structuredClone(body) as Record<string, unknown>;\n  for (const key of FLOW_ENVELOPE_KEYS) {\n    delete result[key];\n  }\n  if (\"audience\" in result && isEmptyAudience(result.audience)) {\n    delete result.audience;\n  }\n  return result;\n}\n\n/**\n * Return a deep copy of a user-schema body with meta-schema property\n * defaults stripped: a property carrying `\"x-editable\": true` (or the\n * other {@link USER_PROPERTY_DEFAULTS}) normalizes to one omitting it.\n * Only exact default values are removed; `$id` and every other field\n * pass through untouched.\n */\nexport function normalizeSchemaBody(body: object): object {\n  const result = structuredClone(body) as Record<string, unknown>;\n  if (!isPlainObject(result.properties)) {\n    return result;\n  }\n  for (const property of Object.values(result.properties)) {\n    if (!isPlainObject(property)) {\n      continue;\n    }\n    for (const [key, defaultValue] of Object.entries(USER_PROPERTY_DEFAULTS)) {\n      if (property[key] === defaultValue) {\n        delete property[key];\n      }\n    }\n  }\n  return result;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,yBAA4D;CACvE,cAAc;CACd,eAAe;CACf,SAAS;CACV;;;;;;AAOD,MAAM,qBAAqB;CAAC;CAAM;CAAc;CAAc;CAAc;CAAa;AAEzF,SAAS,cAAc,OAAkD;AACvE,QAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,MAAM;;;;;;;AAQ7E,SAAS,gBAAgB,OAAyB;AAChD,KAAI,CAAC,cAAc,MAAM,CACvB,QAAO;AAET,QAAO,OAAO,QAAQ,MAAM,CAAC,OAC1B,CAAC,KAAK,YACJ,QAAQ,cAAc,QAAQ,eAC9B,UAAU,QAAQ,UAAU,KAAA,KAAc,MAAM,QAAQ,MAAM,IAAI,MAAM,WAAW,GACvF;;;;;;AAOH,SAAgB,kBAAkB,MAAsB;CACtD,MAAM,SAAS,gBAAgB,KAAK;AACpC,MAAK,MAAM,OAAO,mBAChB,QAAO,OAAO;AAEhB,KAAI,cAAc,UAAU,gBAAgB,OAAO,SAAS,CAC1D,QAAO,OAAO;AAEhB,QAAO;;;;;;;;;AAUT,SAAgB,oBAAoB,MAAsB;CACxD,MAAM,SAAS,gBAAgB,KAAK;AACpC,KAAI,CAAC,cAAc,OAAO,WAAW,CACnC,QAAO;AAET,MAAK,MAAM,YAAY,OAAO,OAAO,OAAO,WAAW,EAAE;AACvD,MAAI,CAAC,cAAc,SAAS,CAC1B;AAEF,OAAK,MAAM,CAAC,KAAK,iBAAiB,OAAO,QAAQ,uBAAuB,CACtE,KAAI,SAAS,SAAS,aACpB,QAAO,SAAS;;AAItB,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zitadel/config",
-  "version": "0.1.0-alpha.14",
+  "version": "0.1.0-alpha.15",
   "description": "Versioned Zitadel local config schemas and defaults",
   "homepage": "https://github.com/zitadel/nextgen/tree/main/packages/config#readme",
   "bugs": {
@@ -35,6 +35,11 @@
       "types": "./dist/schemas.d.mts",
       "import": "./dist/schemas.mjs"
     },
+    "./normalize": {
+      "@zitadel/source": "./src/normalize.ts",
+      "types": "./dist/normalize.d.mts",
+      "import": "./dist/normalize.mjs"
+    },
     "./defaults/default-human-user.json": "./defaults/default-human-user.json",
     "./defaults/default-login.json": "./defaults/default-login.json",
     "./package.json": "./package.json"
@@ -43,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@zitadel/api": "0.1.0-alpha.14"
+    "@zitadel/api": "0.1.0-alpha.15"
   },
   "devDependencies": {
     "tsdown": "^0.21.10",