@wildo-ai/saas-models 1.1.3 → 1.1.5

package/dist/esm/config/entity-identity-config.shared.schemas.js

@@ -12,10 +12,12 @@
  *   - entity-identity-architecture-analysis.md §4.2
  */
 import { z } from 'zod';
+import { ExternalAssuranceEnforcement } from '../external-providers/provider-authentication-assurance.shared.schemas.js';
 import { AuthMethod } from '../security/authentications/authentication.shared.schemas.js';
 import { AppRolesSchema, CORE_APP_ROLES } from '../security/authorizations/roles.shared.schemas.js';
 import { CORE_ORG_ROLES, OrgRolesSchema } from '../security/authorizations/roles.shared.schemas.js';
 import { AppFrontendType } from './app-frontend-type.shared.schemas.js';
+import { OnboardingSurveyQuestionSchema, SURVEY_QUESTION_TYPES_WHOSE_ANSWER_IS_A_VALUE, } from './frontend/onboarding.shared.schemas.js';
 // ─── Enums ──────────────────────────────────────────────────────────────────
 /** Canonical registration-policy discriminant. */
 export var RegistrationMode;
@@ -40,10 +42,51 @@ export var RegistrationAcquisitionChannel;
     RegistrationAcquisitionChannel["INVITATION"] = "invitation";
     RegistrationAcquisitionChannel["ADMINISTRATIVE_PROVISIONING"] = "administrative_provisioning";
 })(RegistrationAcquisitionChannel || (RegistrationAcquisitionChannel = {}));
+/**
+ * @wildo_source:part:start saas.models.config.registration facet:layer:shared facet:audience:app-developer
+ *
+ * WHEN a user type asks a person for their first and last name (#1374). Declared as
+ * `userTypes.<type>.auth.registration.profileNamesCollectedAt`.
+ *
+ * - `REGISTRATION` (the default) — on the sign-up form.
+ * - `ONBOARDING` — after the person has confirmed their address and credential. The sign-up form leaves the names
+ *   out; the account is created without a profile, and the first sign-in stops at the onboarding screen, which asks
+ *   for the names before the account can be used. A person who closes the tab is asked again at their next
+ *   sign-in: whether the names are owed is worked out from the account (does it have a profile yet?), never
+ *   remembered in the session.
+ *
+ * `ONBOARDING` cannot be combined with `additionalProfileQuestions`: those answers are saved WITH the profile, and
+ * at sign-up there is no profile to save them into. The configuration is refused rather than silently discarding
+ * them — ask those questions at `REGISTRATION`, or move them to an in-app guidance survey.
+ */
+export var ProfileNamesCollectionMoment;
+(function (ProfileNamesCollectionMoment) {
+    /** On the sign-up form. */
+    ProfileNamesCollectionMoment["REGISTRATION"] = "registration";
+    /** At the onboarding screen, after the address and credential are proven. */
+    ProfileNamesCollectionMoment["ONBOARDING"] = "onboarding";
+})(ProfileNamesCollectionMoment || (ProfileNamesCollectionMoment = {}));
+/** @wildo_source:part:end saas.models.config.registration */
 /** D-19: Email verification timing. */
 export var EmailVerificationMode;
 (function (EmailVerificationMode) {
+    /**
+     * The account is created pending verification and the emailed link is the only continuation. The
+     * registration answer for a new address is the same acknowledgement an already-registered address
+     * receives, so `POST /auth/register` does not reveal which addresses have accounts (#1010).
+     */
     EmailVerificationMode["REQUIRED_BEFORE_ACCESS"] = "required_before_access";
+    /**
+     * The account is created ACTIVE and a new registrant is signed in (or sent to enrollment / onboarding)
+     * by the registration answer itself.
+     *
+     * **This mode reveals whether an address is registered, by construction.** A new address receives a
+     * session and tokens; an already-registered address can only receive the acknowledgement, because
+     * answering it with a session would sign a stranger into someone else's account. No response shaping
+     * can hide that difference, so choosing this mode accepts account enumeration through registration.
+     * Choose `REQUIRED_BEFORE_ACCESS` where that matters. (Password-less registration never honours this
+     * mode, and stays indistinguishable.)
+     */
     EmailVerificationMode["DEFERRED"] = "deferred";
 })(EmailVerificationMode || (EmailVerificationMode = {}));
 /** E-10, D-15: How much orgs can override user-type auth methods. */
@@ -59,11 +102,17 @@ export const AuthMethodExpandedConfigSchema = z.object({
 });
 /**
  * authMethodsEnabled value: boolean shorthand OR expanded config.
- * Shorthand: PASSWORD: true → normalized at runtime to { enabled: true }.
+ *
+ * NOTHING REWRITES THE STORED SHAPE — the two forms are normalized on READ, by `getEnabledMethods`, and every reader
+ * must go through it. This comment said "normalized at runtime to { enabled: true }", which reads as a guarantee that a
+ * consumer may test the value for truthiness; there is no such normalizer, an object is truthy whatever it says, and
+ * two backend readers did exactly that and admitted a method declared `{ enabled: false }`.
  */
 const AuthMethodValueSchema = z.union([z.boolean(), AuthMethodExpandedConfigSchema]);
 // ─── Policy Sub-Types ───────────────────────────────────────────────────────
 export const MfaPolicyConfigSchema = z.object({
+    /** Missing/insufficient social-login assurance warns by default. STRICT refuses before session issuance. Enterprise SSO delegates MFA to its configured IdP. */
+    externalAssuranceEnforcement: z.enum(ExternalAssuranceEnforcement).optional(),
     requireMFA: z.boolean().default(false),
     /** D-4: EMAIL_OTP alone insufficient when true. Requires TOTP, Passkey, or SMS_OTP. */
     requireStrongMFA: z.boolean().default(false),
@@ -80,6 +129,7 @@ export const MfaPolicyConfigSchema = z.object({
  * Every user type must author this object explicitly. Acquisition policy is security
  * configuration, so omission must never silently become open registration.
  */
+/** @wildo_source:part:start saas.models.config.registration */
 export const RegistrationConfigSchema = z.strictObject({
     mode: z.enum(RegistrationMode),
     /**
@@ -100,7 +150,82 @@ export const RegistrationConfigSchema = z.strictObject({
     emailVerification: z.enum(EmailVerificationMode).default(EmailVerificationMode.REQUIRED_BEFORE_ACCESS),
     /** R-6: Moved from flat auth field. Blocks self-registration for SSO-managed domains. */
     blockForSSODomains: z.boolean().default(false),
+    /**
+     * The email domains that may sign themselves up, when an application wants to restrict that (#1222).
+     *
+     * OMITTED means no restriction, which is the correct default for a public application and the only
+     * honest reading of an unauthored field — an empty ARRAY would mean "nobody may register", a state
+     * an application expresses through `registration.mode` instead.
+     *
+     * ## Distinct from `blockForSSODomains`, which answers the opposite question
+     *
+     * `blockForSSODomains` is a DENY derived from another tenant's declaration: it refuses signup for a
+     * domain somebody else has claimed and put behind their identity provider. This is an ALLOW the
+     * application states about itself: only these domains may sign up here. An internal tool restricting
+     * signup to its own company has no SSO-enforced domain to key on and could not express that at all —
+     * enterprise provisioning had such a control and public signup, the one anonymous surface, had none.
+     *
+     * Compared case-insensitively against the address's domain part, whole-string: `acme.com` does not
+     * admit `notacme.com` and does not admit `sub.acme.com`. Subdomains are a separate decision an
+     * application makes by listing them, because a wildcard that quietly admits every subdomain of a
+     * domain the application does not fully control is the failure this control exists to prevent.
+     */
+    allowedEmailDomains: z.array(z.string().min(1)).optional(),
+    /**
+     * Extra profile questions this user type is asked AT SIGN-UP, beyond the name and email (#1371).
+     *
+     * Each is a survey question — `id`, `type`, `required`, `bindToField` — the same declaration an in-app guidance
+     * survey uses, so one question can be moved between sign-up and a later survey without rewriting it.
+     *
+     * `bindToField` names a field of the person's USER PROFILE, which is where the answer is saved. The account does
+     * not exist while the form is open, so the answers travel with the sign-up request and are saved when the
+     * profile is created.
+     *
+     * Refused when the configuration is loaded:
+     * - a question with no `bindToField` — its answer would be collected and thrown away;
+     * - a choice-type question — its answer is an option key rather than a value, so the profile would store the key;
+     * - any question when `profileNamesCollectedAt` is `ONBOARDING` — there is no profile at sign-up to save into.
+     *
+     * Optional; absent and empty mean the same thing.
+     */
+    additionalProfileQuestions: z.array(OnboardingSurveyQuestionSchema).optional(),
+    /** When the person's first and last name are asked (#1374). See {@link ProfileNamesCollectionMoment}. */
+    profileNamesCollectedAt: z.enum(ProfileNamesCollectionMoment).optional(),
 }).superRefine((registration, ctx) => {
+    /*
+     * Sign-up answers are saved with the profile, and the profile is created from the names: with the names asked at
+     * onboarding there is no profile at sign-up, so every answer would be discarded. Refused rather than tolerated —
+     * a configuration that collects answers and throws them away is worse than one that cannot be written.
+     */
+    if (registration.profileNamesCollectedAt === ProfileNamesCollectionMoment.ONBOARDING
+        && (registration.additionalProfileQuestions?.length ?? 0) > 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['additionalProfileQuestions'],
+            message: 'sign-up profile questions are written with the profile row, which is created from the first and last name; '
+                + 'with profileNamesCollectedAt ONBOARDING there is no row at sign-up, so the answers would be discarded. '
+                + 'Collect the names at REGISTRATION, or move these questions to an in-app guidance survey.',
+        });
+    }
+    (registration.additionalProfileQuestions ?? []).forEach((question, index) => {
+        const path = ['additionalProfileQuestions', index];
+        if (!question.bindToField) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [...path, 'bindToField'],
+                message: `sign-up question "${question.id}" declares no bindToField, so its answer would be collected and `
+                    + 'discarded. Name the user-profile field it fills, or remove the question.',
+            });
+        }
+        if (!SURVEY_QUESTION_TYPES_WHOSE_ANSWER_IS_A_VALUE.includes(question.type)) {
+            ctx.addIssue({
+                code: 'custom',
+                path: [...path, 'type'],
+                message: `sign-up question "${question.id}" is a ${question.type} question, whose answer is an option ref rather `
+                    + `than a value. Use one of ${SURVEY_QUESTION_TYPES_WHOSE_ANSWER_IS_A_VALUE.join(' / ')}.`,
+            });
+        }
+    });
     /*
      * The set with a public-signup implementation. It is enumerated rather than open because the
      * failure this refusal prevents is silent: a method listed here is ADVERTISED to a registrant, and
@@ -109,6 +234,19 @@ export const RegistrationConfigSchema = z.strictObject({
      * MAGIC_LINK and PASSKEY joined in #463. Anything else — SSO, an MFA factor — is an authentication
      * or enrollment method that has no way to CREATE an account from an anonymous caller, and adding it
      * here means building that flow first, not widening this list.
+     *
+     * ## This list reaches PUBLIC SELF-SERVICE SIGNUP, and nothing else (#1222)
+     *
+     * The scope follows from the sentence above: the question it answers only arises when an ANONYMOUS
+     * caller is creating an account for themselves. So it does NOT govern invitation acceptance (the
+     * caller holds an invitation token and the account already exists), SCIM or enterprise provisioning,
+     * or the administrative member-create door. Those paths are governed by `authMethodsEnabled` alone —
+     * a credential the sign-in doors refuse is useless however it was created.
+     *
+     * Recorded because the reach was got wrong in both directions at once: invitation acceptance applied
+     * this list to PASSWORD only, while self-registration checked it and never checked
+     * `authMethodsEnabled`. The second was the one with a cost — an application listing MAGIC_LINK here
+     * while withdrawing it from the doors created ACTIVE accounts that could never sign in.
      */
     const publiclyRegisterableMethods = [
         AuthMethod.PASSWORD,
@@ -133,17 +271,55 @@ export const RegistrationConfigSchema = z.strictObject({
         });
     }
 });
+/**
+ * The ONE reading of when a user type's names are collected (#1374): the declared moment, else `REGISTRATION` —
+ * the behaviour every user type had before the moment could be declared.
+ */
+export function resolveProfileNamesCollectionMoment(registration) {
+    return registration?.profileNamesCollectedAt ?? ProfileNamesCollectionMoment.REGISTRATION;
+}
 /**
  * Password policy — includes expiryDays (R-8, moved from flat auth field).
  * Defined here (not in app-configuration-shared) to avoid circular dependency.
  * PasswordPolicyRulesSchema in app-configuration-shared is the frontend validation subset.
  */
 export const PasswordPolicyConfigSchema = z.object({
-    minLength: z.number().min(6).max(128).default(8),
+    /**
+     * Length is the whole of the length requirement, and the composition flags default OFF (#1249).
+     *
+     * > "Verifiers and CSPs SHALL NOT impose other composition rules (e.g., requiring mixtures of
+     * > different character types) for passwords."
+     *
+     * spec-cite: NIST SP 800-63B-4 §3.1.1.2 "Password Verifiers"
+     * (https://pages.nist.gov/800-63-4/sp800-63b.html). §3.1.1.1 sets the floor at eight characters and
+     * asks verifiers to require fifteen, which is where this default now sits.
+     *
+     * The flags REMAIN authorable, because an application under a regulator that mandates character
+     * mixtures must be able to say so; what changed is which way they point when nobody has decided.
+     * Appendix A.3 is why: "a user who might have chosen 'password' as their password would be
+     * relatively likely to choose 'Password1' if required to include an uppercase letter and a number".
+     * The rule that replaces them is the blocklist — see `assertPasswordNotBlocklisted`.
+     */
+    /**
+     * The shortest password an application may REQUIRE, and the shortest it may ACCEPT.
+     *
+     * The floor is 8, not 6, because the standard states it as an obligation on the verifier:
+     * "Verifiers and CSPs SHALL require passwords to be a minimum of eight characters in length."
+     * spec-cite: NIST SP 800-63B-4 §3.1.1.1 (https://pages.nist.gov/800-63-4/sp800-63b.html).
+     * A schema that admitted 6 let an application declare a policy the standard forbids — quietly,
+     * since nothing downstream re-checked the declared value.
+     *
+     * The DEFAULT is 15 because the same section continues: "Verifiers and CSPs SHOULD require
+     * passwords to be a minimum of 15 characters in length."
+     * spec-cite: NIST SP 800-63B-4 §3.1.1.1 (https://pages.nist.gov/800-63-4/sp800-63b.html).
+     * A framework's default is the answer every application that expresses no opinion receives, so it
+     * takes the SHOULD; the floor only has to stop an application going below the SHALL.
+     */
+    minLength: z.number().min(8).max(128).default(15),
     maxLength: z.number().min(8).max(256).default(128),
-    requireUppercase: z.boolean().default(true),
-    requireLowercase: z.boolean().default(true),
-    requireNumbers: z.boolean().default(true),
+    requireUppercase: z.boolean().default(false),
+    requireLowercase: z.boolean().default(false),
+    requireNumbers: z.boolean().default(false),
     requireSpecialChars: z.boolean().default(false),
     /** R-8: Folded from flat auth.passwordExpiryDays. 0 = never. Backend-only. Enforced in orchestrator authenticate(). */
     expiryDays: z.number().min(0).default(0),
@@ -164,7 +340,21 @@ export const LockoutPolicyConfigSchema = z.object({
 });
 export const MethodManagementConfigSchema = z.object({
     allowUserMethodRemoval: z.boolean().default(true),
-    requireReauthForMethodChanges: z.boolean().default(false),
+    /**
+     * Whether adding or removing an authenticator requires the person to re-prove who they are first.
+     *
+     * ON by default, because NIST SP 800-63B-4 Sec. 4.1.2 requires it when an authenticator is bound to an
+     * existing account: binding is how a stolen session becomes access that survives a password reset.
+     * spec-cite: NIST SP 800-63B-4 Sec. 4.1.2 (Post-Enrollment Binding), fetched 2026-09-20 from
+     * https://pages.nist.gov/800-63-4/sp800-63b/events/
+     *
+     * It never asks during enrollment at sign-in or registration, where the person has just authenticated,
+     * and it never asks an account that holds nothing a re-authentication could check (no password,
+     * verified TOTP or passkey) — that is how an invited or email-link-only account gets its FIRST
+     * authenticator. The proof itself is collected by the shared step-up dialog, so no screen has to know
+     * this setting exists. Setting it to `false` is a declared deviation from the SHALL above.
+     */
+    requireReauthForMethodChanges: z.boolean().default(true),
 });
 // ─── User Type Auth Policy (§2b — complete, non-partial, REQUIRED) ──────────
 /**
@@ -190,11 +380,11 @@ export const UserTypeAuthPolicySchema = z.object({
     registration: RegistrationConfigSchema,
     /** E-7, R-8: Password strength + expiry. */
     passwordPolicy: PasswordPolicyConfigSchema.default({
-        minLength: 8,
+        minLength: 15,
         maxLength: 128,
-        requireUppercase: true,
-        requireLowercase: true,
-        requireNumbers: true,
+        requireUppercase: false,
+        requireLowercase: false,
+        requireNumbers: false,
         requireSpecialChars: false,
         expiryDays: 0,
     }),
@@ -222,7 +412,7 @@ export const UserTypeAuthPolicySchema = z.object({
     stepUpAuth: StepUpAuthConfigSchema.optional(),
     methodManagement: MethodManagementConfigSchema.default({
         allowUserMethodRemoval: true,
-        requireReauthForMethodChanges: false,
+        requireReauthForMethodChanges: true,
     }),
     /** W7.3a: Enables anonymous session support for this user type. When true,
      *  unauthenticated users can interact with isAnonymizable resources via ANONYMOUS scope.
@@ -243,8 +433,19 @@ export const UserTypeAuthPolicySchema = z.object({
 export const UserTypeDefinitionSchema = z.object({
     /** REQUIRED — the complete auth policy for this user type. Not an override of global. */
     auth: UserTypeAuthPolicySchema,
-    /** DEFERRED: Only 'email' supported. Accepts any string; engine warns if !== 'email'. */
-    uniqueIdentifier: z.string().default('email'),
+    /*
+     * `uniqueIdentifier` was REMOVED (#1224). It accepted any string, supported only `'email'`, and its
+     * ONLY reader was a startup warning saying the value "will be treated as email" — so an application
+     * could declare a different identifier, be told at boot that it would be ignored, and have it
+     * ignored. A field whose whole runtime behaviour is to announce that it does nothing is a promise
+     * the framework cannot keep.
+     *
+     * Removed rather than implemented, because implementing it is not a knob: every identity surface
+     * here is keyed on an email address — `findUserByEmail`, the anti-enumeration acknowledgements, the
+     * magic-link and password-reset token subjects, the per-email lockout bucket, the invitation join.
+     * A second identifier kind is a feature with its own design, and it starts by naming which of those
+     * surfaces change, not by re-adding this field.
+     */
     defaultAppRoles: z.array(AppRolesSchema).default([CORE_APP_ROLES.APP_USER]),
     /** D-10: When set, user type auto-revoked when user leaves last org of matching type. */
     requiresOrgMembership: z.object({
@@ -283,7 +484,21 @@ export const FrontendServiceDefinitionSchema = z.object({
  *
  * An ORGANIZATION TYPE is the shape a tenant takes: which user types its members get, which roles
  * exist inside it, whether it can come into existence through sign-up, and how hard it is for its
- * members to prove who they are. Declared as `organizationTypes` in the application configuration.
+ * members to prove who they are. Declared as `organizationTypes` in `wildo.saas.config.ts` — never in the backend
+ * configuration, because the platform reads it to type the organization it seeds for the first administrator.
+ *
+ * ## At least one type, and every organization carries one
+ *
+ * The map may not be empty, and an organization's `type` is required and must name an entry in it. A member of an
+ * organization whose type names nothing here cannot sign in: the type is where that tenant's authentication
+ * restrictions live, and "could not tell" is never read as "no restrictions".
+ *
+ * The first administrator's organization is typed by derivation, never by a separate setting: it gets the one
+ * declared type whose `userTypes` include every one of `bootstrap.firstAdmin.userTypes`, and the configuration is
+ * refused when none or several do. An organization whose stored type resolves to nothing — none stored, or one this
+ * declaration no longer carries — is typed at startup when exactly one type is declared, and the value it replaced is
+ * recorded; with several, the application refuses to start and names them. A member who reaches sign-in anyway is
+ * refused with `authentication_organization_policy_unresolved`, never let through with no restrictions.
  *
  * ## A type only self-creates if it says so
  *
@@ -296,20 +511,20 @@ export const FrontendServiceDefinitionSchema = z.object({
  * registration, `AUTO` derived, or `ONBOARDING` deferred to a later step. `defaultOwnerRole` is who
  * the registrant becomes.
  *
- * ## `authOverrides` tightens, and can never loosen
+ * ## `authOverrides`: method choices and restrictive security requirements
  *
- * A tenant may restrict how its own members authenticate, on four axes and no others — enabled
- * methods, MFA policy, password policy and re-authentication freshness. Session length, lockout and
- * registration are NOT organization-overridable.
+ * Organizations may override enabled methods, MFA, password policy and step-up freshness.
+ * Session length, lockout and registration are not organization-overridable.
  *
- * Every axis is most-restrictive-wins on top of the user type, so an organization can subtract but
- * never add. Two directions worth stating because they differ: for step-up, `enabled` is an OR
- * (either side turning it on wins) while `maxAgeSeconds` is a MIN (the shorter window wins), and
- * `methods` intersects — an organization can withdraw an acceptable re-authentication method and
- * never introduce one the user type does not already allow.
+ * Enabled login methods follow the application's `auth.orgAuthMethodPolicy`: RESTRICT_ONLY intersects
+ * with the user type's methods; EXPAND_WITHIN_SET adds only methods allowed by
+ * `auth.expandableOrgMethods`; UNRESTRICTED uses the organization's enabled set. Across organizations
+ * with explicit `authMethodsEnabled` overrides, the resolved sets intersect, including in expansion
+ * mode. An organization without that override does not participate in this method-set intersection.
  *
- * When a person belongs to SEVERAL organizations the sets intersect across all of them, so belonging
- * to a permissive tenant never restores what a strict one removed.
+ * The other axes remain most-restrictive-wins: MFA requirements cannot be removed, password
+ * requirements cannot be weakened, and step-up `enabled` is OR, `maxAgeSeconds` is MIN and
+ * `methods` intersects. Expanding login methods does not expand accepted step-up methods.
  *
  * How a registration-derived organization obtains its initial display name.
  */
@@ -324,7 +539,7 @@ export const OrgCreationPolicySchema = z.object({
     orgNameSource: z.enum(OrganizationNameSource),
     defaultOwnerRole: z.string().default(CORE_ORG_ROLES.ORG_OWNER),
 });
-/** D-15: Org type auth overrides — Partial, most-restrictive-wins on top of user type. */
+/** Org overrides: login methods follow the application mode; MFA, password and step-up remain restrictive. */
 export const OrgTypeAuthOverridesSchema = z.object({
     authMethodsEnabled: z.partialRecord(z.enum(AuthMethod), AuthMethodValueSchema).optional(),
     mfaPolicy: MfaPolicyConfigSchema.partial().optional(),
@@ -345,10 +560,18 @@ export const OrgTypeAuthOverridesSchema = z.object({
      */
     stepUpAuth: StepUpAuthConfigSchema.partial().optional(),
 }).optional();
-/** G-4: Per-org-type SCIM provisioning (moved from global directoryProvisioningEnabled). */
+/**
+ * G-4: Per-org-type SCIM provisioning (moved from global directoryProvisioningEnabled).
+ *
+ * `syncFrequencyHours` was REMOVED here (#1224): no production code read it — the gate consults only
+ * `.enabled` — so an application could set a sync cadence and nothing would schedule anything.
+ *
+ * It is NOT the per-connection field of the same name, which is live: that one is on
+ * `sso-config.shared.schemas.ts` and is surfaced in the administration view. Two fields, one name, one
+ * of them decorative, is also why this went unnoticed — a search for the name found a reader.
+ */
 export const OrgScimProvisioningSchema = z.object({
     enabled: z.boolean().default(false),
-    syncFrequencyHours: z.number().min(1).max(720).default(24),
 });
 export const OrganizationTypeDefinitionSchema = z.object({
     /** D-10: User types auto-granted when joining this org type. */
@@ -365,14 +588,131 @@ export const OrganizationTypeDefinitionSchema = z.object({
     /** G-4: SCIM provisioning toggle per org type. */
     scimProvisioning: OrgScimProvisioningSchema.optional(),
     creationPolicy: OrgCreationPolicySchema.optional(),
+    /**
+     * This type's organization OPERATES the application — the corporate in an internal tool, the suite
+     * vendor in a product that extends an existing suite.
+     *
+     * ## What it is for
+     *
+     * Some applications are not sold to many tenants. They are built FOR one organization, which runs
+     * them and owns the data in them — and that organization's systems (an ERP, a CRM, a directory) are
+     * the systems of record the application reads. The framework needs to be able to name that
+     * organization before it can say whose rows the remote data is, and an application had no way to
+     * say it: a type carries `userTypes`, roles, auth overrides and a creation policy, none of which
+     * means "this one runs the place".
+     *
+     * Declare it on exactly ONE type, and at most one organization of that type may exist. Everything
+     * downstream that must belong to the operator — not to a customer — resolves through it.
+     *
+     * ```ts
+     * organizationTypes: {
+     *   company:   { ownsApplication: true, userTypes: ['member'] },  // the operator; no creationPolicy
+     *   workspace: { userTypes: ['member'], creationPolicy: { … } },  // tenants that sign themselves up
+     * }
+     * ```
+     *
+     * ## The three rules, and why each exists
+     *
+     * - **At most one type may carry it.** Two would make "the organization that owns the application"
+     *   a choice, and the framework does not choose between declarations by record order.
+     * - **A marked type may NOT declare a `creationPolicy`.** A creation policy is how a type comes
+     *   into existence when somebody signs up, so a marked type with one would produce a new owner per
+     *   registrant. The two statements contradict each other, and the contradiction is refused where it
+     *   is written rather than discovered as a second owner.
+     * - **Its `userTypes` must cover `bootstrap.firstAdmin.userTypes`.** The organization the platform
+     *   seeds for the first administrator IS the owner organization, so a type that does not grant the
+     *   administrator what they are would seed them into an organization contradicting their identity.
+     *
+     * ## What it is NOT
+     *
+     * Not the platform's own `WILDO_OWNER_ORGANIZATION` (`@wildo-ai/platform-config-lib`), which is the
+     * organization that owns *Wildo's* applications inside apps-manager and which no application
+     * backend ever reads. This marker is an APPLICATION-level statement about one of the application's
+     * own tenants. Conflating them would make Wildo the owner of every customer's internal tool.
+     *
+     * Not a claim about privilege either: members of the owner organization hold exactly the roles the
+     * type grants them. What the marker decides is OWNERSHIP of data, not authority over people.
+     *
+     * ## Adding it to an application that is already running
+     *
+     * An organization's `type` is creation-time identity, so an existing organization cannot be
+     * re-typed by an update. The paired door is `organizations.promoteToOwnerOrganization`: a
+     * super-administrator who is a MEMBER of the target organization promotes it, with a justification,
+     * and the promotion is audited. Declare the type, run `wildo config reapply-declaration`, then
+     * promote. Declaring a second type on an application whose organizations are not all typed yet is
+     * refused at boot — boot once with the single type so every row is typed, then add the marked one.
+     *
+     * `z.literal(true)` rather than `z.boolean()`: `ownsApplication: false` would be a way of writing
+     * down a fact that is already true of every type that omits it, and two spellings of the same
+     * statement is how a declaration comes to disagree with itself.
+     */
+    ownsApplication: z.literal(true).optional(),
 });
 /** @wildo_source:part:end saas.models.config.organization-types */
 // ─── Top-Level Config Sections ──────────────────────────────────────────────
 export const UserTypesConfigSchema = z.record(z.string(), UserTypeDefinitionSchema);
 export const FrontendServicesConfigSchema = z.record(z.string(), FrontendServiceDefinitionSchema);
+/**
+ * The application's organization types — at least ONE, always.
+ *
+ * ## Why an empty map is refused (#1032, decided 2026-09-14)
+ *
+ * Every organization carries a `type`, and that type must name an entry here. The authentication
+ * policy resolver refuses a member whose organization's type it cannot resolve, because a type is
+ * where an organization's authentication restrictions live and "could not tell" must never read as
+ * "no restrictions". An application declaring no types therefore could not have a single
+ * organization anybody can sign in through — including the one the platform seeds for its first
+ * administrator. It used to be optional, and the platform seeded that organization with no type at
+ * all, which is how every administrator came to be locked out once the resolver fail-closed.
+ *
+ * Authored in `wildo.saas.config.ts` (not the backend config) so the platform, which seeds the first
+ * organization, can read it.
+ */
 export const OrganizationTypesConfigSchema = z
     .record(z.string(), OrganizationTypeDefinitionSchema)
     .superRefine((organizationTypes, ctx) => {
+    if (Object.keys(organizationTypes).length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [],
+            message: 'At least one organization type must be declared: every organization carries a type, and a '
+                + 'member of an organization whose type names no entry here cannot sign in.',
+        });
+    }
+    /*
+     * At most ONE type may declare `ownsApplication`, and a type that declares it may not also be
+     * created on registration.
+     *
+     * Both refusals live here for the same reason the `ownerByRegisteredUserType` map below does:
+     * they are statements ABOUT THE MAP, not about any one entry, so a per-entry refine could not
+     * see them. And both are contradictions in the declaration rather than states of the world —
+     * refusing them where the file is loaded turns a would-be second owner organization into an
+     * authoring error nobody can commit.
+     */
+    const markedOwnerTypes = Object.entries(organizationTypes)
+        .filter(([, definition]) => definition.ownsApplication === true)
+        .map(([organizationType]) => organizationType);
+    if (markedOwnerTypes.length > 1) {
+        ctx.addIssue({
+            code: 'custom',
+            path: [markedOwnerTypes[1], 'ownsApplication'],
+            message: `Organization types ${markedOwnerTypes.map((type) => `'${type}'`).join(', ')} all declare \`ownsApplication\`, `
+                + 'but an application is owned by exactly one organization, so at most one type may say so. '
+                + 'Keep the marker on the type whose organization operates the application and remove it from the others.',
+        });
+    }
+    for (const organizationType of markedOwnerTypes) {
+        if (organizationTypes[organizationType]?.creationPolicy === undefined)
+            continue;
+        ctx.addIssue({
+            code: 'custom',
+            path: [organizationType, 'creationPolicy'],
+            message: `Organization type '${organizationType}' declares \`ownsApplication\` and a \`creationPolicy\`. `
+                + 'A creation policy makes a new organization of this type every time a matching user registers, '
+                + 'which would produce one owner organization per registrant; at most one may exist. '
+                + 'Keep the marker and drop the creation policy, or move the policy to a separate type for the tenants that sign themselves up.',
+        });
+    }
     const ownerByRegisteredUserType = new Map();
     for (const [organizationType, definition] of Object.entries(organizationTypes)) {
         const registeredUserTypes = definition.creationPolicy?.createOnUserTypeRegistration ?? [];
@@ -414,4 +754,171 @@ export function findOrganizationTypeRegistrationCreationMatches(organizationType
         definition,
     }));
 }
+/**
+ * Why an organization yields no authentication policy — the log-side split of
+ * `ErrorCustomMessageReference.AUTHENTICATION_ORGANIZATION_POLICY_UNRESOLVED` (#1036). Three states, three remedies.
+ */
+export var OrganizationAuthPolicyUnresolvedReason;
+(function (OrganizationAuthPolicyUnresolvedReason) {
+    /** A membership names an organization that cannot be found. Remedy: remove the membership or restore the organization. */
+    OrganizationAuthPolicyUnresolvedReason["ORGANIZATION_NOT_FOUND"] = "organization_not_found";
+    /** The organization carries no type. The engine types such organizations at startup when one type is declared. */
+    OrganizationAuthPolicyUnresolvedReason["ORGANIZATION_TYPE_MISSING"] = "organization_type_missing";
+    /** The organization's type names no declared organization type. Remedy: declare it again, or restart so the engine re-types it. */
+    OrganizationAuthPolicyUnresolvedReason["ORGANIZATION_TYPE_UNDECLARED"] = "organization_type_undeclared";
+})(OrganizationAuthPolicyUnresolvedReason || (OrganizationAuthPolicyUnresolvedReason = {}));
+/**
+ * Why an organization type could, or could not, be derived — the vocabulary both derivations below
+ * answer in.
+ *
+ * A closed vocabulary rather than `string | undefined`, because the two refusals have different
+ * remedies and a caller has to be able to name them: NONE means the declaration offers nothing that
+ * fits (declare a type), AMBIGUOUS means it offers several and the framework will not choose between
+ * them by record order (narrow the declaration).
+ */
+export var OrganizationTypeDerivationOutcome;
+(function (OrganizationTypeDerivationOutcome) {
+    /** Exactly one declared type fits; it is `organizationType`. */
+    OrganizationTypeDerivationOutcome["DERIVED"] = "DERIVED";
+    /** No declared type fits. */
+    OrganizationTypeDerivationOutcome["NONE"] = "NONE";
+    /** More than one declared type fits; they are `candidates`, in declaration order. */
+    OrganizationTypeDerivationOutcome["AMBIGUOUS"] = "AMBIGUOUS";
+})(OrganizationTypeDerivationOutcome || (OrganizationTypeDerivationOutcome = {}));
+const deriveFromCandidates = (candidates) => {
+    if (candidates.length === 1) {
+        return { outcome: OrganizationTypeDerivationOutcome.DERIVED, organizationType: candidates[0] };
+    }
+    return candidates.length === 0
+        ? { outcome: OrganizationTypeDerivationOutcome.NONE }
+        : { outcome: OrganizationTypeDerivationOutcome.AMBIGUOUS, candidates };
+};
+/**
+ * The type of the organization the platform seeds for an application's first administrator.
+ *
+ * DERIVED, never authored: it is the declared organization type whose `userTypes` include every one of
+ * `bootstrap.firstAdmin.userTypes`. An organization type's `userTypes` are what a member of it is
+ * granted, so a type that does not cover the administrator's user types would seed them into an
+ * organization that contradicts who they are. Asking the application author to restate the answer
+ * would be a second copy of a fact the declaration already holds.
+ *
+ * Refuses rather than guesses when several types fit — record order is not a decision.
+ *
+ * ## The owner marker DECIDES, when one of the fitting types carries it
+ *
+ * `ownsApplication` says which organization operates the application, and the organization the
+ * platform seeds for the first administrator IS that organization. So when a fitting type is marked,
+ * the answer is not ambiguous — it is declared, and reading anything else would seed the operator's
+ * own administrator into a customer-shaped tenant.
+ *
+ * This is not a tie-break bolted onto a refusal; without it, an application with a marker would
+ * usually be REFUSED. The natural shape of a case-1 declaration is a marked `company` for the
+ * operator beside an unmarked `workspace` for the tenants that sign themselves up, and both
+ * ordinarily grant the same user types — so both cover the first administrator and `AMBIGUOUS` would
+ * fire on every such application. `AMBIGUOUS` keeps its whole meaning for the unmarked case: several
+ * types fit and NOTHING in the declaration says which, so record order is all that is left and record
+ * order is not a decision.
+ *
+ * Several MARKED types are still ambiguous, and deliberately so. The configuration schema refuses a
+ * second marker, so this can only be reached from a declaration that arrived by another route (a
+ * stored configuration written before the rule, an unparsed runtime input) — exactly the case where
+ * choosing would be a guess dressed as a derivation.
+ */
+export function deriveFirstAdministratorOrganizationType(organizationTypes, firstAdministratorUserTypes) {
+    const fittingTypes = Object.entries(organizationTypes ?? {})
+        .filter(([, definition]) => firstAdministratorUserTypes.every((userType) => definition.userTypes.includes(userType)));
+    const markedFittingTypes = fittingTypes.filter(([, definition]) => definition.ownsApplication === true);
+    if (markedFittingTypes.length > 0) {
+        return deriveFromCandidates(markedFittingTypes.map(([organizationType]) => organizationType));
+    }
+    return deriveFromCandidates(fittingTypes.map(([organizationType]) => organizationType));
+}
+/**
+ * The role that OWNS a newly-created organization of a given type.
+ *
+ * ONE resolution for every door that founds a tenant, because a tenant founded without an owner is
+ * the stranded state `administrative-continuity-floors.md` exists to prevent, and it is reached by
+ * whichever door forgot — not by the ones that remembered.
+ *
+ * There are THREE such doors and they are in two packages, which is why this is a function rather
+ * than a convention: self-service `organizations.create`, the organization derived when a user of a
+ * declaring type registers, and the platform seeding an application's FIRST organization for its
+ * first administrator. The first two already resolved it identically and said so in a comment — *"the
+ * SAME resolution registration uses, so the two creation paths cannot disagree"* — while the third
+ * hard-coded `ORG_ADMIN` and gave every freshly created application an ownerless first tenant, which
+ * its own boot report then reported at CRITICAL forever (#436 established the invariant and fixed two
+ * of its three call sites; `invariant-call-site-enumeration.md`).
+ *
+ * `ORG_OWNER` is the answer when the type declares no `creationPolicy` or no `defaultOwnerRole` —
+ * the same default `OrgCreationPolicySchema` carries, restated here because the seeding lanes reach
+ * types that never passed through that parse (a platform-supplied declaration, a stored
+ * configuration). An application that wants a differently-named founding role declares it once, on
+ * the type, and all three doors follow.
+ */
+export function resolveOrganizationFoundingOwnerRole(organizationTypes, organizationType) {
+    const declared = organizationType === undefined ? undefined : organizationTypes?.[organizationType];
+    return declared?.creationPolicy?.defaultOwnerRole ?? CORE_ORG_ROLES.ORG_OWNER;
+}
+/**
+ * Which declared organization type OWNS the application, if any.
+ *
+ * The one reader of {@link OrganizationTypeDefinition.ownsApplication}, so every surface that needs
+ * "the owner type" asks the same question of the same declaration rather than re-typing the filter.
+ *
+ * `NONE` is an ordinary, correct answer and the default for every application: most applications are
+ * sold to many tenants and no organization operates them. Only a case-1 application — an internal
+ * tool, or a product extending a suite the operator already runs — declares one.
+ *
+ * `AMBIGUOUS` is unreachable from a configuration the schema parsed (a second marker is refused
+ * there), and is returned rather than resolved for the same reason the derivation above does it: a
+ * declaration that reached a runtime by another route must not have its contradiction silently
+ * decided. Callers fail closed on it; nothing is the owner until an operator repairs the declaration.
+ */
+export function resolveApplicationOwnerOrganizationType(organizationTypes) {
+    return deriveFromCandidates(Object.entries(organizationTypes ?? {})
+        .filter(([, definition]) => definition.ownsApplication === true)
+        .map(([organizationType]) => organizationType));
+}
+/**
+ * The type an EXISTING untyped organization receives when the application declares exactly one.
+ *
+ * The narrowest of the three derivations here: it reads only the declaration, so it answers for an
+ * organization about which nothing at all is known. With several declared types it refuses, and the
+ * caller falls through to {@link deriveOrganizationTypeFromMemberUserTypes}, which asks the
+ * organization itself.
+ */
+export function deriveSoleOrganizationType(organizationTypes) {
+    return deriveFromCandidates(Object.keys(organizationTypes ?? {}));
+}
+/**
+ * The type an EXISTING untyped organization receives, read from the user types its own members hold.
+ *
+ * ## Why an existing organization is not silent about its type
+ *
+ * {@link deriveSoleOrganizationType} used to be the only answer for an existing organization, on the
+ * reasoning that one "carries no record of which user types it was meant for". Its MEMBERS carry
+ * exactly that record: an organization type's `userTypes` are what a member of it is granted, so a
+ * type that does not cover every user type the organization's members actually hold is a type this
+ * organization cannot be. When that leaves exactly one candidate, nothing is guessed — it is the same
+ * coverage test {@link deriveFirstAdministratorOrganizationType} already applies to the
+ * first-administrator organization, asked of the members instead of the declaration.
+ *
+ * ## Why an empty `memberUserTypes` is NONE rather than a match
+ *
+ * `every` over an empty set is vacuously true, so an organization with no members to read would match
+ * every declared type and, against a single-type declaration, would derive one. That would not be a
+ * derivation from the organization — it would be {@link deriveSoleOrganizationType} wearing this
+ * function's name, reached without reading anything. Absence of a signal is NONE.
+ *
+ * @param memberUserTypes The union of the user types held by the organization's members. The caller
+ *   decides which memberships count; it is the one judgement this function does not make.
+ */
+export function deriveOrganizationTypeFromMemberUserTypes(organizationTypes, memberUserTypes) {
+    if (memberUserTypes.length === 0) {
+        return { outcome: OrganizationTypeDerivationOutcome.NONE };
+    }
+    return deriveFromCandidates(Object.entries(organizationTypes ?? {})
+        .filter(([, definition]) => memberUserTypes.every((userType) => definition.userTypes.includes(userType)))
+        .map(([organizationType]) => organizationType));
+}
 //# sourceMappingURL=entity-identity-config.shared.schemas.js.map