@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/security/authentications/consumable-token.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"consumable-token.shared.schemas.js","sourceRoot":"","sources":["../../../../src/security/authentications/consumable-token.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,+EAA+E;AAC/E,uEAAuE;AACvE,+EAA+E;AAE/E,MAAM,CAAN,IAAY,wBAoEX;AApED,WAAY,wBAAwB;IAChC,6FAAiE,CAAA;IACjE,6DAAiD,CAAA;IACjD,qEAAqD,CAAA;IACrD,qEAAqD,CAAA;IACrD,yDAA+C,CAAA;IAC/C,+EAA0D,CAAA;IAC1D,yEAAuD,CAAA;IACvD,wFAAwF;IACxF,qEAAqD,CAAA;IACrD,kEAAkE;IAClE,mDAA4C,CAAA;IAC5C,+EAA+E;IAC/E,qDAA6C,CAAA;IAC7C,qEAAqE;IACrE,+CAA0C,CAAA;IAC1C,sFAAsF;IACtF,qEAAqD,CAAA;IACrD,yEAAyE;IACzE,+DAAkD,CAAA;IAClD,kEAAkE;IAClE,6CAAyC,CAAA;IACzC;;;;;OAKG;IACH,+EAA0D,CAAA;IAC1D;;;;;;;;OAQG;IACH,yEAAuD,CAAA;IACvD;;;;;;;;;;;OAWG;IACH,iFAA2D,CAAA;IAC3D;;;;;;;;;;;;;;OAcG;IACH,mEAAoD,CAAA;AACxD,CAAC,EApEW,wBAAwB,KAAxB,wBAAwB,QAoEnC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC;IAC9C,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC;IAChC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACpB,CAAC,CAAC;AAMH,+EAA+E;AAC/E,qEAAqE;AACrE,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,+BAIX;AAJD,WAAY,+BAA+B;IACvC,4DAA8B,CAAA;IAC9B,kEAAiC,CAAA;IACjC,sEAAmC,CAAA;AACvC,CAAC,EAJW,+BAA+B,KAA/B,+BAA+B,QAI1C;AAkLD;;;;GAIG;AACH,MAAM,CAAN,IAAY,yBAGX;AAHD,WAAY,yBAAyB;IACjC,wDAA2B,CAAA;IAC3B,kDAAqB,CAAA;AACzB,CAAC,EAHW,yBAAyB,KAAzB,yBAAyB,QAGpC","sourcesContent":["import { z } from \"zod\";\nimport type { ExpiresInDuration } from \"@wildo-ai/zod-decorators\";\nimport type { ExecutionContext_RoleInfo } from \"../../runtime/execution-context.shared.schemas\";\n\n\n// ============================================================================\n// CONSUMABLE TOKEN TYPES — Extensible enum of engine-level token types\n// ============================================================================\n\nexport enum CoreConsumableTokenTypes {\n    ORGANIZATION_MEMBER_INVITATION = 'organization_member_invitation',\n    PASSWORD_RESET                 = 'password_reset',\n    EMAIL_VERIFICATION             = 'email_verification',\n    FILE_PUBLIC_ACCESS             = 'file_public_access',\n    OAUTH2_STATE                   = 'oauth2_state',\n    EXTERNAL_CALLBACK_STATE        = 'external_callback_state',\n    WEBHOOK_VERIFICATION           = 'webhook_verification',\n    /** Delivers JWT tokens to the frontend after OAuth2 callback processing (Decision 7) */\n    AUTH_CODE_EXCHANGE             = 'auth_code_exchange',\n    /** Email OTP code for MFA second factor verification (Step 10) */\n    EMAIL_OTP                      = 'email_otp',\n    /** Magic link token for passwordless first-factor authentication (Phase G2) */\n    MAGIC_LINK                     = 'magic_link',\n    /** SMS OTP code for first/second factor authentication (Phase G2) */\n    SMS_OTP                        = 'sms_otp',\n    /** Phone number verification code — not an auth flow, just verification (Phase G2) */\n    PHONE_VERIFICATION             = 'phone_verification',\n    /** SAML AuthnRequest correlation state (AUTH-2: SAML Protocol Engine) */\n    SAML_AUTH_STATE                = 'saml_auth_state',\n    /** Re-authentication token for sensitive method changes (#13f) */\n    REAUTH                         = 'reauth',\n    /**\n     * OIDC authorization code (Wildo-as-provider authorization_code flow). Single-use,\n     * short-TTL; its metadata binds the code to the authenticated `userId`, the requesting\n     * `clientId`, the granted `scope`, the `redirectUri`, the PKCE `codeChallenge`, and the\n     * optional `nonce`. Redeemed at the token endpoint for an ID token + access + refresh.\n     */\n    OIDC_AUTHORIZATION_CODE        = 'oidc_authorization_code',\n    /**\n     * OIDC interactive-consent request (Wildo-as-provider authorization_code consent gate). Minted at\n     * `/oauth/authorize` for a client whose `requiresConsent` is true, INSTEAD of auto-issuing the\n     * code. Single-use, short-TTL; its metadata carries the SAME authorization request the code would\n     * bind (`clientId`, `scope`, `redirectUri`, `codeChallenge`, `nonce?`, `resource?`, `state?`)\n     * plus the authenticated `userId`. Consumed at `/oauth/authorize/decision`: on APPROVE it mints\n     * the authorization code from the stored request; on DENY the flow ends with `access_denied`.\n     * Storing the request server-side means the consent decision cannot tamper with the parameters.\n     */\n    OIDC_CONSENT_REQUEST           = 'oidc_consent_request',\n    /**\n     * OIDC RP-Initiated Logout confirmation (revocation-C §6 — the logout-confirmation prompt that\n     * mitigates BROWSER-based logout CSRF; a cross-origin page cannot read this token from the victim's\n     * URL to complete the confirm). Minted at `GET /oauth/end-session` for any request that is NOT a\n     * trusted RP logout (no/forged `id_token_hint`, or a valid hint whose `post_logout_redirect_uri`\n     * is absent / unregistered / mismatched), INSTEAD of terminating the session inline. Single-use,\n     * short-TTL; its metadata carries the already-validated `{ userId?, sessionId? }` the confirm step\n     * acts on (storing it server-side means the confirmation cannot tamper with WHICH session ends).\n     * Consumed at `POST /oauth/end-session/confirm`: on confirm it terminates that session (if any) and\n     * lands on `/oauth/logged-out`. A trusted RP logout (valid hint + exact-match registered redirect)\n     * skips this entirely and terminates + redirects to the RP directly — the Keycloak-style posture.\n     */\n    OIDC_LOGOUT_CONFIRMATION       = 'oidc_logout_confirmation',\n    /**\n     * A single-use grant to upload ONE file into ONE resource file field, minted by a principal who\n     * could perform the target CREATE/UPDATE and redeemed by whoever holds it — an AI agent's `curl`,\n     * or a human on the drop page — without the minter's own credential ever leaving the server.\n     *\n     * Exists because MCP tool arguments are model-generated JSON and cannot carry bytes; see #312.\n     * `SINGLE_USE` only (a reusable upload credential is the presigned-URL defect rebuilt inside\n     * the API). Typed fields carry identity — `userId`/`organizationId`/`roles` snapshot of the\n     * minter, `resourceIdentifier` = target resource, `relatedId` = target row for UPDATE — and\n     * `metadata` carries the ROUTE binding (`fieldName`, `operation`, `minter`, `producedFileId`),\n     * which the upload middleware checks and the identity layer deliberately ignores. Lifetime is\n     * bounded at the mint by `FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES`, rejecting rather than\n     * clamping: this credential is designed to leave the trust boundary (a transcript, a shell\n     * history), so the engine owns the bound.\n     */\n    FILE_UPLOAD_GRANT              = 'file_upload_grant',\n}\n\nexport const ConsumableTokenTypesSchema = z.union([\n    z.enum(CoreConsumableTokenTypes),\n    z.string().min(1),\n]);\n\n\nexport type ConsumableTokenTypes = z.infer<typeof ConsumableTokenTypesSchema>;\n\n\n// ============================================================================\n// CONSUMPTION MODE — Three behavioral categories for token lifecycle\n// ============================================================================\n\n/**\n * Defines how a token behaves when used.\n *\n * - `SINGLE_USE`: Consumed after first successful use (password reset, invitation acceptance)\n * - `BOUNDED_REUSE`: Can be used N times or until expiry (file sharing link, meeting join link)\n * - `EPHEMERAL_STATE`: Carries state through a redirect, consumed on callback (OAuth state, payment callback)\n */\nexport enum ConsumableToken_ConsumptionMode {\n    SINGLE_USE      = 'SINGLE_USE',\n    BOUNDED_REUSE   = 'BOUNDED_REUSE',\n    EPHEMERAL_STATE = 'EPHEMERAL_STATE',\n}\n\n\n// ============================================================================\n// UTILITY TYPE — StaticOrDerived<T>\n// ============================================================================\n\n/**\n * A value that can either be provided statically or derived from the operation result at runtime.\n *\n * Static:  `{ value: 7, unit: 'days' }`\n * Derived: `(currentObject) => ({ value: currentObject.shareDurationDays, unit: 'days' })`\n *\n * NOTE: This is intentionally NOT `ResourceConfiguration_FunctionWithContextNeeds` (R5).\n * `FunctionWithContextNeeds` wraps functions with metadata flags (`needsObjectContext`, `needsUserContext`)\n * for factory introspection. `StaticOrDerived<T>` is simpler — it's just \"literal value OR function from\n * currentObject\" with no metadata flags. The factory marks dynamic values as `_isDynamic` during\n * processing, which is a different mechanism entirely.\n */\nexport type StaticOrDerived<T> = T | ((currentObject: Record<string, any>) => T);\n\n\n// ============================================================================\n// DECLARATIVE CONFIG TYPES — For operation variant configuration\n// ============================================================================\n\n/** @wildo_source:part:start saas.models.resource-config.token-generation facet:layer:shared facet:family:resource-config\n *\n * Config-declared gate deciding whether a `tokenGeneration` side-effect actually\n * mints a token, evaluated against the POST-operation row (`currentObject`).\n *\n * WHY the destructured params-object shape `({ currentObject }) => boolean` and NOT\n * the positional `StaticOrDerived` shape used by `expiresIn`/`grantedRoles` above (R5):\n * this deliberately mirrors the operation-variant `enabledCondition` predicate (see the\n * org-members REVOKE/RESEND configs) so an app author writes ONE predicate form for every\n * \"config-declared gate over currentObject\". The trade-off is worth it — cross-surface\n * authoring consistency beats intra-type consistency with the positional derivers.\n *\n * WHY the params object carries ONLY `currentObject` (unlike the notification `condition`,\n * which also gets `inputDto`/`objectContext`/`initiatorIds`): a token is a PERSISTED\n * side-effect keyed on the resulting row, so its gate must depend only on the persisted\n * result — never on raw request input. Narrowing the params to `currentObject` makes that\n * guarantee structural. (It also keeps this type free of the `resources-config` params type,\n * which would be a circular import — `resources-config.shared.schemas` imports FROM here.)\n */\nexport type TokenGenerationCondition = (params: { currentObject: Record<string, any> }) => boolean;\n/** @wildo_source:part:end saas.models.resource-config.token-generation */\n\n/** @wildo_source:part:start saas.models.resource-config.token-generation facet:layer:shared facet:family:resource-config\n *\n * Declarative config for automatic token generation on an operation variant.\n * Placed on CREATE/RESEND-like operations to generate a token as a side-effect.\n *\n * Import from `@wildo-ai/saas-models`; application authors normally provide\n * this shape through an API-call variant in\n * `createResourceConfiguration_Initialization(...)`.\n *\n * The operation pipeline creates the token in the same persistence transaction\n * as the resource mutation, then injects `additionalContext.tokenValue` into\n * post-commit notification dispatch.\n *\n * The contract requires one canonical persisted resource state. It cannot be\n * authored on a collection/aggregate operation, a core bulk mutation, or a\n * variant with `haveBulkOperation: true`; those operations do not expose one\n * unambiguous related resource identity for the generated token.\n *\n * @example\n * `tokenGeneration: { tokenType: MyTokenType.INVITATION, consumptionMode:\n * ConsumableToken_ConsumptionMode.SINGLE_USE, expiresIn: { value: 7, unit:\n * DurationUnit.DAYS }, relatedIdField: '_id' }`\n */\nexport type TokenGenerationConfig = {\n    /** Token type identifier (from CoreConsumableTokenTypes or custom app enum) */\n    tokenType: ConsumableTokenTypes;\n\n    /** How the token behaves when used */\n    consumptionMode: ConsumableToken_ConsumptionMode;\n\n    /**\n     * Expiration duration — static or derived from currentObject.\n     * Units: minutes, hours, or days only. Value must be ≥ 1.\n     * Static: `{ value: 7, unit: DurationUnit.DAYS }`\n     * Derived: `(currentObject) => ({ value: currentObject.shareDurationDays, unit: 'days' })`\n     */\n    expiresIn: StaticOrDerived<ExpiresInDuration>;\n\n    /**\n     * Optional gate — mint this token ONLY when the predicate returns truthy against the\n     * post-operation row. Absent = always mint.\n     *\n     * Canonical use: a POLYMORPHIC CREATE (org-member INVITE vs DIRECT-ADD) mints the\n     * single-use accept token ONLY for the INVITED branch. A direct-add (founder / SSO-JIT /\n     * SCIM) persists `ACTIVE` with nothing to accept, so minting a token there would leave a\n     * live single-use accept token dangling on an already-ACTIVE row (a hygiene/security\n     * hole). Keying on the resulting `status` — the semantic driver, uniformly present on\n     * every branch's `currentObject` — auto-covers any future non-INVITED direct-add path.\n     *\n     * @example `({ currentObject }) => currentObject.status === OrganizationMemberStatus.INVITED`\n     */\n    condition?: TokenGenerationCondition;\n\n    /**\n     * Roles granted when the token is used for authentication.\n     * Static: `[{ roles: ['ORG_MEMBER'], relatedPrimaryScope: 'ORGANIZATIONS' }]`\n     * Derived: `(currentObject) => [{ roles: [currentObject.assignedRole], relatedPrimaryScope: 'ORGANIZATIONS' }]`\n     */\n    grantedRoles?: StaticOrDerived<ExecutionContext_RoleInfo[]>;\n\n    /** Max uses for BOUNDED_REUSE mode. Required when consumptionMode is BOUNDED_REUSE. */\n    maxUses?: number;\n\n    /** Revoke existing tokens of same type for same relatedId before creating new one (e.g., RESEND) */\n    revokeExistingForSameRelated?: boolean;\n\n    /** Field in currentState to use as relatedId. Defaults to '_id' (the resource's own ID). */\n    relatedIdField?: string;\n\n    /**\n     * Field in currentState to capture as the token's userId (user_self pattern).\n     * e.g., 'invitedUserId' — if not set, no userId stored on token.\n     */\n    userIdField?: string;\n\n    /**\n     * W7.3b: Marks the generated token as exchangeable for a one-off session JWT.\n     * When true, the token can be used via POST /auth/one-off-session/exchange.\n     */\n    createsOneOffSession?: boolean;\n\n    /**\n     * W7.3b: When the token is consumed — at exchange time or at target operation time.\n     * Required when `createsOneOffSession` is true.\n     * - `EXCHANGE`: consumed immediately when exchanged for a JWT (no token carried into session)\n     * - `TARGET_OPERATION`: carried through the session, consumed when the target operation executes\n     */\n    consumeAt?: 'EXCHANGE' | 'TARGET_OPERATION';\n\n    /**\n     * W7.3b: Builds targeting.initiatorIds for frontend URL resolution.\n     * Maps field identifier names to field paths in currentState.\n     * organizationId is auto-included from execution context if not specified.\n     *\n     * Example: `{ taskId: '_id' }` → on a Tasks resource, reads `currentState._id` as the taskId.\n     * The frontend uses these to resolve the target URL after session exchange.\n     */\n    targetingFields?: Record<string, string>;\n\n    /**\n     * Public path of the frontend page that consumes this token (e.g. `/invitation`).\n     * When set, the notification dispatcher builds\n     * `additionalContext.acceptUrl = <frontendPublicUrl><emailLinkPath>?token=<tokenValue>`\n     * for the token-bearing notification email, so the recipient can act on the\n     * token straight from the email. Without it, only the raw `tokenValue` is\n     * exposed and the email falls back to its generic (sign-in) CTA. Use a stable\n     * framework route — the backend cannot import frontend route constants.\n     */\n    emailLinkPath?: string;\n};\n/** @wildo_source:part:end saas.models.resource-config.token-generation */\n\n/**\n * Declarative config for automatic token revocation on an operation variant.\n * Placed on DELETE-like operations to revoke associated tokens before the resource is removed.\n *\n * Pipeline placement: BEFORE the core operation (pre-operation step).\n * Like token generation, revocation requires one canonical current resource\n * state and cannot be combined with collection/aggregate or authored/generated\n * bulk mutation semantics. It also cannot run on CREATE because no current\n * resource exists before persistence.\n */\nexport type TokenRevocationConfig = {\n    /** Which token types to revoke when this operation executes */\n    tokenTypes: ConsumableTokenTypes[];\n\n    /** Field in currentState to use as relatedId for revocation lookup. Defaults to '_id'. */\n    relatedIdField?: string;\n};\n\n/**\n * How a consumable token interacts with JWT/API-key authentication on an operation.\n * ALTERNATIVE: token alone is sufficient (replaces JWT). Used by PASSWORD_RESET, MAGIC_LINK, etc.\n * ADDITIVE: token is required ON TOP of JWT auth. Used by one-off session target operations.\n */\nexport enum TokenAuthenticationPolicy {\n    ALTERNATIVE = 'ALTERNATIVE',\n    ADDITIVE = 'ADDITIVE',\n}\n\n/**\n * Declarative config declaring that an operation accepts consumable tokens for authentication.\n * Replaces the old `ResourceConfiguration_OperationVariant_ApiCall_ConsumableToken`.\n *\n * NOTE: No `isConsumed` field — consumption is controlled by the token user's `consumptionMode`\n * (set at creation time), not by the operation config. This avoids contradictions between config\n * and entity state (Trap 5).\n */\nexport type TokenAuthenticationConfig = {\n    /** Which token types this operation accepts for authentication */\n    types: ConsumableTokenTypes[];\n    policy: TokenAuthenticationPolicy;\n};\n"]}
+{"version":3,"file":"consumable-token.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authentications/consumable-token.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,+EAA+E;AAC/E,uEAAuE;AACvE,+EAA+E;AAE/E,MAAM,CAAN,IAAY,wBA0FX;AA1FD,WAAY,wBAAwB;IAChC,6FAAiE,CAAA;IACjE,6DAAiD,CAAA;IACjD,qEAAqD,CAAA;IACrD,qEAAqD,CAAA;IACrD,yDAA+C,CAAA;IAC/C,+EAA0D,CAAA;IAC1D,yEAAuD,CAAA;IACvD,wFAAwF;IACxF,qEAAqD,CAAA;IACrD,kEAAkE;IAClE,mDAA4C,CAAA;IAC5C,+EAA+E;IAC/E,qDAA6C,CAAA;IAC7C,qEAAqE;IACrE,+CAA0C,CAAA;IAC1C,sFAAsF;IACtF,qEAAqD,CAAA;IACrD,yEAAyE;IACzE,+DAAkD,CAAA;IAClD;;;;OAIG;IACH,6CAAyC,CAAA;IACzC;;;;;;;;;OASG;IACH,uDAA8C,CAAA;IAC9C;;;;;OAKG;IACH,yEAAuD,CAAA;IACvD;;;;;OAKG;IACH,+EAA0D,CAAA;IAC1D;;;;;;;;OAQG;IACH,yEAAuD,CAAA;IACvD;;;;;;;;;;;OAWG;IACH,iFAA2D,CAAA;IAC3D;;;;;;;;;;;;;;OAcG;IACH,mEAAoD,CAAA;AACxD,CAAC,EA1FW,wBAAwB,KAAxB,wBAAwB,QA0FnC;AAED,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC;IAC9C,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC;IAChC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACpB,CAAC,CAAC;AAMH,+EAA+E;AAC/E,qEAAqE;AACrE,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,+BAIX;AAJD,WAAY,+BAA+B;IACvC,4DAA8B,CAAA;IAC9B,kEAAiC,CAAA;IACjC,sEAAmC,CAAA;AACvC,CAAC,EAJW,+BAA+B,KAA/B,+BAA+B,QAI1C;AAkLD;;;;GAIG;AACH,MAAM,CAAN,IAAY,yBAGX;AAHD,WAAY,yBAAyB;IACjC,wDAA2B,CAAA;IAC3B,kDAAqB,CAAA;AACzB,CAAC,EAHW,yBAAyB,KAAzB,yBAAyB,QAGpC","sourcesContent":["import { z } from \"zod\";\nimport type { ExpiresInDuration } from \"@wildo-ai/zod-decorators\";\nimport type { ExecutionContext_RoleInfo } from \"../../runtime/execution-context.shared.schemas\";\n\n\n// ============================================================================\n// CONSUMABLE TOKEN TYPES — Extensible enum of engine-level token types\n// ============================================================================\n\nexport enum CoreConsumableTokenTypes {\n    ORGANIZATION_MEMBER_INVITATION = 'organization_member_invitation',\n    PASSWORD_RESET                 = 'password_reset',\n    EMAIL_VERIFICATION             = 'email_verification',\n    FILE_PUBLIC_ACCESS             = 'file_public_access',\n    OAUTH2_STATE                   = 'oauth2_state',\n    EXTERNAL_CALLBACK_STATE        = 'external_callback_state',\n    WEBHOOK_VERIFICATION           = 'webhook_verification',\n    /** Delivers JWT tokens to the frontend after OAuth2 callback processing (Decision 7) */\n    AUTH_CODE_EXCHANGE             = 'auth_code_exchange',\n    /** Email OTP code for MFA second factor verification (Step 10) */\n    EMAIL_OTP                      = 'email_otp',\n    /** Magic link token for passwordless first-factor authentication (Phase G2) */\n    MAGIC_LINK                     = 'magic_link',\n    /** SMS OTP code for first/second factor authentication (Phase G2) */\n    SMS_OTP                        = 'sms_otp',\n    /** Phone number verification code — not an auth flow, just verification (Phase G2) */\n    PHONE_VERIFICATION             = 'phone_verification',\n    /** SAML AuthnRequest correlation state (AUTH-2: SAML Protocol Engine) */\n    SAML_AUTH_STATE                = 'saml_auth_state',\n    /**\n     * Step-up proof: the account holder re-proved who they are, with a factor the user type's\n     * `stepUpAuth.methods` accepts. The ONLY type a sensitive operation, a method removal or a TOTP\n     * disable accepts (#13f, #422).\n     */\n    REAUTH                         = 'reauth',\n    /**\n     * Binding proof (#1417): the account holder re-proved who they are in order to ADD a way to sign in,\n     * with any factor they hold, whatever the step-up policy names. Accepted by the binding doors and by\n     * nothing else, so it cannot unlock a sensitive operation.\n     *\n     * It exists because a step-up policy that names a factor the account does not hold yet would\n     * otherwise deadlock: a password-only account told to enrol a passkey could only mint a password\n     * proof, and the policy refuses a password. Separating the proof by purpose lets the policy bind the\n     * step-up without locking the enrolment it asks for.\n     */\n    REAUTH_BIND                    = 'reauth_bind',\n    /**\n     * One-time code carrying a re-authentication proof (`REAUTH` or `REAUTH_BIND`) minted by a\n     * federated re-authentication (#1441). The identity provider's callback lands in a popup; the code\n     * is handed to the window that opened it, which redeems it with its OWN bearer, so the proof can be\n     * redeemed only by the account it was minted for, and the proof itself never travels in a URL.\n     */\n    REAUTH_CODE_EXCHANGE           = 'reauth_code_exchange',\n    /**\n     * OIDC authorization code (Wildo-as-provider authorization_code flow). Single-use,\n     * short-TTL; its metadata binds the code to the authenticated `userId`, the requesting\n     * `clientId`, the granted `scope`, the `redirectUri`, the PKCE `codeChallenge`, and the\n     * optional `nonce`. Redeemed at the token endpoint for an ID token + access + refresh.\n     */\n    OIDC_AUTHORIZATION_CODE        = 'oidc_authorization_code',\n    /**\n     * OIDC interactive-consent request (Wildo-as-provider authorization_code consent gate). Minted at\n     * `/oauth/authorize` for a client whose `requiresConsent` is true, INSTEAD of auto-issuing the\n     * code. Single-use, short-TTL; its metadata carries the SAME authorization request the code would\n     * bind (`clientId`, `scope`, `redirectUri`, `codeChallenge`, `nonce?`, `resource?`, `state?`)\n     * plus the authenticated `userId`. Consumed at `/oauth/authorize/decision`: on APPROVE it mints\n     * the authorization code from the stored request; on DENY the flow ends with `access_denied`.\n     * Storing the request server-side means the consent decision cannot tamper with the parameters.\n     */\n    OIDC_CONSENT_REQUEST           = 'oidc_consent_request',\n    /**\n     * OIDC RP-Initiated Logout confirmation (revocation-C §6 — the logout-confirmation prompt that\n     * mitigates BROWSER-based logout CSRF; a cross-origin page cannot read this token from the victim's\n     * URL to complete the confirm). Minted at `GET /oauth/end-session` for any request that is NOT a\n     * trusted RP logout (no/forged `id_token_hint`, or a valid hint whose `post_logout_redirect_uri`\n     * is absent / unregistered / mismatched), INSTEAD of terminating the session inline. Single-use,\n     * short-TTL; its metadata carries the already-validated `{ userId?, sessionId? }` the confirm step\n     * acts on (storing it server-side means the confirmation cannot tamper with WHICH session ends).\n     * Consumed at `POST /oauth/end-session/confirm`: on confirm it terminates that session (if any) and\n     * lands on `/oauth/logged-out`. A trusted RP logout (valid hint + exact-match registered redirect)\n     * skips this entirely and terminates + redirects to the RP directly — the Keycloak-style posture.\n     */\n    OIDC_LOGOUT_CONFIRMATION       = 'oidc_logout_confirmation',\n    /**\n     * A single-use grant to upload ONE file into ONE resource file field, minted by a principal who\n     * could perform the target CREATE/UPDATE and redeemed by whoever holds it — an AI agent's `curl`,\n     * or a human on the drop page — without the minter's own credential ever leaving the server.\n     *\n     * Exists because MCP tool arguments are model-generated JSON and cannot carry bytes; see #312.\n     * `SINGLE_USE` only (a reusable upload credential is the presigned-URL defect rebuilt inside\n     * the API). Typed fields carry identity — `userId`/`organizationId`/`roles` snapshot of the\n     * minter, `resourceIdentifier` = target resource, `relatedId` = target row for UPDATE — and\n     * `metadata` carries the ROUTE binding (`fieldName`, `operation`, `minter`, `producedFileId`),\n     * which the upload middleware checks and the identity layer deliberately ignores. Lifetime is\n     * bounded at the mint by `FILE_UPLOAD_GRANT_ABSOLUTE_MAX_MINUTES`, rejecting rather than\n     * clamping: this credential is designed to leave the trust boundary (a transcript, a shell\n     * history), so the engine owns the bound.\n     */\n    FILE_UPLOAD_GRANT              = 'file_upload_grant',\n}\n\nexport const ConsumableTokenTypesSchema = z.union([\n    z.enum(CoreConsumableTokenTypes),\n    z.string().min(1),\n]);\n\n\nexport type ConsumableTokenTypes = z.infer<typeof ConsumableTokenTypesSchema>;\n\n\n// ============================================================================\n// CONSUMPTION MODE — Three behavioral categories for token lifecycle\n// ============================================================================\n\n/**\n * Defines how a token behaves when used.\n *\n * - `SINGLE_USE`: Consumed after first successful use (password reset, invitation acceptance)\n * - `BOUNDED_REUSE`: Can be used N times or until expiry (file sharing link, meeting join link)\n * - `EPHEMERAL_STATE`: Carries state through a redirect, consumed on callback (OAuth state, payment callback)\n */\nexport enum ConsumableToken_ConsumptionMode {\n    SINGLE_USE      = 'SINGLE_USE',\n    BOUNDED_REUSE   = 'BOUNDED_REUSE',\n    EPHEMERAL_STATE = 'EPHEMERAL_STATE',\n}\n\n\n// ============================================================================\n// UTILITY TYPE — StaticOrDerived<T>\n// ============================================================================\n\n/**\n * A value that can either be provided statically or derived from the operation result at runtime.\n *\n * Static:  `{ value: 7, unit: 'days' }`\n * Derived: `(currentObject) => ({ value: currentObject.shareDurationDays, unit: 'days' })`\n *\n * NOTE: This is intentionally NOT `ResourceConfiguration_FunctionWithContextNeeds` (R5).\n * `FunctionWithContextNeeds` wraps functions with metadata flags (`needsObjectContext`, `needsUserContext`)\n * for factory introspection. `StaticOrDerived<T>` is simpler — it's just \"literal value OR function from\n * currentObject\" with no metadata flags. The factory marks dynamic values as `_isDynamic` during\n * processing, which is a different mechanism entirely.\n */\nexport type StaticOrDerived<T> = T | ((currentObject: Record<string, any>) => T);\n\n\n// ============================================================================\n// DECLARATIVE CONFIG TYPES — For operation variant configuration\n// ============================================================================\n\n/** @wildo_source:part:start saas.models.resource-config.token-generation facet:layer:shared facet:family:resource-config\n *\n * Config-declared gate deciding whether a `tokenGeneration` side-effect actually\n * mints a token, evaluated against the POST-operation row (`currentObject`).\n *\n * WHY the destructured params-object shape `({ currentObject }) => boolean` and NOT\n * the positional `StaticOrDerived` shape used by `expiresIn`/`grantedRoles` above (R5):\n * this deliberately mirrors the operation-variant `enabledCondition` predicate (see the\n * org-members REVOKE/RESEND configs) so an app author writes ONE predicate form for every\n * \"config-declared gate over currentObject\". The trade-off is worth it — cross-surface\n * authoring consistency beats intra-type consistency with the positional derivers.\n *\n * WHY the params object carries ONLY `currentObject` (unlike the notification `condition`,\n * which also gets `inputDto`/`objectContext`/`initiatorIds`): a token is a PERSISTED\n * side-effect keyed on the resulting row, so its gate must depend only on the persisted\n * result — never on raw request input. Narrowing the params to `currentObject` makes that\n * guarantee structural. (It also keeps this type free of the `resources-config` params type,\n * which would be a circular import — `resources-config.shared.schemas` imports FROM here.)\n */\nexport type TokenGenerationCondition = (params: { currentObject: Record<string, any> }) => boolean;\n/** @wildo_source:part:end saas.models.resource-config.token-generation */\n\n/** @wildo_source:part:start saas.models.resource-config.token-generation facet:layer:shared facet:family:resource-config\n *\n * Declarative config for automatic token generation on an operation variant.\n * Placed on CREATE/RESEND-like operations to generate a token as a side-effect.\n *\n * Import from `@wildo-ai/saas-models`; application authors normally provide\n * this shape through an API-call variant in\n * `createResourceConfiguration_Initialization(...)`.\n *\n * The operation pipeline creates the token in the same persistence transaction\n * as the resource mutation, then injects `additionalContext.tokenValue` into\n * post-commit notification dispatch.\n *\n * The contract requires one canonical persisted resource state. It cannot be\n * authored on a collection/aggregate operation, a core bulk mutation, or a\n * variant with `haveBulkOperation: true`; those operations do not expose one\n * unambiguous related resource identity for the generated token.\n *\n * @example\n * `tokenGeneration: { tokenType: MyTokenType.INVITATION, consumptionMode:\n * ConsumableToken_ConsumptionMode.SINGLE_USE, expiresIn: { value: 7, unit:\n * DurationUnit.DAYS }, relatedIdField: '_id' }`\n */\nexport type TokenGenerationConfig = {\n    /** Token type identifier (from CoreConsumableTokenTypes or custom app enum) */\n    tokenType: ConsumableTokenTypes;\n\n    /** How the token behaves when used */\n    consumptionMode: ConsumableToken_ConsumptionMode;\n\n    /**\n     * Expiration duration — static or derived from currentObject.\n     * Units: minutes, hours, or days only. Value must be ≥ 1.\n     * Static: `{ value: 7, unit: DurationUnit.DAYS }`\n     * Derived: `(currentObject) => ({ value: currentObject.shareDurationDays, unit: 'days' })`\n     */\n    expiresIn: StaticOrDerived<ExpiresInDuration>;\n\n    /**\n     * Optional gate — mint this token ONLY when the predicate returns truthy against the\n     * post-operation row. Absent = always mint.\n     *\n     * Canonical use: a POLYMORPHIC CREATE (org-member INVITE vs DIRECT-ADD) mints the\n     * single-use accept token ONLY for the INVITED branch. A direct-add (founder / SSO-JIT /\n     * SCIM) persists `ACTIVE` with nothing to accept, so minting a token there would leave a\n     * live single-use accept token dangling on an already-ACTIVE row (a hygiene/security\n     * hole). Keying on the resulting `status` — the semantic driver, uniformly present on\n     * every branch's `currentObject` — auto-covers any future non-INVITED direct-add path.\n     *\n     * @example `({ currentObject }) => currentObject.status === OrganizationMemberStatus.INVITED`\n     */\n    condition?: TokenGenerationCondition;\n\n    /**\n     * Roles granted when the token is used for authentication.\n     * Static: `[{ roles: ['ORG_MEMBER'], relatedPrimaryScope: 'ORGANIZATIONS' }]`\n     * Derived: `(currentObject) => [{ roles: [currentObject.assignedRole], relatedPrimaryScope: 'ORGANIZATIONS' }]`\n     */\n    grantedRoles?: StaticOrDerived<ExecutionContext_RoleInfo[]>;\n\n    /** Max uses for BOUNDED_REUSE mode. Required when consumptionMode is BOUNDED_REUSE. */\n    maxUses?: number;\n\n    /** Revoke existing tokens of same type for same relatedId before creating new one (e.g., RESEND) */\n    revokeExistingForSameRelated?: boolean;\n\n    /** Field in currentState to use as relatedId. Defaults to '_id' (the resource's own ID). */\n    relatedIdField?: string;\n\n    /**\n     * Field in currentState to capture as the token's userId (user_self pattern).\n     * e.g., 'invitedUserId' — if not set, no userId stored on token.\n     */\n    userIdField?: string;\n\n    /**\n     * W7.3b: Marks the generated token as exchangeable for a one-off session JWT.\n     * When true, the token can be used via POST /auth/one-off-session/exchange.\n     */\n    createsOneOffSession?: boolean;\n\n    /**\n     * W7.3b: When the token is consumed — at exchange time or at target operation time.\n     * Required when `createsOneOffSession` is true.\n     * - `EXCHANGE`: consumed immediately when exchanged for a JWT (no token carried into session)\n     * - `TARGET_OPERATION`: carried through the session, consumed when the target operation executes\n     */\n    consumeAt?: 'EXCHANGE' | 'TARGET_OPERATION';\n\n    /**\n     * W7.3b: Builds targeting.initiatorIds for frontend URL resolution.\n     * Maps field identifier names to field paths in currentState.\n     * organizationId is auto-included from execution context if not specified.\n     *\n     * Example: `{ taskId: '_id' }` → on a Tasks resource, reads `currentState._id` as the taskId.\n     * The frontend uses these to resolve the target URL after session exchange.\n     */\n    targetingFields?: Record<string, string>;\n\n    /**\n     * Public path of the frontend page that consumes this token (e.g. `/invitation`).\n     * When set, the notification dispatcher builds\n     * `additionalContext.acceptUrl = <frontendPublicUrl><emailLinkPath>?token=<tokenValue>`\n     * for the token-bearing notification email, so the recipient can act on the\n     * token straight from the email. Without it, only the raw `tokenValue` is\n     * exposed and the email falls back to its generic (sign-in) CTA. Use a stable\n     * framework route — the backend cannot import frontend route constants.\n     */\n    emailLinkPath?: string;\n};\n/** @wildo_source:part:end saas.models.resource-config.token-generation */\n\n/**\n * Declarative config for automatic token revocation on an operation variant.\n * Placed on DELETE-like operations to revoke associated tokens before the resource is removed.\n *\n * Pipeline placement: BEFORE the core operation (pre-operation step).\n * Like token generation, revocation requires one canonical current resource\n * state and cannot be combined with collection/aggregate or authored/generated\n * bulk mutation semantics. It also cannot run on CREATE because no current\n * resource exists before persistence.\n */\nexport type TokenRevocationConfig = {\n    /** Which token types to revoke when this operation executes */\n    tokenTypes: ConsumableTokenTypes[];\n\n    /** Field in currentState to use as relatedId for revocation lookup. Defaults to '_id'. */\n    relatedIdField?: string;\n};\n\n/**\n * How a consumable token interacts with JWT/API-key authentication on an operation.\n * ALTERNATIVE: token alone is sufficient (replaces JWT). Used by PASSWORD_RESET, MAGIC_LINK, etc.\n * ADDITIVE: token is required ON TOP of JWT auth. Used by one-off session target operations.\n */\nexport enum TokenAuthenticationPolicy {\n    ALTERNATIVE = 'ALTERNATIVE',\n    ADDITIVE = 'ADDITIVE',\n}\n\n/**\n * Declarative config declaring that an operation accepts consumable tokens for authentication.\n * Replaces the old `ResourceConfiguration_OperationVariant_ApiCall_ConsumableToken`.\n *\n * NOTE: No `isConsumed` field — consumption is controlled by the token user's `consumptionMode`\n * (set at creation time), not by the operation config. This avoids contradictions between config\n * and entity state (Trap 5).\n */\nexport type TokenAuthenticationConfig = {\n    /** Which token types this operation accepts for authentication */\n    types: ConsumableTokenTypes[];\n    policy: TokenAuthenticationPolicy;\n};\n"]}

package/dist/esm/security/authentications/cross-frontend-handoff.shared.dto.schemas.d.ts

@@ -185,7 +185,13 @@ export declare const TokenExchangeRequestSchema: z.ZodObject<{
  */
 export type TokenExchangeRequest = z.infer<typeof TokenExchangeRequestSchema>;
 /**
- * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5).
+ * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5) when the code signs in.
+ *
+ * A code a federated sign-in was PARKED behind (#1103 — the account still owes its organization) answers with
+ * the separate `TokenExchangeOrganizationOnboardingResponseSchema` instead (`{ nextStep, sessionId }`, no token).
+ * It is kept out of this schema on purpose: this one is strict and parsed by receivers that can never hold a
+ * parked code (the docs site redeems only handoff codes, which need a signed-in caller), so widening it would
+ * teach them a shape they must then refuse.
  *
  * Lives in this file (rather than `authentication.shared.dto.schemas.ts`)
  * because every receiver of an AUTH_CODE_EXCHANGE token — the SaaS app, the

package/dist/esm/security/authentications/cross-frontend-handoff.shared.dto.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross-frontend-handoff.shared.dto.schemas.d.ts","sourceRoot":"","sources":["../../../../src/security/authentications/cross-frontend-handoff.shared.dto.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,oBAAY,6BAA6B;IACrC,yFAAyF;IACzF,uBAAuB,4BAA4B;IAEnD,8JAA8J;IAC9J,mCAAmC,wCAAwC;IAE3E,2IAA2I;IAC3I,yCAAyC,8CAA8C;CAC1F;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,iCAAiC;;;kBAG5C,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kCAAkC;;;kBAG7C,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;kBAErC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B;;;;;;kBAMtC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}
+{"version":3,"file":"cross-frontend-handoff.shared.dto.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/authentications/cross-frontend-handoff.shared.dto.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;GAKG;AACH,oBAAY,6BAA6B;IACrC,yFAAyF;IACzF,uBAAuB,4BAA4B;IAEnD,8JAA8J;IAC9J,mCAAmC,wCAAwC;IAE3E,2IAA2I;IAC3I,yCAAyC,8CAA8C;CAC1F;AA+FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,eAAO,MAAM,iCAAiC;;;kBAG5C,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iCAAiC,CAAC,CAAC;AAE5F;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,kCAAkC;;;kBAG7C,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B;;kBAErC,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,2BAA2B;;;;;;kBAMtC,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC"}

package/dist/esm/security/authentications/cross-frontend-handoff.shared.dto.schemas.js

@@ -247,7 +247,13 @@ export const TokenExchangeRequestSchema = z.strictObject({
     code: z.string().min(1),
 });
 /**
- * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5).
+ * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5) when the code signs in.
+ *
+ * A code a federated sign-in was PARKED behind (#1103 — the account still owes its organization) answers with
+ * the separate `TokenExchangeOrganizationOnboardingResponseSchema` instead (`{ nextStep, sessionId }`, no token).
+ * It is kept out of this schema on purpose: this one is strict and parsed by receivers that can never hold a
+ * parked code (the docs site redeems only handoff codes, which need a signed-in caller), so widening it would
+ * teach them a shape they must then refuse.
  *
  * Lives in this file (rather than `authentication.shared.dto.schemas.ts`)
  * because every receiver of an AUTH_CODE_EXCHANGE token — the SaaS app, the

package/dist/esm/security/authentications/cross-frontend-handoff.shared.dto.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"cross-frontend-handoff.shared.dto.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authentications/cross-frontend-handoff.shared.dto.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cross-Frontend Handoff DTO atoms (cross-app-jwt-propagation Step 2).\n *\n * Self-service endpoint contract that the source frontend's authenticated user\n * invokes to obtain a one-time AUTH_CODE_EXCHANGE token bound to a target\n * frontend service. The source frontend then redirects the browser to the\n * target frontend's `/auth/exchange` page, which POSTs to the existing\n * `/auth/token/exchange` endpoint to consume the code and receive a fresh\n * JWT pair.\n *\n * Built on the existing AUTH_CODE_EXCHANGE primitive (used by OAuth2 callback\n * today). Does NOT introduce a new consumable token type, a new exchange\n * endpoint, or any cookie-based transport — the contract is bearer-only and\n * piggybacks on the mature exchange + anonymous-transposition wiring.\n *\n * CORS posture: bearer-only. The endpoint reads `Authorization: Bearer …`\n * from the source frontend's session; receivers MUST NOT set\n * `withCredentials: true` on their fetch call. Every declared frontendService\n * is automatically allowed via the existing `deriveCorsOrigins()` seam.\n *\n * Why this file is split out of `authentication.shared.dto.schemas.ts`:\n *   - The parent file is 750+ lines, depends on `UserContextSchema`,\n *     `AvailableMethodSchema`, `SessionType`, `AuthMethod`, `AuthFactorLevel`,\n *     `AuthSessionPurpose`, `AuthUtils`, AND `@wildo-ai/zod-decorators`. Any\n *     browser bundle that touches a single symbol from it pays the full\n *     transitive cost (see `saas-models-public-runtime.md` K-1).\n *   - This file is intentionally minimal: ONLY `import { z } from 'zod'`. It\n *     can be safely re-exported from `@wildo-ai/saas-models/public-runtime`\n *     (saas-models-public-runtime.md K-4) without booting `initZodDecorators`\n *     or pulling `reflect-metadata`.\n *\n * DRY contract:\n *   - `authentication.shared.dto.schemas.ts` re-exports everything in this\n *     file via `export * from './cross-frontend-handoff.shared.dto.schemas'`\n *     so existing root-barrel imports\n *     (`import { CrossFrontendHandoffRequest } from '@wildo-ai/saas-models'`)\n *     keep working unchanged.\n *   - The atoms live ONLY in this file. Do NOT duplicate any declaration\n *     into the parent file — that would defeat the purpose of the split.\n *\n * Historical note — H-3 / M-7 cross-frontend-handoff incident:\n *   An earlier iteration of `engine/saas-technical-doc`'s\n *   `<AuthExchangePage>` shipped a silently-undefined\n *   `response.metadata?.returnPath` read that compiled cleanly even\n *   though `metadata` was not a key on the inferred response type. The\n *   bad read was caught by code review (M-7) and removed by reading the\n *   correct top-level `response.returnPath` instead. The cross-package\n *   `z.infer` types ARE tight when the decorator-framework runtime is\n *   booted on the consuming bundle (the docs runtime entry calls\n *   `ensureZodDecoratorsLoaded(z)` for that reason — see\n *   `engine/saas-technical-doc/src/runtime/index.ts`). The\n *   `expectTypeOf` pins in\n *   `__tests__/authentication.shared.dto.schemas.test.ts` (executed via\n *   Vitest's `typecheck.enabled` mode) defend against future regressions\n *   on the three public-runtime DTOs declared below.\n */\n\nimport { z } from 'zod';\n\nimport { isSameOriginRedirectPath } from './same-origin-redirect-path.shared';\n\n/**\n * Stable error codes for the cross-frontend handoff endpoint, returned as\n * `{ error: { code, message, context } }` with HTTP 400. Exported as a TS enum\n * so callers (notably the docs-site `docsAuthClient.ts`) can branch on the\n * code, not on the message.\n */\nexport enum CrossFrontendHandoffErrorCode {\n    /** The `targetServiceKey` is not a key in `appConfigService.config.frontendServices`. */\n    UNKNOWN_TARGET_FRONTEND = 'UNKNOWN_TARGET_FRONTEND',\n\n    /** The target service is declared but `runtime.endPoints[targetServiceKey].publicUrl` is missing for the current env. Fail-closed (no auto-derived guess). */\n    TARGET_FRONTEND_HOST_NOT_CONFIGURED = 'TARGET_FRONTEND_HOST_NOT_CONFIGURED',\n\n    /** The target service is declared, but its frontend runtime does not mount `/auth/exchange` and therefore cannot redeem a handoff code. */\n    TARGET_FRONTEND_AUTH_EXCHANGE_UNSUPPORTED = 'TARGET_FRONTEND_AUTH_EXCHANGE_UNSUPPORTED',\n}\n\n/**\n * Single source of truth for `returnPath` defense-in-depth refines.\n *\n * Two consumers apply this exact set of rules:\n *   - Issuer side (`CrossFrontendHandoff_ReturnPathSchema`): validates the\n *     request body of `POST /auth/cross-frontend-handoff`. Adds a `.default`\n *     + `.transform` to normalise empty strings to `'/'`.\n *   - Receiver side (`TokenExchangeResponseSchema.returnPath`): validates the\n *     response body of `POST /auth/token/exchange` so a corrupted /\n *     hand-tampered metadata round-trip cannot smuggle an\n *     open-redirect / path-traversal / XSS payload past the receiver schema.\n *     The schema is `.optional()` at the response level (OAuth2-callback\n *     codes don't carry a `returnPath` at all — see `TokenExchangeResponseSchema`\n *     JSDoc) so the refines only run when the field is present.\n *\n * Kept as a list (not as a single chained schema) so we can apply the\n * exact same checks to both an `optional` schema and a `default('').transform`\n * schema without duplicating the message strings. Drift between the two\n * sides would be a security regression — collapsing them onto one source\n * is the K-1 / \"framework mindset\" contract from `design-philosophy.mdc`.\n */\nconst RETURN_PATH_REFINES: ReadonlyArray<{ check: (value: string) => boolean; message: string }> = [\n    { check: (value) => value.length <= 256, message: 'returnPath exceeds 256 characters' },\n    { check: (value) => value.startsWith('/'), message: 'returnPath must start with \"/\"' },\n    /**\n     * Scheme-relative URL: `//evil.com` is interpreted by browsers as\n     * `https://evil.com` when handed to `location.assign` / `<Navigate to>`,\n     * despite passing the `startsWith('/')` check. Classic open-redirect\n     * vector — explicitly rejected here so we cannot silently regress.\n     */\n    { check: (value) => !value.startsWith('//'), message: 'returnPath must not start with \"//\" (scheme-relative URL — open-redirect vector)' },\n    /**\n     * The AUTHORITATIVE origin check, and the reason the character rules below are now\n     * defence-in-depth rather than the guarantee.\n     *\n     * Every rule in this list is a deny-list over BYTES; a browser navigates to what its URL PARSER\n     * produces. The two diverge because the parser strips ASCII tab / LF / CR from the input before\n     * parsing, so `/<TAB>/evil.com` becomes `//evil.com` and resolves cross-origin while satisfying\n     * `startsWith('/')`, `!startsWith('//')`, `!includes('\\\\')` and `!includes('://')` — i.e. every\n     * refine that was here before. Adding three more banned characters would only postpone the next\n     * parser rule, so the question is put to the parser itself.\n     *\n     * This refine is placed AFTER the cheap prefix rules deliberately: those produce a precise,\n     * actionable message for the two shapes an honest caller actually gets wrong, and this one is the\n     * catch-all that must never be reachable by an honest caller at all.\n     */\n    {\n        check: (value) => isSameOriginRedirectPath(value),\n        message: 'returnPath must resolve to a location on this application\\'s own origin',\n    },\n    { check: (value) => !value.includes('..'), message: 'returnPath must not contain \"..\" (path traversal)' },\n    { check: (value) => !value.includes('\\\\'), message: 'returnPath must not contain \"\\\\\" (Windows path injection)' },\n    { check: (value) => !value.includes('://'), message: 'returnPath must not contain \"://\" (absolute URL injection)' },\n    { check: (value) => !/[<>\"]/.test(value), message: 'returnPath must not contain \"<\", \">\", or \"\\\\\"\"' },\n];\n\n/**\n * Apply the shared `RETURN_PATH_REFINES` to any string-producing schema.\n *\n * Generic over the input schema type so the request side (which\n * pre-transforms `''` → `'/'`) and the response side (which keeps the\n * raw string verbatim) both keep their input-type fluency. The runtime\n * effect is identical: a `.refine()` chain in `RETURN_PATH_REFINES` order.\n */\nfunction applyReturnPathRefines<T extends z.ZodType<string>>(schema: T): T {\n    return RETURN_PATH_REFINES.reduce<T>(\n        (acc, { check, message }) => acc.refine(check, { message }) as unknown as T,\n        schema,\n    );\n}\n\n/**\n * Validates a `returnPath` for the cross-frontend handoff endpoint REQUEST body.\n *\n * Defense-in-depth at the schema boundary so direct API consumers cannot\n * bypass handler-level checks. The receiving frontend's `AuthExchangePage`\n * may call `location.assign(returnPath)` after exchanging the token; an\n * unvalidated path is an open-redirect / XSS / path-traversal vector.\n *\n * Rules: see `RETURN_PATH_REFINES` above (single source of truth — also\n * applied to `TokenExchangeResponseSchema.returnPath` so issuer and receiver\n * cannot drift). Additionally:\n * - Empty string is normalised to `'/'` (root) via the schema's `transform`.\n *   Refines run AFTER transform so the post-transform `'/'` is what gets\n *   validated — `''` → `'/'` → passes `startsWith('/')` → accepted.\n */\nconst CrossFrontendHandoff_ReturnPathSchema = applyReturnPathRefines(\n    z\n        .string()\n        .default('')\n        .transform((value) => (value === '' ? '/' : value)),\n);\n\n/**\n * Request body for `POST /auth/cross-frontend-handoff`.\n *\n * The caller is the user themselves, asking the backend \"issue me a one-time\n * code so I can hand my session to frontend X (with optional return path)\".\n *\n * Field semantics:\n * - `targetServiceKey` MUST be the per-service unique identity that\n *   `appConfigService.config.frontendServices` is keyed by AND that\n *   `runtime.endPoints[*]` is keyed by. **Today that identity is the\n *   `serviceName`** declared on `wildo.saas.config.ts → services.<key>.serviceName`\n *   (e.g. `'wonder-todos-docs'`, NOT the services map key `'docs'`):\n *   apps-manager's `buildManagedFrontendServicesSeed` keys\n *   `frontendServices` by `serviceName`, wildo-cli's\n *   `AppBootstrapService.buildRuntimeEndpoints` keys\n *   `APPLICATION_RUNTIME_ENDPOINTS` by `serviceName`, the\n *   `X-Frontend-Service-Name` header carries `serviceName` (via\n *   `VITE_FRONTEND_SERVICE_NAME`), and the K8s ingress builder keys\n *   per-frontend endpoints by `Object.keys(frontendServices)` — i.e.\n *   `serviceName` again. Passing the services map key (`'docs'`)\n *   instead would fail the handler's\n *   `frontendServices[body.targetServiceKey]` membership check\n *   with `UNKNOWN_TARGET_FRONTEND`. The name `targetServiceKey` is\n *   load-bearing only as \"the runtime identity an SDK consumer\n *   passes through\" — semantically it is a `frontendServiceName`.\n *   The eventual convergence on `services.<key>` as the single\n *   canonical identity is tracked under the cross-app / apps-manager\n *   workstream (a multi-PR migration touching apps-manager seeding,\n *   wildo-cli endpoint emission, the `VITE_FRONTEND_SERVICE_NAME`\n *   build-time injection, and every consumer of `lookupFrontendPublicUrl`).\n *   Renamed from the original `targetFrontendSlug` to lock the semantics\n *   in the schema, not just JSDoc — a wrong-typed body fails at parse time.\n * - `returnPath` is the path on the target frontend the user should land on\n *   AFTER the token exchange completes. Validated via\n *   `CrossFrontendHandoff_ReturnPathSchema`.\n *\n *   **Runtime vs type guarantee**: the schema applies\n *   `.default('').transform(empty → '/')` so at RUNTIME, by the time the\n *   parsed body reaches the handler, `returnPath` is always a non-empty\n *   string (defaulted to `'/'` if the caller omitted it or sent `''`).\n *   At the TYPE level, however, `z.infer<typeof CrossFrontendHandoffRequestSchema>`\n *   keeps `returnPath?: string` — TypeScript does not propagate the\n *   post-default tightening through the `.refine()` chain on a\n *   `ZodPipe<ZodDefault<…>, ZodTransform>`. Handler code therefore has\n *   two safe options:\n *     - treat `returnPath` as `string | undefined` and fall back to `'/'`\n *       defensively, OR\n *     - rely on the runtime invariant after parsing (the body NEVER reaches\n *       the handler unparsed; the controller validates it via\n *       `CrossFrontendHandoffRequestSchema.parse()` before dispatch).\n *\n *   The exported `CrossFrontendHandoffRequest` type is `z.infer` of the\n *   schema, so it matches the OUTPUT shape (with the optional-`returnPath`\n *   caveat above). For the WIRE shape (where every other field's optional\n *   semantics may differ), use `z.input<typeof CrossFrontendHandoffRequestSchema>`.\n */\nexport const CrossFrontendHandoffRequestSchema = z.strictObject({\n    targetServiceKey: z.string().min(1, 'targetServiceKey is required'),\n    returnPath: CrossFrontendHandoff_ReturnPathSchema,\n});\n\n/**\n * Output (parsed) shape of `POST /auth/cross-frontend-handoff`'s request body.\n *\n * Consumers that need the WIRE shape (where `returnPath` is `string | undefined`)\n * should use `z.input<typeof CrossFrontendHandoffRequestSchema>` instead.\n *\n * Cross-package safety: every consuming bundle MUST boot\n * `@wildo-ai/zod-decorators` once via `ensureZodDecoratorsLoaded(z)`\n * before reading `z.infer<typeof …>` on schemas exported from this file.\n * The SaaS app + backend get this for free via the saas-models root barrel\n * (which runs `initZodDecorators()` on load); the docs runtime does it\n * explicitly in `engine/saas-technical-doc/src/runtime/index.ts`. The\n * `expectTypeOf` pins in the schemas test file enforce that the inferred\n * shape stays tight; CI runs them via Vitest `typecheck.enabled` mode.\n */\nexport type CrossFrontendHandoffRequest = z.infer<typeof CrossFrontendHandoffRequestSchema>;\n\n/**\n * Response body for `POST /auth/cross-frontend-handoff`.\n *\n * Field semantics:\n * - `handoffUrl` — the URL the source frontend should redirect to:\n *   `https://<targetPublicHost>/auth/exchange?code=<token>&return=<percent-encoded-returnPath>`.\n *   Typed as `string` (not a branded URL type) because consumers immediately\n *   hand it to `location.assign()` / `<Link to>`, neither of which expects\n *   a branded type. The runtime validator enforces `z.url()` shape.\n * - `expiresAt` — ISO-8601 timestamp; the consumable token TTL is 60 seconds\n *   (shorter than OAuth2's 5 min — the user is mid-redirect, not waiting on\n *   a third-party IdP). The strict ISO refine catches a misbehaving server /\n *   fixture that emits a non-ISO string at parse time on the receiving end\n *   (the docs-chat client validates with this schema).\n */\nexport const CrossFrontendHandoffResponseSchema = z.strictObject({\n    handoffUrl: z.url(),\n    expiresAt: z.iso.datetime(),\n});\n\n/**\n * Inferred response shape — see `CrossFrontendHandoffRequest` JSDoc on the\n * cross-package `z.infer` safety contract.\n */\nexport type CrossFrontendHandoffResponse = z.infer<typeof CrossFrontendHandoffResponseSchema>;\n\n/**\n * Request body for `POST /auth/token/exchange`.\n *\n * Kept beside `TokenExchangeResponseSchema` because every consumer that can\n * receive an AUTH_CODE_EXCHANGE code must send this body. Do not let clients\n * hand-roll `{ code }` literals: the request side is part of the same public\n * runtime contract as the response and must drift in lockstep.\n */\nexport const TokenExchangeRequestSchema = z.strictObject({\n    code: z.string().min(1),\n});\n\n/**\n * Inferred request body for `POST /auth/token/exchange`.\n */\nexport type TokenExchangeRequest = z.infer<typeof TokenExchangeRequestSchema>;\n\n/**\n * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5).\n *\n * Lives in this file (rather than `authentication.shared.dto.schemas.ts`)\n * because every receiver of an AUTH_CODE_EXCHANGE token — the SaaS app, the\n * docs site — is by construction also a client-bundle target. Keeping the\n * response schema in the public-runtime-safe atom file lets those receivers\n * import the same source of truth via `@wildo-ai/saas-models/public-runtime`\n * without paying the `initZodDecorators()` boot cost\n * (saas-models-public-runtime.md K-1, K-4).\n *\n * Field semantics:\n * - `accessToken`, `expiresIn` — the freshly minted access-token response for\n *   the consuming frontend. The consumable token's metadata also carries the\n *   refresh token internally, but the exchange handler routes it to the\n *   HttpOnly cookie channel rather than the JSON body.\n * - `returnPath` — present only for handoff-issued codes (NOT OAuth2-callback\n *   codes); the path the receiving frontend should navigate to after the\n *   exchange completes. Refined with the same `RETURN_PATH_REFINES` as the\n *   issuer-side `CrossFrontendHandoff_ReturnPathSchema` (single source of\n *   truth — issuer and receiver cannot drift on which payloads are rejected).\n *   The optional+refines composition means: when absent, the field passes\n *   silently (OAuth2-callback path); when present, it MUST clear every\n *   refine, otherwise the receiver-side `.parse()` call in `tokenExchange()`\n *   throws and the response never goes out. That is intentional — a\n *   tampered metadata round-trip is a security event, not a degraded UX.\n * - `sourceFrontendServiceName`, `targetServiceKey` — present only for\n *   handoff-issued codes. Lets the receiver render telemetry / breadcrumbs\n *   (\"you came from the admin panel\") without round-tripping another API call.\n *\n * Why optional fields rather than a discriminated union: OAuth2-callback\n * codes go through the same exchange handler with the same metadata\n * skeleton minus the handoff-specific fields, so a discriminator would\n * require a synthetic `kind` field that adds no information. The optionality\n * IS the discriminator: presence of `returnPath` (or `sourceFrontendServiceName`)\n * tells the receiver \"this came from a cross-frontend handoff, treat it\n * accordingly\". This load-bearing invariant is enforced upstream by the\n * `tokenExchange()` controller, which mints the response object via\n * `if (typeof metadata.returnPath === 'string') response.returnPath = …`\n * (omit-when-absent). If a future regression starts emitting `null` or `''`\n * for OAuth2-callback codes, the receiver-side discrimination breaks\n * silently — the contract is documented here and pinned by the integration\n * test in `cross-frontend-handoff-token-exchange.integration.test.ts`.\n *\n * **H-3 history**: an early `<AuthExchangePage>` implementation read\n * `response.metadata?.returnPath` (always undefined — `metadata` is not\n * a key on the response). The bad read was caught by code review (M-7)\n * and replaced by reading the correct top-level `response.returnPath`.\n * Cross-package `z.infer<typeof TokenExchangeResponseSchema>` IS tight\n * (the same bad access today fires `TS2339: Property 'metadata' does\n * not exist`) provided the consuming bundle has booted\n * `@wildo-ai/zod-decorators` once via `ensureZodDecoratorsLoaded(z)` —\n * which the docs runtime entry does (`engine/saas-technical-doc/src/runtime/index.ts`)\n * and the SaaS app gets implicitly via the saas-models root barrel. The\n * `expectTypeOf` pins in the schemas test file enforce that the inferred\n * shape stays tight; CI runs them via Vitest `typecheck.enabled` mode.\n */\n/**\n * Token exchange response (cross-app-jwt-propagation Step 5 + OAuth2 callback).\n *\n * **Wire contract — refresh token is NEVER included** (Auth-hardening\n * Slice A Step 6, 2026-04-13). Pre-Slice-A this schema carried\n * `refreshToken: z.string()` which was emitted in the JSON body for\n * AUTH_CODE_EXCHANGE redemptions. The cookie migration (A-Step 2)\n * routed the refresh token to `Set-Cookie: __wildo_refresh=…`;\n * A-Step 6 removes the body field entirely. The receiving frontend\n * (SaaS app via `saas-frontend-lib`, or docs site via `docsAuthClient`)\n * stores the access token in memory; the SaaS app additionally\n * receives the refresh cookie automatically (same-origin browser\n * default), while the docs site has no refresh loop and re-handshakes\n * on next gated navigation when the access token expires.\n *\n * The strict-object shape pins the H-3 invariant: `returnPath` lives at\n * the TOP LEVEL — there is intentionally NO `metadata` envelope. Adding\n * an unknown key would now ALSO fire because `refreshToken` is removed\n * (a server still emitting `refreshToken` would fail strict-parse on\n * the receiver — surfacing the misalignment loudly rather than letting\n * the field silently leak through).\n */\nexport const TokenExchangeResponseSchema = z.strictObject({\n    accessToken: z.string(),\n    expiresIn: z.number(),\n    returnPath: applyReturnPathRefines(z.string()).optional(),\n    sourceFrontendServiceName: z.string().optional(),\n    targetServiceKey: z.string().optional(),\n});\n\n/**\n * Inferred response shape — see `TokenExchangeResponseSchema` JSDoc on\n * the cross-package `z.infer` safety contract (post-H-3 fix).\n */\nexport type TokenExchangeResponse = z.infer<typeof TokenExchangeResponseSchema>;\n"]}
+{"version":3,"file":"cross-frontend-handoff.shared.dto.schemas.js","sourceRoot":"","sources":["../../../../../src/security/authentications/cross-frontend-handoff.shared.dto.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cross-Frontend Handoff DTO atoms (cross-app-jwt-propagation Step 2).\n *\n * Self-service endpoint contract that the source frontend's authenticated user\n * invokes to obtain a one-time AUTH_CODE_EXCHANGE token bound to a target\n * frontend service. The source frontend then redirects the browser to the\n * target frontend's `/auth/exchange` page, which POSTs to the existing\n * `/auth/token/exchange` endpoint to consume the code and receive a fresh\n * JWT pair.\n *\n * Built on the existing AUTH_CODE_EXCHANGE primitive (used by OAuth2 callback\n * today). Does NOT introduce a new consumable token type, a new exchange\n * endpoint, or any cookie-based transport — the contract is bearer-only and\n * piggybacks on the mature exchange + anonymous-transposition wiring.\n *\n * CORS posture: bearer-only. The endpoint reads `Authorization: Bearer …`\n * from the source frontend's session; receivers MUST NOT set\n * `withCredentials: true` on their fetch call. Every declared frontendService\n * is automatically allowed via the existing `deriveCorsOrigins()` seam.\n *\n * Why this file is split out of `authentication.shared.dto.schemas.ts`:\n *   - The parent file is 750+ lines, depends on `UserContextSchema`,\n *     `AvailableMethodSchema`, `SessionType`, `AuthMethod`, `AuthFactorLevel`,\n *     `AuthSessionPurpose`, `AuthUtils`, AND `@wildo-ai/zod-decorators`. Any\n *     browser bundle that touches a single symbol from it pays the full\n *     transitive cost (see `saas-models-public-runtime.md` K-1).\n *   - This file is intentionally minimal: ONLY `import { z } from 'zod'`. It\n *     can be safely re-exported from `@wildo-ai/saas-models/public-runtime`\n *     (saas-models-public-runtime.md K-4) without booting `initZodDecorators`\n *     or pulling `reflect-metadata`.\n *\n * DRY contract:\n *   - `authentication.shared.dto.schemas.ts` re-exports everything in this\n *     file via `export * from './cross-frontend-handoff.shared.dto.schemas'`\n *     so existing root-barrel imports\n *     (`import { CrossFrontendHandoffRequest } from '@wildo-ai/saas-models'`)\n *     keep working unchanged.\n *   - The atoms live ONLY in this file. Do NOT duplicate any declaration\n *     into the parent file — that would defeat the purpose of the split.\n *\n * Historical note — H-3 / M-7 cross-frontend-handoff incident:\n *   An earlier iteration of `engine/saas-technical-doc`'s\n *   `<AuthExchangePage>` shipped a silently-undefined\n *   `response.metadata?.returnPath` read that compiled cleanly even\n *   though `metadata` was not a key on the inferred response type. The\n *   bad read was caught by code review (M-7) and removed by reading the\n *   correct top-level `response.returnPath` instead. The cross-package\n *   `z.infer` types ARE tight when the decorator-framework runtime is\n *   booted on the consuming bundle (the docs runtime entry calls\n *   `ensureZodDecoratorsLoaded(z)` for that reason — see\n *   `engine/saas-technical-doc/src/runtime/index.ts`). The\n *   `expectTypeOf` pins in\n *   `__tests__/authentication.shared.dto.schemas.test.ts` (executed via\n *   Vitest's `typecheck.enabled` mode) defend against future regressions\n *   on the three public-runtime DTOs declared below.\n */\n\nimport { z } from 'zod';\n\nimport { isSameOriginRedirectPath } from './same-origin-redirect-path.shared';\n\n/**\n * Stable error codes for the cross-frontend handoff endpoint, returned as\n * `{ error: { code, message, context } }` with HTTP 400. Exported as a TS enum\n * so callers (notably the docs-site `docsAuthClient.ts`) can branch on the\n * code, not on the message.\n */\nexport enum CrossFrontendHandoffErrorCode {\n    /** The `targetServiceKey` is not a key in `appConfigService.config.frontendServices`. */\n    UNKNOWN_TARGET_FRONTEND = 'UNKNOWN_TARGET_FRONTEND',\n\n    /** The target service is declared but `runtime.endPoints[targetServiceKey].publicUrl` is missing for the current env. Fail-closed (no auto-derived guess). */\n    TARGET_FRONTEND_HOST_NOT_CONFIGURED = 'TARGET_FRONTEND_HOST_NOT_CONFIGURED',\n\n    /** The target service is declared, but its frontend runtime does not mount `/auth/exchange` and therefore cannot redeem a handoff code. */\n    TARGET_FRONTEND_AUTH_EXCHANGE_UNSUPPORTED = 'TARGET_FRONTEND_AUTH_EXCHANGE_UNSUPPORTED',\n}\n\n/**\n * Single source of truth for `returnPath` defense-in-depth refines.\n *\n * Two consumers apply this exact set of rules:\n *   - Issuer side (`CrossFrontendHandoff_ReturnPathSchema`): validates the\n *     request body of `POST /auth/cross-frontend-handoff`. Adds a `.default`\n *     + `.transform` to normalise empty strings to `'/'`.\n *   - Receiver side (`TokenExchangeResponseSchema.returnPath`): validates the\n *     response body of `POST /auth/token/exchange` so a corrupted /\n *     hand-tampered metadata round-trip cannot smuggle an\n *     open-redirect / path-traversal / XSS payload past the receiver schema.\n *     The schema is `.optional()` at the response level (OAuth2-callback\n *     codes don't carry a `returnPath` at all — see `TokenExchangeResponseSchema`\n *     JSDoc) so the refines only run when the field is present.\n *\n * Kept as a list (not as a single chained schema) so we can apply the\n * exact same checks to both an `optional` schema and a `default('').transform`\n * schema without duplicating the message strings. Drift between the two\n * sides would be a security regression — collapsing them onto one source\n * is the K-1 / \"framework mindset\" contract from `design-philosophy.mdc`.\n */\nconst RETURN_PATH_REFINES: ReadonlyArray<{ check: (value: string) => boolean; message: string }> = [\n    { check: (value) => value.length <= 256, message: 'returnPath exceeds 256 characters' },\n    { check: (value) => value.startsWith('/'), message: 'returnPath must start with \"/\"' },\n    /**\n     * Scheme-relative URL: `//evil.com` is interpreted by browsers as\n     * `https://evil.com` when handed to `location.assign` / `<Navigate to>`,\n     * despite passing the `startsWith('/')` check. Classic open-redirect\n     * vector — explicitly rejected here so we cannot silently regress.\n     */\n    { check: (value) => !value.startsWith('//'), message: 'returnPath must not start with \"//\" (scheme-relative URL — open-redirect vector)' },\n    /**\n     * The AUTHORITATIVE origin check, and the reason the character rules below are now\n     * defence-in-depth rather than the guarantee.\n     *\n     * Every rule in this list is a deny-list over BYTES; a browser navigates to what its URL PARSER\n     * produces. The two diverge because the parser strips ASCII tab / LF / CR from the input before\n     * parsing, so `/<TAB>/evil.com` becomes `//evil.com` and resolves cross-origin while satisfying\n     * `startsWith('/')`, `!startsWith('//')`, `!includes('\\\\')` and `!includes('://')` — i.e. every\n     * refine that was here before. Adding three more banned characters would only postpone the next\n     * parser rule, so the question is put to the parser itself.\n     *\n     * This refine is placed AFTER the cheap prefix rules deliberately: those produce a precise,\n     * actionable message for the two shapes an honest caller actually gets wrong, and this one is the\n     * catch-all that must never be reachable by an honest caller at all.\n     */\n    {\n        check: (value) => isSameOriginRedirectPath(value),\n        message: 'returnPath must resolve to a location on this application\\'s own origin',\n    },\n    { check: (value) => !value.includes('..'), message: 'returnPath must not contain \"..\" (path traversal)' },\n    { check: (value) => !value.includes('\\\\'), message: 'returnPath must not contain \"\\\\\" (Windows path injection)' },\n    { check: (value) => !value.includes('://'), message: 'returnPath must not contain \"://\" (absolute URL injection)' },\n    { check: (value) => !/[<>\"]/.test(value), message: 'returnPath must not contain \"<\", \">\", or \"\\\\\"\"' },\n];\n\n/**\n * Apply the shared `RETURN_PATH_REFINES` to any string-producing schema.\n *\n * Generic over the input schema type so the request side (which\n * pre-transforms `''` → `'/'`) and the response side (which keeps the\n * raw string verbatim) both keep their input-type fluency. The runtime\n * effect is identical: a `.refine()` chain in `RETURN_PATH_REFINES` order.\n */\nfunction applyReturnPathRefines<T extends z.ZodType<string>>(schema: T): T {\n    return RETURN_PATH_REFINES.reduce<T>(\n        (acc, { check, message }) => acc.refine(check, { message }) as unknown as T,\n        schema,\n    );\n}\n\n/**\n * Validates a `returnPath` for the cross-frontend handoff endpoint REQUEST body.\n *\n * Defense-in-depth at the schema boundary so direct API consumers cannot\n * bypass handler-level checks. The receiving frontend's `AuthExchangePage`\n * may call `location.assign(returnPath)` after exchanging the token; an\n * unvalidated path is an open-redirect / XSS / path-traversal vector.\n *\n * Rules: see `RETURN_PATH_REFINES` above (single source of truth — also\n * applied to `TokenExchangeResponseSchema.returnPath` so issuer and receiver\n * cannot drift). Additionally:\n * - Empty string is normalised to `'/'` (root) via the schema's `transform`.\n *   Refines run AFTER transform so the post-transform `'/'` is what gets\n *   validated — `''` → `'/'` → passes `startsWith('/')` → accepted.\n */\nconst CrossFrontendHandoff_ReturnPathSchema = applyReturnPathRefines(\n    z\n        .string()\n        .default('')\n        .transform((value) => (value === '' ? '/' : value)),\n);\n\n/**\n * Request body for `POST /auth/cross-frontend-handoff`.\n *\n * The caller is the user themselves, asking the backend \"issue me a one-time\n * code so I can hand my session to frontend X (with optional return path)\".\n *\n * Field semantics:\n * - `targetServiceKey` MUST be the per-service unique identity that\n *   `appConfigService.config.frontendServices` is keyed by AND that\n *   `runtime.endPoints[*]` is keyed by. **Today that identity is the\n *   `serviceName`** declared on `wildo.saas.config.ts → services.<key>.serviceName`\n *   (e.g. `'wonder-todos-docs'`, NOT the services map key `'docs'`):\n *   apps-manager's `buildManagedFrontendServicesSeed` keys\n *   `frontendServices` by `serviceName`, wildo-cli's\n *   `AppBootstrapService.buildRuntimeEndpoints` keys\n *   `APPLICATION_RUNTIME_ENDPOINTS` by `serviceName`, the\n *   `X-Frontend-Service-Name` header carries `serviceName` (via\n *   `VITE_FRONTEND_SERVICE_NAME`), and the K8s ingress builder keys\n *   per-frontend endpoints by `Object.keys(frontendServices)` — i.e.\n *   `serviceName` again. Passing the services map key (`'docs'`)\n *   instead would fail the handler's\n *   `frontendServices[body.targetServiceKey]` membership check\n *   with `UNKNOWN_TARGET_FRONTEND`. The name `targetServiceKey` is\n *   load-bearing only as \"the runtime identity an SDK consumer\n *   passes through\" — semantically it is a `frontendServiceName`.\n *   The eventual convergence on `services.<key>` as the single\n *   canonical identity is tracked under the cross-app / apps-manager\n *   workstream (a multi-PR migration touching apps-manager seeding,\n *   wildo-cli endpoint emission, the `VITE_FRONTEND_SERVICE_NAME`\n *   build-time injection, and every consumer of `lookupFrontendPublicUrl`).\n *   Renamed from the original `targetFrontendSlug` to lock the semantics\n *   in the schema, not just JSDoc — a wrong-typed body fails at parse time.\n * - `returnPath` is the path on the target frontend the user should land on\n *   AFTER the token exchange completes. Validated via\n *   `CrossFrontendHandoff_ReturnPathSchema`.\n *\n *   **Runtime vs type guarantee**: the schema applies\n *   `.default('').transform(empty → '/')` so at RUNTIME, by the time the\n *   parsed body reaches the handler, `returnPath` is always a non-empty\n *   string (defaulted to `'/'` if the caller omitted it or sent `''`).\n *   At the TYPE level, however, `z.infer<typeof CrossFrontendHandoffRequestSchema>`\n *   keeps `returnPath?: string` — TypeScript does not propagate the\n *   post-default tightening through the `.refine()` chain on a\n *   `ZodPipe<ZodDefault<…>, ZodTransform>`. Handler code therefore has\n *   two safe options:\n *     - treat `returnPath` as `string | undefined` and fall back to `'/'`\n *       defensively, OR\n *     - rely on the runtime invariant after parsing (the body NEVER reaches\n *       the handler unparsed; the controller validates it via\n *       `CrossFrontendHandoffRequestSchema.parse()` before dispatch).\n *\n *   The exported `CrossFrontendHandoffRequest` type is `z.infer` of the\n *   schema, so it matches the OUTPUT shape (with the optional-`returnPath`\n *   caveat above). For the WIRE shape (where every other field's optional\n *   semantics may differ), use `z.input<typeof CrossFrontendHandoffRequestSchema>`.\n */\nexport const CrossFrontendHandoffRequestSchema = z.strictObject({\n    targetServiceKey: z.string().min(1, 'targetServiceKey is required'),\n    returnPath: CrossFrontendHandoff_ReturnPathSchema,\n});\n\n/**\n * Output (parsed) shape of `POST /auth/cross-frontend-handoff`'s request body.\n *\n * Consumers that need the WIRE shape (where `returnPath` is `string | undefined`)\n * should use `z.input<typeof CrossFrontendHandoffRequestSchema>` instead.\n *\n * Cross-package safety: every consuming bundle MUST boot\n * `@wildo-ai/zod-decorators` once via `ensureZodDecoratorsLoaded(z)`\n * before reading `z.infer<typeof …>` on schemas exported from this file.\n * The SaaS app + backend get this for free via the saas-models root barrel\n * (which runs `initZodDecorators()` on load); the docs runtime does it\n * explicitly in `engine/saas-technical-doc/src/runtime/index.ts`. The\n * `expectTypeOf` pins in the schemas test file enforce that the inferred\n * shape stays tight; CI runs them via Vitest `typecheck.enabled` mode.\n */\nexport type CrossFrontendHandoffRequest = z.infer<typeof CrossFrontendHandoffRequestSchema>;\n\n/**\n * Response body for `POST /auth/cross-frontend-handoff`.\n *\n * Field semantics:\n * - `handoffUrl` — the URL the source frontend should redirect to:\n *   `https://<targetPublicHost>/auth/exchange?code=<token>&return=<percent-encoded-returnPath>`.\n *   Typed as `string` (not a branded URL type) because consumers immediately\n *   hand it to `location.assign()` / `<Link to>`, neither of which expects\n *   a branded type. The runtime validator enforces `z.url()` shape.\n * - `expiresAt` — ISO-8601 timestamp; the consumable token TTL is 60 seconds\n *   (shorter than OAuth2's 5 min — the user is mid-redirect, not waiting on\n *   a third-party IdP). The strict ISO refine catches a misbehaving server /\n *   fixture that emits a non-ISO string at parse time on the receiving end\n *   (the docs-chat client validates with this schema).\n */\nexport const CrossFrontendHandoffResponseSchema = z.strictObject({\n    handoffUrl: z.url(),\n    expiresAt: z.iso.datetime(),\n});\n\n/**\n * Inferred response shape — see `CrossFrontendHandoffRequest` JSDoc on the\n * cross-package `z.infer` safety contract.\n */\nexport type CrossFrontendHandoffResponse = z.infer<typeof CrossFrontendHandoffResponseSchema>;\n\n/**\n * Request body for `POST /auth/token/exchange`.\n *\n * Kept beside `TokenExchangeResponseSchema` because every consumer that can\n * receive an AUTH_CODE_EXCHANGE code must send this body. Do not let clients\n * hand-roll `{ code }` literals: the request side is part of the same public\n * runtime contract as the response and must drift in lockstep.\n */\nexport const TokenExchangeRequestSchema = z.strictObject({\n    code: z.string().min(1),\n});\n\n/**\n * Inferred request body for `POST /auth/token/exchange`.\n */\nexport type TokenExchangeRequest = z.infer<typeof TokenExchangeRequestSchema>;\n\n/**\n * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5) when the code signs in.\n *\n * A code a federated sign-in was PARKED behind (#1103 — the account still owes its organization) answers with\n * the separate `TokenExchangeOrganizationOnboardingResponseSchema` instead (`{ nextStep, sessionId }`, no token).\n * It is kept out of this schema on purpose: this one is strict and parsed by receivers that can never hold a\n * parked code (the docs site redeems only handoff codes, which need a signed-in caller), so widening it would\n * teach them a shape they must then refuse.\n *\n * Lives in this file (rather than `authentication.shared.dto.schemas.ts`)\n * because every receiver of an AUTH_CODE_EXCHANGE token — the SaaS app, the\n * docs site — is by construction also a client-bundle target. Keeping the\n * response schema in the public-runtime-safe atom file lets those receivers\n * import the same source of truth via `@wildo-ai/saas-models/public-runtime`\n * without paying the `initZodDecorators()` boot cost\n * (saas-models-public-runtime.md K-1, K-4).\n *\n * Field semantics:\n * - `accessToken`, `expiresIn` — the freshly minted access-token response for\n *   the consuming frontend. The consumable token's metadata also carries the\n *   refresh token internally, but the exchange handler routes it to the\n *   HttpOnly cookie channel rather than the JSON body.\n * - `returnPath` — present only for handoff-issued codes (NOT OAuth2-callback\n *   codes); the path the receiving frontend should navigate to after the\n *   exchange completes. Refined with the same `RETURN_PATH_REFINES` as the\n *   issuer-side `CrossFrontendHandoff_ReturnPathSchema` (single source of\n *   truth — issuer and receiver cannot drift on which payloads are rejected).\n *   The optional+refines composition means: when absent, the field passes\n *   silently (OAuth2-callback path); when present, it MUST clear every\n *   refine, otherwise the receiver-side `.parse()` call in `tokenExchange()`\n *   throws and the response never goes out. That is intentional — a\n *   tampered metadata round-trip is a security event, not a degraded UX.\n * - `sourceFrontendServiceName`, `targetServiceKey` — present only for\n *   handoff-issued codes. Lets the receiver render telemetry / breadcrumbs\n *   (\"you came from the admin panel\") without round-tripping another API call.\n *\n * Why optional fields rather than a discriminated union: OAuth2-callback\n * codes go through the same exchange handler with the same metadata\n * skeleton minus the handoff-specific fields, so a discriminator would\n * require a synthetic `kind` field that adds no information. The optionality\n * IS the discriminator: presence of `returnPath` (or `sourceFrontendServiceName`)\n * tells the receiver \"this came from a cross-frontend handoff, treat it\n * accordingly\". This load-bearing invariant is enforced upstream by the\n * `tokenExchange()` controller, which mints the response object via\n * `if (typeof metadata.returnPath === 'string') response.returnPath = …`\n * (omit-when-absent). If a future regression starts emitting `null` or `''`\n * for OAuth2-callback codes, the receiver-side discrimination breaks\n * silently — the contract is documented here and pinned by the integration\n * test in `cross-frontend-handoff-token-exchange.integration.test.ts`.\n *\n * **H-3 history**: an early `<AuthExchangePage>` implementation read\n * `response.metadata?.returnPath` (always undefined — `metadata` is not\n * a key on the response). The bad read was caught by code review (M-7)\n * and replaced by reading the correct top-level `response.returnPath`.\n * Cross-package `z.infer<typeof TokenExchangeResponseSchema>` IS tight\n * (the same bad access today fires `TS2339: Property 'metadata' does\n * not exist`) provided the consuming bundle has booted\n * `@wildo-ai/zod-decorators` once via `ensureZodDecoratorsLoaded(z)` —\n * which the docs runtime entry does (`engine/saas-technical-doc/src/runtime/index.ts`)\n * and the SaaS app gets implicitly via the saas-models root barrel. The\n * `expectTypeOf` pins in the schemas test file enforce that the inferred\n * shape stays tight; CI runs them via Vitest `typecheck.enabled` mode.\n */\n/**\n * Token exchange response (cross-app-jwt-propagation Step 5 + OAuth2 callback).\n *\n * **Wire contract — refresh token is NEVER included** (Auth-hardening\n * Slice A Step 6, 2026-04-13). Pre-Slice-A this schema carried\n * `refreshToken: z.string()` which was emitted in the JSON body for\n * AUTH_CODE_EXCHANGE redemptions. The cookie migration (A-Step 2)\n * routed the refresh token to `Set-Cookie: __wildo_refresh=…`;\n * A-Step 6 removes the body field entirely. The receiving frontend\n * (SaaS app via `saas-frontend-lib`, or docs site via `docsAuthClient`)\n * stores the access token in memory; the SaaS app additionally\n * receives the refresh cookie automatically (same-origin browser\n * default), while the docs site has no refresh loop and re-handshakes\n * on next gated navigation when the access token expires.\n *\n * The strict-object shape pins the H-3 invariant: `returnPath` lives at\n * the TOP LEVEL — there is intentionally NO `metadata` envelope. Adding\n * an unknown key would now ALSO fire because `refreshToken` is removed\n * (a server still emitting `refreshToken` would fail strict-parse on\n * the receiver — surfacing the misalignment loudly rather than letting\n * the field silently leak through).\n */\nexport const TokenExchangeResponseSchema = z.strictObject({\n    accessToken: z.string(),\n    expiresIn: z.number(),\n    returnPath: applyReturnPathRefines(z.string()).optional(),\n    sourceFrontendServiceName: z.string().optional(),\n    targetServiceKey: z.string().optional(),\n});\n\n/**\n * Inferred response shape — see `TokenExchangeResponseSchema` JSDoc on\n * the cross-package `z.infer` safety contract (post-H-3 fix).\n */\nexport type TokenExchangeResponse = z.infer<typeof TokenExchangeResponseSchema>;\n"]}

package/dist/esm/security/authentications/password-blocklist.shared.utils.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The passwords a verifier must refuse, and the rule that REPLACED composition rules.
+ *
+ * > "When processing a request to establish or change a password, verifiers SHALL compare the
+ * > prospective secret against a blocklist that contains known commonly used, expected, or
+ * > compromised passwords. The entire password SHALL be subject to comparison, not substrings or
+ * > words that might be contained therein."
+ *
+ * spec-cite: NIST SP 800-63B-4 §3.1.1.2 "Password Verifiers"
+ * (https://pages.nist.gov/800-63-4/sp800-63b.html).
+ *
+ * That same section is where Wildo's composition rules went: "Verifiers and CSPs SHALL NOT impose
+ * other composition rules (e.g., requiring mixtures of different character types) for passwords."
+ * So this list is not an extra check bolted onto the old policy — it is the check the standard asks
+ * for INSTEAD of the ones that were removed, and without it the policy would have lost a rule and
+ * gained nothing.
+ *
+ * ## Why the list is SMALL, deliberately
+ *
+ * The standard says so in the same paragraph: "Excessively large blocklists are of little
+ * incremental security benefit because the blocklist is used to defend against online attacks, which
+ * are already limited by the throttling requirements described in Sec. 3.2.2."
+ * spec-cite: NIST SP 800-63B-4 §3.1.1.2 (https://pages.nist.gov/800-63-4/sp800-63b.html).
+ * Wildo's lockout policy IS that throttling. So this list only has to cover what an attacker reaches BEFORE the
+ * throttle bites — a few hundred guesses, not a breach corpus.
+ *
+ * ## Why it is bundled rather than fetched
+ *
+ * A k-anonymity range query to a third-party breach API sends a hash prefix off the machine every
+ * time anybody sets a password. That is an outbound dependency on the sign-up path: it fails when
+ * the third party does, and it is a privacy fact a generated application would owe its own users.
+ * A bundled list costs nothing at runtime, works offline, and the standard explicitly says size is
+ * not where the security comes from. An application wanting a corpus check can add one; the
+ * framework's floor does not rest on somebody else's uptime.
+ *
+ * ## The two CONTEXTUAL guesses matter more than the list
+ *
+ * Appendix A.3 names them: "specific words (e.g., the name of the service itself) that users are
+ * likely to choose". The application's own name and the local part of the user's own address are the
+ * first two things an attacker tries and the two no static list can hold, because they differ per
+ * application and per person.
+ *
+ * ## Comparison is WHOLE-STRING
+ *
+ * Case-folded and trimmed, and nothing else. Substring matching is refused by the sentence quoted
+ * above, and it is also what makes a blocklist infuriating: rejecting everything CONTAINING "admin"
+ * refuses `administrative-quandary-seven` for no reason. It is why `correct horse battery staple`
+ * is ACCEPTED while `correcthorsebatterystaple` is refused — the spaced form is a different string,
+ * and only the closed-up form is a famous enough guess to be worth refusing.
+ *
+ * assurance-control: WILDO.IDENTITY.CREDENTIAL_LIFECYCLE — a password an attacker would reach before
+ * the throttle does is refused at the moment it is set.
+ */
+/**
+ * What an attacker guesses about THIS application and THIS person, which no static list can hold.
+ *
+ * `appName` is the service's own name and `email` contributes its local part. Both are also compared
+ * with separators squashed out, because `Wonder Todos` and `wondertodos` are one guess.
+ */
+export interface PasswordBlocklistContext {
+    readonly appName?: string;
+    readonly email?: string;
+}
+/**
+ * Is this password one an attacker reaches before the throttle does?
+ *
+ * Whole-string comparison against the bundled list and the two contextual guesses. An empty
+ * candidate answers `false`: an empty password is the length rule's business, and answering `true`
+ * here would report the wrong reason for it.
+ */
+export declare function isPasswordBlocklisted(password: string, context?: PasswordBlocklistContext): boolean;
+/** The bundled entry count, for tests that assert the list has not been emptied by a bad edit. */
+export declare const COMMON_PASSWORD_BLOCKLIST_SIZE: number;
+//# sourceMappingURL=password-blocklist.shared.utils.d.ts.map

package/dist/esm/security/authentications/password-blocklist.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-blocklist.shared.utils.d.ts","sourceRoot":"","sources":["../../../../../src/security/authentications/password-blocklist.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAuCH;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAiBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAKnG;AAED,kGAAkG;AAClG,eAAO,MAAM,8BAA8B,EAAE,MAAiC,CAAC"}

package/dist/esm/security/authentications/password-blocklist.shared.utils.js

@@ -0,0 +1,122 @@
+/**
+ * The passwords a verifier must refuse, and the rule that REPLACED composition rules.
+ *
+ * > "When processing a request to establish or change a password, verifiers SHALL compare the
+ * > prospective secret against a blocklist that contains known commonly used, expected, or
+ * > compromised passwords. The entire password SHALL be subject to comparison, not substrings or
+ * > words that might be contained therein."
+ *
+ * spec-cite: NIST SP 800-63B-4 §3.1.1.2 "Password Verifiers"
+ * (https://pages.nist.gov/800-63-4/sp800-63b.html).
+ *
+ * That same section is where Wildo's composition rules went: "Verifiers and CSPs SHALL NOT impose
+ * other composition rules (e.g., requiring mixtures of different character types) for passwords."
+ * So this list is not an extra check bolted onto the old policy — it is the check the standard asks
+ * for INSTEAD of the ones that were removed, and without it the policy would have lost a rule and
+ * gained nothing.
+ *
+ * ## Why the list is SMALL, deliberately
+ *
+ * The standard says so in the same paragraph: "Excessively large blocklists are of little
+ * incremental security benefit because the blocklist is used to defend against online attacks, which
+ * are already limited by the throttling requirements described in Sec. 3.2.2."
+ * spec-cite: NIST SP 800-63B-4 §3.1.1.2 (https://pages.nist.gov/800-63-4/sp800-63b.html).
+ * Wildo's lockout policy IS that throttling. So this list only has to cover what an attacker reaches BEFORE the
+ * throttle bites — a few hundred guesses, not a breach corpus.
+ *
+ * ## Why it is bundled rather than fetched
+ *
+ * A k-anonymity range query to a third-party breach API sends a hash prefix off the machine every
+ * time anybody sets a password. That is an outbound dependency on the sign-up path: it fails when
+ * the third party does, and it is a privacy fact a generated application would owe its own users.
+ * A bundled list costs nothing at runtime, works offline, and the standard explicitly says size is
+ * not where the security comes from. An application wanting a corpus check can add one; the
+ * framework's floor does not rest on somebody else's uptime.
+ *
+ * ## The two CONTEXTUAL guesses matter more than the list
+ *
+ * Appendix A.3 names them: "specific words (e.g., the name of the service itself) that users are
+ * likely to choose". The application's own name and the local part of the user's own address are the
+ * first two things an attacker tries and the two no static list can hold, because they differ per
+ * application and per person.
+ *
+ * ## Comparison is WHOLE-STRING
+ *
+ * Case-folded and trimmed, and nothing else. Substring matching is refused by the sentence quoted
+ * above, and it is also what makes a blocklist infuriating: rejecting everything CONTAINING "admin"
+ * refuses `administrative-quandary-seven` for no reason. It is why `correct horse battery staple`
+ * is ACCEPTED while `correcthorsebatterystaple` is refused — the spaced form is a different string,
+ * and only the closed-up form is a famous enough guess to be worth refusing.
+ *
+ * assurance-control: WILDO.IDENTITY.CREDENTIAL_LIFECYCLE — a password an attacker would reach before
+ * the throttle does is refused at the moment it is set.
+ */
+/**
+ * The passwords attackers try first, ordered roughly by observed frequency in public breach
+ * analyses. The order carries no meaning at runtime — membership is a set lookup — and it is kept as
+ * a readable array rather than a generated artifact so that a reader wondering "is mine in here?"
+ * can answer it by looking.
+ */
+const COMMON_PASSWORDS = [
+    '123456', '123456789', '12345678', '1234567890', '1234567', '12345', '123123', '111111', '000000',
+    '654321', '666666', '888888', '121212', '112233', '159753', '987654321', '123321', '1234',
+    'password', 'password1', 'password123', 'passw0rd', 'p@ssw0rd', 'p@ssword', 'pass', 'passwd',
+    'password12', 'password1234', 'passw0rd1', 'secret', 'secret123',
+    'qwerty', 'qwerty123', 'qwerty1234', 'qwertyuiop', 'qwe123', '1q2w3e4r', '1q2w3e4r5t', 'asdfgh',
+    'asdfghjkl', 'zxcvbnm', 'azerty', 'qazwsx', 'qwertz', 'asdf', 'asdf1234',
+    'iloveyou', 'iloveyou1', 'princess', 'sunshine', 'monkey', 'dragon', 'football', 'baseball',
+    'superman', 'batman', 'starwars', 'master', 'shadow', 'hunter', 'trustno1', 'trustnoone',
+    'freedom', 'whatever', 'letmein', 'letmein123', 'welcome', 'welcome1', 'welcome123',
+    'login', 'admin', 'admin123', 'admin1234', 'administrator', 'root', 'root123', 'guest',
+    'test', 'test123', 'demo', 'user', 'default', 'changeme', 'changeme123', 'access',
+    'abc123', 'abcd1234', 'a1b2c3', 'aaaaaa', 'temp', 'temporary',
+    'summer', 'winter', 'spring', 'autumn', 'january', 'december',
+    'chocolate', 'liverpool', 'arsenal', 'chelsea', 'barcelona', 'juventus',
+    'computer', 'internet', 'samsung', 'google', 'facebook', 'linkedin',
+    'ninja', 'cheese', 'pepper', 'ginger', 'cookie', 'flower', 'purple', 'orange', 'silver',
+    'loveme', 'lovely', 'family', 'friends', 'forever', 'nothing', 'anything',
+    'soccer', 'hockey', 'killer', 'michael', 'jennifer', 'jordan', 'george', 'charlie', 'thomas',
+    'robert', 'daniel', 'andrew', 'matthew', 'joshua', 'anthony', 'william', 'nicole', 'ashley',
+    'amanda', 'jessica', 'samantha',
+    'correcthorsebatterystaple',
+];
+const COMMON_PASSWORD_SET = new Set(COMMON_PASSWORDS);
+/** Case-folded and trimmed. Nothing else — the comparison is whole-string, per §3.1.1.2. */
+function normalizeCandidate(candidate) {
+    return candidate.trim().toLowerCase();
+}
+function contextualGuesses(context) {
+    const guesses = new Set();
+    const add = (value) => {
+        if (!value)
+            return;
+        const normalized = normalizeCandidate(value);
+        if (normalized.length === 0)
+            return;
+        guesses.add(normalized);
+        const squashed = normalized.replace(/[\s._-]+/g, '');
+        if (squashed.length > 0)
+            guesses.add(squashed);
+    };
+    add(context?.appName);
+    add(context?.email?.split('@')[0]);
+    return guesses;
+}
+/**
+ * Is this password one an attacker reaches before the throttle does?
+ *
+ * Whole-string comparison against the bundled list and the two contextual guesses. An empty
+ * candidate answers `false`: an empty password is the length rule's business, and answering `true`
+ * here would report the wrong reason for it.
+ */
+export function isPasswordBlocklisted(password, context) {
+    const normalized = normalizeCandidate(password);
+    if (normalized.length === 0)
+        return false;
+    if (COMMON_PASSWORD_SET.has(normalized))
+        return true;
+    return contextualGuesses(context).has(normalized);
+}
+/** The bundled entry count, for tests that assert the list has not been emptied by a bad edit. */
+export const COMMON_PASSWORD_BLOCKLIST_SIZE = COMMON_PASSWORD_SET.size;
+//# sourceMappingURL=password-blocklist.shared.utils.js.map

package/dist/esm/security/authentications/password-blocklist.shared.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-blocklist.shared.utils.js","sourceRoot":"","sources":["../../../../../src/security/authentications/password-blocklist.shared.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The passwords a verifier must refuse, and the rule that REPLACED composition rules.\n *\n * > \"When processing a request to establish or change a password, verifiers SHALL compare the\n * > prospective secret against a blocklist that contains known commonly used, expected, or\n * > compromised passwords. The entire password SHALL be subject to comparison, not substrings or\n * > words that might be contained therein.\"\n *\n * spec-cite: NIST SP 800-63B-4 §3.1.1.2 \"Password Verifiers\"\n * (https://pages.nist.gov/800-63-4/sp800-63b.html).\n *\n * That same section is where Wildo's composition rules went: \"Verifiers and CSPs SHALL NOT impose\n * other composition rules (e.g., requiring mixtures of different character types) for passwords.\"\n * So this list is not an extra check bolted onto the old policy — it is the check the standard asks\n * for INSTEAD of the ones that were removed, and without it the policy would have lost a rule and\n * gained nothing.\n *\n * ## Why the list is SMALL, deliberately\n *\n * The standard says so in the same paragraph: \"Excessively large blocklists are of little\n * incremental security benefit because the blocklist is used to defend against online attacks, which\n * are already limited by the throttling requirements described in Sec. 3.2.2.\"\n * spec-cite: NIST SP 800-63B-4 §3.1.1.2 (https://pages.nist.gov/800-63-4/sp800-63b.html).\n * Wildo's lockout policy IS that throttling. So this list only has to cover what an attacker reaches BEFORE the\n * throttle bites — a few hundred guesses, not a breach corpus.\n *\n * ## Why it is bundled rather than fetched\n *\n * A k-anonymity range query to a third-party breach API sends a hash prefix off the machine every\n * time anybody sets a password. That is an outbound dependency on the sign-up path: it fails when\n * the third party does, and it is a privacy fact a generated application would owe its own users.\n * A bundled list costs nothing at runtime, works offline, and the standard explicitly says size is\n * not where the security comes from. An application wanting a corpus check can add one; the\n * framework's floor does not rest on somebody else's uptime.\n *\n * ## The two CONTEXTUAL guesses matter more than the list\n *\n * Appendix A.3 names them: \"specific words (e.g., the name of the service itself) that users are\n * likely to choose\". The application's own name and the local part of the user's own address are the\n * first two things an attacker tries and the two no static list can hold, because they differ per\n * application and per person.\n *\n * ## Comparison is WHOLE-STRING\n *\n * Case-folded and trimmed, and nothing else. Substring matching is refused by the sentence quoted\n * above, and it is also what makes a blocklist infuriating: rejecting everything CONTAINING \"admin\"\n * refuses `administrative-quandary-seven` for no reason. It is why `correct horse battery staple`\n * is ACCEPTED while `correcthorsebatterystaple` is refused — the spaced form is a different string,\n * and only the closed-up form is a famous enough guess to be worth refusing.\n *\n * assurance-control: WILDO.IDENTITY.CREDENTIAL_LIFECYCLE — a password an attacker would reach before\n * the throttle does is refused at the moment it is set.\n */\n\n/**\n * The passwords attackers try first, ordered roughly by observed frequency in public breach\n * analyses. The order carries no meaning at runtime — membership is a set lookup — and it is kept as\n * a readable array rather than a generated artifact so that a reader wondering \"is mine in here?\"\n * can answer it by looking.\n */\nconst COMMON_PASSWORDS: readonly string[] = [\n  '123456', '123456789', '12345678', '1234567890', '1234567', '12345', '123123', '111111', '000000',\n  '654321', '666666', '888888', '121212', '112233', '159753', '987654321', '123321', '1234',\n  'password', 'password1', 'password123', 'passw0rd', 'p@ssw0rd', 'p@ssword', 'pass', 'passwd',\n  'password12', 'password1234', 'passw0rd1', 'secret', 'secret123',\n  'qwerty', 'qwerty123', 'qwerty1234', 'qwertyuiop', 'qwe123', '1q2w3e4r', '1q2w3e4r5t', 'asdfgh',\n  'asdfghjkl', 'zxcvbnm', 'azerty', 'qazwsx', 'qwertz', 'asdf', 'asdf1234',\n  'iloveyou', 'iloveyou1', 'princess', 'sunshine', 'monkey', 'dragon', 'football', 'baseball',\n  'superman', 'batman', 'starwars', 'master', 'shadow', 'hunter', 'trustno1', 'trustnoone',\n  'freedom', 'whatever', 'letmein', 'letmein123', 'welcome', 'welcome1', 'welcome123',\n  'login', 'admin', 'admin123', 'admin1234', 'administrator', 'root', 'root123', 'guest',\n  'test', 'test123', 'demo', 'user', 'default', 'changeme', 'changeme123', 'access',\n  'abc123', 'abcd1234', 'a1b2c3', 'aaaaaa', 'temp', 'temporary',\n  'summer', 'winter', 'spring', 'autumn', 'january', 'december',\n  'chocolate', 'liverpool', 'arsenal', 'chelsea', 'barcelona', 'juventus',\n  'computer', 'internet', 'samsung', 'google', 'facebook', 'linkedin',\n  'ninja', 'cheese', 'pepper', 'ginger', 'cookie', 'flower', 'purple', 'orange', 'silver',\n  'loveme', 'lovely', 'family', 'friends', 'forever', 'nothing', 'anything',\n  'soccer', 'hockey', 'killer', 'michael', 'jennifer', 'jordan', 'george', 'charlie', 'thomas',\n  'robert', 'daniel', 'andrew', 'matthew', 'joshua', 'anthony', 'william', 'nicole', 'ashley',\n  'amanda', 'jessica', 'samantha',\n  'correcthorsebatterystaple',\n];\n\nconst COMMON_PASSWORD_SET: ReadonlySet<string> = new Set(COMMON_PASSWORDS);\n\n/** Case-folded and trimmed. Nothing else — the comparison is whole-string, per §3.1.1.2. */\nfunction normalizeCandidate(candidate: string): string {\n  return candidate.trim().toLowerCase();\n}\n\n/**\n * What an attacker guesses about THIS application and THIS person, which no static list can hold.\n *\n * `appName` is the service's own name and `email` contributes its local part. Both are also compared\n * with separators squashed out, because `Wonder Todos` and `wondertodos` are one guess.\n */\nexport interface PasswordBlocklistContext {\n  readonly appName?: string;\n  readonly email?: string;\n}\n\nfunction contextualGuesses(context: PasswordBlocklistContext | undefined): Set<string> {\n  const guesses = new Set<string>();\n  const add = (value: string | undefined): void => {\n    if (!value) return;\n    const normalized = normalizeCandidate(value);\n    if (normalized.length === 0) return;\n    guesses.add(normalized);\n    const squashed = normalized.replace(/[\\s._-]+/g, '');\n    if (squashed.length > 0) guesses.add(squashed);\n  };\n  add(context?.appName);\n  add(context?.email?.split('@')[0]);\n  return guesses;\n}\n\n/**\n * Is this password one an attacker reaches before the throttle does?\n *\n * Whole-string comparison against the bundled list and the two contextual guesses. An empty\n * candidate answers `false`: an empty password is the length rule's business, and answering `true`\n * here would report the wrong reason for it.\n */\nexport function isPasswordBlocklisted(password: string, context?: PasswordBlocklistContext): boolean {\n  const normalized = normalizeCandidate(password);\n  if (normalized.length === 0) return false;\n  if (COMMON_PASSWORD_SET.has(normalized)) return true;\n  return contextualGuesses(context).has(normalized);\n}\n\n/** The bundled entry count, for tests that assert the list has not been emptied by a bad edit. */\nexport const COMMON_PASSWORD_BLOCKLIST_SIZE: number = COMMON_PASSWORD_SET.size;\n"]}

package/dist/esm/security/authentications/password-reset.shared.dto.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"password-reset.shared.dto.schemas.d.ts","sourceRoot":"","sources":["../../../../src/security/authentications/password-reset.shared.dto.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;GAGG;AACH,eAAO,MAAM,6BAA6B;;iBAIxC,CAAC;AAGH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;iBAGzC,CAAC;AAGH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAMtF;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC;;;iBAO7C,CAAC;AAGH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC"}
+{"version":3,"file":"password-reset.shared.dto.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/security/authentications/password-reset.shared.dto.schemas.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;GAGG;AACH,eAAO,MAAM,6BAA6B;;iBAIxC,CAAC;AAGH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;iBAGzC,CAAC;AAGH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAMtF;;;;;;;GAOG;AACH,eAAO,MAAM,kCAAkC;;;iBAO7C,CAAC;AAGH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC"}