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

package/dist/meta-schemas-8nlyVL7g.mjs

@@ -0,0 +1,456 @@
+//#region meta-schemas/auth-method.json
+var auth_method_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	title: "AuthMethod",
+	type: "object",
+	required: ["enabled", "position"],
+	properties: {
+		"enabled": {
+			"type": "boolean",
+			"description": "Whether the authentication method is enabled or not"
+		},
+		"position": {
+			"type": "integer",
+			"minimum": 0,
+			"description": "The position of the authentication method in the list of supported methods"
+		}
+	}
+};
+//#endregion
+//#region meta-schemas/auth-methods.json
+var auth_methods_default = {
+	type: "object",
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	description: "A list of authentication methods supported by the user definition.",
+	minProperties: 1,
+	additionalProperties: false,
+	properties: {
+		"password": { "$ref": "auth-method.json" },
+		"passkey": { "$ref": "auth-method.json" },
+		"magic_link": { "$ref": "auth-method.json" },
+		"sso": { "$ref": "auth-method.json" },
+		"otp": { "$ref": "auth-method.json" }
+	}
+};
+//#endregion
+//#region meta-schemas/flow-definition.json
+var flow_definition_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	title: "FlowDefinition",
+	description: "Admin-authored configuration for a flow. A flow definition is a directed graph of steps backed by a user schema. The flow engine selects a definition based on `purpose` and `audience`, then walks the graph by evaluating `transitions` against client submissions.  This schema describes the configuration shape only. Runtime emission to the client (capability dictionaries, branding, localized text) is a separate concern and is not modelled here.",
+	type: "object",
+	required: [
+		"name",
+		"status",
+		"user_schema",
+		"purposes",
+		"steps"
+	],
+	additionalProperties: false,
+	properties: {
+		"$schema": {
+			"type": "string",
+			"description": "Editor affordance: path or URL of this meta-schema so editors validate and autocomplete the file (scaffolded flow files point at `.zitadel/meta/flow-definition.json`). Ignored by the platform."
+		},
+		"name": {
+			"type": "string",
+			"pattern": "^[a-z][a-z0-9-]*$",
+			"examples": ["standard-login", "combined-auth"],
+			"description": "Stable identifier for this flow, used as the target of cross-flow `switch` and `pivot` transitions. Renaming is not supported — the `name` is part of the public contract another definition may reference. Acts as the human display label as well; no separate slug."
+		},
+		"status": {
+			"type": "string",
+			"enum": ["active", "draft"],
+			"description": "Lifecycle state. - active: the engine can select this definition for new flows. - draft: never selected for new flows; existing flows referencing it must handle it gracefully."
+		},
+		"user_schema": {
+			"type": "string",
+			"examples": ["sch_01KWHF18816ZQESRCS7Z2STJ05"],
+			"description": "Server-assigned identifier of the user schema this flow operates on, as returned by `POST /schemas`. Opaque to the client — the shape is a server implementation detail. Step `fields` reference property names defined in that schema; the engine resolves field type, validation, and implicit transition outcomes from the schema's `x-*` annotations at runtime."
+		},
+		"purposes": {
+			"type": "object",
+			"minProperties": 1,
+			"propertyNames": { "$ref": "#/$defs/Purpose" },
+			"additionalProperties": {
+				"type": "string",
+				"description": "Name of an entry-point step within this definition."
+			},
+			"examples": [{ "login": "identify" }, {
+				"login": "identify",
+				"register": "identify"
+			}],
+			"description": "Maps each purpose this definition handles to the step that begins the flow for that purpose. Every value must match a `name` in `steps`; the check is enforced by the engine, not by this schema."
+		},
+		"audience": {
+			"$ref": "#/$defs/Audience",
+			"description": "Scopes which requests this definition applies to. Omitted or empty arrays mean project-wide. The engine ranks matches by specificity (app > team > project-wide)."
+		},
+		"steps": {
+			"type": "array",
+			"minItems": 1,
+			"items": { "$ref": "#/$defs/Step" },
+			"description": "Step graph. Order is for human readability; actual sequencing is determined entirely by `transitions`. Every step's `name` must be unique within this array."
+		}
+	},
+	$defs: {
+		"Purpose": {
+			"type": "string",
+			"enum": [
+				"login",
+				"register",
+				"recovery",
+				"profiling",
+				"reauth",
+				"link_account"
+			],
+			"description": "What the user is trying to accomplish. - login: authenticate an existing user. - register: create a new user. - recovery: recover access (e.g. password reset). - profiling: collect required profile fields after authentication. - reauth: re-verify factors on an active session for step-up. - link_account: attach an external identity to an existing user."
+		},
+		"Audience": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"team_ids": {
+					"type": "array",
+					"uniqueItems": true,
+					"items": { "type": "string" },
+					"examples": [["team_acme"]],
+					"description": "Restrict to specific teams (organizations)."
+				},
+				"app_ids": {
+					"type": "array",
+					"uniqueItems": true,
+					"items": { "type": "string" },
+					"examples": [["app_dashboard"]],
+					"description": "Restrict to specific applications."
+				}
+			}
+		},
+		"Step": {
+			"type": "object",
+			"required": ["name"],
+			"additionalProperties": false,
+			"properties": {
+				"name": {
+					"type": "string",
+					"pattern": "^[a-z][a-z0-9-]*$",
+					"examples": [
+						"identify",
+						"authenticate",
+						"done"
+					],
+					"description": "Unique step identifier within this definition. Slug-shaped so it is safe to use as a transition `target` and as a value in `purposes`. Referenced by other steps in the same definition."
+				},
+				"fields": {
+					"type": "array",
+					"uniqueItems": true,
+					"items": { "type": "string" },
+					"examples": [["email"], ["email", "password"]],
+					"description": "Schema property names to collect from the user on this step. Each entry must resolve to a property in the definition's `user_schema`, or use the reserved token `x-auth-methods#<method>` (e.g. `x-auth-methods#password`) to collect a credential proof for a method enabled at the schema root. The engine reads the schema's `x-*` annotations to derive: - field type and validation (rendered into the runtime payload), - implicit transition outcomes - e.g. a property with a non-empty `x-unique` scope makes `user_not_found` a valid `transitions` key on this step."
+				},
+				"actions": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/Action" },
+					"description": "Ordered list of actions the user can take on this step. The `name` is what the client echoes back on submit. Every action's name must have a matching key in `transitions`; the engine rejects submissions for actions without a defined transition."
+				},
+				"gates": {
+					"type": "object",
+					"additionalProperties": { "$ref": "#/$defs/Gate" },
+					"description": "Security challenges that must be satisfied before this step's submission is accepted. Keyed by gate name (free identifier; referenced as the key in the runtime `step.gates` dictionary). The engine may inject additional gates at runtime based on policy or risk evaluation."
+				},
+				"sso_providers": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/SSOProvider" },
+					"description": "Identity providers available on this step. When non-empty, the step must define a `transitions.callback` entry — the engine handles the reserved `sso` action transparently (redirect to the IdP, code exchange, user resolution) and fires `callback` on this step when the IdP returns. The flow author never writes a `transitions.sso`."
+				},
+				"on_success": {
+					"type": "string",
+					"enum": ["create_user"],
+					"description": "Server-side mutation to run after the step's fields validate and before the transition fires. - create_user: materialize the user from collected schema   fields. Used by register flows."
+				},
+				"complete": {
+					"type": "string",
+					"enum": ["redirect", "show"],
+					"description": "Marks this step as terminal. A terminal step has no `fields`, `actions`, `transitions`, `gates`, or `sso_providers`. - redirect: client navigates to a `redirect_uri` resolved from   the originating protocol request (OIDC, SAML). - show: client renders the step as a success or info screen."
+				},
+				"transitions": {
+					"type": "object",
+					"additionalProperties": { "$ref": "#/$defs/Transition" },
+					"description": "Maps action names and engine-emitted outcomes to the next state. Keys are either: - an action name declared in this step's `actions`, or - a reserved outcome the engine produces: - `user_not_found` - emitted when a unique field (`x-unique`) does not match an existing user. - `user_already_exists` - emitted when registration matches an existing user. - `callback` - emitted when an external system returns control to the flow (SSO callback, device authorization poll, etc.). A transition's `action` field controls whether the target is interpreted as a step in this definition (default) or as the name of another definition to switch or pivot into."
+				}
+			}
+		},
+		"Action": {
+			"type": "object",
+			"additionalProperties": false,
+			"properties": {
+				"name": {
+					"type": "string",
+					"minLength": 1,
+					"examples": [
+						"submit",
+						"passkey",
+						"email_fallback"
+					],
+					"description": "Action identifier, echoed back by the client on submit and matched against `transitions`. The name `back` is reserved for engine-injected back navigation."
+				},
+				"kind": {
+					"type": "string",
+					"enum": [
+						"submit",
+						"passkey",
+						"passkey_register",
+						"navigate"
+					],
+					"description": "How the engine handles the action. - submit: collect the step's fields and run validate/dispatch/on_success. - passkey: issue a WebAuthn assertion challenge; the matching transition fires once the assertion verifies. - passkey_register: issue a WebAuthn registration challenge; the matching transition fires once the attestation verifies. - navigate: route through the transition without running the input pipeline. (`back` exists on the wire but is engine-injected; declaring it is rejected.)"
+				},
+				"primary": {
+					"type": "boolean",
+					"default": false,
+					"description": "Marks this as the default/primary action. The runtime template uses this hint to choose visual emphasis. At most one action per step should be primary; this is not enforced here."
+				},
+				"text_key": {
+					"type": "string",
+					"examples": ["actions.signin.submit"],
+					"description": "Optional localization key override for the action's label. When omitted, the engine derives a key from the step and action names. Display text is resolved client-side from a locale dictionary, never by the engine."
+				}
+			},
+			"description": "Configuration for a user-invokable action on a step.",
+			"required": ["name", "kind"]
+		},
+		"Gate": {
+			"type": "object",
+			"required": ["kind", "provider"],
+			"additionalProperties": false,
+			"properties": {
+				"kind": {
+					"type": "string",
+					"enum": ["captcha"],
+					"description": "The gate category. Only `captcha` is currently defined. Authenticator ceremonies (e.g. passkey) are modelled as credential auth_attempts via `x-credential` on a field, not as gates."
+				},
+				"provider": {
+					"type": "string",
+					"examples": [
+						"altcha",
+						"turnstile",
+						"hcaptcha"
+					],
+					"description": "Provider identifier within the gate kind — e.g. `altcha`, `turnstile`, `hcaptcha`. The engine looks up an implementation in its provider registry."
+				},
+				"config": {
+					"type": "object",
+					"additionalProperties": true,
+					"examples": [{ "site_key": "0x4AAAAAAAxxxxxxxxxxxxxx" }],
+					"description": "Provider-specific configuration consumed by the implementation when issuing the per-render challenge. Opaque to the engine."
+				}
+			}
+		},
+		"SSOProvider": {
+			"type": "object",
+			"required": [
+				"id",
+				"name",
+				"template"
+			],
+			"additionalProperties": false,
+			"properties": {
+				"id": {
+					"type": "string",
+					"examples": ["google", "corp_idp"],
+					"description": "Provider instance identifier. Echoed back by the client when the user picks a provider; routed to the corresponding configured IdP at the engine."
+				},
+				"name": {
+					"type": "string",
+					"examples": ["Google", "Acme SSO"],
+					"description": "Display name surfaced to the user. Localized client-side if a matching text key exists in the locale dictionary."
+				},
+				"template": {
+					"type": "string",
+					"examples": [
+						"google",
+						"entraid",
+						"github"
+					],
+					"description": "Hint for rendering (logo, brand colors) — e.g. `google`, `entraid`, `github`. Consumed by the runtime template, not by the engine."
+				}
+			}
+		},
+		"Transition": {
+			"type": "object",
+			"required": ["target"],
+			"additionalProperties": false,
+			"properties": {
+				"target": {
+					"type": "string",
+					"examples": [
+						"authenticate",
+						"register",
+						"recovery"
+					],
+					"description": "When `action` is omitted, the `name` of a step in the same definition. When `action` is `switch` or `pivot`, the `name` of another flow definition in the same project."
+				},
+				"action": {
+					"type": ["string", "null"],
+					"enum": [
+						"switch",
+						"pivot",
+						null
+					],
+					"description": "How to interpret `target`. - Omitted: transition to a step in the current definition. - `switch`: replace the current flow with the target flow.   No return; the current flow is discarded. Typical use:   navigating between peer flows like login ↔ register. - `pivot`: push the target flow onto the stack. The current   flow is paused; when the target flow completes the engine   auto-pops back. Typical use: login → recovery → back to login."
+				}
+			}
+		}
+	}
+};
+//#endregion
+//#region meta-schemas/user-property.json
+var user_property_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	title: "UserProperty",
+	type: "object",
+	allOf: [{ "$ref": "https://json-schema.org/draft/2020-12/schema" }],
+	additionalProperties: true,
+	properties: {
+		"$schema": {
+			"type": "string",
+			"const": "https://json-schema.org/draft/2020-12/schema",
+			"description": "The JSON Schema version used for this schema."
+		},
+		"x-verify": {
+			"oneOf": [{ "type": "string" }, { "type": "null" }],
+			"description": "The verification method for this property, if applicable"
+		},
+		"x-unique": {
+			"oneOf": [{
+				"type": "string",
+				"enum": [
+					"unspecified",
+					"project",
+					"team"
+				]
+			}, { "type": "null" }],
+			"description": "The level of uniqueness for this property, if applicable"
+		},
+		"x-claim": {
+			"oneOf": [{ "type": "string" }, { "type": "null" }],
+			"description": "The claim name for this property, if applicable"
+		},
+		"x-editable": {
+			"type": "boolean",
+			"default": true,
+			"description": "Whether this property is editable by the user or not"
+		},
+		"x-sensitive": {
+			"type": "boolean",
+			"default": false,
+			"description": "Whether this property contains sensitive information or not"
+		},
+		"x-mfa": {
+			"type": "boolean",
+			"default": false,
+			"description": "Whether this property is used for multi-factor authentication or not"
+		},
+		"properties": {
+			"type": "object",
+			"description": "A map of additional properties for the user definition, where the key is the property name and the value is the property schema",
+			"additionalProperties": true
+		}
+	}
+};
+//#endregion
+//#region meta-schemas/user-schema.json
+var user_schema_default = {
+	title: "UserSchema",
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	type: "object",
+	required: [
+		"metaSchema",
+		"kind",
+		"x-auth-methods"
+	],
+	allOf: [{ "$ref": "https://json-schema.org/draft/2020-12/schema" }],
+	additionalProperties: true,
+	properties: {
+		"$schema": {
+			"type": "string",
+			"const": "https://json-schema.org/draft/2020-12/schema",
+			"description": "The JSON Schema version used for this schema."
+		},
+		"objectType": {
+			"type": "string",
+			"maxLength": 256,
+			"description": "The type of user this schema describes. This is a customer chosen name.",
+			"example": "human-user"
+		},
+		"kind": {
+			"type": "string",
+			"const": "user-schema",
+			"description": "Discriminator value for a user schema create request."
+		},
+		"metaSchema": {
+			"type": "string",
+			"maxLength": 1024,
+			"format": "uri",
+			"description": "The user Schema version used for this schema."
+		},
+		"x-auth-methods": { "$ref": "auth-methods.json" },
+		"properties": {
+			"type": "object",
+			"description": "A map of additional properties for the user definition, where the key is the property name and the value is the property schema",
+			"additionalProperties": { "$ref": "user-property.json" }
+		}
+	}
+};
+//#endregion
+//#region src/meta-schemas.ts
+/**
+* The dialect meta-schemas `zitadel setup` copies into a project's
+* `.zitadel/meta/` so the flow/schema dialect is machine-readable offline:
+* editors validate flow files against `flow-definition.json` via a relative
+* `$schema` pointer, and agents read the dialect files before authoring
+* edits — no docs crawl, no hosted schema required.
+*
+* The files under `meta-schemas/` are committed copies of
+* `api/openapi/endpoints/schemas/*.json` (the source the server embeds);
+* a drift-audit test keeps them byte-identical in the monorepo.
+*/
+/** Project-relative directory setup writes the meta-schemas to. */
+const META_SCHEMA_DIR = ".zitadel/meta";
+/**
+* The `$schema` value scaffolded flow files carry, relative to
+* `.zitadel/flows/` — resolves to `{@link META_SCHEMA_DIR}/flow-definition.json`.
+*/
+const FLOW_FILE_SCHEMA_REF = "../meta/flow-definition.json";
+/**
+* The dialect files to materialize, in write order. `auth-methods.json` and
+* `auth-method.json` are pulled in by `user-schema.json`'s relative `$ref`s —
+* without them the copied dialect cannot resolve offline.
+*/
+function metaSchemaFiles() {
+	return [
+		{
+			name: "flow-definition.json",
+			body: flow_definition_default
+		},
+		{
+			name: "user-schema.json",
+			body: user_schema_default
+		},
+		{
+			name: "user-property.json",
+			body: user_property_default
+		},
+		{
+			name: "auth-methods.json",
+			body: auth_methods_default
+		},
+		{
+			name: "auth-method.json",
+			body: auth_method_default
+		}
+	];
+}
+//#endregion
+export { META_SCHEMA_DIR as n, metaSchemaFiles as r, FLOW_FILE_SCHEMA_REF as t };
+
+//# sourceMappingURL=meta-schemas-8nlyVL7g.mjs.map

package/dist/meta-schemas-8nlyVL7g.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-schemas-8nlyVL7g.mjs","names":["flowDefinitionMetaSchema","userSchemaMetaSchema","userPropertyMetaSchema","authMethodsMetaSchema","authMethodMetaSchema"],"sources":["../meta-schemas/auth-method.json","../meta-schemas/auth-methods.json","../meta-schemas/flow-definition.json","../meta-schemas/user-property.json","../meta-schemas/user-schema.json","../src/meta-schemas.ts"],"sourcesContent":["","","","","","/**\n * The dialect meta-schemas `zitadel setup` copies into a project's\n * `.zitadel/meta/` so the flow/schema dialect is machine-readable offline:\n * editors validate flow files against `flow-definition.json` via a relative\n * `$schema` pointer, and agents read the dialect files before authoring\n * edits — no docs crawl, no hosted schema required.\n *\n * The files under `meta-schemas/` are committed copies of\n * `api/openapi/endpoints/schemas/*.json` (the source the server embeds);\n * a drift-audit test keeps them byte-identical in the monorepo.\n */\nimport authMethodMetaSchema from \"../meta-schemas/auth-method.json\" with {\n  type: \"json\",\n};\nimport authMethodsMetaSchema from \"../meta-schemas/auth-methods.json\" with {\n  type: \"json\",\n};\nimport flowDefinitionMetaSchema from \"../meta-schemas/flow-definition.json\" with {\n  type: \"json\",\n};\nimport userPropertyMetaSchema from \"../meta-schemas/user-property.json\" with {\n  type: \"json\",\n};\nimport userSchemaMetaSchema from \"../meta-schemas/user-schema.json\" with {\n  type: \"json\",\n};\n\n/** Project-relative directory setup writes the meta-schemas to. */\nexport const META_SCHEMA_DIR = \".zitadel/meta\";\n\n/**\n * The `$schema` value scaffolded flow files carry, relative to\n * `.zitadel/flows/` — resolves to `{@link META_SCHEMA_DIR}/flow-definition.json`.\n */\nexport const FLOW_FILE_SCHEMA_REF = \"../meta/flow-definition.json\";\n\nexport type MetaSchemaFile = { name: string; body: object };\n\n/**\n * The dialect files to materialize, in write order. `auth-methods.json` and\n * `auth-method.json` are pulled in by `user-schema.json`'s relative `$ref`s —\n * without them the copied dialect cannot resolve offline.\n */\nexport function metaSchemaFiles(): ReadonlyArray<MetaSchemaFile> {\n  return [\n    { name: \"flow-definition.json\", body: flowDefinitionMetaSchema as object },\n    { name: \"user-schema.json\", body: userSchemaMetaSchema as object },\n    { name: \"user-property.json\", body: userPropertyMetaSchema as object },\n    { name: \"auth-methods.json\", body: authMethodsMetaSchema as object },\n    { name: \"auth-method.json\", body: authMethodMetaSchema as object },\n  ];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AK4BA,MAAa,kBAAkB;;;;;AAM/B,MAAa,uBAAuB;;;;;;AASpC,SAAgB,kBAAiD;AAC/D,QAAO;EACL;GAAE,MAAM;GAAwB,MAAMA;GAAoC;EAC1E;GAAE,MAAM;GAAoB,MAAMC;GAAgC;EAClE;GAAE,MAAM;GAAsB,MAAMC;GAAkC;EACtE;GAAE,MAAM;GAAqB,MAAMC;GAAiC;EACpE;GAAE,MAAM;GAAoB,MAAMC;GAAgC;EACnE"}

package/dist/meta-schemas.d.mts

@@ -0,0 +1,21 @@
+//#region src/meta-schemas.d.ts
+/** Project-relative directory setup writes the meta-schemas to. */
+declare const META_SCHEMA_DIR = ".zitadel/meta";
+/**
+ * The `$schema` value scaffolded flow files carry, relative to
+ * `.zitadel/flows/` — resolves to `{@link META_SCHEMA_DIR}/flow-definition.json`.
+ */
+declare const FLOW_FILE_SCHEMA_REF = "../meta/flow-definition.json";
+type MetaSchemaFile = {
+  name: string;
+  body: object;
+};
+/**
+ * The dialect files to materialize, in write order. `auth-methods.json` and
+ * `auth-method.json` are pulled in by `user-schema.json`'s relative `$ref`s —
+ * without them the copied dialect cannot resolve offline.
+ */
+declare function metaSchemaFiles(): ReadonlyArray<MetaSchemaFile>;
+//#endregion
+export { FLOW_FILE_SCHEMA_REF, META_SCHEMA_DIR, MetaSchemaFile, metaSchemaFiles };
+//# sourceMappingURL=meta-schemas.d.mts.map

package/dist/meta-schemas.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-schemas.d.mts","names":[],"sources":["../src/meta-schemas.ts"],"mappings":";;cA4Ba,eAAA;;;;;cAMA,oBAAA;AAAA,KAED,cAAA;EAAmB,IAAA;EAAc,IAAA;AAAA;AAA7C;;;;;AAAA,iBAOgB,eAAA,CAAA,GAAmB,aAAA,CAAc,cAAA"}

package/dist/meta-schemas.mjs

@@ -0,0 +1,2 @@
+import { n as META_SCHEMA_DIR, r as metaSchemaFiles, t as FLOW_FILE_SCHEMA_REF } from "./meta-schemas-8nlyVL7g.mjs";
+export { FLOW_FILE_SCHEMA_REF, META_SCHEMA_DIR, metaSchemaFiles };

package/dist/normalize.d.mts

@@ -0,0 +1,45 @@
+//#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. A
+ * top-level `$schema` is stripped too — it is a local editor affordance
+ * (scaffolded flow files point it at `.zitadel/meta/flow-definition.json`),
+ * never part of the resource: the server skips it on decode and omits it
+ * from responses, so comparing with it would read every scaffolded file
+ * as permanently diverged.
+ */
+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;;;;;AA0CA;;;;;AAmBA;;;;;;;;;;;cA7Da,sBAAA,EAAwB,QAAA,CAAS,MAAA;;;;;;;;;;iBA0C9B,iBAAA,CAAkB,IAAA;;;;;;;;iBAmBlB,mBAAA,CAAoB,IAAA"}

package/dist/normalize.mjs

@@ -0,0 +1,88 @@
+//#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. A
+* top-level `$schema` is stripped too — it is a local editor affordance
+* (scaffolded flow files point it at `.zitadel/meta/flow-definition.json`),
+* never part of the resource: the server skips it on decode and omits it
+* from responses, so comparing with it would read every scaffolded file
+* as permanently diverged.
+*/
+function normalizeFlowBody(body) {
+	const result = structuredClone(body);
+	for (const key of FLOW_ENVELOPE_KEYS) delete result[key];
+	delete result.$schema;
+	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. A\n * top-level `$schema` is stripped too — it is a local editor affordance\n * (scaffolded flow files point it at `.zitadel/meta/flow-definition.json`),\n * never part of the resource: the server skips it on decode and omits it\n * from responses, so comparing with it would read every scaffolded file\n * as permanently diverged.\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  delete result.$schema;\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;;;;;;;;;;;AAYH,SAAgB,kBAAkB,MAAsB;CACtD,MAAM,SAAS,gBAAgB,KAAK;AACpC,MAAK,MAAM,OAAO,mBAChB,QAAO,OAAO;AAEhB,QAAO,OAAO;AACd,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"}