@wildo-ai/saas-frontend-lib 1.0.1 → 1.1.0

package/dist/esm/core/security/auth-redirect.frontend.utils.js

@@ -1,10 +1,32 @@
+import { isSameOriginRedirectPath } from '@wildo-ai/saas-models/public-runtime';
 import { CommonRoutePaths } from '../../core/runtime/routes.frontend.definitions.js';
 export const AUTH_REDIRECT_QUERY_PARAM = 'redirect';
+/**
+ * Is this a redirect target the app may navigate to after authentication?
+ *
+ * ## Why this delegates instead of testing prefixes
+ *
+ * The previous implementation was `target.startsWith('/') && !target.startsWith('//')`, and it is
+ * worth writing down why that is not a weaker version of the check but a broken one: it tests the
+ * bytes a human reads, while the browser navigates to what its URL PARSER produces, and the two
+ * disagree on a whole family of inputs. SEVEN shapes passed it and resolved to `https://evil.com/` —
+ * `/\evil.com`, `/\\evil.com`, `/\/evil.com`, and the tab / LF / CR variants that the parser strips
+ * before parsing. The measurement and the two parser rules behind it are documented once, at
+ * {@link isSameOriginRedirectPath}.
+ *
+ * The exploit is post-authentication, which is what makes it worth more than an ordinary open
+ * redirect: the user has just proved who they are to a site they trust, and the app hands them to the
+ * attacker's origin carrying that established trust.
+ *
+ * ## Why the predicate is imported rather than written here
+ *
+ * Three other surfaces answer the same question — the one-off-session receiver, the docs-site auth
+ * exchange page, and the issuer/receiver schemas in `saas-models` — and on 2026-08-15 all four
+ * carried the same hole, because each was a separately hand-written deny-list that "mirrored" the
+ * others. One importable predicate is what stops the fifth copy from being written.
+ */
 export function isSafeAuthRedirectTarget(target) {
-    if (!target) {
-        return false;
-    }
-    return target.startsWith('/') && !target.startsWith('//');
+    return isSameOriginRedirectPath(target);
 }
 export function buildAuthRedirectTarget(params) {
     return `${params.pathname}${params.search ?? ''}${params.hash ?? ''}`;
@@ -28,4 +50,4 @@ export function extractAuthRedirectFromSearch(search) {
 export function resolvePostAuthRedirect(search, fallbackPath = CommonRoutePaths.home) {
     return extractAuthRedirectFromSearch(search) ?? fallbackPath;
 }
-//# sourceMappingURL=auth-redirect.frontend.utils.js.map
+//# sourceMappingURL=auth-redirect.frontend.utils.js.map

package/dist/esm/core/security/auth-redirect.frontend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-redirect.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/security/auth-redirect.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,8DAA8D,CAAC;AAEhG,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEpD,MAAM,UAAU,wBAAwB,CAAC,MAAiC;IACxE,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAIvC;IACC,OAAO,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,QAAgB,EAChB,cAAyC;IAEzC,IAAI,CAAC,wBAAwB,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,YAAY,EAAE,IAAI,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,CAAC,QAAQ,EAAE,KAAK,GAAG,EAAE,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAChD,YAAY,CAAC,GAAG,CAAC,yBAAyB,EAAE,cAAc,CAAC,CAAC;IAE5D,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC;IAC1C,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,MAAc;IAC1D,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,YAAY,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAEnE,OAAO,wBAAwB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,eAAuB,gBAAgB,CAAC,IAAI;IAE5C,OAAO,6BAA6B,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"auth-redirect.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/security/auth-redirect.frontend.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,sCAAsC,CAAC;AAEhF,OAAO,EAAE,gBAAgB,EAAE,MAAM,8DAA8D,CAAC;AAEhG,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAiC;IACxE,OAAO,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,MAIvC;IACC,OAAO,GAAG,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,GAAG,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,QAAgB,EAChB,cAAyC;IAEzC,IAAI,CAAC,wBAAwB,CAAC,cAAc,CAAC,EAAE,CAAC;QAC9C,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,CAAC,YAAY,EAAE,IAAI,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,CAAC,QAAQ,EAAE,KAAK,GAAG,EAAE,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACvD,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAC;IAChD,YAAY,CAAC,GAAG,CAAC,yBAAyB,EAAE,cAAc,CAAC,CAAC;IAE5D,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,EAAE,CAAC;IAC1C,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,MAAc;IAC1D,MAAM,YAAY,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,YAAY,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IAEnE,OAAO,wBAAwB,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,eAAuB,gBAAgB,CAAC,IAAI;IAE5C,OAAO,6BAA6B,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC;AAC/D,CAAC","sourcesContent":["import { isSameOriginRedirectPath } from '@wildo-ai/saas-models/public-runtime';\n\nimport { CommonRoutePaths } from '~wildo-frontend-lib/core/runtime/routes.frontend.definitions';\n\nexport const AUTH_REDIRECT_QUERY_PARAM = 'redirect';\n\n/**\n * Is this a redirect target the app may navigate to after authentication?\n *\n * ## Why this delegates instead of testing prefixes\n *\n * The previous implementation was `target.startsWith('/') && !target.startsWith('//')`, and it is\n * worth writing down why that is not a weaker version of the check but a broken one: it tests the\n * bytes a human reads, while the browser navigates to what its URL PARSER produces, and the two\n * disagree on a whole family of inputs. SEVEN shapes passed it and resolved to `https://evil.com/` —\n * `/\\evil.com`, `/\\\\evil.com`, `/\\/evil.com`, and the tab / LF / CR variants that the parser strips\n * before parsing. The measurement and the two parser rules behind it are documented once, at\n * {@link isSameOriginRedirectPath}.\n *\n * The exploit is post-authentication, which is what makes it worth more than an ordinary open\n * redirect: the user has just proved who they are to a site they trust, and the app hands them to the\n * attacker's origin carrying that established trust.\n *\n * ## Why the predicate is imported rather than written here\n *\n * Three other surfaces answer the same question — the one-off-session receiver, the docs-site auth\n * exchange page, and the issuer/receiver schemas in `saas-models` — and on 2026-08-15 all four\n * carried the same hole, because each was a separately hand-written deny-list that \"mirrored\" the\n * others. One importable predicate is what stops the fifth copy from being written.\n */\nexport function isSafeAuthRedirectTarget(target: string | null | undefined): target is string {\n  return isSameOriginRedirectPath(target);\n}\n\nexport function buildAuthRedirectTarget(params: {\n  pathname: string;\n  search?: string;\n  hash?: string;\n}): string {\n  return `${params.pathname}${params.search ?? ''}${params.hash ?? ''}`;\n}\n\nexport function appendAuthRedirectToPath(\n  basePath: string,\n  redirectTarget: string | null | undefined,\n): string {\n  if (!isSafeAuthRedirectTarget(redirectTarget)) {\n    return basePath;\n  }\n\n  const [pathAndQuery, hash = ''] = basePath.split('#');\n  const [pathname, query = ''] = pathAndQuery.split('?');\n  const searchParams = new URLSearchParams(query);\n  searchParams.set(AUTH_REDIRECT_QUERY_PARAM, redirectTarget);\n\n  const nextQuery = searchParams.toString();\n  return `${pathname}${nextQuery ? `?${nextQuery}` : ''}${hash ? `#${hash}` : ''}`;\n}\n\nexport function extractAuthRedirectFromSearch(search: string): string | undefined {\n  const searchParams = new URLSearchParams(search);\n  const redirectTarget = searchParams.get(AUTH_REDIRECT_QUERY_PARAM);\n\n  return isSafeAuthRedirectTarget(redirectTarget) ? redirectTarget : undefined;\n}\n\nexport function resolvePostAuthRedirect(\n  search: string,\n  fallbackPath: string = CommonRoutePaths.home,\n): string {\n  return extractAuthRedirectFromSearch(search) ?? fallbackPath;\n}\n"]}

package/dist/esm/core/security/auth-session.utils.d.ts

@@ -11,7 +11,21 @@ export interface AccountCompletenessResult {
 export declare class AuthSessionUtils {
     private constructor();
     /**
-     * Check if an error is an authentication or authorization error using Wildo error types.
+     * Check if an error is an AUTHENTICATION (session-invalid) error — i.e. the
+     * caller's session/token is missing, expired, or invalid and they must
+     * re-authenticate. This drives the session-restore force-logout, so a false
+     * positive here logs a perfectly valid session out.
+     *
+     * Authentication (401 / session-invalid) and AUTHORIZATION (403 / scope /
+     * permission) are DISTINCT axes and are mutually exclusive: a permission
+     * denial is NOT a reason to destroy the session. We therefore short-circuit
+     * to `false` for any authorization error BEFORE the reference-list check
+     * below — this neutralizes `AUTHENTICATION_USER_NOT_AUTHORIZED`, which is
+     * semantically an authorization concept that merely lives in the
+     * authentication-namespaced `ErrorCustomMessageReference` enum. When it
+     * arrives as a 403 (the realistic case) it is an authorization error, full
+     * stop, and must not log the user out (recovered 2026-06-29: the
+     * session-restore path over-logged-out on scope errors carrying this ref).
      */
     static isAuthenticationError(error: any): boolean;
     /**

package/dist/esm/core/security/auth-session.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-session.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/security/auth-session.utils.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAkBD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO;IAEP;;OAEG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAmCjD;;;OAGG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAiBhD;;;;;;;;OAQG;IACH,MAAM,CAAC,2BAA2B,CAChC,WAAW,EAAE,OAAO,EACpB,mBAAmB,EAAE,UAAU,EAAE,EACjC,2BAA2B,EAAE,UAAU,EAAE,EACzC,oBAAoB,EAAE,UAAU,EAAE,GACjC,yBAAyB;CA0B7B"}
+{"version":3,"file":"auth-session.utils.d.ts","sourceRoot":"","sources":["../../../../../src/core/security/auth-session.utils.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,UAAU,EAAE,CAAC;IAC7B,eAAe,EAAE,UAAU,EAAE,CAAC;IAC9B,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAkBD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO;IAEP;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAuCjD;;;OAGG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO;IAiBhD;;;;;;;;OAQG;IACH,MAAM,CAAC,2BAA2B,CAChC,WAAW,EAAE,OAAO,EACpB,mBAAmB,EAAE,UAAU,EAAE,EACjC,2BAA2B,EAAE,UAAU,EAAE,EACzC,oBAAoB,EAAE,UAAU,EAAE,GACjC,yBAAyB;CAyC7B"}

package/dist/esm/core/security/auth-session.utils.js

@@ -21,9 +21,26 @@ const AUTHENTICATION_ERROR_REFERENCES = [
 export class AuthSessionUtils {
     constructor() { }
     /**
-     * Check if an error is an authentication or authorization error using Wildo error types.
+     * Check if an error is an AUTHENTICATION (session-invalid) error — i.e. the
+     * caller's session/token is missing, expired, or invalid and they must
+     * re-authenticate. This drives the session-restore force-logout, so a false
+     * positive here logs a perfectly valid session out.
+     *
+     * Authentication (401 / session-invalid) and AUTHORIZATION (403 / scope /
+     * permission) are DISTINCT axes and are mutually exclusive: a permission
+     * denial is NOT a reason to destroy the session. We therefore short-circuit
+     * to `false` for any authorization error BEFORE the reference-list check
+     * below — this neutralizes `AUTHENTICATION_USER_NOT_AUTHORIZED`, which is
+     * semantically an authorization concept that merely lives in the
+     * authentication-namespaced `ErrorCustomMessageReference` enum. When it
+     * arrives as a 403 (the realistic case) it is an authorization error, full
+     * stop, and must not log the user out (recovered 2026-06-29: the
+     * session-restore path over-logged-out on scope errors carrying this ref).
      */
     static isAuthenticationError(error) {
+        if (AuthSessionUtils.isAuthorizationError(error)) {
+            return false;
+        }
         const wildoError = error?.wildoError;
         if (wildoError) {
             if (wildoError.type === ErrorType.AUTHENTICATION) {
@@ -89,8 +106,23 @@ export class AuthSessionUtils {
                 requiresEnrollment: false,
             };
         }
+        // `acceptableMFAMethods` NARROWS the policy-derived list — it never replaces it.
+        //
+        // This mirrors the backend, where `_getAvailableSecondFactorMethods` seeds its candidates from the
+        // intrinsic factor map and applies `acceptableMFAMethods` as a FILTER, so app config can only ever
+        // subtract methods. Resolving it as a REPLACEMENT here (`acceptable.length > 0 ? acceptable : available`)
+        // widened the set back out to raw config, which could name methods that are impossible for this user:
+        // an SSO redirect flow (intrinsically FIRST_ONLY — never an MFA ceremony, B-SEC-1) or a method disabled
+        // for their user type. `isComplete` was never wrong — it requires an ENROLLED method to match, and those
+        // are never enrolled — but `missingMethods` was, so the enrollment UI could instruct a user to enrol
+        // something they can never enrol.
+        //
+        // An EMPTY intersection is honest, not a regression: it means the policy admits no second factor this
+        // user could satisfy, which the startup config validator now rejects outright as a deadlock — so it
+        // cannot reach production, and surfacing "enrollment required, nothing offered" beats naming an
+        // impossible method.
         const acceptableSet = acceptableMFAMethods.length > 0
-            ? acceptableMFAMethods
+            ? availableMFAMethods.filter((method) => acceptableMFAMethods.includes(method))
             : availableMFAMethods;
         const enrolledSet = new Set(enrolledSecondFactorMethods);
         const hasAcceptableEnrollment = acceptableSet.some(m => enrolledSet.has(m));
@@ -103,4 +135,4 @@ export class AuthSessionUtils {
         };
     }
 }
-//# sourceMappingURL=auth-session.utils.js.map
+//# sourceMappingURL=auth-session.utils.js.map

package/dist/esm/core/security/auth-session.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-session.utils.js","sourceRoot":"","sources":["../../../../src/core/security/auth-session.utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth-session.utils.js","sourceRoot":"","sources":["../../../../../src/core/security/auth-session.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  ErrorType,\n  HttpStatusCode,\n} from '@wildo-ai/saas-models';\nimport { WildoError_Frontend, ErrorCustomMessageReference } from '@wildo-ai/saas-models';\nimport type { AuthMethod } from '@wildo-ai/saas-models';\n\nexport interface AccountCompletenessResult {\n  isComplete: boolean;\n  missingMethods: AuthMethod[];\n  enrolledMethods: AuthMethod[];\n  requiresEnrollment: boolean;\n}\n\nconst AUTHENTICATION_ERROR_REFERENCES: readonly ErrorCustomMessageReference[] = [\n  ErrorCustomMessageReference.AUTHENTICATION,\n  ErrorCustomMessageReference.JWT_TOKEN_EXPIRED,\n  ErrorCustomMessageReference.JWT_TOKEN_INVALID,\n  ErrorCustomMessageReference.JWT_TOKEN_NOT_FOUND,\n  ErrorCustomMessageReference.JWT_TOKEN_NOT_VERIFIED,\n  ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,\n  ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED,\n  ErrorCustomMessageReference.AUTHENTICATION_SESSION_INVALID,\n  ErrorCustomMessageReference.AUTHENTICATION_SESSION_EXPIRED,\n  ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_AUTHORIZED,\n  ErrorCustomMessageReference.AUTHENTICATION_API_KEY_INVALID,\n  ErrorCustomMessageReference.AUTHENTICATION_API_KEY_FAILED,\n  ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED,\n] as const;\n\n/**\n * Static utility class for authentication/session non-component logic.\n */\nexport class AuthSessionUtils {\n  private constructor() {}\n\n  /**\n   * Check if an error is an AUTHENTICATION (session-invalid) error — i.e. the\n   * caller's session/token is missing, expired, or invalid and they must\n   * re-authenticate. This drives the session-restore force-logout, so a false\n   * positive here logs a perfectly valid session out.\n   *\n   * Authentication (401 / session-invalid) and AUTHORIZATION (403 / scope /\n   * permission) are DISTINCT axes and are mutually exclusive: a permission\n   * denial is NOT a reason to destroy the session. We therefore short-circuit\n   * to `false` for any authorization error BEFORE the reference-list check\n   * below — this neutralizes `AUTHENTICATION_USER_NOT_AUTHORIZED`, which is\n   * semantically an authorization concept that merely lives in the\n   * authentication-namespaced `ErrorCustomMessageReference` enum. When it\n   * arrives as a 403 (the realistic case) it is an authorization error, full\n   * stop, and must not log the user out (recovered 2026-06-29: the\n   * session-restore path over-logged-out on scope errors carrying this ref).\n   */\n  static isAuthenticationError(error: any): boolean {\n    if (AuthSessionUtils.isAuthorizationError(error)) {\n      return false;\n    }\n\n    const wildoError = error?.wildoError as WildoError_Frontend | undefined;\n    if (wildoError) {\n      if (wildoError.type === ErrorType.AUTHENTICATION) {\n        return true;\n      }\n      if (wildoError.customMessageReference) {\n        if (AUTHENTICATION_ERROR_REFERENCES.includes(wildoError.customMessageReference as ErrorCustomMessageReference)) {\n          return true;\n        }\n      }\n    }\n\n    if (error?.response?.status) {\n      const status = error.response.status;\n      if (status === HttpStatusCode.UNAUTHORIZED) {\n        return true;\n      }\n    }\n\n    if (error?.response?.data?.error) {\n      const errorData = error.response.data.error;\n      if (errorData.type === ErrorType.AUTHENTICATION) {\n        return true;\n      }\n      if (errorData.code) {\n        if (AUTHENTICATION_ERROR_REFERENCES.includes(errorData.code as ErrorCustomMessageReference)) {\n          return true;\n        }\n      }\n    }\n\n    return false;\n  }\n\n  /**\n   * Check whether an error represents an authorization/scope problem rather than an\n   * invalid or expired authentication session.\n   */\n  static isAuthorizationError(error: any): boolean {\n    const wildoError = error?.wildoError as WildoError_Frontend | undefined;\n    if (wildoError?.type === ErrorType.AUTHORIZATION) {\n      return true;\n    }\n\n    if (error?.response?.status === HttpStatusCode.FORBIDDEN) {\n      return true;\n    }\n\n    if (error?.response?.data?.error?.type === ErrorType.AUTHORIZATION) {\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * D7: Frontend-only computation. Evaluates whether the user has enrolled sufficient\n   * second-factor methods to satisfy the MFA policy.\n   *\n   * @param requiresMFA - Backend-computed flag incorporating app-level + org-level policy\n   * @param availableMFAMethods - Policy-filtered methods from the auth response\n   * @param enrolledSecondFactorMethods - Methods the user has already enrolled\n   * @param acceptableMFAMethods - App-config `mfaPolicy.acceptableMFAMethods` (may be empty)\n   */\n  static evaluateAccountCompleteness(\n    requiresMFA: boolean,\n    availableMFAMethods: AuthMethod[],\n    enrolledSecondFactorMethods: AuthMethod[],\n    acceptableMFAMethods: AuthMethod[],\n  ): AccountCompletenessResult {\n    if (!requiresMFA) {\n      return {\n        isComplete: true,\n        missingMethods: [],\n        enrolledMethods: enrolledSecondFactorMethods,\n        requiresEnrollment: false,\n      };\n    }\n\n    // `acceptableMFAMethods` NARROWS the policy-derived list — it never replaces it.\n    //\n    // This mirrors the backend, where `_getAvailableSecondFactorMethods` seeds its candidates from the\n    // intrinsic factor map and applies `acceptableMFAMethods` as a FILTER, so app config can only ever\n    // subtract methods. Resolving it as a REPLACEMENT here (`acceptable.length > 0 ? acceptable : available`)\n    // widened the set back out to raw config, which could name methods that are impossible for this user:\n    // an SSO redirect flow (intrinsically FIRST_ONLY — never an MFA ceremony, B-SEC-1) or a method disabled\n    // for their user type. `isComplete` was never wrong — it requires an ENROLLED method to match, and those\n    // are never enrolled — but `missingMethods` was, so the enrollment UI could instruct a user to enrol\n    // something they can never enrol.\n    //\n    // An EMPTY intersection is honest, not a regression: it means the policy admits no second factor this\n    // user could satisfy, which the startup config validator now rejects outright as a deadlock — so it\n    // cannot reach production, and surfacing \"enrollment required, nothing offered\" beats naming an\n    // impossible method.\n    const acceptableSet: AuthMethod[] = acceptableMFAMethods.length > 0\n      ? availableMFAMethods.filter((method) => acceptableMFAMethods.includes(method))\n      : availableMFAMethods;\n\n    const enrolledSet = new Set(enrolledSecondFactorMethods);\n    const hasAcceptableEnrollment = acceptableSet.some(m => enrolledSet.has(m));\n\n    const missingMethods = acceptableSet.filter(m => !enrolledSet.has(m));\n\n    return {\n      isComplete: hasAcceptableEnrollment,\n      missingMethods,\n      enrolledMethods: enrolledSecondFactorMethods,\n      requiresEnrollment: !hasAcceptableEnrollment,\n    };\n  }\n}\n"]}

package/dist/esm/core/security/cross-frontend-handoff.frontend.service.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Cross-Frontend Handoff helper — first-party SaaS-app wrapper around
+ * `POST /api/v1/auth/cross-frontend-handoff` (cross-app-jwt-propagation Step 3).
+ *
+ * Two surfaces:
+ *
+ *   1. `requestCrossFrontendHandoff(input)` — vanilla TS / no React. Wraps the
+ *      manual-calls HTTP client, maps backend `CrossFrontendHandoffErrorCode`
+ *      values onto a typed `CrossFrontendHandoffClientError`, and returns the
+ *      `{ handoffUrl, expiresAt }` payload unchanged. The caller decides how
+ *      to use the URL (`location.assign` for replace, `window.open` for new
+ *      tab) — the helper deliberately does NOT navigate.
+ *
+ *   2. `useCrossFrontendHandoff()` — thin React hook wrapper for first-party
+ *      app components that want `{ status, data, error, requestHandoff, reset }`
+ *      ergonomics without bringing React Query in for a one-shot mutation.
+ *
+ * DTO atoms come from `@wildo-ai/saas-models/public-runtime`
+ * (saas-models-public-runtime.md K-7) so the same symbol identity used by the
+ * docs-site `docs-auth-client.ts` flows through here. The runtime call delegates
+ * to `getManualCallsHttpClient()`, which inherits the auth + frontend-service
+ * header injection performed by the base `WildoBackendHttpClient` interceptors.
+ *
+ * The bearer + `X-Frontend-Service-Name` header are injected automatically by
+ * the base client; callers do NOT need to thread them through.
+ */
+import { CrossFrontendHandoffErrorCode, type CrossFrontendHandoffRequest, type CrossFrontendHandoffResponse } from '@wildo-ai/saas-models/public-runtime';
+import type { RequestOptions } from '../../core/requests/wildo-http-client.frontend.service';
+/**
+ * Stable, finite set of error codes a SaaS-app caller may encounter when
+ * invoking `requestCrossFrontendHandoff()`.
+ *
+ * Mirrors the backend enum 1:1 PLUS three runtime-only codes that never reach
+ * the wire:
+ *
+ *   - `unauthenticated` — the caller's bearer is missing/expired/rejected
+ *     (HTTP 401). Surfaced WITHOUT trying to parse a backend `code` so the
+ *     caller can deep-link to login instead of branching on UNKNOWN_TARGET_*.
+ *   - `network`        — no HTTP response was received (offline, DNS, CORS
+ *     pre-flight rejection, etc.). The base client retried per its policy
+ *     before this code is surfaced.
+ *   - `malformed_response` — the request returned 2xx but the body did not
+ *     match `CrossFrontendHandoffResponse`, OR the request returned an error
+ *     body without a recognizable `error.details.code` field. Treat as a
+ *     transient backend incident.
+ */
+export type CrossFrontendHandoffClientErrorCode = CrossFrontendHandoffErrorCode | 'unauthenticated' | 'network' | 'malformed_response';
+/**
+ * Typed error thrown by `requestCrossFrontendHandoff()` and stored in the
+ * `error` field of `useCrossFrontendHandoff()`.
+ *
+ * Subclasses native `Error` so `instanceof CrossFrontendHandoffClientError` is
+ * the safe way to distinguish from generic axios / network errors at a call
+ * site. The `code` discriminator is the contract surface that callers branch
+ * on; `httpStatus` is provided for telemetry / Sentry breadcrumbs only.
+ */
+export declare class CrossFrontendHandoffClientError extends Error {
+    readonly code: CrossFrontendHandoffClientErrorCode;
+    readonly httpStatus: number | null;
+    constructor(code: CrossFrontendHandoffClientErrorCode, message: string, httpStatus: number | null);
+}
+/**
+ * Vanilla TS handoff request — no React.
+ *
+ * Behavior:
+ *   - On 2xx with a well-formed body, returns the response unchanged.
+ *   - On 2xx with a malformed body, throws `code: 'malformed_response'`.
+ *   - On 401, throws `code: 'unauthenticated'` regardless of the backend's
+ *     specific code (the base client may already have triggered a refresh-loop
+ *     before this branch is reached).
+ *   - On other 4xx with a recognized `error.details.code`, throws with that
+ *     `CrossFrontendHandoffErrorCode` code so the caller can branch on
+ *     `UNKNOWN_TARGET_FRONTEND` vs `TARGET_FRONTEND_HOST_NOT_CONFIGURED`.
+ *   - On 4xx/5xx without a recognized code, throws `code: 'malformed_response'`.
+ *   - On network failure (no response), throws `code: 'network'`.
+ *
+ * Pass-through `options` are forwarded to the underlying HTTP client; useful
+ * fields: `signal` (AbortController), `silent` (suppress global error toast).
+ */
+export declare function requestCrossFrontendHandoff(input: CrossFrontendHandoffRequest, options?: RequestOptions): Promise<CrossFrontendHandoffResponse>;
+export type CrossFrontendHandoffStatus = 'idle' | 'pending' | 'success' | 'error';
+/**
+ * State + action surface returned by `useCrossFrontendHandoff()`.
+ *
+ * `requestHandoff` returns the resolved `CrossFrontendHandoffResponse` on
+ * success and re-throws the typed `CrossFrontendHandoffClientError` on failure
+ * — so callers that need to redirect immediately can `await` it without also
+ * subscribing to `status`. Hook state (`status` / `data` / `error`) is updated
+ * regardless, which is convenient for components that render status without
+ * holding a ref to the promise.
+ */
+export interface UseCrossFrontendHandoffResult {
+    status: CrossFrontendHandoffStatus;
+    data: CrossFrontendHandoffResponse | null;
+    error: CrossFrontendHandoffClientError | null;
+    requestHandoff: (input: CrossFrontendHandoffRequest, options?: RequestOptions) => Promise<CrossFrontendHandoffResponse>;
+    reset: () => void;
+}
+/**
+ * React hook wrapper around `requestCrossFrontendHandoff()` for first-party
+ * SaaS-app components.
+ *
+ * Why not `useMutation` / `useReducer`: this is a one-shot, fire-and-forget
+ * mutation with no caching / invalidation needs; pulling React Query in for
+ * three lines of state would inflate the bundle and force a peer dep that
+ * `saas-frontend-lib` does not currently take. `useState` + `useCallback` +
+ * an `unmounted` guard cover the use case.
+ */
+export declare function useCrossFrontendHandoff(): UseCrossFrontendHandoffResult;
+//# sourceMappingURL=cross-frontend-handoff.frontend.service.d.ts.map

package/dist/esm/core/security/cross-frontend-handoff.frontend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-frontend-handoff.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/security/cross-frontend-handoff.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EACL,6BAA6B,EAC7B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EAClC,MAAM,sCAAsC,CAAC;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sEAAsE,CAAC;AAE3G;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,mCAAmC,GAC3C,6BAA6B,GAC7B,iBAAiB,GACjB,SAAS,GACT,oBAAoB,CAAC;AAEzB;;;;;;;;GAQG;AACH,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,IAAI,EAAE,mCAAmC,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;gBAEvB,IAAI,EAAE,mCAAmC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;CAMlG;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,2BAA2B,EAClC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,4BAA4B,CAAC,CAoBvC;AAiED,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAElF;;;;;;;;;GASG;AACH,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,0BAA0B,CAAC;IACnC,IAAI,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAC1C,KAAK,EAAE,+BAA+B,GAAG,IAAI,CAAC;IAC9C,cAAc,EAAE,CACd,KAAK,EAAE,2BAA2B,EAClC,OAAO,CAAC,EAAE,cAAc,KACrB,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAC3C,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,IAAI,6BAA6B,CAyDvE"}

package/dist/esm/core/security/cross-frontend-handoff.frontend.service.js

@@ -0,0 +1,167 @@
+/**
+ * Cross-Frontend Handoff helper — first-party SaaS-app wrapper around
+ * `POST /api/v1/auth/cross-frontend-handoff` (cross-app-jwt-propagation Step 3).
+ *
+ * Two surfaces:
+ *
+ *   1. `requestCrossFrontendHandoff(input)` — vanilla TS / no React. Wraps the
+ *      manual-calls HTTP client, maps backend `CrossFrontendHandoffErrorCode`
+ *      values onto a typed `CrossFrontendHandoffClientError`, and returns the
+ *      `{ handoffUrl, expiresAt }` payload unchanged. The caller decides how
+ *      to use the URL (`location.assign` for replace, `window.open` for new
+ *      tab) — the helper deliberately does NOT navigate.
+ *
+ *   2. `useCrossFrontendHandoff()` — thin React hook wrapper for first-party
+ *      app components that want `{ status, data, error, requestHandoff, reset }`
+ *      ergonomics without bringing React Query in for a one-shot mutation.
+ *
+ * DTO atoms come from `@wildo-ai/saas-models/public-runtime`
+ * (saas-models-public-runtime.md K-7) so the same symbol identity used by the
+ * docs-site `docs-auth-client.ts` flows through here. The runtime call delegates
+ * to `getManualCallsHttpClient()`, which inherits the auth + frontend-service
+ * header injection performed by the base `WildoBackendHttpClient` interceptors.
+ *
+ * The bearer + `X-Frontend-Service-Name` header are injected automatically by
+ * the base client; callers do NOT need to thread them through.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { CrossFrontendHandoffErrorCode, } from '@wildo-ai/saas-models/public-runtime';
+import { getManualCallsHttpClient } from '../../core/requests/wildo-http-client-manual-calls.frontend.service.js';
+/**
+ * Typed error thrown by `requestCrossFrontendHandoff()` and stored in the
+ * `error` field of `useCrossFrontendHandoff()`.
+ *
+ * Subclasses native `Error` so `instanceof CrossFrontendHandoffClientError` is
+ * the safe way to distinguish from generic axios / network errors at a call
+ * site. The `code` discriminator is the contract surface that callers branch
+ * on; `httpStatus` is provided for telemetry / Sentry breadcrumbs only.
+ */
+export class CrossFrontendHandoffClientError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus) {
+        super(message);
+        this.name = 'CrossFrontendHandoffClientError';
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+/**
+ * Vanilla TS handoff request — no React.
+ *
+ * Behavior:
+ *   - On 2xx with a well-formed body, returns the response unchanged.
+ *   - On 2xx with a malformed body, throws `code: 'malformed_response'`.
+ *   - On 401, throws `code: 'unauthenticated'` regardless of the backend's
+ *     specific code (the base client may already have triggered a refresh-loop
+ *     before this branch is reached).
+ *   - On other 4xx with a recognized `error.details.code`, throws with that
+ *     `CrossFrontendHandoffErrorCode` code so the caller can branch on
+ *     `UNKNOWN_TARGET_FRONTEND` vs `TARGET_FRONTEND_HOST_NOT_CONFIGURED`.
+ *   - On 4xx/5xx without a recognized code, throws `code: 'malformed_response'`.
+ *   - On network failure (no response), throws `code: 'network'`.
+ *
+ * Pass-through `options` are forwarded to the underlying HTTP client; useful
+ * fields: `signal` (AbortController), `silent` (suppress global error toast).
+ */
+export async function requestCrossFrontendHandoff(input, options) {
+    let response;
+    try {
+        response = await getManualCallsHttpClient().crossFrontendHandoff(input, options);
+    }
+    catch (rawError) {
+        throw mapHandoffError(rawError);
+    }
+    if (!response ||
+        typeof response.handoffUrl !== 'string' ||
+        typeof response.expiresAt !== 'string') {
+        throw new CrossFrontendHandoffClientError('malformed_response', 'Cross-frontend handoff response missing required fields', null);
+    }
+    return { handoffUrl: response.handoffUrl, expiresAt: response.expiresAt };
+}
+const HANDOFF_ERROR_CODES = new Set(Object.values(CrossFrontendHandoffErrorCode));
+/**
+ * Internal — translate any thrown value (axios error, native Error, string,
+ * unknown) into a `CrossFrontendHandoffClientError`.
+ *
+ * The base client's `responseErrorInterceptor` mutates the axios error in
+ * place: it sets `error.httpStatus`, `error.context = nested.details`, and
+ * preserves the raw envelope on `error.response.data`. We read the raw
+ * envelope first (most reliable) and fall back to `error.context` second.
+ */
+function mapHandoffError(rawError) {
+    if (rawError instanceof CrossFrontendHandoffClientError)
+        return rawError;
+    const errorLike = rawError;
+    const httpStatus = typeof errorLike?.response?.status === 'number'
+        ? errorLike.response.status
+        : typeof errorLike?.httpStatus === 'number'
+            ? errorLike.httpStatus
+            : null;
+    if (httpStatus === null) {
+        return new CrossFrontendHandoffClientError('network', errorLike?.message ?? 'Cross-frontend handoff request failed (no response)', null);
+    }
+    if (httpStatus === 401) {
+        return new CrossFrontendHandoffClientError('unauthenticated', 'Cross-frontend handoff requires an authenticated session', 401);
+    }
+    const rawCode = errorLike?.response?.data?.error?.details?.code ??
+        errorLike?.context?.code;
+    if (typeof rawCode === 'string' && HANDOFF_ERROR_CODES.has(rawCode)) {
+        return new CrossFrontendHandoffClientError(rawCode, errorLike?.message ?? `Cross-frontend handoff failed (HTTP ${httpStatus})`, httpStatus);
+    }
+    return new CrossFrontendHandoffClientError('malformed_response', errorLike?.message ?? `Cross-frontend handoff failed (HTTP ${httpStatus})`, httpStatus);
+}
+/**
+ * React hook wrapper around `requestCrossFrontendHandoff()` for first-party
+ * SaaS-app components.
+ *
+ * Why not `useMutation` / `useReducer`: this is a one-shot, fire-and-forget
+ * mutation with no caching / invalidation needs; pulling React Query in for
+ * three lines of state would inflate the bundle and force a peer dep that
+ * `saas-frontend-lib` does not currently take. `useState` + `useCallback` +
+ * an `unmounted` guard cover the use case.
+ */
+export function useCrossFrontendHandoff() {
+    const [status, setStatus] = useState('idle');
+    const [data, setData] = useState(null);
+    const [error, setError] = useState(null);
+    const unmountedRef = useRef(false);
+    const callIdRef = useRef(0);
+    useEffect(() => {
+        unmountedRef.current = false;
+        return () => {
+            unmountedRef.current = true;
+        };
+    }, []);
+    const requestHandoff = useCallback(async (input, options) => {
+        const callId = ++callIdRef.current;
+        setStatus('pending');
+        setError(null);
+        try {
+            const response = await requestCrossFrontendHandoff(input, options);
+            if (!unmountedRef.current && callId === callIdRef.current) {
+                setData(response);
+                setStatus('success');
+            }
+            return response;
+        }
+        catch (rawError) {
+            const typedError = rawError instanceof CrossFrontendHandoffClientError
+                ? rawError
+                : new CrossFrontendHandoffClientError('malformed_response', rawError instanceof Error ? rawError.message : 'Cross-frontend handoff failed', null);
+            if (!unmountedRef.current && callId === callIdRef.current) {
+                setError(typedError);
+                setStatus('error');
+            }
+            throw typedError;
+        }
+    }, []);
+    const reset = useCallback(() => {
+        callIdRef.current++;
+        setStatus('idle');
+        setData(null);
+        setError(null);
+    }, []);
+    return { status, data, error, requestHandoff, reset };
+}
+//# sourceMappingURL=cross-frontend-handoff.frontend.service.js.map

package/dist/esm/core/security/cross-frontend-handoff.frontend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-frontend-handoff.frontend.service.js","sourceRoot":"","sources":["../../../../../src/core/security/cross-frontend-handoff.frontend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Cross-Frontend Handoff helper — first-party SaaS-app wrapper around\n * `POST /api/v1/auth/cross-frontend-handoff` (cross-app-jwt-propagation Step 3).\n *\n * Two surfaces:\n *\n *   1. `requestCrossFrontendHandoff(input)` — vanilla TS / no React. Wraps the\n *      manual-calls HTTP client, maps backend `CrossFrontendHandoffErrorCode`\n *      values onto a typed `CrossFrontendHandoffClientError`, and returns the\n *      `{ handoffUrl, expiresAt }` payload unchanged. The caller decides how\n *      to use the URL (`location.assign` for replace, `window.open` for new\n *      tab) — the helper deliberately does NOT navigate.\n *\n *   2. `useCrossFrontendHandoff()` — thin React hook wrapper for first-party\n *      app components that want `{ status, data, error, requestHandoff, reset }`\n *      ergonomics without bringing React Query in for a one-shot mutation.\n *\n * DTO atoms come from `@wildo-ai/saas-models/public-runtime`\n * (saas-models-public-runtime.md K-7) so the same symbol identity used by the\n * docs-site `docs-auth-client.ts` flows through here. The runtime call delegates\n * to `getManualCallsHttpClient()`, which inherits the auth + frontend-service\n * header injection performed by the base `WildoBackendHttpClient` interceptors.\n *\n * The bearer + `X-Frontend-Service-Name` header are injected automatically by\n * the base client; callers do NOT need to thread them through.\n */\n\nimport { useCallback, useEffect, useRef, useState } from 'react';\nimport {\n  CrossFrontendHandoffErrorCode,\n  type CrossFrontendHandoffRequest,\n  type CrossFrontendHandoffResponse,\n} from '@wildo-ai/saas-models/public-runtime';\nimport { getManualCallsHttpClient } from '~wildo-frontend-lib/core/requests/wildo-http-client-manual-calls.frontend.service';\nimport type { RequestOptions } from '~wildo-frontend-lib/core/requests/wildo-http-client.frontend.service';\n\n/**\n * Stable, finite set of error codes a SaaS-app caller may encounter when\n * invoking `requestCrossFrontendHandoff()`.\n *\n * Mirrors the backend enum 1:1 PLUS three runtime-only codes that never reach\n * the wire:\n *\n *   - `unauthenticated` — the caller's bearer is missing/expired/rejected\n *     (HTTP 401). Surfaced WITHOUT trying to parse a backend `code` so the\n *     caller can deep-link to login instead of branching on UNKNOWN_TARGET_*.\n *   - `network`        — no HTTP response was received (offline, DNS, CORS\n *     pre-flight rejection, etc.). The base client retried per its policy\n *     before this code is surfaced.\n *   - `malformed_response` — the request returned 2xx but the body did not\n *     match `CrossFrontendHandoffResponse`, OR the request returned an error\n *     body without a recognizable `error.details.code` field. Treat as a\n *     transient backend incident.\n */\nexport type CrossFrontendHandoffClientErrorCode =\n  | CrossFrontendHandoffErrorCode\n  | 'unauthenticated'\n  | 'network'\n  | 'malformed_response';\n\n/**\n * Typed error thrown by `requestCrossFrontendHandoff()` and stored in the\n * `error` field of `useCrossFrontendHandoff()`.\n *\n * Subclasses native `Error` so `instanceof CrossFrontendHandoffClientError` is\n * the safe way to distinguish from generic axios / network errors at a call\n * site. The `code` discriminator is the contract surface that callers branch\n * on; `httpStatus` is provided for telemetry / Sentry breadcrumbs only.\n */\nexport class CrossFrontendHandoffClientError extends Error {\n  readonly code: CrossFrontendHandoffClientErrorCode;\n  readonly httpStatus: number | null;\n\n  constructor(code: CrossFrontendHandoffClientErrorCode, message: string, httpStatus: number | null) {\n    super(message);\n    this.name = 'CrossFrontendHandoffClientError';\n    this.code = code;\n    this.httpStatus = httpStatus;\n  }\n}\n\n/**\n * Vanilla TS handoff request — no React.\n *\n * Behavior:\n *   - On 2xx with a well-formed body, returns the response unchanged.\n *   - On 2xx with a malformed body, throws `code: 'malformed_response'`.\n *   - On 401, throws `code: 'unauthenticated'` regardless of the backend's\n *     specific code (the base client may already have triggered a refresh-loop\n *     before this branch is reached).\n *   - On other 4xx with a recognized `error.details.code`, throws with that\n *     `CrossFrontendHandoffErrorCode` code so the caller can branch on\n *     `UNKNOWN_TARGET_FRONTEND` vs `TARGET_FRONTEND_HOST_NOT_CONFIGURED`.\n *   - On 4xx/5xx without a recognized code, throws `code: 'malformed_response'`.\n *   - On network failure (no response), throws `code: 'network'`.\n *\n * Pass-through `options` are forwarded to the underlying HTTP client; useful\n * fields: `signal` (AbortController), `silent` (suppress global error toast).\n */\nexport async function requestCrossFrontendHandoff(\n  input: CrossFrontendHandoffRequest,\n  options?: RequestOptions,\n): Promise<CrossFrontendHandoffResponse> {\n  let response: CrossFrontendHandoffResponse;\n  try {\n    response = await getManualCallsHttpClient().crossFrontendHandoff(input, options);\n  } catch (rawError: unknown) {\n    throw mapHandoffError(rawError);\n  }\n\n  if (\n    !response ||\n    typeof response.handoffUrl !== 'string' ||\n    typeof response.expiresAt !== 'string'\n  ) {\n    throw new CrossFrontendHandoffClientError(\n      'malformed_response',\n      'Cross-frontend handoff response missing required fields',\n      null,\n    );\n  }\n  return { handoffUrl: response.handoffUrl, expiresAt: response.expiresAt };\n}\n\nconst HANDOFF_ERROR_CODES = new Set<string>(Object.values(CrossFrontendHandoffErrorCode));\n\n/**\n * Internal — translate any thrown value (axios error, native Error, string,\n * unknown) into a `CrossFrontendHandoffClientError`.\n *\n * The base client's `responseErrorInterceptor` mutates the axios error in\n * place: it sets `error.httpStatus`, `error.context = nested.details`, and\n * preserves the raw envelope on `error.response.data`. We read the raw\n * envelope first (most reliable) and fall back to `error.context` second.\n */\nfunction mapHandoffError(rawError: unknown): CrossFrontendHandoffClientError {\n  if (rawError instanceof CrossFrontendHandoffClientError) return rawError;\n\n  const errorLike = rawError as {\n    response?: { status?: number; data?: { error?: { details?: { code?: unknown } } } };\n    httpStatus?: number;\n    context?: { code?: unknown };\n    message?: string;\n  } | null;\n\n  const httpStatus =\n    typeof errorLike?.response?.status === 'number'\n      ? errorLike.response.status\n      : typeof errorLike?.httpStatus === 'number'\n        ? errorLike.httpStatus\n        : null;\n\n  if (httpStatus === null) {\n    return new CrossFrontendHandoffClientError(\n      'network',\n      errorLike?.message ?? 'Cross-frontend handoff request failed (no response)',\n      null,\n    );\n  }\n\n  if (httpStatus === 401) {\n    return new CrossFrontendHandoffClientError(\n      'unauthenticated',\n      'Cross-frontend handoff requires an authenticated session',\n      401,\n    );\n  }\n\n  const rawCode =\n    errorLike?.response?.data?.error?.details?.code ??\n    errorLike?.context?.code;\n\n  if (typeof rawCode === 'string' && HANDOFF_ERROR_CODES.has(rawCode)) {\n    return new CrossFrontendHandoffClientError(\n      rawCode as CrossFrontendHandoffErrorCode,\n      errorLike?.message ?? `Cross-frontend handoff failed (HTTP ${httpStatus})`,\n      httpStatus,\n    );\n  }\n\n  return new CrossFrontendHandoffClientError(\n    'malformed_response',\n    errorLike?.message ?? `Cross-frontend handoff failed (HTTP ${httpStatus})`,\n    httpStatus,\n  );\n}\n\nexport type CrossFrontendHandoffStatus = 'idle' | 'pending' | 'success' | 'error';\n\n/**\n * State + action surface returned by `useCrossFrontendHandoff()`.\n *\n * `requestHandoff` returns the resolved `CrossFrontendHandoffResponse` on\n * success and re-throws the typed `CrossFrontendHandoffClientError` on failure\n * — so callers that need to redirect immediately can `await` it without also\n * subscribing to `status`. Hook state (`status` / `data` / `error`) is updated\n * regardless, which is convenient for components that render status without\n * holding a ref to the promise.\n */\nexport interface UseCrossFrontendHandoffResult {\n  status: CrossFrontendHandoffStatus;\n  data: CrossFrontendHandoffResponse | null;\n  error: CrossFrontendHandoffClientError | null;\n  requestHandoff: (\n    input: CrossFrontendHandoffRequest,\n    options?: RequestOptions,\n  ) => Promise<CrossFrontendHandoffResponse>;\n  reset: () => void;\n}\n\n/**\n * React hook wrapper around `requestCrossFrontendHandoff()` for first-party\n * SaaS-app components.\n *\n * Why not `useMutation` / `useReducer`: this is a one-shot, fire-and-forget\n * mutation with no caching / invalidation needs; pulling React Query in for\n * three lines of state would inflate the bundle and force a peer dep that\n * `saas-frontend-lib` does not currently take. `useState` + `useCallback` +\n * an `unmounted` guard cover the use case.\n */\nexport function useCrossFrontendHandoff(): UseCrossFrontendHandoffResult {\n  const [status, setStatus] = useState<CrossFrontendHandoffStatus>('idle');\n  const [data, setData] = useState<CrossFrontendHandoffResponse | null>(null);\n  const [error, setError] = useState<CrossFrontendHandoffClientError | null>(null);\n\n  const unmountedRef = useRef(false);\n  const callIdRef = useRef(0);\n\n  useEffect(() => {\n    unmountedRef.current = false;\n    return () => {\n      unmountedRef.current = true;\n    };\n  }, []);\n\n  const requestHandoff = useCallback(\n    async (\n      input: CrossFrontendHandoffRequest,\n      options?: RequestOptions,\n    ): Promise<CrossFrontendHandoffResponse> => {\n      const callId = ++callIdRef.current;\n      setStatus('pending');\n      setError(null);\n      try {\n        const response = await requestCrossFrontendHandoff(input, options);\n        if (!unmountedRef.current && callId === callIdRef.current) {\n          setData(response);\n          setStatus('success');\n        }\n        return response;\n      } catch (rawError: unknown) {\n        const typedError =\n          rawError instanceof CrossFrontendHandoffClientError\n            ? rawError\n            : new CrossFrontendHandoffClientError(\n                'malformed_response',\n                rawError instanceof Error ? rawError.message : 'Cross-frontend handoff failed',\n                null,\n              );\n        if (!unmountedRef.current && callId === callIdRef.current) {\n          setError(typedError);\n          setStatus('error');\n        }\n        throw typedError;\n      }\n    },\n    [],\n  );\n\n  const reset = useCallback(() => {\n    callIdRef.current++;\n    setStatus('idle');\n    setData(null);\n    setError(null);\n  }, []);\n\n  return { status, data, error, requestHandoff, reset };\n}\n"]}

package/dist/esm/core/security/jwt.frontend.utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../src/core/security/jwt.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,CAAC,CAO1F"}
+{"version":3,"file":"jwt.frontend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/core/security/jwt.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,CAAC,CAO1F"}

package/dist/esm/core/security/jwt.frontend.utils.js

@@ -25,4 +25,4 @@ export function decodeJwtPayload(accessToken) {
     }
     return JSON.parse(decodeBase64UrlToUtf8(tokenParts[1]));
 }
-//# sourceMappingURL=jwt.frontend.utils.js.map
+//# sourceMappingURL=jwt.frontend.utils.js.map

package/dist/esm/core/security/jwt.frontend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"jwt.frontend.utils.js","sourceRoot":"","sources":["../../../../src/core/security/jwt.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjE,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5E,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAoC,WAAmB;IACrF,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAM,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"jwt.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/security/jwt.frontend.utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,SAAS,qBAAqB,CAAC,OAAe;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACjE,MAAM,aAAa,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,GAAG,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IAE5E,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAoC,WAAmB;IACrF,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAM,CAAC;AAC/D,CAAC","sourcesContent":["/**\n * Frontend JWT utilities.\n *\n * JWT payload segments use base64url, not plain base64. Consumers that decode\n * payload claims must normalize `-` / `_` and padding before parsing.\n */\n\nfunction decodeBase64UrlToUtf8(segment: string): string {\n  const normalized = segment.replace(/-/g, '+').replace(/_/g, '/');\n  const paddingLength = (4 - (normalized.length % 4)) % 4;\n  const padded = `${normalized}${'='.repeat(paddingLength)}`;\n  const binary = atob(padded);\n  const bytes = Uint8Array.from(binary, character => character.charCodeAt(0));\n\n  return new TextDecoder().decode(bytes);\n}\n\n/**\n * Decode and parse the payload segment of a JWT access token.\n *\n * Throws when the token is malformed or when the payload is not valid JSON so\n * callers can apply context-specific logging/error handling policy.\n */\nexport function decodeJwtPayload<T extends Record<string, unknown>>(accessToken: string): T {\n  const tokenParts = accessToken.split('.');\n  if (tokenParts.length !== 3) {\n    throw new Error('JWT must contain exactly three segments');\n  }\n\n  return JSON.parse(decodeBase64UrlToUtf8(tokenParts[1])) as T;\n}\n"]}

package/dist/esm/core/security/security.frontend.schemas.d.ts

@@ -5,14 +5,24 @@
  */
 import { AuthIdentificationResponse, SessionType, type AuthMethod, type AvailableMethod, type AuthSessionPurpose } from '@wildo-ai/saas-models';
 /**
- * Authentication state - contains only authentication-related fields
+ * Authentication state — contains only authentication-related fields.
+ *
+ * **No `refreshToken` field** (Auth-hardening Slice A Step 6,
+ * 2026-04-13). Pre-Slice-A this carried `refreshToken: string | null`
+ * mirroring the legacy body-channel rotation contract. A-Step 2
+ * (cookie migration) made the cookie the sole owner of the refresh
+ * token, A-Step 3 stopped this state from being read by any consumer,
+ * and A-Step 6 dropped the field entirely. The refresh token now lives
+ * EXCLUSIVELY in the `__wildo_refresh` `HttpOnly` cookie — JS-invisible
+ * by design (XSS exfiltration surface closed). Consumers that want to
+ * "check if the user has a valid session" should look at `accessToken`
+ * (or `sessionRestored`) — never at the cookie, which is opaque to JS.
  */
 export interface AuthState {
     isLoading: boolean;
     error: string | null;
     sessionId: string | null;
     accessToken: string | null;
-    refreshToken: string | null;
     identification: AuthIdentificationResponse | null;
     sessionState: any | null;
     isRestoringSession: boolean;
@@ -35,6 +45,49 @@ export interface AuthState {
         scopedInitiatorIds?: Record<string, string>;
         applicationId?: string;
     };
+    /**
+     * cross-app-jwt-propagation.md Step 5: Context data populated when an
+     * AUTH_CODE_EXCHANGE token was minted by the cross-frontend-handoff issuer.
+     * `AuthSessionContext.handleAuthCodeExchange()` populates this field only
+     * when the token-exchange response carries a top-level `returnPath`; OAuth2
+     * callback codes omit that field and therefore leave this context undefined.
+     *
+     * Distinct from `oneOffContext` on purpose (semantic distinction over
+     * convenience — see `design-philosophy.mdc`):
+     *   - `oneOffContext` describes a W7.3b ephemeral one-off session
+     *     (resource-scoped targeting, applicationId, consumable replay).
+     *   - `crossFrontendHandoffContext` describes a session-transfer landing
+     *     (returnPath, source/target frontend telemetry). The session itself
+     *     is a regular persistent session driven by the receiver's storage
+     *     adapter (cross-app-jwt-propagation.md K-7).
+     *
+     * Consumed by `Auth_OneOffSession` in cross-frontend-handoff mode to drive
+     * post-exchange navigation (`returnPath`); also available to app-level
+     * telemetry hooks that want to know "this user just landed via a handoff
+     * from $sourceFrontendServiceName".
+     */
+    crossFrontendHandoffContext?: {
+        /**
+         * Path to navigate to after the exchange completes. Already passed
+         * `CrossFrontendHandoff_ReturnPathSchema` refines at issuance, but
+         * receivers MUST sanitize defense-in-depth (a malicious caller could
+         * hand-craft an exchange URL bypassing the issuer).
+         */
+        returnPath: string;
+        /**
+         * The frontend that initiated the handoff (e.g., `'admin-console'`).
+         * Optional because the source frontend identifies itself only via the
+         * `X-Frontend-Service-Name` request header (set by the shared HTTP
+         * client interceptor). Non-browser callers — server-to-server
+         * invocations, hand-crafted curl sessions — may legitimately omit
+         * the header (the issuer falls back to "unknown" source for audit
+         * purposes), in which case the receiver simply has no source
+         * identity to display in telemetry / breadcrumbs.
+         */
+        sourceFrontendServiceName?: string;
+        /** The target frontend the handoff was minted for. Useful for telemetry / breadcrumb rendering. */
+        targetServiceKey?: string;
+    };
 }
 /**
  * Effective permissions for the current user

package/dist/esm/core/security/security.frontend.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.frontend.schemas.d.ts","sourceRoot":"","sources":["../../../../src/core/security/security.frontend.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,0BAA0B,EAC1B,WAAW,EACX,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAClD,YAAY,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mBAAmB,EAAE,eAAe,EAAE,CAAC;IACvC,0BAA0B,EAAE,UAAU,EAAE,CAAC;IACzC,2BAA2B,EAAE,MAAM,EAAE,CAAC;IACtC,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACnC,oEAAoE;IACpE,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,wGAAwG;IACxG,aAAa,CAAC,EAAE;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAmB9B,CAAC;AAIF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC"}
+{"version":3,"file":"security.frontend.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/core/security/security.frontend.schemas.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EACL,0BAA0B,EAC1B,WAAW,EACX,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAClD,YAAY,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,mBAAmB,EAAE,eAAe,EAAE,CAAC;IACvC,0BAA0B,EAAE,UAAU,EAAE,CAAC;IACzC,2BAA2B,EAAE,MAAM,EAAE,CAAC;IACtC,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACnC,oEAAoE;IACpE,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,wGAAwG;IACxG,aAAa,CAAC,EAAE;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;QAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;QAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,2BAA2B,CAAC,EAAE;QAC5B;;;;;WAKG;QACH,UAAU,EAAE,MAAM,CAAC;QACnB;;;;;;;;;WASG;QACH,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,mGAAmG;QACnG,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAmB9B,CAAC;AAIF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAEpE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC"}

package/dist/esm/core/security/security.frontend.schemas.js

@@ -11,7 +11,6 @@ export const EMPTY_AUTH_STATE = {
     error: null,
     sessionId: null,
     accessToken: null,
-    refreshToken: null,
     identification: null,
     sessionState: null,
     isRestoringSession: false,
@@ -25,5 +24,6 @@ export const EMPTY_AUTH_STATE = {
     purpose: null,
     sessionType: null,
     oneOffContext: undefined,
+    crossFrontendHandoffContext: undefined,
 };
-//# sourceMappingURL=security.frontend.schemas.js.map
+//# sourceMappingURL=security.frontend.schemas.js.map