@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.4

package/dist/host/openapi/description.js

@@ -0,0 +1,181 @@
+"use strict";
+// =============================================================================
+// The `info.description` Markdown shown at the top of /api/docs (issue #53)
+// =============================================================================
+//
+// This is the getting-started guide. It is baked into the OpenAPI document
+// rather than written on a separate page so that it travels with the spec:
+// anyone who downloads `/api/openapi.json`, imports it into Postman, or
+// generates an SDK from it gets the same orientation the docs page shows.
+//
+// Keep it task-shaped (how do I get a token, what does a response look like,
+// how do I page) rather than a feature tour — the tag sections below it are the
+// feature tour. And keep it TRUE: everything here is checked against the
+// running code, because a getting-started guide that lies costs more than one
+// that is missing.
+//
+// Packaged in the host slice by #867: it describes the platform (sign-in,
+// tokens, the envelope, the error filter, permissions), so every app gets it;
+// the product name and repository URL arrive as arguments.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildApiDescription = buildApiDescription;
+/**
+ * Builds the Markdown intro.
+ *
+ * @param version - resolved application version, echoed so a reader can tell
+ *   which build they are pointed at without cross-checking `info.version`.
+ * @param identity - the product name and repository URL.
+ * @returns the Markdown.
+ * @stability experimental
+ */
+function buildApiDescription(version, identity) {
+    const { appName: APP_NAME, repoUrl: REPO_URL } = identity;
+    return `
+The HTTP API behind the **${APP_NAME}** — a production-grade application
+base with Google OAuth sign-in, role- and permission-based authorization, per-user and
+system settings, object storage, and an email allowlist gating who may sign in at all.
+
+This page is generated from the running server (build \`${version}\`), so it always matches the
+deployment you are pointed at. The machine-readable document is at
+[\`/api/openapi.json\`](/api/openapi.json).
+
+---
+
+## Getting a token
+
+Authentication is applied per route. Every operation below states which credentials it
+accepts; an operation with no security requirement listed needs none (the health probes and
+the sign-in routes themselves).
+
+There are three ways to obtain a bearer token, in rough order of how often you will want each.
+
+### 1. Your browser session (fastest, for exploring these docs)
+
+If you are already signed in to this deployment in this browser, press **Authorize with my
+session** at the top of this page. It calls \`POST /api/auth/refresh\` with your existing refresh
+cookie and loads the returned access token into the client below. Nothing to copy or paste, and
+the authorization survives a reload.
+
+Access tokens are short-lived (15 minutes by default). If calls start returning \`401\`, press the
+button again.
+
+### 2. Personal access token — scripts and automation
+
+Mint a \`pat_…\` token via \`POST /api/pat\` and send it as \`Authorization: Bearer pat_…\`. The
+authentication guard recognizes the \`pat_\` prefix before it ever reaches JWT verification, so a
+PAT is accepted on **every** authenticated route in this document — there is no narrower scope.
+It resolves to the full role and permission set of the user that minted it, which is why it should
+be treated exactly like that user's password. Revoke with \`DELETE /api/pat/{id}\`.
+
+### 3. Device authorization grant — CLI and other browserless clients
+
+For a machine that cannot open a browser, use the RFC 8628 flow: \`POST /api/auth/device/code\`
+to get a user code, show it to the user, and poll \`POST /api/auth/device/token\` until they
+approve it at the activation page. Sessions created this way are listed and revocable under
+**Device Authorization**; revoking one also revokes the credential the device collected.
+
+Note that sign-in of any kind is gated by the email allowlist: an address an administrator has
+not added cannot complete OAuth at all, regardless of which flow it uses.
+
+---
+
+## Response shape
+
+A global response interceptor wraps every successful JSON body in a \`data\` envelope, adding a
+sibling \`meta\` carrying the server timestamp:
+
+\`\`\`json
+{
+  "data": { "id": "…", "email": "…" },
+  "meta": { "timestamp": "2026-08-17T04:37:58.000Z" }
+}
+\`\`\`
+
+The one exception is a handler that already returns an object with a \`data\` key — the interceptor
+passes those through untouched, so they get no \`meta\`. The response schema shown for each
+operation is authoritative; it is generated by applying that same rule to the document.
+
+### Paginated lists
+
+Every list endpoint is offset-paginated with \`page\` and \`pageSize\` query parameters, but there
+are **two different body shapes**, and a client that consumes more than one list will hit both:
+
+- **Flat** — \`GET /api/users\`, \`GET /api/allowlist\`. Counts sit beside \`items\`:
+
+  \`\`\`json
+  { "data": { "items": [ … ], "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 } }
+  \`\`\`
+
+- **Nested** — \`GET /api/storage/objects\`. Counts sit in a \`meta\` object *inside* \`data\`, and
+  the total is named \`totalItems\` rather than \`total\`:
+
+  \`\`\`json
+  { "data": { "items": [ … ], "meta": { "page": 1, "pageSize": 20, "totalItems": 42, "totalPages": 3 } } }
+  \`\`\`
+
+Note also that the inner \`meta\` of a nested list is a different object from the envelope's own
+\`meta\`, which holds the timestamp. This asymmetry is a known defect, tracked separately; it is
+documented here rather than quietly smoothed over because the wire format is what it is today and
+a client has to handle both.
+
+---
+
+## Errors
+
+Every error passes through one exception filter, which rebuilds the body from a fixed key
+allowlist. These six keys are the complete set — nothing else can appear:
+
+\`\`\`json
+{
+  "statusCode": 409,
+  "code": "CONFLICT",
+  "message": "Email already in allowlist",
+  "details": { "field": "email" },
+  "timestamp": "2026-08-17T04:37:58.000Z",
+  "path": "/api/allowlist"
+}
+\`\`\`
+
+\`details\` is present only when the failure carried structured data, and it is the **only** place
+endpoint-specific data survives: a custom top-level field on a thrown exception is dropped before
+it reaches you. \`code\` is derived from the status by the filter and overrides anything the thrown
+exception set, so it is always one of the values enumerated on \`ErrorDto\` — branch on it rather
+than on \`message\`, which is prose.
+
+Errors are **not** wrapped in the \`data\` envelope: the filter writes straight to the reply and
+bypasses the response interceptor.
+
+---
+
+## Permissions
+
+Authorization is a single layer. A user holds one or more **system roles** — \`admin\`,
+\`contributor\`, \`viewer\` — and each role grants a set of **permissions** named \`resource:action\`
+(\`users:read\`, \`system_settings:write\`, \`storage:delete_any\`, \`rbac:manage\`).
+
+Guarded operations state their requirements in a generated **Requires:** line. Where several
+roles are listed the guard admits any one of them; where several permissions are listed the guard
+requires all of them. Those lines are rendered from the same \`@Auth()\` metadata the guards read,
+so they cannot drift from what the server enforces.
+
+Deactivated users are rejected at authentication time regardless of their roles.
+
+---
+
+## Conventions
+
+- All timestamps are ISO 8601 in UTC.
+- All ids are UUIDs unless documented otherwise.
+- Object sizes are returned as **strings**, not numbers — they are 64-bit values that would lose
+  precision as JSON numbers.
+- \`204 No Content\` responses have no body, and are therefore not enveloped.
+- The API is served same-origin under \`/api\`; this document's server is \`/\`.
+
+## Further reading
+
+Architecture, security and operations documentation lives in the repository under
+[\`docs/\`](${REPO_URL}/tree/main/docs).
+`.trim();
+}
+//# sourceMappingURL=description.js.map

package/dist/host/openapi/description.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"description.js","sourceRoot":"","sources":["../../../src/host/openapi/description.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,4EAA4E;AAC5E,gFAAgF;AAChF,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,wEAAwE;AACxE,0EAA0E;AAC1E,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,yEAAyE;AACzE,8EAA8E;AAC9E,mBAAmB;AACnB,EAAE;AACF,0EAA0E;AAC1E,8EAA8E;AAC9E,2DAA2D;AAC3D,gFAAgF;;AAuBhF,kDAoJC;AA7JD;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAAC,OAAe,EAAE,QAAgC;IACnF,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,QAAQ,CAAC;IAC1D,OAAO;4BACmB,QAAQ;;;;0DAIsB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2InD,QAAQ;CACrB,CAAC,IAAI,EAAE,CAAC;AACT,CAAC"}

package/dist/host/openapi/docs-page.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Where the standalone Scalar bundle is loaded from, unless `API_DOCS_CDN` overrides it.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_SCALAR_CDN = "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
+/**
+ * What {@link renderDocsPage} renders.
+ *
+ * @stability experimental
+ */
+export interface DocsPageOptions {
+    /** Browser tab title. */
+    title: string;
+    /** The product name, shown as `<appName> API` in the header bar. */
+    appName: string;
+    /** Application version, shown in the header bar. */
+    version: string;
+    /** Path the spec is fetched from, relative to the app root. */
+    specUrl: string;
+    /** Override for the reference bundle URL. */
+    cdn?: string;
+}
+/**
+ * What {@link renderDocsUnavailablePage} renders.
+ *
+ * @stability experimental
+ */
+export interface DocsUnavailablePageOptions {
+    /** Operator-facing explanation of why the reference is missing. */
+    message: string;
+    /** Path of the machine-readable spec, which is down for the same reason. */
+    specUrl: string;
+}
+/**
+ * Renders the complete docs page.
+ *
+ * Every interpolated value is either JSON-serialized or HTML-escaped; the two
+ * inline scripts additionally guard against a `</script` sequence closing the
+ * block early, which is the one way a JSON literal can break out of one.
+ *
+ * @param options - the title, product name, version and spec path.
+ * @returns the HTML page.
+ * @stability experimental
+ */
+export declare function renderDocsPage(options: DocsPageOptions): string;
+/**
+ * The page served at `/api/docs` when document generation failed at startup.
+ *
+ * Deliberately self-contained: no CDN bundle, no spec fetch, no script. The one
+ * thing that failed is the document, so a page that needs the document to
+ * render would fail the same way — and this page's whole job is to be the thing
+ * that still works.
+ *
+ * It names the failure and points at the logs rather than reproducing the
+ * error. The stack is in the process log, at `error` level, where an operator
+ * can already read it; putting it on an unauthenticated page would leak
+ * internals to anyone who can reach `/api/docs`.
+ *
+ * @param options - the message and spec path.
+ * @returns the HTML page.
+ * @stability experimental
+ */
+export declare function renderDocsUnavailablePage(options: DocsUnavailablePageOptions): string;
+/**
+ * The page's only runtime logic: exchange the session cookie for an access
+ * token, then mount Scalar pre-authorized with it.
+ *
+ * Exported, and returned as a standalone string, so `docs-page.spec.ts` can
+ * **execute** it against stubbed globals rather than pattern-match the markup.
+ * That distinction is not academic — this shipped broken precisely because the
+ * tests asserted the page *contained* `fetch('/api/auth/refresh')` and never ran
+ * it, so nothing noticed the response was being read one level too shallow.
+ *
+ * A plain string rather than a serialized TypeScript function on purpose: a
+ * function put through `Function.prototype.toString()` carries whatever the
+ * compiler emitted, including coverage instrumentation under `test:cov`, which
+ * would be broken JavaScript in a browser. A string is inert data, and the spec
+ * evaluates exactly the bytes the browser receives.
+ *
+ * @param config - the Scalar configuration.
+ * @param scheme - the security scheme the session token is loaded into.
+ * @returns the script body.
+ * @stability experimental
+ */
+export declare function buildDocsAuthScript(config: unknown, scheme: string): string;
+/**
+ * Kept in sync with `SECURITY_SCHEMES.JWT_AUTH` by the assertion in
+ * `docs-page.spec.ts` — importing it here would drag the whole document
+ * builder (and Nest) into a module that only renders a string.
+ *
+ * @stability experimental
+ */
+export declare const SESSION_SECURITY_SCHEME = "JWT-auth";
+//# sourceMappingURL=docs-page.d.ts.map

package/dist/host/openapi/docs-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-page.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/docs-page.ts"],"names":[],"mappings":"AA2BA;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,uDAAuD,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;CACjB;AAgBD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CA8D/D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,0BAA0B,GAClC,MAAM,CAgDR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA2D3E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,aAAa,CAAC"}

package/dist/host/openapi/docs-page.js

@@ -0,0 +1,297 @@
+"use strict";
+// =============================================================================
+// The /api/docs page (issue #53)
+// =============================================================================
+//
+// Renders the Scalar API reference: a searchable sectioned sidebar, a built-in
+// request client, generated code samples, and dark mode — replacing the stock
+// Swagger UI that shipped with the scaffold.
+//
+// WHY THIS TEMPLATE INSTEAD OF `@scalar/nestjs-api-reference`
+// -----------------------------------------------------------------------------
+// That package renders a fixed template whose last statement is the
+// `Scalar.createApiReference(...)` call. The one-click session auth below has to
+// resolve a token BEFORE that call, so it can be handed to Scalar as
+// pre-authorization rather than poked into Scalar's internal store afterwards.
+// The token cannot be resolved server-side either: the refresh cookie is scoped
+// to `path=/api/auth` and is therefore never sent to `/api/docs`. So the fetch
+// must happen in the browser, before mount — which is exactly the seam the
+// packaged template does not expose. Sixty lines of template we control beats
+// string-surgery on generated HTML.
+//
+// The reference bundle is loaded from a CDN, matching Scalar's own default.
+// `API_DOCS_CDN` overrides it, which is the escape hatch for an air-gapped
+// deployment that wants to self-host the bundle behind its own nginx.
+//
+// Packaged in the host slice by #867; the product name arrives as `appName`.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_SECURITY_SCHEME = exports.DEFAULT_SCALAR_CDN = void 0;
+exports.renderDocsPage = renderDocsPage;
+exports.renderDocsUnavailablePage = renderDocsUnavailablePage;
+exports.buildDocsAuthScript = buildDocsAuthScript;
+/**
+ * Where the standalone Scalar bundle is loaded from, unless `API_DOCS_CDN` overrides it.
+ *
+ * @stability experimental
+ */
+exports.DEFAULT_SCALAR_CDN = 'https://cdn.jsdelivr.net/npm/@scalar/api-reference';
+/**
+ * A 🧱 favicon as a data URI.
+ *
+ * Inline rather than a served file so the docs page has no second request and
+ * no dependency on static-asset routing, which differs between the dev server
+ * and the nginx-fronted deployment.
+ */
+const FAVICON = 'data:image/svg+xml,' +
+    encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">' +
+        '<text y=".9em" font-size="90">🧱</text></svg>');
+/**
+ * Renders the complete docs page.
+ *
+ * Every interpolated value is either JSON-serialized or HTML-escaped; the two
+ * inline scripts additionally guard against a `</script` sequence closing the
+ * block early, which is the one way a JSON literal can break out of one.
+ *
+ * @param options - the title, product name, version and spec path.
+ * @returns the HTML page.
+ * @stability experimental
+ */
+function renderDocsPage(options) {
+    const cdn = options.cdn || process.env.API_DOCS_CDN || exports.DEFAULT_SCALAR_CDN;
+    const scalarConfig = {
+        url: options.specUrl,
+        theme: 'default',
+        // Dark mode follows the OS by default, with Scalar's own toggle left
+        // visible so a reader can override it — same posture as the app itself.
+        hideDarkModeToggle: false,
+        layout: 'modern',
+        // Ordering is already deliberate in `tags.ts`; re-sorting here would throw
+        // that away and render the sections alphabetically.
+        defaultOpenAllTags: false,
+        hideModels: false,
+        searchHotKey: 'k',
+    };
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(options.title)}</title>
+    <link rel="icon" href="${FAVICON}" />
+    <style>
+      body { margin: 0; }
+      #eaf-authbar {
+        display: flex; align-items: center; gap: 12px; flex-wrap: wrap;
+        padding: 8px 16px; font: 13px/1.4 ui-sans-serif, system-ui, -apple-system, sans-serif;
+        background: #11131e; color: #e7e7e7; border-bottom: 1px solid rgba(255,255,255,.12);
+      }
+      #eaf-authbar strong { font-weight: 600; }
+      #eaf-authbar .eaf-version { color: #8e93a8; }
+      #eaf-authbar .eaf-spacer { flex: 1 1 auto; }
+      #eaf-authbar button {
+        font: inherit; cursor: pointer; padding: 5px 12px; border-radius: 6px;
+        border: 1px solid rgba(255,255,255,.2); background: #2f354a; color: inherit;
+      }
+      #eaf-authbar button:hover { background: #3c435c; }
+      #eaf-status::before { content: '●'; margin-right: 6px; }
+      #eaf-status.eaf-ok { color: #30beb0; }
+      #eaf-status.eaf-warn { color: #ffc90d; }
+      #eaf-status.eaf-pending { color: #8e93a8; }
+    </style>
+  </head>
+  <body>
+    <div id="eaf-authbar">
+      <strong>${escapeHtml(`${options.appName} API`)}</strong>
+      <span class="eaf-version">${escapeHtml(options.version)}</span>
+      <span class="eaf-spacer"></span>
+      <span id="eaf-status" class="eaf-pending">Checking your session…</span>
+      <button id="eaf-auth" type="button">Authorize with my session</button>
+      <a href="${escapeHtml(options.specUrl)}" style="color:#2cb6f6">openapi.json</a>
+    </div>
+    <div id="app"></div>
+    <script src="${escapeHtml(cdn)}"></script>
+    <script>
+${buildDocsAuthScript(scalarConfig, exports.SESSION_SECURITY_SCHEME)}
+    </script>
+  </body>
+</html>
+`;
+}
+/**
+ * The page served at `/api/docs` when document generation failed at startup.
+ *
+ * Deliberately self-contained: no CDN bundle, no spec fetch, no script. The one
+ * thing that failed is the document, so a page that needs the document to
+ * render would fail the same way — and this page's whole job is to be the thing
+ * that still works.
+ *
+ * It names the failure and points at the logs rather than reproducing the
+ * error. The stack is in the process log, at `error` level, where an operator
+ * can already read it; putting it on an unauthenticated page would leak
+ * internals to anyone who can reach `/api/docs`.
+ *
+ * @param options - the message and spec path.
+ * @returns the HTML page.
+ * @stability experimental
+ */
+function renderDocsUnavailablePage(options) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>API Reference Unavailable</title>
+    <link rel="icon" href="${FAVICON}" />
+    <style>
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: #f7f7f8;
+        color: #1a1a1a;
+        font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+        line-height: 1.6;
+      }
+      main { max-width: 34rem; padding: 2rem; }
+      h1 { font-size: 1.5rem; margin: 0 0 1rem; }
+      p { margin: 0 0 1rem; }
+      code {
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        background: #ececf0;
+        border-radius: 3px;
+        padding: 0.1em 0.35em;
+      }
+      @media (prefers-color-scheme: dark) {
+        body { background: #131316; color: #e8e8ea; }
+        code { background: #26262b; }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>API reference unavailable</h1>
+      <p>${escapeHtml(options.message)}</p>
+      <p>
+        The API itself is unaffected — only this reference and
+        <code>${escapeHtml(options.specUrl)}</code> are down. They return again
+        once the document builds on a restart.
+      </p>
+    </main>
+  </body>
+</html>
+`;
+}
+/**
+ * The page's only runtime logic: exchange the session cookie for an access
+ * token, then mount Scalar pre-authorized with it.
+ *
+ * Exported, and returned as a standalone string, so `docs-page.spec.ts` can
+ * **execute** it against stubbed globals rather than pattern-match the markup.
+ * That distinction is not academic — this shipped broken precisely because the
+ * tests asserted the page *contained* `fetch('/api/auth/refresh')` and never ran
+ * it, so nothing noticed the response was being read one level too shallow.
+ *
+ * A plain string rather than a serialized TypeScript function on purpose: a
+ * function put through `Function.prototype.toString()` carries whatever the
+ * compiler emitted, including coverage instrumentation under `test:cov`, which
+ * would be broken JavaScript in a browser. A string is inert data, and the spec
+ * evaluates exactly the bytes the browser receives.
+ *
+ * @param config - the Scalar configuration.
+ * @param scheme - the security scheme the session token is loaded into.
+ * @returns the script body.
+ * @stability experimental
+ */
+function buildDocsAuthScript(config, scheme) {
+    return `      (function () {
+        var CONFIG = ${jsonForScript(config)};
+        var SCHEME = ${jsonForScript(scheme)};
+        var statusEl = document.getElementById('eaf-status');
+        var buttonEl = document.getElementById('eaf-auth');
+
+        function setStatus(text, kind) {
+          statusEl.textContent = text;
+          statusEl.className = 'eaf-' + kind;
+        }
+
+        // Exchanges the browser's refresh cookie for a short-lived access
+        // token. \`credentials: 'include'\` is required even same-origin here:
+        // the cookie is path-scoped to /api/auth, so it rides along only
+        // because this request targets that path.
+        function fetchSessionToken() {
+          return fetch('/api/auth/refresh', {
+            method: 'POST',
+            credentials: 'include',
+            headers: { Accept: 'application/json' },
+          })
+            .then(function (res) { return res.ok ? res.json() : null; })
+            .then(function (body) {
+              // The global response interceptor wraps every JSON body in
+              // { data, meta }, so the token is at body.data.accessToken — NOT
+              // body.accessToken. Tolerating both mirrors the web client, and
+              // means this keeps working whichever shape the endpoint returns.
+              var payload = (body && body.data) || body;
+              return (payload && payload.accessToken) || null;
+            })
+            .catch(function () { return null; });
+        }
+
+        function mount(token) {
+          var config = Object.assign({}, CONFIG);
+          if (token) {
+            var schemes = {};
+            schemes[SCHEME] = { token: token };
+            config.authentication = { preferredSecurityScheme: SCHEME, securitySchemes: schemes };
+            setStatus('Authorized with your session', 'ok');
+          } else {
+            setStatus('Not signed in \u2014 sign in, then reload', 'warn');
+          }
+          window.Scalar.createApiReference('#app', config);
+          return token;
+        }
+
+        // Re-authorizing means re-mounting, and re-mounting cleanly is what a
+        // reload already does — the fetch above runs again on load. The button
+        // is for a token that has expired (15 minutes); landing here signed in
+        // needs no click at all.
+        buttonEl.addEventListener('click', function () { window.location.reload(); });
+
+        // Exposed so the spec can await the bootstrap, and so a reader
+        // debugging an authorization problem in the console has something to
+        // inspect.
+        window.__eafDocsAuth = fetchSessionToken().then(mount);
+      })();`;
+}
+/**
+ * Kept in sync with `SECURITY_SCHEMES.JWT_AUTH` by the assertion in
+ * `docs-page.spec.ts` — importing it here would drag the whole document
+ * builder (and Nest) into a module that only renders a string.
+ *
+ * @stability experimental
+ */
+exports.SESSION_SECURITY_SCHEME = 'JWT-auth';
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+/**
+ * JSON for embedding inside a `<script>` block.
+ *
+ * `JSON.stringify` alone is not safe there: a `</script` inside any string
+ * value ends the block, and `<!--` starts an HTML comment. Both are escaped
+ * into equivalent JSON that the parser reads identically.
+ */
+function jsonForScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+//# sourceMappingURL=docs-page.js.map

package/dist/host/openapi/docs-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-page.js","sourceRoot":"","sources":["../../../src/host/openapi/docs-page.ts"],"names":[],"mappings":"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"}