@wildo-ai/saas-technical-doc 1.1.1

package/dist/esm/runtime/AuthExchangePage.js

@@ -0,0 +1,188 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { isSameOriginRedirectPath } from '@wildo-ai/saas-models/public-runtime';
+import { useDocsAuthSession } from './use-docs-auth-session.js';
+/**
+ * Page component mounted at `/auth/exchange` on the docs site
+ * (saas-technical-doc.md Step 5).
+ *
+ * Lifecycle on mount:
+ *
+ *   1. Read `?code=` and `?return=` from `window.location.search`.
+ *   2. If `code` is missing → render the missingCode UI (no network call).
+ *   3. Else call `useDocsAuthSession().beginExchange(code)`, which POSTs
+ *      `/auth/token/exchange` and updates the in-memory context.
+ *   4. On success, navigate to `returnPath` (defaults to `/`) using the
+ *      consumer-supplied `onSuccessNavigate` (Docusaurus / react-router
+ *      hosts MUST pass a client-side `history.push` — see the prop
+ *      docstring below for why a full reload is incorrect here).
+ *   5. On failure, render the error UI with a link back to `/`.
+ *
+ * Why a single component (rather than splitting effect + render):
+ *
+ *   - Keeps the exchange contract trivially auditable from one file.
+ *   - The effect intentionally runs ONCE per mount (`hasRunRef` guard) —
+ *     `code` values are single-use AUTH_CODE_EXCHANGE consumable tokens
+ *     and a stray re-mount in React 18 strict-mode dev would burn the
+ *     code with the second call returning `invalid_or_expired_code`.
+ *
+ * Visual layer: this component renders a minimal centered "Signing you
+ * in…" / error block. Apps that want to brand it can either pass a
+ * `render` prop (consumer-controlled UI for each status) or skip this
+ * component entirely and call `useDocsAuthSession().beginExchange(code)`
+ * from their own page. The default rendering deliberately uses inline
+ * styles (no Tailwind / no CSS imports) so the component can be mounted
+ * by any Docusaurus theme without dragging in extra build pipeline.
+ */
+export const AuthExchangePage = ({ render, onSuccessNavigate }) => {
+    const { beginExchange } = useDocsAuthSession();
+    const [status, setStatus] = useState('pending');
+    const [error, setError] = useState(null);
+    const [returnPath, setReturnPath] = useState('/');
+    const hasRunRef = useRef(false);
+    useEffect(() => {
+        if (hasRunRef.current)
+            return;
+        hasRunRef.current = true;
+        /**
+         * SSR / build-time safety: Docusaurus may evaluate page modules in
+         * Node during the static build pre-render pass. `window` is undefined
+         * there. Bailing out keeps the static HTML emission clean — the real
+         * exchange runs on hydration in the browser.
+         */
+        if (typeof window === 'undefined')
+            return;
+        const params = new URLSearchParams(window.location.search);
+        const code = params.get('code');
+        /**
+         * URL `?return=` is kept as a defense-in-depth fallback for codes
+         * minted before the cross-app-jwt-propagation.md Step 5 metadata
+         * roll-out (which carries `returnPath` inside the exchange response
+         * envelope). The post-exchange `safeReturn` resolution below prefers
+         * the response-borne value because the issuer signs both into the
+         * same code and the response value cannot be tampered with by
+         * rewriting only the URL query string.
+         */
+        const rawUrlReturn = params.get('return') ?? '/';
+        const urlSafeReturn = sanitizeReturnPath(rawUrlReturn);
+        setReturnPath(urlSafeReturn);
+        if (!code) {
+            setStatus('missingCode');
+            return;
+        }
+        setStatus('exchanging');
+        beginExchange(code)
+            .then(({ claims, returnPath: responseReturnPath }) => {
+            /**
+             * Source-of-truth ordering for navigation target:
+             *   1. `responseReturnPath` — issuer-supplied via the exchange
+             *      response's TOP-LEVEL `returnPath` field (NOT a `metadata`
+             *      sub-field — the response has no `metadata` envelope; see
+             *      `TokenExchangeResponseSchema`). Sanitized again here even
+             *      though the issuer already validates at minting time; an
+             *      attacker who can intercept the response body should not be
+             *      able to weaponise it.
+             *   2. `urlSafeReturn` — the URL `?return=` query parameter
+             *      (already sanitized above). Used when codes were minted
+             *      without a `returnPath` (OAuth2 callbacks, by contract)
+             *      OR when the response otherwise omits it.
+             *   3. `/` — the docs root. Final fallback so the user is never
+             *      stranded on `/auth/exchange`.
+             */
+            const safeReturn = responseReturnPath
+                ? sanitizeReturnPath(responseReturnPath)
+                : urlSafeReturn;
+            setReturnPath(safeReturn);
+            if (claims === null) {
+                setError('This sign-in link could not be exchanged. It may have expired or already been used. Please re-open the docs from the application.');
+                setStatus('error');
+                return;
+            }
+            setStatus('success');
+            // Navigate AFTER the React state flush so any other consumers of
+            // `useDocsAuthSession()` see the authenticated session before the
+            // page disappears. The default `window.location.assign` is the
+            // plain-HTML fallback; SPA hosts override via `onSuccessNavigate`
+            // (see prop docstring — full reload would tear down the in-memory
+            // provider state we just populated).
+            const navigate = onSuccessNavigate ?? ((path) => window.location.assign(path));
+            window.setTimeout(() => {
+                navigate(safeReturn);
+            }, 0);
+        })
+            .catch((cause) => {
+            setError(cause instanceof Error ? cause.message : 'Sign-in failed');
+            setStatus('error');
+        });
+    }, [beginExchange, onSuccessNavigate]);
+    if (render)
+        return _jsx(_Fragment, { children: render({ status, returnPath, error }) });
+    return _jsx(DefaultExchangeUi, { status: status, returnPath: returnPath, error: error });
+};
+/**
+ * Minimal client-side validation of the `return` query parameter.
+ *
+ * The cross-frontend handoff endpoint already validates `returnPath` at
+ * the schema boundary (see `CrossFrontendHandoff_ReturnPathSchema` in
+ * `authentication.shared.dto.schemas.ts`). This duplicate check is
+ * defense-in-depth: anyone could construct a docs URL like
+ * `/auth/exchange?code=…&return=https://evil.com` directly without
+ * going through the backend. Without this guard, the `location.assign`
+ * fallback (used by plain-HTML hosts when `onSuccessNavigate` is not
+ * supplied) would happily redirect to that origin.
+ *
+ * The ORIGIN question is delegated to the shared
+ * {@link isSameOriginRedirectPath} predicate on the bundle-safe seam, and
+ * that delegation is a fix, not tidying. This function was a verbatim copy
+ * of the SaaS-app receiver's copy, which was itself a copy of the issuer
+ * schema's rules — and all three admitted `/<TAB>/evil.com`, because the
+ * URL parser strips ASCII tab / LF / CR from the input BEFORE parsing, so
+ * the target the browser sees is `//evil.com`. Every copy banned `\`; none
+ * banned the whitespace that becomes a `/`. Three mirrors reflected the
+ * same hole, which is why the answer now has one home.
+ *
+ * The character rules are KEPT as defence-in-depth for the concerns the
+ * origin predicate deliberately does not own: path traversal (`..`), markup
+ * injection (`<>"`) and the length ceiling.
+ */
+function sanitizeReturnPath(raw) {
+    // Authoritative: `//evil.com`, `/\evil.com` and the stripped-control-character
+    // family all fail here, in one parse-based check.
+    if (!isSameOriginRedirectPath(raw))
+        return '/';
+    if (raw.includes('..'))
+        return '/';
+    if (raw.includes('\\'))
+        return '/';
+    if (raw.includes('://'))
+        return '/';
+    if (/[<>"]/.test(raw))
+        return '/';
+    if (raw.length > 256)
+        return '/';
+    return raw;
+}
+/**
+ * Default zero-style status block. Apps that brand the docs site override
+ * this via the `render` prop on `<AuthExchangePage>`.
+ */
+const DefaultExchangeUi = ({ status, returnPath, error }) => {
+    const containerStyle = {
+        maxWidth: 480,
+        margin: '6rem auto',
+        padding: '2rem',
+        fontFamily: 'system-ui, sans-serif',
+        textAlign: 'center',
+    };
+    if (status === 'pending' || status === 'exchanging') {
+        return (_jsxs("div", { style: containerStyle, children: [_jsx("h1", { style: { fontSize: '1.25rem' }, children: "Signing you in\u2026" }), _jsx("p", { style: { color: '#666' }, children: "This will only take a moment." })] }));
+    }
+    if (status === 'success') {
+        return (_jsxs("div", { style: containerStyle, children: [_jsx("h1", { style: { fontSize: '1.25rem' }, children: "You're signed in." }), _jsxs("p", { style: { color: '#666' }, children: ["Redirecting to ", returnPath, "\u2026"] })] }));
+    }
+    if (status === 'missingCode') {
+        return (_jsxs("div", { style: containerStyle, children: [_jsx("h1", { style: { fontSize: '1.25rem' }, children: "This page requires a sign-in code." }), _jsx("p", { style: { color: '#666' }, children: "Please open the documentation from the application." }), _jsx("p", { children: _jsx("a", { href: "/", children: "Go to docs home" }) })] }));
+    }
+    return (_jsxs("div", { style: containerStyle, children: [_jsx("h1", { style: { fontSize: '1.25rem' }, children: "Sign-in failed" }), _jsx("p", { style: { color: '#666' }, children: error ?? 'Unknown error.' }), _jsx("p", { children: _jsx("a", { href: "/", children: "Go to docs home" }) })] }));
+};
+//# sourceMappingURL=AuthExchangePage.js.map

package/dist/esm/runtime/AuthExchangePage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthExchangePage.js","sourceRoot":"","sources":["../../../../src/runtime/AuthExchangePage.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useEffect, useRef, useState, type CSSProperties, type FC, type ReactNode } from 'react';\nimport { isSameOriginRedirectPath } from '@wildo-ai/saas-models/public-runtime';\nimport { useDocsAuthSession } from './use-docs-auth-session';\n\n/**\n * Status of the auth-code exchange the page is performing.\n *\n *   - `pending`   — initial mount; effect has not yet run.\n *   - `exchanging`— the `/auth/token/exchange` POST is in flight.\n *   - `success`   — tokens received; about to navigate to `returnPath`.\n *   - `error`     — exchange failed; the page renders a fallback message\n *                   and a manual link back to the docs root.\n *   - `missingCode`— landed on `/auth/exchange` without `?code=…` (someone\n *                    bookmarked the page or arrived via a stale link).\n */\nexport type AuthExchangeStatus =\n  | 'pending'\n  | 'exchanging'\n  | 'success'\n  | 'error'\n  | 'missingCode';\n\n/**\n * Page component mounted at `/auth/exchange` on the docs site\n * (saas-technical-doc.md Step 5).\n *\n * Lifecycle on mount:\n *\n *   1. Read `?code=` and `?return=` from `window.location.search`.\n *   2. If `code` is missing → render the missingCode UI (no network call).\n *   3. Else call `useDocsAuthSession().beginExchange(code)`, which POSTs\n *      `/auth/token/exchange` and updates the in-memory context.\n *   4. On success, navigate to `returnPath` (defaults to `/`) using the\n *      consumer-supplied `onSuccessNavigate` (Docusaurus / react-router\n *      hosts MUST pass a client-side `history.push` — see the prop\n *      docstring below for why a full reload is incorrect here).\n *   5. On failure, render the error UI with a link back to `/`.\n *\n * Why a single component (rather than splitting effect + render):\n *\n *   - Keeps the exchange contract trivially auditable from one file.\n *   - The effect intentionally runs ONCE per mount (`hasRunRef` guard) —\n *     `code` values are single-use AUTH_CODE_EXCHANGE consumable tokens\n *     and a stray re-mount in React 18 strict-mode dev would burn the\n *     code with the second call returning `invalid_or_expired_code`.\n *\n * Visual layer: this component renders a minimal centered \"Signing you\n * in…\" / error block. Apps that want to brand it can either pass a\n * `render` prop (consumer-controlled UI for each status) or skip this\n * component entirely and call `useDocsAuthSession().beginExchange(code)`\n * from their own page. The default rendering deliberately uses inline\n * styles (no Tailwind / no CSS imports) so the component can be mounted\n * by any Docusaurus theme without dragging in extra build pipeline.\n */\nexport const AuthExchangePage: FC<{\n  /**\n   * Override the default rendering. Receives the current status and (when\n   * the page reaches a terminal state) a recovery URL the consumer can\n   * link back to.\n   */\n  render?: (props: { status: AuthExchangeStatus; returnPath: string; error: string | null }) => ReactNode;\n  /**\n   * Post-success navigation. **SPA hosts (Docusaurus, react-router,\n   * Vite/React-Router apps) MUST pass a client-side router push** — the\n   * default `window.location.assign` triggers a full browser navigation\n   * which destroys the in-memory `DocsAuthProvider` state we just\n   * populated (the entire JS bundle re-executes from scratch on the\n   * destination page, the React tree re-mounts, and `session` resets to\n   * `'anonymous'`). For a Docusaurus consumer that looks like:\n   *\n   * ```tsx\n   * import { useHistory } from '@docusaurus/router';\n   *\n   * function AuthExchangeRoute() {\n   *   const history = useHistory();\n   *   return <AuthExchangePage onSuccessNavigate={(p) => history.push(p)} />;\n   * }\n   * ```\n   *\n   * The default `window.location.assign` only works for plain-HTML hosts\n   * that have no in-memory client state to preserve across the redirect.\n   * It is kept as the default so the runtime stays usable in those hosts\n   * with zero ceremony, but for SPAs failing to override it would\n   * silently break the entire handoff (the user lands on the destination\n   * page anonymous and any role-gated content rejects them).\n   */\n  onSuccessNavigate?: (returnPath: string) => void;\n}> = ({ render, onSuccessNavigate }) => {\n  const { beginExchange } = useDocsAuthSession();\n\n  const [status, setStatus] = useState<AuthExchangeStatus>('pending');\n  const [error, setError] = useState<string | null>(null);\n  const [returnPath, setReturnPath] = useState<string>('/');\n\n  const hasRunRef = useRef(false);\n\n  useEffect(() => {\n    if (hasRunRef.current) return;\n    hasRunRef.current = true;\n\n    /**\n     * SSR / build-time safety: Docusaurus may evaluate page modules in\n     * Node during the static build pre-render pass. `window` is undefined\n     * there. Bailing out keeps the static HTML emission clean — the real\n     * exchange runs on hydration in the browser.\n     */\n    if (typeof window === 'undefined') return;\n\n    const params = new URLSearchParams(window.location.search);\n    const code = params.get('code');\n    /**\n     * URL `?return=` is kept as a defense-in-depth fallback for codes\n     * minted before the cross-app-jwt-propagation.md Step 5 metadata\n     * roll-out (which carries `returnPath` inside the exchange response\n     * envelope). The post-exchange `safeReturn` resolution below prefers\n     * the response-borne value because the issuer signs both into the\n     * same code and the response value cannot be tampered with by\n     * rewriting only the URL query string.\n     */\n    const rawUrlReturn = params.get('return') ?? '/';\n    const urlSafeReturn = sanitizeReturnPath(rawUrlReturn);\n    setReturnPath(urlSafeReturn);\n\n    if (!code) {\n      setStatus('missingCode');\n      return;\n    }\n\n    setStatus('exchanging');\n    beginExchange(code)\n      .then(({ claims, returnPath: responseReturnPath }) => {\n        /**\n         * Source-of-truth ordering for navigation target:\n         *   1. `responseReturnPath` — issuer-supplied via the exchange\n         *      response's TOP-LEVEL `returnPath` field (NOT a `metadata`\n         *      sub-field — the response has no `metadata` envelope; see\n         *      `TokenExchangeResponseSchema`). Sanitized again here even\n         *      though the issuer already validates at minting time; an\n         *      attacker who can intercept the response body should not be\n         *      able to weaponise it.\n         *   2. `urlSafeReturn` — the URL `?return=` query parameter\n         *      (already sanitized above). Used when codes were minted\n         *      without a `returnPath` (OAuth2 callbacks, by contract)\n         *      OR when the response otherwise omits it.\n         *   3. `/` — the docs root. Final fallback so the user is never\n         *      stranded on `/auth/exchange`.\n         */\n        const safeReturn = responseReturnPath\n          ? sanitizeReturnPath(responseReturnPath)\n          : urlSafeReturn;\n        setReturnPath(safeReturn);\n\n        if (claims === null) {\n          setError(\n            'This sign-in link could not be exchanged. It may have expired or already been used. Please re-open the docs from the application.',\n          );\n          setStatus('error');\n          return;\n        }\n        setStatus('success');\n        // Navigate AFTER the React state flush so any other consumers of\n        // `useDocsAuthSession()` see the authenticated session before the\n        // page disappears. The default `window.location.assign` is the\n        // plain-HTML fallback; SPA hosts override via `onSuccessNavigate`\n        // (see prop docstring — full reload would tear down the in-memory\n        // provider state we just populated).\n        const navigate =\n          onSuccessNavigate ?? ((path: string) => window.location.assign(path));\n        window.setTimeout(() => {\n          navigate(safeReturn);\n        }, 0);\n      })\n      .catch((cause: unknown) => {\n        setError(cause instanceof Error ? cause.message : 'Sign-in failed');\n        setStatus('error');\n      });\n  }, [beginExchange, onSuccessNavigate]);\n\n  if (render) return <>{render({ status, returnPath, error })}</>;\n\n  return <DefaultExchangeUi status={status} returnPath={returnPath} error={error} />;\n};\n\n/**\n * Minimal client-side validation of the `return` query parameter.\n *\n * The cross-frontend handoff endpoint already validates `returnPath` at\n * the schema boundary (see `CrossFrontendHandoff_ReturnPathSchema` in\n * `authentication.shared.dto.schemas.ts`). This duplicate check is\n * defense-in-depth: anyone could construct a docs URL like\n * `/auth/exchange?code=…&return=https://evil.com` directly without\n * going through the backend. Without this guard, the `location.assign`\n * fallback (used by plain-HTML hosts when `onSuccessNavigate` is not\n * supplied) would happily redirect to that origin.\n *\n * The ORIGIN question is delegated to the shared\n * {@link isSameOriginRedirectPath} predicate on the bundle-safe seam, and\n * that delegation is a fix, not tidying. This function was a verbatim copy\n * of the SaaS-app receiver's copy, which was itself a copy of the issuer\n * schema's rules — and all three admitted `/<TAB>/evil.com`, because the\n * URL parser strips ASCII tab / LF / CR from the input BEFORE parsing, so\n * the target the browser sees is `//evil.com`. Every copy banned `\\`; none\n * banned the whitespace that becomes a `/`. Three mirrors reflected the\n * same hole, which is why the answer now has one home.\n *\n * The character rules are KEPT as defence-in-depth for the concerns the\n * origin predicate deliberately does not own: path traversal (`..`), markup\n * injection (`<>\"`) and the length ceiling.\n */\nfunction sanitizeReturnPath(raw: string): string {\n  // Authoritative: `//evil.com`, `/\\evil.com` and the stripped-control-character\n  // family all fail here, in one parse-based check.\n  if (!isSameOriginRedirectPath(raw)) return '/';\n  if (raw.includes('..')) return '/';\n  if (raw.includes('\\\\')) return '/';\n  if (raw.includes('://')) return '/';\n  if (/[<>\"]/.test(raw)) return '/';\n  if (raw.length > 256) return '/';\n  return raw;\n}\n\n/**\n * Default zero-style status block. Apps that brand the docs site override\n * this via the `render` prop on `<AuthExchangePage>`.\n */\nconst DefaultExchangeUi: FC<{\n  status: AuthExchangeStatus;\n  returnPath: string;\n  error: string | null;\n}> = ({ status, returnPath, error }) => {\n  const containerStyle: CSSProperties = {\n    maxWidth: 480,\n    margin: '6rem auto',\n    padding: '2rem',\n    fontFamily: 'system-ui, sans-serif',\n    textAlign: 'center',\n  };\n\n  if (status === 'pending' || status === 'exchanging') {\n    return (\n      <div style={containerStyle}>\n        <h1 style={{ fontSize: '1.25rem' }}>Signing you in…</h1>\n        <p style={{ color: '#666' }}>This will only take a moment.</p>\n      </div>\n    );\n  }\n\n  if (status === 'success') {\n    return (\n      <div style={containerStyle}>\n        <h1 style={{ fontSize: '1.25rem' }}>You&apos;re signed in.</h1>\n        <p style={{ color: '#666' }}>Redirecting to {returnPath}…</p>\n      </div>\n    );\n  }\n\n  if (status === 'missingCode') {\n    return (\n      <div style={containerStyle}>\n        <h1 style={{ fontSize: '1.25rem' }}>This page requires a sign-in code.</h1>\n        <p style={{ color: '#666' }}>Please open the documentation from the application.</p>\n        <p>\n          <a href=\"/\">Go to docs home</a>\n        </p>\n      </div>\n    );\n  }\n\n  return (\n    <div style={containerStyle}>\n      <h1 style={{ fontSize: '1.25rem' }}>Sign-in failed</h1>\n      <p style={{ color: '#666' }}>{error ?? 'Unknown error.'}</p>\n      <p>\n        <a href=\"/\">Go to docs home</a>\n      </p>\n    </div>\n  );\n};\n"]}

package/dist/esm/runtime/DocsAuthContext.d.ts

@@ -0,0 +1,119 @@
+import { type Context, type FC, type ReactNode } from 'react';
+import type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';
+import { DocsAuthClient } from './docs-auth-client';
+import type { DocsAuthSession, DocsJwtClaims } from './docs-auth-session.schemas';
+import { type FrontendTechdocProviderRegistry } from './frontend-provider-registry.techdoc';
+/**
+ * Result of a `beginExchange()` call surfaced to `<AuthExchangePage>`.
+ *
+ * `claims`     — decoded `DocsJwtClaims` (or `null` if the access token
+ *                came back undecodable — treated as anonymous).
+ * `returnPath` — the issuer-supplied `returnPath` from the token exchange
+ *                response (cross-app-jwt-propagation.md Step 5). It is
+ *                a TOP-LEVEL field on `TokenExchangeResponseSchema` —
+ *                NOT nested under `metadata`. The earlier draft of this
+ *                JSDoc said "metadata.returnPath" and the implementation
+ *                read `response.metadata?.returnPath` (always undefined,
+ *                because no such key exists on the response). H-3 in the
+ *                Step 5 second deep-review log fixes both the docstring
+ *                and the read site.
+ *                `null` for OAuth2-callback codes (which never carry a
+ *                `returnPath` at all — discriminator invariant pinned by
+ *                `TokenExchangeResponseSchema` JSDoc); the exchange page
+ *                falls back to the URL `?return=` parameter in that case
+ *                (defense-in-depth).
+ */
+export interface DocsBeginExchangeResult {
+    readonly claims: DocsJwtClaims | null;
+    readonly returnPath: string | null;
+}
+/**
+ * Public surface of `useDocsAuthSession()`.
+ *
+ * `session`           — discriminated union (anonymous / exchanging / authenticated).
+ * `client`            — the singleton `DocsAuthClient` for authenticated docs
+ *                       runtime code that needs to request a handoff to another
+ *                       frontend. Anonymous docs gates deep-link to the SaaS app
+ *                       because handoff issuance requires a bearer.
+ * `frontendProviderRegistry`
+ *                     — hydrated registry of the frontend-safe provider entries
+ *                       materialized for the active docs service. Browser-only
+ *                       docs widgets (search, analytics, future SDK protocols)
+ *                       read from this instead of importing generated artifacts.
+ * `beginExchange`     — called by `<AuthExchangePage>` when a `?code=` arrives.
+ *                       Returns the decoded claims AND the issuer-supplied
+ *                       top-level `returnPath` from the exchange response
+ *                       (the SOURCE OF TRUTH for post-exchange navigation;
+ *                       the URL `?return=` is a defense-in-depth fallback
+ *                       only). NOT `response.metadata.returnPath` — the
+ *                       response has no `metadata` envelope (H-3 fix).
+ * `clear`             — called when the user explicitly closes the docs
+ *                       session (e.g. a "Sign out of docs" link). NOT called
+ *                       on tab close — ephemeral state evaporates on its own.
+ */
+export interface DocsAuthContextValue {
+    readonly session: DocsAuthSession;
+    readonly client: DocsAuthClient;
+    readonly frontendProviderRegistry: FrontendTechdocProviderRegistry;
+    beginExchange(code: string): Promise<DocsBeginExchangeResult>;
+    clear(): void;
+}
+/**
+ * @internal — consumers should call `useDocsAuthSession()` instead of
+ * touching this directly. Exported so the matching hook can `useContext`
+ * it from a sibling module (Fast Refresh boundary).
+ */
+export declare const DocsAuthContext: Context<DocsAuthContextValue | null>;
+/**
+ * In-memory React context owning the docs-site authenticated session
+ * (saas-technical-doc.md K-9b).
+ *
+ * Storage characteristics — locked by K-9b:
+ *
+ *   - In-memory only. NO `localStorage`, NO `sessionStorage`, NO cookies.
+ *     Closing the tab destroys the session.
+ *   - NO refresh-token loop. `/auth/token/exchange` no longer returns a
+ *     refresh token in the JSON body; SaaS-app receivers get refresh via the
+ *     HttpOnly cookie channel, while docs intentionally keeps only the access
+ *     token in memory. When the access token's `exp` passes, the next access
+ *     becomes anonymous and the user re-handshakes from the SaaS app on demand.
+ *   - NO BroadcastChannel cross-tab coordination. Each docs tab owns its
+ *     own session — opening a new tab is anonymous until it gets its own
+ *     `?code=` redirect.
+ *
+ * These choices are deliberate: the docs site is a session RECEIVER
+ * (never a session OWNER), and the SaaS app is the authoritative source
+ * of authentication. Replicating the SaaS app's session-management stack
+ * here would force the docs Docusaurus bundle to ship inversify, the
+ * resources framework, and a refresh interceptor — all of which are
+ * about to be hardened (auth-hardening.md Slice A) in the SaaS app
+ * specifically because they are sensitive surfaces. Keeping the docs
+ * site free of those mechanisms keeps its attack surface tiny.
+ *
+ * The `apiBaseUrl` prop is supplied by the docs site at mount time
+ * (typically read from a small `appConfig.json` shipped alongside the
+ * Docusaurus bundle, or from an env var injected at build time). It is
+ * not pulled from `saas-frontend-lib`'s `useApplication()` because that
+ * would force this package to import the inversify-bound `appConfig`
+ * provider — exactly the dependency we are avoiding.
+ */
+export declare const DocsAuthProvider: FC<{
+    children: ReactNode;
+    apiBaseUrl: string;
+    /**
+     * Optional materialized provider block for the active docs service.
+     * When omitted, the docs runtime exposes an empty provider registry.
+     */
+    frontendProviders?: FrontendProvidersBlock;
+    /**
+     * Runtime frontend service identity used for the `X-Frontend-Service-Name`
+     * header on exchange/handoff auth calls.
+     */
+    frontendServiceName?: string | null;
+    /**
+     * Optional override for tests. Production code constructs a
+     * `DocsAuthClient` from `apiBaseUrl` + the in-memory bearer.
+     */
+    client?: DocsAuthClient;
+}>;
+//# sourceMappingURL=DocsAuthContext.d.ts.map

package/dist/esm/runtime/DocsAuthContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsAuthContext.d.ts","sourceRoot":"","sources":["../../../../src/runtime/DocsAuthContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,OAAO,EACZ,KAAK,EAAE,EACP,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAClF,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,sCAAsC,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,wBAAwB,EAAE,+BAA+B,CAAC;IACnE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAC9D,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,OAAO,CAAC,oBAAoB,GAAG,IAAI,CACf,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB,CA0GA,CAAC"}

package/dist/esm/runtime/DocsAuthContext.js

@@ -0,0 +1,171 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useEffect, useMemo, useRef, useState, } from 'react';
+import { decodeJwtClaims } from './decode-jwt-claims.js';
+import { DocsAuthClient } from './docs-auth-client.js';
+import { createFrontendTechdocProviderRegistry, } from './frontend-provider-registry.techdoc.js';
+/**
+ * @internal — consumers should call `useDocsAuthSession()` instead of
+ * touching this directly. Exported so the matching hook can `useContext`
+ * it from a sibling module (Fast Refresh boundary).
+ */
+export const DocsAuthContext = createContext(null);
+/**
+ * In-memory React context owning the docs-site authenticated session
+ * (saas-technical-doc.md K-9b).
+ *
+ * Storage characteristics — locked by K-9b:
+ *
+ *   - In-memory only. NO `localStorage`, NO `sessionStorage`, NO cookies.
+ *     Closing the tab destroys the session.
+ *   - NO refresh-token loop. `/auth/token/exchange` no longer returns a
+ *     refresh token in the JSON body; SaaS-app receivers get refresh via the
+ *     HttpOnly cookie channel, while docs intentionally keeps only the access
+ *     token in memory. When the access token's `exp` passes, the next access
+ *     becomes anonymous and the user re-handshakes from the SaaS app on demand.
+ *   - NO BroadcastChannel cross-tab coordination. Each docs tab owns its
+ *     own session — opening a new tab is anonymous until it gets its own
+ *     `?code=` redirect.
+ *
+ * These choices are deliberate: the docs site is a session RECEIVER
+ * (never a session OWNER), and the SaaS app is the authoritative source
+ * of authentication. Replicating the SaaS app's session-management stack
+ * here would force the docs Docusaurus bundle to ship inversify, the
+ * resources framework, and a refresh interceptor — all of which are
+ * about to be hardened (auth-hardening.md Slice A) in the SaaS app
+ * specifically because they are sensitive surfaces. Keeping the docs
+ * site free of those mechanisms keeps its attack surface tiny.
+ *
+ * The `apiBaseUrl` prop is supplied by the docs site at mount time
+ * (typically read from a small `appConfig.json` shipped alongside the
+ * Docusaurus bundle, or from an env var injected at build time). It is
+ * not pulled from `saas-frontend-lib`'s `useApplication()` because that
+ * would force this package to import the inversify-bound `appConfig`
+ * provider — exactly the dependency we are avoiding.
+ */
+export const DocsAuthProvider = ({ children, apiBaseUrl, frontendProviders, frontendServiceName = null, client: clientOverride, }) => {
+    const [session, setSession] = useState({ status: 'anonymous' });
+    /**
+     * `getAuthBearer` reads from a closure over `session` so the bearer
+     * always reflects the *current* state without re-creating the client
+     * on every state change. The `useMemo` below depends only on
+     * `apiBaseUrl` so the client identity is stable across re-renders,
+     * which keeps `useEffect` dependency arrays in swizzles honest.
+     */
+    const sessionRef = useLatestRef(session);
+    const client = useMemo(() => {
+        if (clientOverride)
+            return clientOverride;
+        return new DocsAuthClient({
+            apiBaseUrl,
+            frontendServiceName,
+            getAuthBearer: () => sessionRef.current.status === 'authenticated'
+                ? sessionRef.current.accessToken
+                : null,
+        });
+    }, [apiBaseUrl, frontendServiceName, clientOverride, sessionRef]);
+    const frontendProviderRegistry = useMemo(() => createFrontendTechdocProviderRegistry(frontendProviders), [frontendProviders]);
+    /**
+     * Auto-clear when the access token expires.
+     *
+     * Sets a single timer based on `claims.exp`; on tick, transitions the
+     * session back to `anonymous`. No polling, no refresh — the next
+     * gated action will trigger a re-handshake via `requestCrossFrontendHandoff`.
+     *
+     * The timer is recreated whenever the session transitions to
+     * `authenticated`, and cleared on unmount or on transition AWAY from
+     * `authenticated` to avoid stale timers firing into a fresh session.
+     */
+    useEffect(() => {
+        if (session.status !== 'authenticated')
+            return;
+        const msUntilExpiry = session.claims.exp * 1000 - Date.now();
+        if (msUntilExpiry <= 0) {
+            setSession({ status: 'anonymous' });
+            return;
+        }
+        const handle = setTimeout(() => {
+            setSession({ status: 'anonymous' });
+        }, msUntilExpiry);
+        return () => clearTimeout(handle);
+    }, [session]);
+    const beginExchange = useCallback(async (code) => {
+        setSession({ status: 'exchanging' });
+        try {
+            const response = await client.exchangeAuthCode(code);
+            // `returnPath` lives at the TOP LEVEL of `TokenExchangeResponseSchema`
+            // — NOT under `metadata`. Reading `response.metadata?.returnPath`
+            // (the previous shape this code targeted) is silently `undefined`
+            // because the schema has no `metadata` envelope. The previous
+            // implementation made every docs handoff fall through to the URL
+            // `?return=` value, defeating Step 5's "response value is the
+            // source of truth" contract. See H-3 in the Step 5 second
+            // deep-review log on `cross-app-jwt-propagation.md`.
+            const returnPath = response.returnPath ?? null;
+            const claims = decodeJwtClaims(response.accessToken);
+            if (!claims) {
+                /**
+                 * The exchange succeeded but the returned token isn't decodable.
+                 * Treat as anonymous rather than half-authenticated — the
+                 * swizzles never have to handle a `claims === null &&
+                 * status === 'authenticated'` corner case. We still surface
+                 * `returnPath` so the exchange page can navigate the user
+                 * somewhere sensible (e.g. `/`) instead of stranding them on
+                 * `/auth/exchange`.
+                 */
+                setSession({ status: 'anonymous' });
+                return { claims: null, returnPath };
+            }
+            setSession({ status: 'authenticated', accessToken: response.accessToken, claims });
+            return { claims, returnPath };
+        }
+        catch {
+            setSession({ status: 'anonymous' });
+            return { claims: null, returnPath: null };
+        }
+    }, [client]);
+    const clear = useCallback(() => {
+        setSession({ status: 'anonymous' });
+    }, []);
+    const value = useMemo(() => ({ session, client, frontendProviderRegistry, beginExchange, clear }), [session, client, frontendProviderRegistry, beginExchange, clear]);
+    return _jsx(DocsAuthContext.Provider, { value: value, children: children });
+};
+/**
+ * Tiny ref-of-latest-value helper. Avoids pulling in a utility lib for
+ * one ~6-line function. Used here so the `DocsAuthClient`'s
+ * `getAuthBearer` callback always sees the freshest session without
+ * re-instantiating the client.
+ *
+ * Implementation discipline (L-NEW-1 fix from the Step 6 third
+ * deep-review log): the previous implementation mutated `ref.current`
+ * DURING render (the `ref.current = value;` line ran in the function
+ * body), which violates React's "no side effects during render"
+ * invariant and produces inconsistent reads under concurrent
+ * rendering — a render that gets discarded by React's scheduler can
+ * still leave a stale `ref.current` behind for the next render.
+ *
+ * The fix is the textbook React 18 pattern: hold the value in a real
+ * `useRef`, then sync it inside `useEffect` after commit.
+ *
+ * Trade-off acknowledged: between render and effect-flush,
+ * `ref.current` lags by one render. That is SAFE for this consumer
+ * because `getAuthBearer()` is only invoked ASYNCHRONOUSLY (inside a
+ * `fetch()` call originated by `requestCrossFrontendHandoff()` /
+ * `exchangeAuthCode()`) — by the time the bearer is read, every
+ * `useEffect` from the triggering render has already flushed and
+ * `ref.current` reflects the latest committed session.
+ *
+ * Concretely: if the user clicks an org-API navbar entry that promotes
+ * the session from `anonymous` → `exchanging` → `authenticated`, the
+ * next fetch the client issues sees `authenticated` (ref synced after
+ * commit) — never the stale `exchanging` value, even though the
+ * `useMemo` factory may have captured the closure at the earlier
+ * render.
+ */
+function useLatestRef(value) {
+    const ref = useRef(value);
+    useEffect(() => {
+        ref.current = value;
+    });
+    return ref;
+}
+//# sourceMappingURL=DocsAuthContext.js.map

package/dist/esm/runtime/DocsAuthContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocsAuthContext.js","sourceRoot":"","sources":["../../../../src/runtime/DocsAuthContext.tsx"],"names":[],"mappings":"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","sourcesContent":["import {\n  createContext,\n  useCallback,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n  type Context,\n  type FC,\n  type ReactNode,\n} from 'react';\nimport type { FrontendProvidersBlock } from '@wildo-ai/saas-models/public-runtime';\nimport { decodeJwtClaims } from './decode-jwt-claims';\nimport { DocsAuthClient } from './docs-auth-client';\nimport type { DocsAuthSession, DocsJwtClaims } from './docs-auth-session.schemas';\nimport {\n  createFrontendTechdocProviderRegistry,\n  type FrontendTechdocProviderRegistry,\n} from './frontend-provider-registry.techdoc';\n\n/**\n * Result of a `beginExchange()` call surfaced to `<AuthExchangePage>`.\n *\n * `claims`     — decoded `DocsJwtClaims` (or `null` if the access token\n *                came back undecodable — treated as anonymous).\n * `returnPath` — the issuer-supplied `returnPath` from the token exchange\n *                response (cross-app-jwt-propagation.md Step 5). It is\n *                a TOP-LEVEL field on `TokenExchangeResponseSchema` —\n *                NOT nested under `metadata`. The earlier draft of this\n *                JSDoc said \"metadata.returnPath\" and the implementation\n *                read `response.metadata?.returnPath` (always undefined,\n *                because no such key exists on the response). H-3 in the\n *                Step 5 second deep-review log fixes both the docstring\n *                and the read site.\n *                `null` for OAuth2-callback codes (which never carry a\n *                `returnPath` at all — discriminator invariant pinned by\n *                `TokenExchangeResponseSchema` JSDoc); the exchange page\n *                falls back to the URL `?return=` parameter in that case\n *                (defense-in-depth).\n */\nexport interface DocsBeginExchangeResult {\n  readonly claims: DocsJwtClaims | null;\n  readonly returnPath: string | null;\n}\n\n/**\n * Public surface of `useDocsAuthSession()`.\n *\n * `session`           — discriminated union (anonymous / exchanging / authenticated).\n * `client`            — the singleton `DocsAuthClient` for authenticated docs\n *                       runtime code that needs to request a handoff to another\n *                       frontend. Anonymous docs gates deep-link to the SaaS app\n *                       because handoff issuance requires a bearer.\n * `frontendProviderRegistry`\n *                     — hydrated registry of the frontend-safe provider entries\n *                       materialized for the active docs service. Browser-only\n *                       docs widgets (search, analytics, future SDK protocols)\n *                       read from this instead of importing generated artifacts.\n * `beginExchange`     — called by `<AuthExchangePage>` when a `?code=` arrives.\n *                       Returns the decoded claims AND the issuer-supplied\n *                       top-level `returnPath` from the exchange response\n *                       (the SOURCE OF TRUTH for post-exchange navigation;\n *                       the URL `?return=` is a defense-in-depth fallback\n *                       only). NOT `response.metadata.returnPath` — the\n *                       response has no `metadata` envelope (H-3 fix).\n * `clear`             — called when the user explicitly closes the docs\n *                       session (e.g. a \"Sign out of docs\" link). NOT called\n *                       on tab close — ephemeral state evaporates on its own.\n */\nexport interface DocsAuthContextValue {\n  readonly session: DocsAuthSession;\n  readonly client: DocsAuthClient;\n  readonly frontendProviderRegistry: FrontendTechdocProviderRegistry;\n  beginExchange(code: string): Promise<DocsBeginExchangeResult>;\n  clear(): void;\n}\n\n/**\n * @internal — consumers should call `useDocsAuthSession()` instead of\n * touching this directly. Exported so the matching hook can `useContext`\n * it from a sibling module (Fast Refresh boundary).\n */\nexport const DocsAuthContext: Context<DocsAuthContextValue | null> =\n  createContext<DocsAuthContextValue | null>(null);\n\n/**\n * In-memory React context owning the docs-site authenticated session\n * (saas-technical-doc.md K-9b).\n *\n * Storage characteristics — locked by K-9b:\n *\n *   - In-memory only. NO `localStorage`, NO `sessionStorage`, NO cookies.\n *     Closing the tab destroys the session.\n *   - NO refresh-token loop. `/auth/token/exchange` no longer returns a\n *     refresh token in the JSON body; SaaS-app receivers get refresh via the\n *     HttpOnly cookie channel, while docs intentionally keeps only the access\n *     token in memory. When the access token's `exp` passes, the next access\n *     becomes anonymous and the user re-handshakes from the SaaS app on demand.\n *   - NO BroadcastChannel cross-tab coordination. Each docs tab owns its\n *     own session — opening a new tab is anonymous until it gets its own\n *     `?code=` redirect.\n *\n * These choices are deliberate: the docs site is a session RECEIVER\n * (never a session OWNER), and the SaaS app is the authoritative source\n * of authentication. Replicating the SaaS app's session-management stack\n * here would force the docs Docusaurus bundle to ship inversify, the\n * resources framework, and a refresh interceptor — all of which are\n * about to be hardened (auth-hardening.md Slice A) in the SaaS app\n * specifically because they are sensitive surfaces. Keeping the docs\n * site free of those mechanisms keeps its attack surface tiny.\n *\n * The `apiBaseUrl` prop is supplied by the docs site at mount time\n * (typically read from a small `appConfig.json` shipped alongside the\n * Docusaurus bundle, or from an env var injected at build time). It is\n * not pulled from `saas-frontend-lib`'s `useApplication()` because that\n * would force this package to import the inversify-bound `appConfig`\n * provider — exactly the dependency we are avoiding.\n */\nexport const DocsAuthProvider: FC<{\n  children: ReactNode;\n  apiBaseUrl: string;\n  /**\n   * Optional materialized provider block for the active docs service.\n   * When omitted, the docs runtime exposes an empty provider registry.\n   */\n  frontendProviders?: FrontendProvidersBlock;\n  /**\n   * Runtime frontend service identity used for the `X-Frontend-Service-Name`\n   * header on exchange/handoff auth calls.\n   */\n  frontendServiceName?: string | null;\n  /**\n   * Optional override for tests. Production code constructs a\n   * `DocsAuthClient` from `apiBaseUrl` + the in-memory bearer.\n   */\n  client?: DocsAuthClient;\n}> = ({\n  children,\n  apiBaseUrl,\n  frontendProviders,\n  frontendServiceName = null,\n  client: clientOverride,\n}) => {\n  const [session, setSession] = useState<DocsAuthSession>({ status: 'anonymous' });\n\n  /**\n   * `getAuthBearer` reads from a closure over `session` so the bearer\n   * always reflects the *current* state without re-creating the client\n   * on every state change. The `useMemo` below depends only on\n   * `apiBaseUrl` so the client identity is stable across re-renders,\n   * which keeps `useEffect` dependency arrays in swizzles honest.\n   */\n  const sessionRef = useLatestRef(session);\n\n  const client = useMemo<DocsAuthClient>(() => {\n    if (clientOverride) return clientOverride;\n    return new DocsAuthClient({\n      apiBaseUrl,\n      frontendServiceName,\n      getAuthBearer: () =>\n        sessionRef.current.status === 'authenticated'\n          ? sessionRef.current.accessToken\n          : null,\n    });\n  }, [apiBaseUrl, frontendServiceName, clientOverride, sessionRef]);\n  const frontendProviderRegistry = useMemo(\n    () => createFrontendTechdocProviderRegistry(frontendProviders),\n    [frontendProviders],\n  );\n\n  /**\n   * Auto-clear when the access token expires.\n   *\n   * Sets a single timer based on `claims.exp`; on tick, transitions the\n   * session back to `anonymous`. No polling, no refresh — the next\n   * gated action will trigger a re-handshake via `requestCrossFrontendHandoff`.\n   *\n   * The timer is recreated whenever the session transitions to\n   * `authenticated`, and cleared on unmount or on transition AWAY from\n   * `authenticated` to avoid stale timers firing into a fresh session.\n   */\n  useEffect(() => {\n    if (session.status !== 'authenticated') return;\n    const msUntilExpiry = session.claims.exp * 1000 - Date.now();\n    if (msUntilExpiry <= 0) {\n      setSession({ status: 'anonymous' });\n      return;\n    }\n    const handle = setTimeout(() => {\n      setSession({ status: 'anonymous' });\n    }, msUntilExpiry);\n    return () => clearTimeout(handle);\n  }, [session]);\n\n  const beginExchange = useCallback(\n    async (code: string): Promise<DocsBeginExchangeResult> => {\n      setSession({ status: 'exchanging' });\n      try {\n        const response = await client.exchangeAuthCode(code);\n        // `returnPath` lives at the TOP LEVEL of `TokenExchangeResponseSchema`\n        // — NOT under `metadata`. Reading `response.metadata?.returnPath`\n        // (the previous shape this code targeted) is silently `undefined`\n        // because the schema has no `metadata` envelope. The previous\n        // implementation made every docs handoff fall through to the URL\n        // `?return=` value, defeating Step 5's \"response value is the\n        // source of truth\" contract. See H-3 in the Step 5 second\n        // deep-review log on `cross-app-jwt-propagation.md`.\n        const returnPath = response.returnPath ?? null;\n        const claims = decodeJwtClaims(response.accessToken);\n        if (!claims) {\n          /**\n           * The exchange succeeded but the returned token isn't decodable.\n           * Treat as anonymous rather than half-authenticated — the\n           * swizzles never have to handle a `claims === null &&\n           * status === 'authenticated'` corner case. We still surface\n           * `returnPath` so the exchange page can navigate the user\n           * somewhere sensible (e.g. `/`) instead of stranding them on\n           * `/auth/exchange`.\n           */\n          setSession({ status: 'anonymous' });\n          return { claims: null, returnPath };\n        }\n        setSession({ status: 'authenticated', accessToken: response.accessToken, claims });\n        return { claims, returnPath };\n      } catch {\n        setSession({ status: 'anonymous' });\n        return { claims: null, returnPath: null };\n      }\n    },\n    [client],\n  );\n\n  const clear = useCallback(() => {\n    setSession({ status: 'anonymous' });\n  }, []);\n\n  const value = useMemo<DocsAuthContextValue>(\n    () => ({ session, client, frontendProviderRegistry, beginExchange, clear }),\n    [session, client, frontendProviderRegistry, beginExchange, clear],\n  );\n\n  return <DocsAuthContext.Provider value={value}>{children}</DocsAuthContext.Provider>;\n};\n\n/**\n * Tiny ref-of-latest-value helper. Avoids pulling in a utility lib for\n * one ~6-line function. Used here so the `DocsAuthClient`'s\n * `getAuthBearer` callback always sees the freshest session without\n * re-instantiating the client.\n *\n * Implementation discipline (L-NEW-1 fix from the Step 6 third\n * deep-review log): the previous implementation mutated `ref.current`\n * DURING render (the `ref.current = value;` line ran in the function\n * body), which violates React's \"no side effects during render\"\n * invariant and produces inconsistent reads under concurrent\n * rendering — a render that gets discarded by React's scheduler can\n * still leave a stale `ref.current` behind for the next render.\n *\n * The fix is the textbook React 18 pattern: hold the value in a real\n * `useRef`, then sync it inside `useEffect` after commit.\n *\n * Trade-off acknowledged: between render and effect-flush,\n * `ref.current` lags by one render. That is SAFE for this consumer\n * because `getAuthBearer()` is only invoked ASYNCHRONOUSLY (inside a\n * `fetch()` call originated by `requestCrossFrontendHandoff()` /\n * `exchangeAuthCode()`) — by the time the bearer is read, every\n * `useEffect` from the triggering render has already flushed and\n * `ref.current` reflects the latest committed session.\n *\n * Concretely: if the user clicks an org-API navbar entry that promotes\n * the session from `anonymous` → `exchanging` → `authenticated`, the\n * next fetch the client issues sees `authenticated` (ref synced after\n * commit) — never the stale `exchanging` value, even though the\n * `useMemo` factory may have captured the closure at the earlier\n * render.\n */\nfunction useLatestRef<T>(value: T): { current: T } {\n  const ref = useRef<T>(value);\n  useEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n"]}

package/dist/esm/runtime/decode-jwt-claims.d.ts

@@ -0,0 +1,39 @@
+import { type DocsJwtClaims } from './docs-auth-session.schemas';
+/**
+ * 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 declare function decodeJwtClaims(token: string): DocsJwtClaims | null;
+//# sourceMappingURL=decode-jwt-claims.d.ts.map

package/dist/esm/runtime/decode-jwt-claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-jwt-claims.d.ts","sourceRoot":"","sources":["../../../../src/runtime/decode-jwt-claims.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAoCnE"}