@wildo-ai/saas-models 1.0.1 → 1.1.0

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

@@ -0,0 +1,278 @@
+/**
+ * Cross-Frontend Handoff DTO atoms (cross-app-jwt-propagation Step 2).
+ *
+ * Self-service endpoint contract that the source frontend's authenticated user
+ * invokes to obtain a one-time AUTH_CODE_EXCHANGE token bound to a target
+ * frontend service. The source frontend then redirects the browser to the
+ * target frontend's `/auth/exchange` page, which POSTs to the existing
+ * `/auth/token/exchange` endpoint to consume the code and receive a fresh
+ * JWT pair.
+ *
+ * Built on the existing AUTH_CODE_EXCHANGE primitive (used by OAuth2 callback
+ * today). Does NOT introduce a new consumable token type, a new exchange
+ * endpoint, or any cookie-based transport — the contract is bearer-only and
+ * piggybacks on the mature exchange + anonymous-transposition wiring.
+ *
+ * CORS posture: bearer-only. The endpoint reads `Authorization: Bearer …`
+ * from the source frontend's session; receivers MUST NOT set
+ * `withCredentials: true` on their fetch call. Every declared frontendService
+ * is automatically allowed via the existing `deriveCorsOrigins()` seam.
+ *
+ * Why this file is split out of `authentication.shared.dto.schemas.ts`:
+ *   - The parent file is 750+ lines, depends on `UserContextSchema`,
+ *     `AvailableMethodSchema`, `SessionType`, `AuthMethod`, `AuthFactorLevel`,
+ *     `AuthSessionPurpose`, `AuthUtils`, AND `@wildo-ai/zod-decorators`. Any
+ *     browser bundle that touches a single symbol from it pays the full
+ *     transitive cost (see `saas-models-public-runtime.md` K-1).
+ *   - This file is intentionally minimal: ONLY `import { z } from 'zod'`. It
+ *     can be safely re-exported from `@wildo-ai/saas-models/public-runtime`
+ *     (saas-models-public-runtime.md K-4) without booting `initZodDecorators`
+ *     or pulling `reflect-metadata`.
+ *
+ * DRY contract:
+ *   - `authentication.shared.dto.schemas.ts` re-exports everything in this
+ *     file via `export * from './cross-frontend-handoff.shared.dto.schemas'`
+ *     so existing root-barrel imports
+ *     (`import { CrossFrontendHandoffRequest } from '@wildo-ai/saas-models'`)
+ *     keep working unchanged.
+ *   - The atoms live ONLY in this file. Do NOT duplicate any declaration
+ *     into the parent file — that would defeat the purpose of the split.
+ *
+ * Historical note — H-3 / M-7 cross-frontend-handoff incident:
+ *   An earlier iteration of `engine/saas-technical-doc`'s
+ *   `<AuthExchangePage>` shipped a silently-undefined
+ *   `response.metadata?.returnPath` read that compiled cleanly even
+ *   though `metadata` was not a key on the inferred response type. The
+ *   bad read was caught by code review (M-7) and removed by reading the
+ *   correct top-level `response.returnPath` instead. The cross-package
+ *   `z.infer` types ARE tight when the decorator-framework runtime is
+ *   booted on the consuming bundle (the docs runtime entry calls
+ *   `ensureZodDecoratorsLoaded(z)` for that reason — see
+ *   `engine/saas-technical-doc/src/runtime/index.ts`). The
+ *   `expectTypeOf` pins in
+ *   `__tests__/authentication.shared.dto.schemas.test.ts` (executed via
+ *   Vitest's `typecheck.enabled` mode) defend against future regressions
+ *   on the three public-runtime DTOs declared below.
+ */
+import { z } from 'zod';
+/**
+ * Stable error codes for the cross-frontend handoff endpoint, returned as
+ * `{ error: { code, message, context } }` with HTTP 400. Exported as a TS enum
+ * so callers (notably the docs-site `docsAuthClient.ts`) can branch on the
+ * code, not on the message.
+ */
+export declare enum CrossFrontendHandoffErrorCode {
+    /** The `targetServiceKey` is not a key in `appConfigService.config.frontendServices`. */
+    UNKNOWN_TARGET_FRONTEND = "UNKNOWN_TARGET_FRONTEND",
+    /** The target service is declared but `runtime.endPoints[targetServiceKey].publicUrl` is missing for the current env. Fail-closed (no auto-derived guess). */
+    TARGET_FRONTEND_HOST_NOT_CONFIGURED = "TARGET_FRONTEND_HOST_NOT_CONFIGURED",
+    /** The target service is declared, but its frontend runtime does not mount `/auth/exchange` and therefore cannot redeem a handoff code. */
+    TARGET_FRONTEND_AUTH_EXCHANGE_UNSUPPORTED = "TARGET_FRONTEND_AUTH_EXCHANGE_UNSUPPORTED"
+}
+/**
+ * Request body for `POST /auth/cross-frontend-handoff`.
+ *
+ * The caller is the user themselves, asking the backend "issue me a one-time
+ * code so I can hand my session to frontend X (with optional return path)".
+ *
+ * Field semantics:
+ * - `targetServiceKey` MUST be the per-service unique identity that
+ *   `appConfigService.config.frontendServices` is keyed by AND that
+ *   `runtime.endPoints[*]` is keyed by. **Today that identity is the
+ *   `serviceName`** declared on `wildo.saas.config.ts → services.<key>.serviceName`
+ *   (e.g. `'wonder-todos-docs'`, NOT the services map key `'docs'`):
+ *   apps-manager's `buildManagedFrontendServicesSeed` keys
+ *   `frontendServices` by `serviceName`, wildo-cli's
+ *   `AppBootstrapService.buildRuntimeEndpoints` keys
+ *   `APPLICATION_RUNTIME_ENDPOINTS` by `serviceName`, the
+ *   `X-Frontend-Service-Name` header carries `serviceName` (via
+ *   `VITE_FRONTEND_SERVICE_NAME`), and the K8s ingress builder keys
+ *   per-frontend endpoints by `Object.keys(frontendServices)` — i.e.
+ *   `serviceName` again. Passing the services map key (`'docs'`)
+ *   instead would fail the handler's
+ *   `frontendServices[body.targetServiceKey]` membership check
+ *   with `UNKNOWN_TARGET_FRONTEND`. The name `targetServiceKey` is
+ *   load-bearing only as "the runtime identity an SDK consumer
+ *   passes through" — semantically it is a `frontendServiceName`.
+ *   The eventual convergence on `services.<key>` as the single
+ *   canonical identity is tracked under the cross-app / apps-manager
+ *   workstream (a multi-PR migration touching apps-manager seeding,
+ *   wildo-cli endpoint emission, the `VITE_FRONTEND_SERVICE_NAME`
+ *   build-time injection, and every consumer of `lookupFrontendPublicUrl`).
+ *   Renamed from the original `targetFrontendSlug` to lock the semantics
+ *   in the schema, not just JSDoc — a wrong-typed body fails at parse time.
+ * - `returnPath` is the path on the target frontend the user should land on
+ *   AFTER the token exchange completes. Validated via
+ *   `CrossFrontendHandoff_ReturnPathSchema`.
+ *
+ *   **Runtime vs type guarantee**: the schema applies
+ *   `.default('').transform(empty → '/')` so at RUNTIME, by the time the
+ *   parsed body reaches the handler, `returnPath` is always a non-empty
+ *   string (defaulted to `'/'` if the caller omitted it or sent `''`).
+ *   At the TYPE level, however, `z.infer<typeof CrossFrontendHandoffRequestSchema>`
+ *   keeps `returnPath?: string` — TypeScript does not propagate the
+ *   post-default tightening through the `.refine()` chain on a
+ *   `ZodPipe<ZodDefault<…>, ZodTransform>`. Handler code therefore has
+ *   two safe options:
+ *     - treat `returnPath` as `string | undefined` and fall back to `'/'`
+ *       defensively, OR
+ *     - rely on the runtime invariant after parsing (the body NEVER reaches
+ *       the handler unparsed; the controller validates it via
+ *       `CrossFrontendHandoffRequestSchema.parse()` before dispatch).
+ *
+ *   The exported `CrossFrontendHandoffRequest` type is `z.infer` of the
+ *   schema, so it matches the OUTPUT shape (with the optional-`returnPath`
+ *   caveat above). For the WIRE shape (where every other field's optional
+ *   semantics may differ), use `z.input<typeof CrossFrontendHandoffRequestSchema>`.
+ */
+export declare const CrossFrontendHandoffRequestSchema: z.ZodObject<{
+    targetServiceKey: z.ZodString;
+    returnPath: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string, string>>;
+}, z.core.$strict>;
+/**
+ * Output (parsed) shape of `POST /auth/cross-frontend-handoff`'s request body.
+ *
+ * Consumers that need the WIRE shape (where `returnPath` is `string | undefined`)
+ * should use `z.input<typeof CrossFrontendHandoffRequestSchema>` instead.
+ *
+ * Cross-package safety: every consuming bundle MUST boot
+ * `@wildo-ai/zod-decorators` once via `ensureZodDecoratorsLoaded(z)`
+ * before reading `z.infer<typeof …>` on schemas exported from this file.
+ * The SaaS app + backend get this for free via the saas-models root barrel
+ * (which runs `initZodDecorators()` on load); the docs runtime does it
+ * explicitly in `engine/saas-technical-doc/src/runtime/index.ts`. The
+ * `expectTypeOf` pins in the schemas test file enforce that the inferred
+ * shape stays tight; CI runs them via Vitest `typecheck.enabled` mode.
+ */
+export type CrossFrontendHandoffRequest = z.infer<typeof CrossFrontendHandoffRequestSchema>;
+/**
+ * Response body for `POST /auth/cross-frontend-handoff`.
+ *
+ * Field semantics:
+ * - `handoffUrl` — the URL the source frontend should redirect to:
+ *   `https://<targetPublicHost>/auth/exchange?code=<token>&return=<percent-encoded-returnPath>`.
+ *   Typed as `string` (not a branded URL type) because consumers immediately
+ *   hand it to `location.assign()` / `<Link to>`, neither of which expects
+ *   a branded type. The runtime validator enforces `z.url()` shape.
+ * - `expiresAt` — ISO-8601 timestamp; the consumable token TTL is 60 seconds
+ *   (shorter than OAuth2's 5 min — the user is mid-redirect, not waiting on
+ *   a third-party IdP). The strict ISO refine catches a misbehaving server /
+ *   fixture that emits a non-ISO string at parse time on the receiving end
+ *   (the docs-chat client validates with this schema).
+ */
+export declare const CrossFrontendHandoffResponseSchema: z.ZodObject<{
+    handoffUrl: z.ZodURL;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+/**
+ * Inferred response shape — see `CrossFrontendHandoffRequest` JSDoc on the
+ * cross-package `z.infer` safety contract.
+ */
+export type CrossFrontendHandoffResponse = z.infer<typeof CrossFrontendHandoffResponseSchema>;
+/**
+ * Request body for `POST /auth/token/exchange`.
+ *
+ * Kept beside `TokenExchangeResponseSchema` because every consumer that can
+ * receive an AUTH_CODE_EXCHANGE code must send this body. Do not let clients
+ * hand-roll `{ code }` literals: the request side is part of the same public
+ * runtime contract as the response and must drift in lockstep.
+ */
+export declare const TokenExchangeRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+}, z.core.$strict>;
+/**
+ * Inferred request body for `POST /auth/token/exchange`.
+ */
+export type TokenExchangeRequest = z.infer<typeof TokenExchangeRequestSchema>;
+/**
+ * Response body for `POST /auth/token/exchange` (cross-app-jwt-propagation Step 5).
+ *
+ * Lives in this file (rather than `authentication.shared.dto.schemas.ts`)
+ * because every receiver of an AUTH_CODE_EXCHANGE token — the SaaS app, the
+ * docs site — is by construction also a client-bundle target. Keeping the
+ * response schema in the public-runtime-safe atom file lets those receivers
+ * import the same source of truth via `@wildo-ai/saas-models/public-runtime`
+ * without paying the `initZodDecorators()` boot cost
+ * (saas-models-public-runtime.md K-1, K-4).
+ *
+ * Field semantics:
+ * - `accessToken`, `expiresIn` — the freshly minted access-token response for
+ *   the consuming frontend. The consumable token's metadata also carries the
+ *   refresh token internally, but the exchange handler routes it to the
+ *   HttpOnly cookie channel rather than the JSON body.
+ * - `returnPath` — present only for handoff-issued codes (NOT OAuth2-callback
+ *   codes); the path the receiving frontend should navigate to after the
+ *   exchange completes. Refined with the same `RETURN_PATH_REFINES` as the
+ *   issuer-side `CrossFrontendHandoff_ReturnPathSchema` (single source of
+ *   truth — issuer and receiver cannot drift on which payloads are rejected).
+ *   The optional+refines composition means: when absent, the field passes
+ *   silently (OAuth2-callback path); when present, it MUST clear every
+ *   refine, otherwise the receiver-side `.parse()` call in `tokenExchange()`
+ *   throws and the response never goes out. That is intentional — a
+ *   tampered metadata round-trip is a security event, not a degraded UX.
+ * - `sourceFrontendServiceName`, `targetServiceKey` — present only for
+ *   handoff-issued codes. Lets the receiver render telemetry / breadcrumbs
+ *   ("you came from the admin panel") without round-tripping another API call.
+ *
+ * Why optional fields rather than a discriminated union: OAuth2-callback
+ * codes go through the same exchange handler with the same metadata
+ * skeleton minus the handoff-specific fields, so a discriminator would
+ * require a synthetic `kind` field that adds no information. The optionality
+ * IS the discriminator: presence of `returnPath` (or `sourceFrontendServiceName`)
+ * tells the receiver "this came from a cross-frontend handoff, treat it
+ * accordingly". This load-bearing invariant is enforced upstream by the
+ * `tokenExchange()` controller, which mints the response object via
+ * `if (typeof metadata.returnPath === 'string') response.returnPath = …`
+ * (omit-when-absent). If a future regression starts emitting `null` or `''`
+ * for OAuth2-callback codes, the receiver-side discrimination breaks
+ * silently — the contract is documented here and pinned by the integration
+ * test in `cross-frontend-handoff-token-exchange.integration.test.ts`.
+ *
+ * **H-3 history**: an early `<AuthExchangePage>` implementation read
+ * `response.metadata?.returnPath` (always undefined — `metadata` is not
+ * a key on the response). The bad read was caught by code review (M-7)
+ * and replaced by reading the correct top-level `response.returnPath`.
+ * Cross-package `z.infer<typeof TokenExchangeResponseSchema>` IS tight
+ * (the same bad access today fires `TS2339: Property 'metadata' does
+ * not exist`) provided the consuming bundle has booted
+ * `@wildo-ai/zod-decorators` once via `ensureZodDecoratorsLoaded(z)` —
+ * which the docs runtime entry does (`engine/saas-technical-doc/src/runtime/index.ts`)
+ * and the SaaS app gets implicitly via the saas-models root barrel. The
+ * `expectTypeOf` pins in the schemas test file enforce that the inferred
+ * shape stays tight; CI runs them via Vitest `typecheck.enabled` mode.
+ */
+/**
+ * Token exchange response (cross-app-jwt-propagation Step 5 + OAuth2 callback).
+ *
+ * **Wire contract — refresh token is NEVER included** (Auth-hardening
+ * Slice A Step 6, 2026-04-13). Pre-Slice-A this schema carried
+ * `refreshToken: z.string()` which was emitted in the JSON body for
+ * AUTH_CODE_EXCHANGE redemptions. The cookie migration (A-Step 2)
+ * routed the refresh token to `Set-Cookie: __wildo_refresh=…`;
+ * A-Step 6 removes the body field entirely. The receiving frontend
+ * (SaaS app via `saas-frontend-lib`, or docs site via `docsAuthClient`)
+ * stores the access token in memory; the SaaS app additionally
+ * receives the refresh cookie automatically (same-origin browser
+ * default), while the docs site has no refresh loop and re-handshakes
+ * on next gated navigation when the access token expires.
+ *
+ * The strict-object shape pins the H-3 invariant: `returnPath` lives at
+ * the TOP LEVEL — there is intentionally NO `metadata` envelope. Adding
+ * an unknown key would now ALSO fire because `refreshToken` is removed
+ * (a server still emitting `refreshToken` would fail strict-parse on
+ * the receiver — surfacing the misalignment loudly rather than letting
+ * the field silently leak through).
+ */
+export declare const TokenExchangeResponseSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    expiresIn: z.ZodNumber;
+    returnPath: z.ZodOptional<z.ZodString>;
+    sourceFrontendServiceName: z.ZodOptional<z.ZodString>;
+    targetServiceKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * Inferred response shape — see `TokenExchangeResponseSchema` JSDoc on
+ * the cross-package `z.infer` safety contract (post-H-3 fix).
+ */
+export type TokenExchangeResponse = z.infer<typeof TokenExchangeResponseSchema>;
+//# sourceMappingURL=cross-frontend-handoff.shared.dto.schemas.d.ts.map

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

@@ -0,0 +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"}

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

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