@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/runtime/decode-jwt-claims.js

@@ -0,0 +1,86 @@
+import { DocsJwtClaimsSchema, DocsRole, } from './docs-auth-session.schemas.js';
+/**
+ * Hand-rolled JWT-claims decoder for the docs-site auth runtime.
+ *
+ * Rationale (saas-technical-doc.md K-9b): the docs Docusaurus bundle is
+ * intentionally lean. Pulling in `jwt-decode` (or any general-purpose
+ * JWT library) for the SOLE purpose of base64-decoding the middle segment
+ * is a 30 KB+ bundle cost we refuse to pay for ~20 lines of code.
+ *
+ * SECURITY MODEL — important:
+ *
+ *   This decoder DOES NOT verify the JWT signature. It cannot — the
+ *   verification key lives on the backend, not in the browser bundle.
+ *   The decoded claims are treated as DISPLAY HINTS ONLY: the docs
+ *   navbar uses them to decide whether to render the "Organization API"
+ *   link, and the DocItem swizzle uses them to decide whether to gate
+ *   `/api/organization/*` pages.
+ *
+ *   The REAL gating happens server-side: the OpenAPI YAMLs for the
+ *   organization API are served by the backend behind the same
+ *   authorization decorators as the underlying resources. A user who
+ *   forges a JWT with `role: 'org_admin'` will see the docs navbar link
+ *   appear, but every actual API call from those docs to the backend
+ *   will still 401/403. The docs-site gating exists for UX, not security.
+ *
+ *   This is the SAME contract the SaaS app's frontend has: it decodes
+ *   the access-token claims for UI gating without verifying signatures,
+ *   and the backend is the authoritative authorizer.
+ *
+ * Returns `null` for any malformed input — never throws. The session
+ * context (`DocsAuthContext`) treats `null` as "fall back to anonymous"
+ * rather than surfacing a UI error, because by the time we are decoding
+ * the token we have already accepted it from the `/auth/token/exchange`
+ * response and the only remaining failure modes are clock skew, library
+ * mis-issuance, or actual tampering — none of which yield a useful error
+ * message at the docs-site level.
+ */
+export function decodeJwtClaims(token) {
+    const segments = token.split('.');
+    if (segments.length !== 3)
+        return null;
+    const payloadSegment = segments[1];
+    if (!payloadSegment)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(base64UrlDecode(payloadSegment));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    /**
+     * Normalize the raw role string → `DocsRole`.
+     *
+     * The access token's `role` claim can be any of the SaaS app's roles
+     * (`org_admin`, `org_member`, `app_user`, …); the docs site only cares
+     * about the org-admin / not-org-admin distinction (K-11).
+     */
+    const raw = parsed;
+    const rawRole = typeof raw.role === 'string' ? raw.role : '';
+    const role = rawRole === DocsRole.ORG_ADMIN ? DocsRole.ORG_ADMIN : DocsRole.OTHER;
+    const candidate = {
+        userId: typeof raw.userId === 'string' ? raw.userId : raw.sub,
+        email: typeof raw.email === 'string' ? raw.email : undefined,
+        role,
+        exp: typeof raw.exp === 'number' ? raw.exp : NaN,
+    };
+    const result = DocsJwtClaimsSchema.safeParse(candidate);
+    return result.success ? result.data : null;
+}
+/**
+ * Base64url → string. Pads the input to a multiple of 4 and translates
+ * `-`/`_` back to `+`/`/` before delegating to the platform's `atob`.
+ *
+ * `atob` is available in every browser and in Node ≥ 16 — both of which
+ * the docs site supports (Docusaurus build runs in Node, runtime in the
+ * browser).
+ */
+function base64UrlDecode(input) {
+    const padded = input + '='.repeat((4 - (input.length % 4)) % 4);
+    const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');
+    return atob(base64);
+}
+//# sourceMappingURL=decode-jwt-claims.js.map

package/dist/esm/runtime/decode-jwt-claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-jwt-claims.js","sourceRoot":"","sources":["../../../../src/runtime/decode-jwt-claims.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,QAAQ,GAET,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEvC,MAAM,cAAc,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,cAAc;QAAE,OAAO,IAAI,CAAC;IAEjC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC;IACvD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE/D;;;;;;OAMG;IACH,MAAM,GAAG,GAAG,MAAiC,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,MAAM,IAAI,GAAG,OAAO,KAAK,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;IAElF,MAAM,SAAS,GAAG;QAChB,MAAM,EAAE,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG;QAC7D,KAAK,EAAE,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;QAC5D,IAAI;QACJ,GAAG,EAAE,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG;KACjD,CAAC;IAEF,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IACxD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,MAAM,MAAM,GAAG,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC5D,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC","sourcesContent":["import {\n  DocsJwtClaimsSchema,\n  DocsRole,\n  type DocsJwtClaims,\n} from './docs-auth-session.schemas';\n\n/**\n * Hand-rolled JWT-claims decoder for the docs-site auth runtime.\n *\n * Rationale (saas-technical-doc.md K-9b): the docs Docusaurus bundle is\n * intentionally lean. Pulling in `jwt-decode` (or any general-purpose\n * JWT library) for the SOLE purpose of base64-decoding the middle segment\n * is a 30 KB+ bundle cost we refuse to pay for ~20 lines of code.\n *\n * SECURITY MODEL — important:\n *\n *   This decoder DOES NOT verify the JWT signature. It cannot — the\n *   verification key lives on the backend, not in the browser bundle.\n *   The decoded claims are treated as DISPLAY HINTS ONLY: the docs\n *   navbar uses them to decide whether to render the \"Organization API\"\n *   link, and the DocItem swizzle uses them to decide whether to gate\n *   `/api/organization/*` pages.\n *\n *   The REAL gating happens server-side: the OpenAPI YAMLs for the\n *   organization API are served by the backend behind the same\n *   authorization decorators as the underlying resources. A user who\n *   forges a JWT with `role: 'org_admin'` will see the docs navbar link\n *   appear, but every actual API call from those docs to the backend\n *   will still 401/403. The docs-site gating exists for UX, not security.\n *\n *   This is the SAME contract the SaaS app's frontend has: it decodes\n *   the access-token claims for UI gating without verifying signatures,\n *   and the backend is the authoritative authorizer.\n *\n * Returns `null` for any malformed input — never throws. The session\n * context (`DocsAuthContext`) treats `null` as \"fall back to anonymous\"\n * rather than surfacing a UI error, because by the time we are decoding\n * the token we have already accepted it from the `/auth/token/exchange`\n * response and the only remaining failure modes are clock skew, library\n * mis-issuance, or actual tampering — none of which yield a useful error\n * message at the docs-site level.\n */\nexport function decodeJwtClaims(token: string): DocsJwtClaims | null {\n  const segments = token.split('.');\n  if (segments.length !== 3) return null;\n\n  const payloadSegment = segments[1];\n  if (!payloadSegment) return null;\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(base64UrlDecode(payloadSegment));\n  } catch {\n    return null;\n  }\n\n  if (typeof parsed !== 'object' || parsed === null) return null;\n\n  /**\n   * Normalize the raw role string → `DocsRole`.\n   *\n   * The access token's `role` claim can be any of the SaaS app's roles\n   * (`org_admin`, `org_member`, `app_user`, …); the docs site only cares\n   * about the org-admin / not-org-admin distinction (K-11).\n   */\n  const raw = parsed as Record<string, unknown>;\n  const rawRole = typeof raw.role === 'string' ? raw.role : '';\n  const role = rawRole === DocsRole.ORG_ADMIN ? DocsRole.ORG_ADMIN : DocsRole.OTHER;\n\n  const candidate = {\n    userId: typeof raw.userId === 'string' ? raw.userId : raw.sub,\n    email: typeof raw.email === 'string' ? raw.email : undefined,\n    role,\n    exp: typeof raw.exp === 'number' ? raw.exp : NaN,\n  };\n\n  const result = DocsJwtClaimsSchema.safeParse(candidate);\n  return result.success ? result.data : null;\n}\n\n/**\n * Base64url → string. Pads the input to a multiple of 4 and translates\n * `-`/`_` back to `+`/`/` before delegating to the platform's `atob`.\n *\n * `atob` is available in every browser and in Node ≥ 16 — both of which\n * the docs site supports (Docusaurus build runs in Node, runtime in the\n * browser).\n */\nfunction base64UrlDecode(input: string): string {\n  const padded = input + '='.repeat((4 - (input.length % 4)) % 4);\n  const base64 = padded.replace(/-/g, '+').replace(/_/g, '/');\n  return atob(base64);\n}\n"]}

package/dist/esm/runtime/docs-auth-client.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Imports come from `@wildo-ai/saas-models/public-runtime` — NOT the root
+ * barrel (saas-models-public-runtime.md K-7).
+ *
+ * Why the subpath matters here: the root barrel pulls the full ~150-
+ * schema graph (resources, presets, business semantics, …) — none of
+ * which the docs Docusaurus bundle consumes. The `/public-runtime`
+ * subpath exposes just the handful of atoms the docs auth runtime
+ * actually reads (cross-frontend-handoff DTOs, token-exchange response).
+ *
+ * The Zod decorator augmentation itself (the augmented `ZodObject`
+ * interface authored by `@wildo-ai/zod-decorators`) IS booted by the
+ * docs runtime — see `runtime/index.ts`'s `ensureZodDecoratorsLoaded(z)`
+ * side-effect. That guarantees `z.infer<…>` results in this bundle
+ * match what the SaaS app sees (the cross-package agreement that H-3 /
+ * M-7 turned out to depend on).
+ *
+ * Do NOT change this import to the root barrel — the
+ * `engine/saas-technical-doc/__tests__/runtime-bundle-isolation.test.ts`
+ * boundary test will fail.
+ */
+import { CrossFrontendHandoffErrorCode, type CrossFrontendHandoffRequest, type CrossFrontendHandoffResponse, type TokenExchangeResponse } from '@wildo-ai/saas-models/public-runtime';
+/**
+ * Lightweight, fetch-based HTTP client used by the docs Docusaurus runtime
+ * (saas-technical-doc.md K-9b).
+ *
+ * Knows EXACTLY two endpoints:
+ *   - `POST /api/v1/auth/token/exchange`         — consumes an
+ *                                                  `AUTH_CODE_EXCHANGE` code
+ *                                                  arriving on `?code=…`.
+ *   - `POST /api/v1/auth/cross-frontend-handoff` — issues a one-time code for
+ *                                                  an already-authenticated docs
+ *                                                  session to move to another
+ *                                                  frontend.
+ *
+ * Deliberately does NOT include:
+ *   - Axios / inversify / a resource registry  (would balloon the bundle).
+ *   - Request interceptors                     (no refresh loop here — see
+ *                                              K-9b's "no refresh loop" rule).
+ *   - Retries / backoff                        (the docs site is read-mostly;
+ *                                              if a network call fails the
+ *                                              session falls back to anonymous).
+ *   - Any cookie / `withCredentials: true`    (the platform is bearer-only;
+ *                                              the cookie story belongs to
+ *                                              auth-hardening.md Slice A
+ *                                              which is `SAAS_APP`-scoped).
+ *
+ * SSR / build-time safety: the constructor does not touch `window`, `document`,
+ * `localStorage`, or `fetch`. `fetch` is only called inside the two methods,
+ * which are only invoked from React effects (always client-side under
+ * Docusaurus). This makes the class safe to import from a Docusaurus theme
+ * file that gets evaluated during the static build.
+ */
+export declare class DocsAuthClient {
+    private readonly apiBaseUrl;
+    private readonly getAuthBearer;
+    private readonly frontendServiceName;
+    constructor(args: {
+        /**
+         * Origin of the SaaS backend API (e.g. `https://app.example.com` or
+         * `https://api.example.com` depending on the app's ingress topology).
+         * This is a backend ORIGIN, not an `/api/v1` root. A trailing `/api/v1`
+         * is tolerated and normalized away to avoid double-prefixing.
+         *
+         * Authored by the docs site at runtime from `appConfig.runtime.endPoints
+         * .main_backend_api.publicUrl` — the same shape `saas-frontend-lib`
+         * reads. Trailing slashes are tolerated and stripped by the constructor.
+         */
+        apiBaseUrl: string;
+        /**
+         * Returns the current access token to attach as `Authorization: Bearer …`
+         * on the cross-frontend-handoff request.
+         *
+         * The exchange endpoint (`/api/v1/auth/token/exchange`) does NOT require a
+         * bearer — the `code` itself is the credential — so this callback is
+         * only consulted by `requestCrossFrontendHandoff()`.
+         *
+         * Returning `null` signals "no session"; in that case
+         * `requestCrossFrontendHandoff` rejects synchronously with an
+         * `'unauthenticated'` error rather than calling the network. This
+         * matches the docs site's intended UX (the DocItem swizzle handles
+         * anonymous users by deep-linking the SaaS app's login, not by
+         * calling the handoff endpoint).
+         */
+        getAuthBearer?: () => string | null;
+        /**
+         * Runtime frontend service identity. Required for redeeming handoff-issued
+         * AUTH_CODE_EXCHANGE codes because the backend binds each code to the
+         * intended target service at redemption time. Optional for tests and for
+         * non-handoff OAuth2-like exchanges.
+         */
+        frontendServiceName?: string | null;
+    });
+    /**
+     * Consume an `AUTH_CODE_EXCHANGE` consumable token (60s TTL) and receive
+     * a fresh JWT pair plus the cross-frontend-handoff context fields.
+     *
+     * Called by `<AuthExchangePage>` when the user lands on
+     * `/auth/exchange?code=…&return=…` after a cross-frontend handoff.
+     *
+     * Returns the full `TokenExchangeResponseSchema` shape (sourced from
+     * `@wildo-ai/saas-models/public-runtime`) — including the optional
+     * top-level `returnPath`, `sourceFrontendServiceName`, and
+     * `targetServiceKey` fields populated by the issuer for handoff-issued
+     * codes (cross-app-jwt-propagation.md Step 5). These three fields live
+     * at the TOP LEVEL of the response — there is intentionally NO
+     * `metadata` envelope (the discriminator invariant pinned by
+     * `TokenExchangeResponseSchema` JSDoc says: presence of `returnPath`
+     * marks the response as a cross-frontend handoff vs. an OAuth2
+     * callback). The exchange page treats `returnPath` as the SOURCE OF
+     * TRUTH for navigation — the URL `?return=` value is kept only as a
+     * defense-in-depth fallback when the response omits it.
+     *
+     * Maps the backend's stable `AUTHENTICATION_INVALID_TOKEN` error onto
+     * a `DocsAuthClientError` with `code: 'invalid_or_expired_code'` so the
+     * exchange page can render a clean "this link expired — please re-open
+     * docs from the app" message without leaking backend wording.
+     *
+     * Bundle note: `TokenExchangeResponseSchema.safeParse` is bundle-safe
+     * because the schema is exported from `@wildo-ai/saas-models/public-runtime`,
+     * which is already on the runtime allow-list — see
+     * `runtime-bundle-isolation.test.ts`.
+     */
+    exchangeAuthCode(code: string): Promise<TokenExchangeResponse>;
+    /**
+     * Ask the SaaS backend to issue a one-time code that hands the current
+     * session to a target frontend service (typically the SaaS app itself).
+     *
+     * This method is only usable when the docs tab already holds an access
+     * token. Anonymous docs visitors cannot call the endpoint; the Wonder Todos
+     * swizzle deep-links them to the SaaS app instead, where login/session
+     * ownership lives.
+     *
+     * The error surface mirrors the backend's `CrossFrontendHandoffErrorCode`
+     * enum 1:1 — the swizzle can branch on `error.code` to render the right
+     * "configuration is wrong, contact support" message
+     * (UNKNOWN_TARGET_FRONTEND, TARGET_FRONTEND_HOST_NOT_CONFIGURED).
+     */
+    requestCrossFrontendHandoff(request: CrossFrontendHandoffRequest): Promise<CrossFrontendHandoffResponse>;
+    /**
+     * Best-effort parse of the backend's `{ error: { details: { code, … } } }`
+     * envelope.
+     *
+     * The path is `error.details.code` (NOT `error.code`) — see the
+     * `error-handler.backend.service.ts` response shape, which spreads
+     * `sanitizedError.context` under `details`. The error builder's
+     * sanitization allowlist explicitly promotes `code` so cross-frontend
+     * handoff failures expose the stable `CrossFrontendHandoffErrorCode`
+     * enum value (cross-app-jwt-propagation.md C-4 contract).
+     *
+     * Falls back to `'malformed_response'` when the body is missing or its
+     * `error.details.code` is not a known `CrossFrontendHandoffErrorCode`.
+     * This keeps the client side strictly typed (`DocsAuthClientErrorCode`)
+     * even when faced with a transitional / proxy / CDN response that does
+     * not match the platform envelope.
+     */
+    private parseHandoffErrorCode;
+    private joinUrl;
+}
+/**
+ * Stable, finite set of error codes the runtime can surface to the
+ * Docusaurus swizzles + `<AuthExchangePage>`.
+ *
+ * Mirrors `CrossFrontendHandoffErrorCode` for the handoff path PLUS three
+ * runtime-only codes:
+ *
+ *   - `unauthenticated`           — the caller asked for a handoff while no
+ *                                   session was loaded; surfaced WITHOUT a
+ *                                   network call so the DocItem swizzle can
+ *                                   redirect to the SaaS app's login instead.
+ *   - `invalid_or_expired_code`   — the `/api/v1/auth/token/exchange` call returned
+ *                                   non-200; covers expired, already-consumed,
+ *                                   or otherwise rejected codes.
+ *   - `malformed_response`        — a transport / CDN / parser hiccup; rare,
+ *                                   but typed so the swizzle never has to
+ *                                   handle "untyped error" branches.
+ */
+export type DocsAuthClientErrorCode = CrossFrontendHandoffErrorCode | 'unauthenticated' | 'invalid_or_expired_code' | 'malformed_response';
+/**
+ * Typed error thrown by every `DocsAuthClient` method.
+ *
+ * Subclasses native `Error` (not `WildoBackendError`) on purpose — pulling
+ * `WildoBackendError` here would force a dependency on `@wildo-ai/saas-models`
+ * runtime utilities that the docs bundle has no other use for. The
+ * swizzles `instanceof DocsAuthClientError` to distinguish from generic
+ * fetch/abort errors.
+ */
+export declare class DocsAuthClientError extends Error {
+    readonly code: DocsAuthClientErrorCode;
+    readonly httpStatus: number;
+    constructor(code: DocsAuthClientErrorCode, message: string, httpStatus: number);
+}
+//# sourceMappingURL=docs-auth-client.d.ts.map

package/dist/esm/runtime/docs-auth-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-auth-client.d.ts","sourceRoot":"","sources":["../../../../src/runtime/docs-auth-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,6BAA6B,EAK7B,KAAK,2BAA2B,EAChC,KAAK,4BAA4B,EACjC,KAAK,qBAAqB,EAC3B,MAAM,sCAAsC,CAAC;AAM9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAsB;IACpD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAgB;gBAExC,IAAI,EAAE;QAChB;;;;;;;;;WASG;QACH,UAAU,EAAE,MAAM,CAAC;QAEnB;;;;;;;;;;;;;;WAcG;QACH,aAAa,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;QACpC;;;;;WAKG;QACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACrC;IAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA+BpE;;;;;;;;;;;;;OAaG;IACG,2BAA2B,CAC/B,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,4BAA4B,CAAC;IAwCxC;;;;;;;;;;;;;;;;OAgBG;YACW,qBAAqB;IAkBnC,OAAO,CAAC,OAAO;CAGhB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,uBAAuB,GAC/B,6BAA6B,GAC7B,iBAAiB,GACjB,yBAAyB,GACzB,oBAAoB,CAAC;AAEzB;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAM/E"}

package/dist/esm/runtime/docs-auth-client.js

@@ -0,0 +1,211 @@
+/**
+ * Imports come from `@wildo-ai/saas-models/public-runtime` — NOT the root
+ * barrel (saas-models-public-runtime.md K-7).
+ *
+ * Why the subpath matters here: the root barrel pulls the full ~150-
+ * schema graph (resources, presets, business semantics, …) — none of
+ * which the docs Docusaurus bundle consumes. The `/public-runtime`
+ * subpath exposes just the handful of atoms the docs auth runtime
+ * actually reads (cross-frontend-handoff DTOs, token-exchange response).
+ *
+ * The Zod decorator augmentation itself (the augmented `ZodObject`
+ * interface authored by `@wildo-ai/zod-decorators`) IS booted by the
+ * docs runtime — see `runtime/index.ts`'s `ensureZodDecoratorsLoaded(z)`
+ * side-effect. That guarantees `z.infer<…>` results in this bundle
+ * match what the SaaS app sees (the cross-package agreement that H-3 /
+ * M-7 turned out to depend on).
+ *
+ * Do NOT change this import to the root barrel — the
+ * `engine/saas-technical-doc/__tests__/runtime-bundle-isolation.test.ts`
+ * boundary test will fail.
+ */
+import { CrossFrontendHandoffErrorCode, MAIN_API_BASE_PATH, TokenExchangeRequestSchema, TokenExchangeResponseSchema, WildoHeaderKeys, } from '@wildo-ai/saas-models/public-runtime';
+const MANUAL_API_PREFIX = MAIN_API_BASE_PATH;
+const TOKEN_EXCHANGE_PATH = `${MANUAL_API_PREFIX}/auth/token/exchange`;
+const CROSS_FRONTEND_HANDOFF_PATH = `${MANUAL_API_PREFIX}/auth/cross-frontend-handoff`;
+/**
+ * Lightweight, fetch-based HTTP client used by the docs Docusaurus runtime
+ * (saas-technical-doc.md K-9b).
+ *
+ * Knows EXACTLY two endpoints:
+ *   - `POST /api/v1/auth/token/exchange`         — consumes an
+ *                                                  `AUTH_CODE_EXCHANGE` code
+ *                                                  arriving on `?code=…`.
+ *   - `POST /api/v1/auth/cross-frontend-handoff` — issues a one-time code for
+ *                                                  an already-authenticated docs
+ *                                                  session to move to another
+ *                                                  frontend.
+ *
+ * Deliberately does NOT include:
+ *   - Axios / inversify / a resource registry  (would balloon the bundle).
+ *   - Request interceptors                     (no refresh loop here — see
+ *                                              K-9b's "no refresh loop" rule).
+ *   - Retries / backoff                        (the docs site is read-mostly;
+ *                                              if a network call fails the
+ *                                              session falls back to anonymous).
+ *   - Any cookie / `withCredentials: true`    (the platform is bearer-only;
+ *                                              the cookie story belongs to
+ *                                              auth-hardening.md Slice A
+ *                                              which is `SAAS_APP`-scoped).
+ *
+ * SSR / build-time safety: the constructor does not touch `window`, `document`,
+ * `localStorage`, or `fetch`. `fetch` is only called inside the two methods,
+ * which are only invoked from React effects (always client-side under
+ * Docusaurus). This makes the class safe to import from a Docusaurus theme
+ * file that gets evaluated during the static build.
+ */
+export class DocsAuthClient {
+    apiBaseUrl;
+    getAuthBearer;
+    frontendServiceName;
+    constructor(args) {
+        this.apiBaseUrl = args.apiBaseUrl.replace(/\/+$/, '').replace(/\/api\/v1$/, '');
+        this.getAuthBearer = args.getAuthBearer ?? (() => null);
+        this.frontendServiceName = args.frontendServiceName ?? null;
+    }
+    /**
+     * Consume an `AUTH_CODE_EXCHANGE` consumable token (60s TTL) and receive
+     * a fresh JWT pair plus the cross-frontend-handoff context fields.
+     *
+     * Called by `<AuthExchangePage>` when the user lands on
+     * `/auth/exchange?code=…&return=…` after a cross-frontend handoff.
+     *
+     * Returns the full `TokenExchangeResponseSchema` shape (sourced from
+     * `@wildo-ai/saas-models/public-runtime`) — including the optional
+     * top-level `returnPath`, `sourceFrontendServiceName`, and
+     * `targetServiceKey` fields populated by the issuer for handoff-issued
+     * codes (cross-app-jwt-propagation.md Step 5). These three fields live
+     * at the TOP LEVEL of the response — there is intentionally NO
+     * `metadata` envelope (the discriminator invariant pinned by
+     * `TokenExchangeResponseSchema` JSDoc says: presence of `returnPath`
+     * marks the response as a cross-frontend handoff vs. an OAuth2
+     * callback). The exchange page treats `returnPath` as the SOURCE OF
+     * TRUTH for navigation — the URL `?return=` value is kept only as a
+     * defense-in-depth fallback when the response omits it.
+     *
+     * Maps the backend's stable `AUTHENTICATION_INVALID_TOKEN` error onto
+     * a `DocsAuthClientError` with `code: 'invalid_or_expired_code'` so the
+     * exchange page can render a clean "this link expired — please re-open
+     * docs from the app" message without leaking backend wording.
+     *
+     * Bundle note: `TokenExchangeResponseSchema.safeParse` is bundle-safe
+     * because the schema is exported from `@wildo-ai/saas-models/public-runtime`,
+     * which is already on the runtime allow-list — see
+     * `runtime-bundle-isolation.test.ts`.
+     */
+    async exchangeAuthCode(code) {
+        const headers = { 'content-type': 'application/json' };
+        if (this.frontendServiceName) {
+            headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] = this.frontendServiceName;
+        }
+        const response = await fetch(this.joinUrl(TOKEN_EXCHANGE_PATH), {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(TokenExchangeRequestSchema.parse({ code })),
+        });
+        if (!response.ok) {
+            throw new DocsAuthClientError('invalid_or_expired_code', `Token exchange failed (HTTP ${response.status})`, response.status);
+        }
+        const parsed = TokenExchangeResponseSchema.safeParse(await response.json());
+        if (!parsed.success) {
+            throw new DocsAuthClientError('invalid_or_expired_code', 'Token exchange response failed schema validation', response.status);
+        }
+        return parsed.data;
+    }
+    /**
+     * Ask the SaaS backend to issue a one-time code that hands the current
+     * session to a target frontend service (typically the SaaS app itself).
+     *
+     * This method is only usable when the docs tab already holds an access
+     * token. Anonymous docs visitors cannot call the endpoint; the Wonder Todos
+     * swizzle deep-links them to the SaaS app instead, where login/session
+     * ownership lives.
+     *
+     * The error surface mirrors the backend's `CrossFrontendHandoffErrorCode`
+     * enum 1:1 — the swizzle can branch on `error.code` to render the right
+     * "configuration is wrong, contact support" message
+     * (UNKNOWN_TARGET_FRONTEND, TARGET_FRONTEND_HOST_NOT_CONFIGURED).
+     */
+    async requestCrossFrontendHandoff(request) {
+        const bearer = this.getAuthBearer();
+        if (!bearer) {
+            throw new DocsAuthClientError('unauthenticated', 'Cross-frontend handoff requires an authenticated docs session', 401);
+        }
+        const response = await fetch(this.joinUrl(CROSS_FRONTEND_HANDOFF_PATH), {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${bearer}`,
+                ...(this.frontendServiceName ? { [WildoHeaderKeys.FRONTEND_SERVICE_NAME]: this.frontendServiceName } : {}),
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const code = await this.parseHandoffErrorCode(response);
+            throw new DocsAuthClientError(code, `Cross-frontend handoff failed (HTTP ${response.status})`, response.status);
+        }
+        const json = (await response.json());
+        if (typeof json.handoffUrl !== 'string' || typeof json.expiresAt !== 'string') {
+            throw new DocsAuthClientError('malformed_response', 'Cross-frontend handoff response missing required fields', response.status);
+        }
+        return { handoffUrl: json.handoffUrl, expiresAt: json.expiresAt };
+    }
+    /**
+     * Best-effort parse of the backend's `{ error: { details: { code, … } } }`
+     * envelope.
+     *
+     * The path is `error.details.code` (NOT `error.code`) — see the
+     * `error-handler.backend.service.ts` response shape, which spreads
+     * `sanitizedError.context` under `details`. The error builder's
+     * sanitization allowlist explicitly promotes `code` so cross-frontend
+     * handoff failures expose the stable `CrossFrontendHandoffErrorCode`
+     * enum value (cross-app-jwt-propagation.md C-4 contract).
+     *
+     * Falls back to `'malformed_response'` when the body is missing or its
+     * `error.details.code` is not a known `CrossFrontendHandoffErrorCode`.
+     * This keeps the client side strictly typed (`DocsAuthClientErrorCode`)
+     * even when faced with a transitional / proxy / CDN response that does
+     * not match the platform envelope.
+     */
+    async parseHandoffErrorCode(response) {
+        let body;
+        try {
+            body = await response.json();
+        }
+        catch {
+            return 'malformed_response';
+        }
+        const code = body
+            ?.error?.details?.code;
+        if (typeof code !== 'string')
+            return 'malformed_response';
+        const handoffCodes = Object.values(CrossFrontendHandoffErrorCode);
+        if (handoffCodes.includes(code)) {
+            return code;
+        }
+        return 'malformed_response';
+    }
+    joinUrl(path) {
+        return `${this.apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    }
+}
+/**
+ * Typed error thrown by every `DocsAuthClient` method.
+ *
+ * Subclasses native `Error` (not `WildoBackendError`) on purpose — pulling
+ * `WildoBackendError` here would force a dependency on `@wildo-ai/saas-models`
+ * runtime utilities that the docs bundle has no other use for. The
+ * swizzles `instanceof DocsAuthClientError` to distinguish from generic
+ * fetch/abort errors.
+ */
+export class DocsAuthClientError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus) {
+        super(message);
+        this.name = 'DocsAuthClientError';
+        this.code = code;
+        this.httpStatus = httpStatus;
+    }
+}
+//# sourceMappingURL=docs-auth-client.js.map

package/dist/esm/runtime/docs-auth-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-auth-client.js","sourceRoot":"","sources":["../../../../src/runtime/docs-auth-client.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Imports come from `@wildo-ai/saas-models/public-runtime` — NOT the root\n * barrel (saas-models-public-runtime.md K-7).\n *\n * Why the subpath matters here: the root barrel pulls the full ~150-\n * schema graph (resources, presets, business semantics, …) — none of\n * which the docs Docusaurus bundle consumes. The `/public-runtime`\n * subpath exposes just the handful of atoms the docs auth runtime\n * actually reads (cross-frontend-handoff DTOs, token-exchange response).\n *\n * The Zod decorator augmentation itself (the augmented `ZodObject`\n * interface authored by `@wildo-ai/zod-decorators`) IS booted by the\n * docs runtime — see `runtime/index.ts`'s `ensureZodDecoratorsLoaded(z)`\n * side-effect. That guarantees `z.infer<…>` results in this bundle\n * match what the SaaS app sees (the cross-package agreement that H-3 /\n * M-7 turned out to depend on).\n *\n * Do NOT change this import to the root barrel — the\n * `engine/saas-technical-doc/__tests__/runtime-bundle-isolation.test.ts`\n * boundary test will fail.\n */\nimport {\n  CrossFrontendHandoffErrorCode,\n  MAIN_API_BASE_PATH,\n  TokenExchangeRequestSchema,\n  TokenExchangeResponseSchema,\n  WildoHeaderKeys,\n  type CrossFrontendHandoffRequest,\n  type CrossFrontendHandoffResponse,\n  type TokenExchangeResponse,\n} from '@wildo-ai/saas-models/public-runtime';\n\nconst MANUAL_API_PREFIX = MAIN_API_BASE_PATH;\nconst TOKEN_EXCHANGE_PATH = `${MANUAL_API_PREFIX}/auth/token/exchange`;\nconst CROSS_FRONTEND_HANDOFF_PATH = `${MANUAL_API_PREFIX}/auth/cross-frontend-handoff`;\n\n/**\n * Lightweight, fetch-based HTTP client used by the docs Docusaurus runtime\n * (saas-technical-doc.md K-9b).\n *\n * Knows EXACTLY two endpoints:\n *   - `POST /api/v1/auth/token/exchange`         — consumes an\n *                                                  `AUTH_CODE_EXCHANGE` code\n *                                                  arriving on `?code=…`.\n *   - `POST /api/v1/auth/cross-frontend-handoff` — issues a one-time code for\n *                                                  an already-authenticated docs\n *                                                  session to move to another\n *                                                  frontend.\n *\n * Deliberately does NOT include:\n *   - Axios / inversify / a resource registry  (would balloon the bundle).\n *   - Request interceptors                     (no refresh loop here — see\n *                                              K-9b's \"no refresh loop\" rule).\n *   - Retries / backoff                        (the docs site is read-mostly;\n *                                              if a network call fails the\n *                                              session falls back to anonymous).\n *   - Any cookie / `withCredentials: true`    (the platform is bearer-only;\n *                                              the cookie story belongs to\n *                                              auth-hardening.md Slice A\n *                                              which is `SAAS_APP`-scoped).\n *\n * SSR / build-time safety: the constructor does not touch `window`, `document`,\n * `localStorage`, or `fetch`. `fetch` is only called inside the two methods,\n * which are only invoked from React effects (always client-side under\n * Docusaurus). This makes the class safe to import from a Docusaurus theme\n * file that gets evaluated during the static build.\n */\nexport class DocsAuthClient {\n  private readonly apiBaseUrl: string;\n  private readonly getAuthBearer: () => string | null;\n  private readonly frontendServiceName: string | null;\n\n  constructor(args: {\n    /**\n     * Origin of the SaaS backend API (e.g. `https://app.example.com` or\n     * `https://api.example.com` depending on the app's ingress topology).\n     * This is a backend ORIGIN, not an `/api/v1` root. A trailing `/api/v1`\n     * is tolerated and normalized away to avoid double-prefixing.\n     *\n     * Authored by the docs site at runtime from `appConfig.runtime.endPoints\n     * .main_backend_api.publicUrl` — the same shape `saas-frontend-lib`\n     * reads. Trailing slashes are tolerated and stripped by the constructor.\n     */\n    apiBaseUrl: string;\n\n    /**\n     * Returns the current access token to attach as `Authorization: Bearer …`\n     * on the cross-frontend-handoff request.\n     *\n     * The exchange endpoint (`/api/v1/auth/token/exchange`) does NOT require a\n     * bearer — the `code` itself is the credential — so this callback is\n     * only consulted by `requestCrossFrontendHandoff()`.\n     *\n     * Returning `null` signals \"no session\"; in that case\n     * `requestCrossFrontendHandoff` rejects synchronously with an\n     * `'unauthenticated'` error rather than calling the network. This\n     * matches the docs site's intended UX (the DocItem swizzle handles\n     * anonymous users by deep-linking the SaaS app's login, not by\n     * calling the handoff endpoint).\n     */\n    getAuthBearer?: () => string | null;\n    /**\n     * Runtime frontend service identity. Required for redeeming handoff-issued\n     * AUTH_CODE_EXCHANGE codes because the backend binds each code to the\n     * intended target service at redemption time. Optional for tests and for\n     * non-handoff OAuth2-like exchanges.\n     */\n    frontendServiceName?: string | null;\n  }) {\n    this.apiBaseUrl = args.apiBaseUrl.replace(/\\/+$/, '').replace(/\\/api\\/v1$/, '');\n    this.getAuthBearer = args.getAuthBearer ?? (() => null);\n    this.frontendServiceName = args.frontendServiceName ?? null;\n  }\n\n  /**\n   * Consume an `AUTH_CODE_EXCHANGE` consumable token (60s TTL) and receive\n   * a fresh JWT pair plus the cross-frontend-handoff context fields.\n   *\n   * Called by `<AuthExchangePage>` when the user lands on\n   * `/auth/exchange?code=…&return=…` after a cross-frontend handoff.\n   *\n   * Returns the full `TokenExchangeResponseSchema` shape (sourced from\n   * `@wildo-ai/saas-models/public-runtime`) — including the optional\n   * top-level `returnPath`, `sourceFrontendServiceName`, and\n   * `targetServiceKey` fields populated by the issuer for handoff-issued\n   * codes (cross-app-jwt-propagation.md Step 5). These three fields live\n   * at the TOP LEVEL of the response — there is intentionally NO\n   * `metadata` envelope (the discriminator invariant pinned by\n   * `TokenExchangeResponseSchema` JSDoc says: presence of `returnPath`\n   * marks the response as a cross-frontend handoff vs. an OAuth2\n   * callback). The exchange page treats `returnPath` as the SOURCE OF\n   * TRUTH for navigation — the URL `?return=` value is kept only as a\n   * defense-in-depth fallback when the response omits it.\n   *\n   * Maps the backend's stable `AUTHENTICATION_INVALID_TOKEN` error onto\n   * a `DocsAuthClientError` with `code: 'invalid_or_expired_code'` so the\n   * exchange page can render a clean \"this link expired — please re-open\n   * docs from the app\" message without leaking backend wording.\n   *\n   * Bundle note: `TokenExchangeResponseSchema.safeParse` is bundle-safe\n   * because the schema is exported from `@wildo-ai/saas-models/public-runtime`,\n   * which is already on the runtime allow-list — see\n   * `runtime-bundle-isolation.test.ts`.\n   */\n  async exchangeAuthCode(code: string): Promise<TokenExchangeResponse> {\n    const headers: Record<string, string> = { 'content-type': 'application/json' };\n    if (this.frontendServiceName) {\n      headers[WildoHeaderKeys.FRONTEND_SERVICE_NAME] = this.frontendServiceName;\n    }\n\n    const response = await fetch(this.joinUrl(TOKEN_EXCHANGE_PATH), {\n      method: 'POST',\n      headers,\n      body: JSON.stringify(TokenExchangeRequestSchema.parse({ code })),\n    });\n\n    if (!response.ok) {\n      throw new DocsAuthClientError(\n        'invalid_or_expired_code',\n        `Token exchange failed (HTTP ${response.status})`,\n        response.status,\n      );\n    }\n\n    const parsed = TokenExchangeResponseSchema.safeParse(await response.json());\n    if (!parsed.success) {\n      throw new DocsAuthClientError(\n        'invalid_or_expired_code',\n        'Token exchange response failed schema validation',\n        response.status,\n      );\n    }\n    return parsed.data;\n  }\n\n  /**\n   * Ask the SaaS backend to issue a one-time code that hands the current\n   * session to a target frontend service (typically the SaaS app itself).\n   *\n   * This method is only usable when the docs tab already holds an access\n   * token. Anonymous docs visitors cannot call the endpoint; the Wonder Todos\n   * swizzle deep-links them to the SaaS app instead, where login/session\n   * ownership lives.\n   *\n   * The error surface mirrors the backend's `CrossFrontendHandoffErrorCode`\n   * enum 1:1 — the swizzle can branch on `error.code` to render the right\n   * \"configuration is wrong, contact support\" message\n   * (UNKNOWN_TARGET_FRONTEND, TARGET_FRONTEND_HOST_NOT_CONFIGURED).\n   */\n  async requestCrossFrontendHandoff(\n    request: CrossFrontendHandoffRequest,\n  ): Promise<CrossFrontendHandoffResponse> {\n    const bearer = this.getAuthBearer();\n    if (!bearer) {\n      throw new DocsAuthClientError(\n        'unauthenticated',\n        'Cross-frontend handoff requires an authenticated docs session',\n        401,\n      );\n    }\n\n    const response = await fetch(this.joinUrl(CROSS_FRONTEND_HANDOFF_PATH), {\n      method: 'POST',\n      headers: {\n        'content-type': 'application/json',\n        authorization: `Bearer ${bearer}`,\n        ...(this.frontendServiceName ? { [WildoHeaderKeys.FRONTEND_SERVICE_NAME]: this.frontendServiceName } : {}),\n      },\n      body: JSON.stringify(request),\n    });\n\n    if (!response.ok) {\n      const code = await this.parseHandoffErrorCode(response);\n      throw new DocsAuthClientError(\n        code,\n        `Cross-frontend handoff failed (HTTP ${response.status})`,\n        response.status,\n      );\n    }\n\n    const json = (await response.json()) as Partial<CrossFrontendHandoffResponse>;\n    if (typeof json.handoffUrl !== 'string' || typeof json.expiresAt !== 'string') {\n      throw new DocsAuthClientError(\n        'malformed_response',\n        'Cross-frontend handoff response missing required fields',\n        response.status,\n      );\n    }\n    return { handoffUrl: json.handoffUrl, expiresAt: json.expiresAt };\n  }\n\n  /**\n   * Best-effort parse of the backend's `{ error: { details: { code, … } } }`\n   * envelope.\n   *\n   * The path is `error.details.code` (NOT `error.code`) — see the\n   * `error-handler.backend.service.ts` response shape, which spreads\n   * `sanitizedError.context` under `details`. The error builder's\n   * sanitization allowlist explicitly promotes `code` so cross-frontend\n   * handoff failures expose the stable `CrossFrontendHandoffErrorCode`\n   * enum value (cross-app-jwt-propagation.md C-4 contract).\n   *\n   * Falls back to `'malformed_response'` when the body is missing or its\n   * `error.details.code` is not a known `CrossFrontendHandoffErrorCode`.\n   * This keeps the client side strictly typed (`DocsAuthClientErrorCode`)\n   * even when faced with a transitional / proxy / CDN response that does\n   * not match the platform envelope.\n   */\n  private async parseHandoffErrorCode(response: Response): Promise<DocsAuthClientErrorCode> {\n    let body: unknown;\n    try {\n      body = await response.json();\n    } catch {\n      return 'malformed_response';\n    }\n    const code = (body as { error?: { details?: { code?: unknown } } } | null)\n      ?.error?.details?.code;\n    if (typeof code !== 'string') return 'malformed_response';\n\n    const handoffCodes = Object.values(CrossFrontendHandoffErrorCode) as string[];\n    if (handoffCodes.includes(code)) {\n      return code as CrossFrontendHandoffErrorCode;\n    }\n    return 'malformed_response';\n  }\n\n  private joinUrl(path: string): string {\n    return `${this.apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`;\n  }\n}\n\n/**\n * Stable, finite set of error codes the runtime can surface to the\n * Docusaurus swizzles + `<AuthExchangePage>`.\n *\n * Mirrors `CrossFrontendHandoffErrorCode` for the handoff path PLUS three\n * runtime-only codes:\n *\n *   - `unauthenticated`           — the caller asked for a handoff while no\n *                                   session was loaded; surfaced WITHOUT a\n *                                   network call so the DocItem swizzle can\n *                                   redirect to the SaaS app's login instead.\n *   - `invalid_or_expired_code`   — the `/api/v1/auth/token/exchange` call returned\n *                                   non-200; covers expired, already-consumed,\n *                                   or otherwise rejected codes.\n *   - `malformed_response`        — a transport / CDN / parser hiccup; rare,\n *                                   but typed so the swizzle never has to\n *                                   handle \"untyped error\" branches.\n */\nexport type DocsAuthClientErrorCode =\n  | CrossFrontendHandoffErrorCode\n  | 'unauthenticated'\n  | 'invalid_or_expired_code'\n  | 'malformed_response';\n\n/**\n * Typed error thrown by every `DocsAuthClient` method.\n *\n * Subclasses native `Error` (not `WildoBackendError`) on purpose — pulling\n * `WildoBackendError` here would force a dependency on `@wildo-ai/saas-models`\n * runtime utilities that the docs bundle has no other use for. The\n * swizzles `instanceof DocsAuthClientError` to distinguish from generic\n * fetch/abort errors.\n */\nexport class DocsAuthClientError extends Error {\n  readonly code: DocsAuthClientErrorCode;\n  readonly httpStatus: number;\n\n  constructor(code: DocsAuthClientErrorCode, message: string, httpStatus: number) {\n    super(message);\n    this.name = 'DocsAuthClientError';\n    this.code = code;\n    this.httpStatus = httpStatus;\n  }\n}\n"]}

package/dist/esm/runtime/docs-auth-session.schemas.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+/**
+ * Roles relevant to the docs-site gating decisions.
+ *
+ * Mirrors the role axis the SaaS app uses on access tokens. The docs site
+ * itself only cares about ONE distinction: "is this user an org admin or
+ * not?" — used by the Navbar swizzle to hide the "Organization API" link
+ * and by the DocItem swizzle to gate `/api/organization/*` pages
+ * (saas-technical-doc.md K-11).
+ *
+ * `ORG_ADMIN` value matches the string carried by the access token's
+ * `role` claim issued by `auth-token-issuer.backend.service.ts`. The
+ * generic `OTHER` bucket covers every other role (regular org member,
+ * viewer, application-level admin, etc.) — none of them grant Org-API
+ * visibility on the docs site.
+ */
+export declare enum DocsRole {
+    ORG_ADMIN = "org_admin",
+    OTHER = "other"
+}
+/**
+ * Subset of access-token claims the docs site cares about.
+ *
+ * The full access-token payload issued by the SaaS backend carries many
+ * more fields (organization id, application id, scopes, …) — we
+ * deliberately project only the minimum needed by the docs-site swizzles
+ * so that:
+ *   1. A future change to the access-token shape that adds fields
+ *      doesn't ripple into the docs site.
+ *   2. The docs site never accidentally renders or transmits sensitive
+ *      claims it has no business consuming.
+ *
+ * `userId` and `email` are present for display purposes ("Signed in as
+ * <email>" in the navbar — done by the Navbar swizzle, not this package).
+ *
+ * `role` is the gating axis (see {@link DocsRole}).
+ *
+ * `exp` (UNIX seconds) lets the context clear the in-memory session as
+ * soon as the access token expires — without ever calling the network.
+ * No refresh loop (K-9b): when `exp` passes, the user is anonymous again
+ * until they re-handshake from the SaaS app.
+ */
+export declare const DocsJwtClaimsSchema: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodOptional<z.ZodEmail>;
+    role: z.ZodEnum<typeof DocsRole>;
+    exp: z.ZodNumber;
+}, z.core.$strict>;
+export type DocsJwtClaims = z.infer<typeof DocsJwtClaimsSchema>;
+/**
+ * Public shape exposed by `useDocsAuthSession()` (saas-technical-doc.md K-11).
+ *
+ * Three mutually-exclusive states:
+ *   - `status: 'anonymous'`        — no handoff has been completed.
+ *   - `status: 'exchanging'`       — `/auth/exchange?code=…` is in flight.
+ *   - `status: 'authenticated'`    — `claims` and `accessToken` are present.
+ *
+ * Consumers (the three swizzles) discriminate on `status` and never reach
+ * for `accessToken`/`claims` while in the `anonymous` or `exchanging`
+ * states — the type narrows correctly thanks to the discriminated union.
+ *
+ * Does NOT model an `error` state directly: errors during the exchange
+ * are surfaced via the `AuthExchangePage` component's local UI, after
+ * which the session falls back to `anonymous`. Keeping the session shape
+ * tight prevents the swizzles from having to render error-recovery UI
+ * for events they did not cause.
+ */
+export type DocsAuthSession = {
+    status: 'anonymous';
+} | {
+    status: 'exchanging';
+} | {
+    status: 'authenticated';
+    accessToken: string;
+    claims: DocsJwtClaims;
+};
+//# sourceMappingURL=docs-auth-session.schemas.d.ts.map

package/dist/esm/runtime/docs-auth-session.schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-auth-session.schemas.d.ts","sourceRoot":"","sources":["../../../../src/runtime/docs-auth-session.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;GAcG;AACH,oBAAY,QAAQ;IAClB,SAAS,cAAc;IACvB,KAAK,UAAU;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB;;;;;kBAK9B,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,WAAW,CAAA;CAAE,GACvB;IAAE,MAAM,EAAE,YAAY,CAAA;CAAE,GACxB;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC"}