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

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

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUIREMENTS_MARKER = void 0;
+exports.applyRbacDocs = applyRbacDocs;
+exports.describeRequirements = describeRequirements;
+const index_1 = require("../../identity/index");
+const types_1 = require("./types");
+/**
+ * Marker prepended to every generated requirements line.
+ *
+ * Serves two purposes: it is the visible label a reader sees, and it makes the
+ * pass idempotent — an operation whose description already contains it is left
+ * alone, so running the enrichment twice (a test, a re-created document) can
+ * never stack duplicate blocks.
+ *
+ * @stability experimental
+ */
+exports.REQUIREMENTS_MARKER = '**Requires:**';
+/**
+ * Renders the `x-rbac` extension stamped by `@Auth()` into each operation's
+ * description.
+ *
+ * This runs over the finished document rather than inside the decorator on
+ * purpose. A decorator that wrote `description` directly would race the
+ * controller's own `@ApiOperation({ description })` — decorators evaluate
+ * bottom-up and `@nestjs/swagger` merges operation metadata shallowly, so
+ * whichever ran last would silently clobber the other. Post-processing appends
+ * instead, so hand-written prose and generated requirements coexist.
+ */
+function applyRbacDocs(document) {
+    (0, types_1.forEachOperation)(document, (operation) => {
+        const line = describeRequirements(operation);
+        if (!line)
+            return;
+        const existing = operation.description ?? '';
+        if (existing.includes(exports.REQUIREMENTS_MARKER))
+            return;
+        operation.description = existing ? `${existing}\n\n${line}` : line;
+    });
+    return document;
+}
+/**
+ * The one-line requirements sentence for an operation, or `null` when the
+ * operation is something this pass has nothing to say about.
+ */
+function describeRequirements(operation) {
+    const rbac = operation[index_1.RBAC_EXTENSION_KEY];
+    if (!rbac || rbac.authenticated !== true) {
+        // No `@Auth()` on this handler. A few routes — on the auth and
+        // device-authorization controllers — instead compose
+        // `@UseGuards(JwtAuthGuard)` with a bare `@ApiBearerAuth('JWT-auth')`,
+        // where the RBAC guards would have nothing to check. Those declare a
+        // security requirement and nothing more, which is exactly what the
+        // authentication-only line says.
+        //
+        // Everything else is `@Public()` or guarded by something bespoke: no
+        // decorator metadata to render, and inventing a claim about it would be
+        // worse than saying nothing.
+        const declaresSecurity = (operation.security ?? []).length > 0;
+        return declaresSecurity ? authenticationOnly() : null;
+    }
+    const clauses = [];
+    const roles = rbac.roles ?? [];
+    const permissions = rbac.permissions ?? [];
+    const anyPermissions = rbac.anyPermissions ?? [];
+    if (roles.length === 1) {
+        clauses.push(`system role ${code(roles[0])}`);
+    }
+    else if (roles.length > 1) {
+        clauses.push(`any of the system roles ${roles.map(code).join(', ')}`);
+    }
+    if (permissions.length === 1) {
+        clauses.push(`permission ${code(permissions[0])}`);
+    }
+    else if (permissions.length > 1) {
+        // The guard requires ALL of them, so join with "and" rather than a bare
+        // comma list that reads as alternatives.
+        clauses.push(`permissions ${permissions.map(code).join(' and ')}`);
+    }
+    if (anyPermissions.length === 1) {
+        clauses.push(`permission ${code(anyPermissions[0])}`);
+    }
+    else if (anyPermissions.length > 1) {
+        // `anyPermissions`: the guard admits a holder of AT LEAST ONE (a route two
+        // scopes reach, such as `users:read` for system roles and
+        // `org_members:read` for org roles).
+        clauses.push(`at least one of the permissions ${anyPermissions.map(code).join(' or ')}`);
+    }
+    if (clauses.length === 0) {
+        return authenticationOnly();
+    }
+    return `${exports.REQUIREMENTS_MARKER} authentication, plus ${joinClauses(clauses)}.`;
+}
+function authenticationOnly() {
+    return `${exports.REQUIREMENTS_MARKER} authentication only — any signed-in user may call this.`;
+}
+function code(value) {
+    return `\`${value}\``;
+}
+function joinClauses(clauses) {
+    if (clauses.length === 1)
+        return clauses[0];
+    return `${clauses.slice(0, -1).join(', ')} and ${clauses[clauses.length - 1]}`;
+}
+//# sourceMappingURL=rbac-docs.js.map

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

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

package/dist/host/openapi/register-docs-routes.d.ts

@@ -0,0 +1,177 @@
+import type { INestApplication } from '@nestjs/common';
+import type { OpenAPIObject } from '@nestjs/swagger';
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import { type PlatformOpenApiOptions } from './document';
+/**
+ * Canonical machine-readable document.
+ *
+ * @stability experimental
+ */
+export declare const OPENAPI_JSON_PATH = "/api/openapi.json";
+/**
+ * Interactive reference.
+ *
+ * @stability experimental
+ */
+export declare const DOCS_PATH = "/api/docs";
+/**
+ * Who the docs page names and which build it reports.
+ *
+ * @stability experimental
+ */
+export interface DocsRoutesOptions {
+    /** The product name: the page title is `<appName> API Reference`. */
+    appName: string;
+    /** The version shown in the header bar. */
+    version: string;
+}
+/**
+ * The Fastify-backed application the docs routes mount on (structural, so the
+ * package does not need `@nestjs/platform-fastify` at runtime).
+ *
+ * @stability experimental
+ */
+export type DocsHostApplication = INestApplication & {
+    /** The HTTP adapter; its instance is the Fastify server. */
+    getHttpAdapter(): DocsHttpAdapter;
+};
+/**
+ * The HTTP adapter of a {@link DocsHostApplication}.
+ *
+ * @stability experimental
+ */
+export interface DocsHttpAdapter {
+    /** The underlying server. */
+    getInstance(): DocsHttpServer;
+}
+/**
+ * The slice of the Fastify instance the docs routes use.
+ *
+ * @stability experimental
+ */
+export interface DocsHttpServer {
+    /** Registers a GET route. */
+    get(path: string, handler: (request: FastifyRequest, reply: FastifyReply) => unknown): unknown;
+}
+/**
+ * Machine-readable code on the degraded JSON response.
+ *
+ * Not one of `HttpExceptionFilter`'s status-derived codes: these are raw
+ * Fastify routes that never reach the filter, and the code it would produce for
+ * a 503 is the `ERROR` fallback, which tells a client nothing. A distinct code
+ * lets a consumer distinguish "the spec is temporarily ungenerated" from any
+ * other 503 the deployment can emit.
+ *
+ * @stability experimental
+ */
+export declare const OPENAPI_UNAVAILABLE_CODE = "OPENAPI_DOCUMENT_UNAVAILABLE";
+/**
+ * Shown on the degraded page and returned as the degraded JSON `message`.
+ *
+ * @stability experimental
+ */
+export declare const DOCS_UNAVAILABLE_MESSAGE: string;
+/**
+ * The subset of `Logger` this module needs, so a spec can pass a spy without
+ * constructing (or silencing) a real Nest logger.
+ *
+ * @stability experimental
+ */
+export interface DocsLogger {
+    /** Logs one error line, with the stack when there is one. */
+    error(message: string, stack?: string): void;
+}
+/**
+ * Registers the two documentation routes on the Fastify instance.
+ *
+ * Raw Fastify routes rather than `SwaggerModule.setup`, for two reasons: the
+ * page is our own template (see `docs-page.ts` for why), and `setup` would
+ * additionally mount the stock Swagger UI on the same path.
+ *
+ * Registering directly also keeps both routes outside the Nest guard pipeline —
+ * matching what `SwaggerModule.setup` already did, and keeping the reference
+ * readable during maintenance mode, which is exactly when an operator is most
+ * likely to want it.
+ *
+ * Lives here rather than inline in `main.ts` so it can be exercised against a
+ * test application; `main.ts` itself is excluded from coverage and cannot be
+ * booted by a spec.
+ *
+ * Throws whatever `renderDocsPage` throws. `main.ts` calls
+ * {@link registerDocsRoutesOrDegrade} instead, which is this plus the failure
+ * handling; call this one directly only where a throw is what you want.
+ *
+ * @param app - the Fastify-backed application, before `init()`/`listen()`.
+ * @param document - the built document.
+ * @param options - the product name and version the page shows.
+ * @stability experimental
+ */
+export declare function registerDocsRoutes(app: DocsHostApplication, document: OpenAPIObject, options: DocsRoutesOptions): void;
+/**
+ * Builds the document and registers the routes, degrading to a 503 on both
+ * paths if either step throws.
+ *
+ * WHY THIS IS WRAPPED AT ALL (issue #69)
+ * ---------------------------------------------------------------------------
+ * `main.ts` builds the document before `app.listen()`. Generation walks every
+ * controller's metadata and every DTO's schema, which is the largest failure
+ * surface of anything that runs before the port is bound — so an unguarded
+ * throw turns a documentation defect into a total outage. That is not
+ * hypothetical: issue #60 was four DTOs using `z.date()`, which zod v4 refuses
+ * to represent in JSON Schema, and the API could not start in any environment
+ * because of it. The reference is a convenience; the API is not. Their
+ * availability should not be coupled.
+ *
+ * WHY THERE IS NO `NODE_ENV` GATE
+ * ---------------------------------------------------------------------------
+ * The obvious alternative is to rethrow outside production, on the theory that
+ * a developer wants a loud crash. We deliberately do not, for two reasons.
+ *
+ * First, it would make the recovery path production-only — a path that runs
+ * exclusively in the environment nobody can rehearse in, discovered for the
+ * first time during the incident it exists to soften. Degrading everywhere
+ * means every `npm test` run, every local boot and every CI job exercises the
+ * same code production depends on.
+ *
+ * Second, the loud signal a developer needs already exists and is stronger than
+ * a crash: the `openapi` CI job runs `openapi:dump`, which calls
+ * `createOpenApiDocument` outside any try/catch and exits non-zero on failure,
+ * so a broken document still fails the build and cannot merge. Add the
+ * `error`-level log below and the 503 that replaces the page, and a local
+ * failure is impossible to miss without also being impossible to work around.
+ * Degrading here narrows the blast radius; it does not make a broken document
+ * acceptable.
+ *
+ * @param app - the Fastify-backed application, before `init()`/`listen()`.
+ * @param buildDocument - builds the document; a throw degrades both routes.
+ * @param options - the product name and version the page shows.
+ * @param logger - where a generation failure is logged.
+ * @returns `true` if the real reference was registered, `false` if the degraded
+ *   one was — so the caller can log accordingly.
+ * @stability experimental
+ */
+export declare function registerDocsRoutesOrDegrade(app: DocsHostApplication, buildDocument: () => OpenAPIObject, options: DocsRoutesOptions, logger?: DocsLogger): boolean;
+/**
+ * Builds the app's OpenAPI document and mounts `/api/docs` and
+ * `/api/openapi.json`, degrading both to a 503 when generation throws (the
+ * rest of the API is unaffected). Call it once in `main.ts`, after
+ * `setGlobalPrefix('api')` and before `listen()`.
+ *
+ * @param app - the Fastify-backed application.
+ * @param openApi - the app's identity and version (the same object its
+ *   `PlatformHostCoreModule.forRoot({ openApi })` and its dump script use).
+ * @param logger - where a generation failure is logged.
+ * @returns `true` when the real reference was mounted, `false` when the degraded one was.
+ *
+ * @example
+ * ```ts
+ * app.setGlobalPrefix('api');
+ * const docsReady = registerPlatformDocs(app, APP_OPENAPI);
+ * await app.listen(port, '0.0.0.0');
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+export declare function registerPlatformDocs(app: DocsHostApplication, openApi: PlatformOpenApiOptions, logger?: DocsLogger): boolean;
+//# sourceMappingURL=register-docs-routes.d.ts.map

package/dist/host/openapi/register-docs-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-docs-routes.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/register-docs-routes.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE5D,OAAO,EAAgD,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEvG;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD;;;;GAIG;AACH,eAAO,MAAM,SAAS,cAAc,CAAC;AAErC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,gBAAgB,GAAG;IACnD,4DAA4D;IAC5D,cAAc,IAAI,eAAe,CAAC;CACnC,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,WAAW,IAAI,cAAc,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,GAAG,OAAO,CAAC;CAChG;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,iCAAiC,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,QAEc,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9C;AAWD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,mBAAmB,EACxB,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,iBAAiB,GACzB,IAAI,CAEN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,mBAAmB,EACxB,aAAa,EAAE,MAAM,aAAa,EAClC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,GAAE,UAAkC,GACzC,OAAO,CAsBT;AAqED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,mBAAmB,EACxB,OAAO,EAAE,sBAAsB,EAC/B,MAAM,GAAE,UAAkC,GACzC,OAAO,CAOT"}

package/dist/host/openapi/register-docs-routes.js

@@ -0,0 +1,218 @@
+"use strict";
+// =============================================================================
+// `/api/docs` and `/api/openapi.json` (issue #53; packaged by #867)
+// =============================================================================
+//
+// Two raw Fastify routes, mounted at bootstrap (after `setGlobalPrefix`, before
+// `listen`) by `registerPlatformDocs(app)`. Outside Nest's router, so neither
+// reaches the maintenance guard: the reference stays readable during a window
+// (docs/specs/maintenance-mode.md).
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOCS_UNAVAILABLE_MESSAGE = exports.OPENAPI_UNAVAILABLE_CODE = exports.DOCS_PATH = exports.OPENAPI_JSON_PATH = void 0;
+exports.registerDocsRoutes = registerDocsRoutes;
+exports.registerDocsRoutesOrDegrade = registerDocsRoutesOrDegrade;
+exports.registerPlatformDocs = registerPlatformDocs;
+const common_1 = require("@nestjs/common");
+const docs_page_1 = require("./docs-page");
+const document_1 = require("./document");
+/**
+ * Canonical machine-readable document.
+ *
+ * @stability experimental
+ */
+exports.OPENAPI_JSON_PATH = '/api/openapi.json';
+/**
+ * Interactive reference.
+ *
+ * @stability experimental
+ */
+exports.DOCS_PATH = '/api/docs';
+/**
+ * Machine-readable code on the degraded JSON response.
+ *
+ * Not one of `HttpExceptionFilter`'s status-derived codes: these are raw
+ * Fastify routes that never reach the filter, and the code it would produce for
+ * a 503 is the `ERROR` fallback, which tells a client nothing. A distinct code
+ * lets a consumer distinguish "the spec is temporarily ungenerated" from any
+ * other 503 the deployment can emit.
+ *
+ * @stability experimental
+ */
+exports.OPENAPI_UNAVAILABLE_CODE = 'OPENAPI_DOCUMENT_UNAVAILABLE';
+/**
+ * Shown on the degraded page and returned as the degraded JSON `message`.
+ *
+ * @stability experimental
+ */
+exports.DOCS_UNAVAILABLE_MESSAGE = 'The API reference failed to generate when this server started. ' +
+    'Check the server logs for the underlying error.';
+/**
+ * Registers the two documentation routes on the Fastify instance.
+ *
+ * Raw Fastify routes rather than `SwaggerModule.setup`, for two reasons: the
+ * page is our own template (see `docs-page.ts` for why), and `setup` would
+ * additionally mount the stock Swagger UI on the same path.
+ *
+ * Registering directly also keeps both routes outside the Nest guard pipeline —
+ * matching what `SwaggerModule.setup` already did, and keeping the reference
+ * readable during maintenance mode, which is exactly when an operator is most
+ * likely to want it.
+ *
+ * Lives here rather than inline in `main.ts` so it can be exercised against a
+ * test application; `main.ts` itself is excluded from coverage and cannot be
+ * booted by a spec.
+ *
+ * Throws whatever `renderDocsPage` throws. `main.ts` calls
+ * {@link registerDocsRoutesOrDegrade} instead, which is this plus the failure
+ * handling; call this one directly only where a throw is what you want.
+ *
+ * @param app - the Fastify-backed application, before `init()`/`listen()`.
+ * @param document - the built document.
+ * @param options - the product name and version the page shows.
+ * @stability experimental
+ */
+function registerDocsRoutes(app, document, options) {
+    mountDocsRoutes(app, buildDocsHandlers(document, options));
+}
+/**
+ * Builds the document and registers the routes, degrading to a 503 on both
+ * paths if either step throws.
+ *
+ * WHY THIS IS WRAPPED AT ALL (issue #69)
+ * ---------------------------------------------------------------------------
+ * `main.ts` builds the document before `app.listen()`. Generation walks every
+ * controller's metadata and every DTO's schema, which is the largest failure
+ * surface of anything that runs before the port is bound — so an unguarded
+ * throw turns a documentation defect into a total outage. That is not
+ * hypothetical: issue #60 was four DTOs using `z.date()`, which zod v4 refuses
+ * to represent in JSON Schema, and the API could not start in any environment
+ * because of it. The reference is a convenience; the API is not. Their
+ * availability should not be coupled.
+ *
+ * WHY THERE IS NO `NODE_ENV` GATE
+ * ---------------------------------------------------------------------------
+ * The obvious alternative is to rethrow outside production, on the theory that
+ * a developer wants a loud crash. We deliberately do not, for two reasons.
+ *
+ * First, it would make the recovery path production-only — a path that runs
+ * exclusively in the environment nobody can rehearse in, discovered for the
+ * first time during the incident it exists to soften. Degrading everywhere
+ * means every `npm test` run, every local boot and every CI job exercises the
+ * same code production depends on.
+ *
+ * Second, the loud signal a developer needs already exists and is stronger than
+ * a crash: the `openapi` CI job runs `openapi:dump`, which calls
+ * `createOpenApiDocument` outside any try/catch and exits non-zero on failure,
+ * so a broken document still fails the build and cannot merge. Add the
+ * `error`-level log below and the 503 that replaces the page, and a local
+ * failure is impossible to miss without also being impossible to work around.
+ * Degrading here narrows the blast radius; it does not make a broken document
+ * acceptable.
+ *
+ * @param app - the Fastify-backed application, before `init()`/`listen()`.
+ * @param buildDocument - builds the document; a throw degrades both routes.
+ * @param options - the product name and version the page shows.
+ * @param logger - where a generation failure is logged.
+ * @returns `true` if the real reference was registered, `false` if the degraded
+ *   one was — so the caller can log accordingly.
+ * @stability experimental
+ */
+function registerDocsRoutesOrDegrade(app, buildDocument, options, logger = new common_1.Logger('OpenAPI')) {
+    let handlers;
+    let ok = true;
+    // Everything fallible happens here, BEFORE the first `fastify.get`. If a
+    // route were already mounted when the failure surfaced, mounting the
+    // replacement would collide with it and throw a second time — out of the
+    // catch, and back into the outage this function exists to prevent.
+    try {
+        handlers = buildDocsHandlers(buildDocument(), options);
+    }
+    catch (error) {
+        ok = false;
+        logger.error(`OpenAPI document generation failed; ${exports.DOCS_PATH} and ${exports.OPENAPI_JSON_PATH} ` +
+            'will return 503. The rest of the API is unaffected.', error instanceof Error ? error.stack : String(error));
+        handlers = buildDegradedDocsHandlers();
+    }
+    mountDocsRoutes(app, handlers);
+    return ok;
+}
+/** Handlers for a document that built successfully. */
+function buildDocsHandlers(document, options) {
+    const page = (0, docs_page_1.renderDocsPage)({
+        title: `${options.appName} API Reference`,
+        appName: options.appName,
+        version: options.version,
+        specUrl: exports.OPENAPI_JSON_PATH,
+    });
+    return {
+        json: (_req, reply) => reply.type('application/json').send(document),
+        page: (_req, reply) => reply.type('text/html').send(page),
+    };
+}
+/**
+ * Handlers for a document that did not build.
+ *
+ * 503 rather than 404 or a bare status: a 404 would read as "this deployment
+ * has no reference", which is wrong and sends the reader looking in the wrong
+ * place. 503 says the resource exists and is currently unavailable, and both
+ * bodies say why and where to look. Neither carries the error itself — that is
+ * in the log, and these routes are unauthenticated.
+ */
+function buildDegradedDocsHandlers() {
+    const page = (0, docs_page_1.renderDocsUnavailablePage)({
+        message: exports.DOCS_UNAVAILABLE_MESSAGE,
+        specUrl: exports.OPENAPI_JSON_PATH,
+    });
+    return {
+        json: (request, reply) => reply
+            .code(503)
+            .type('application/json')
+            // The shared error envelope, hand-built: `HttpExceptionFilter` shapes
+            // this for Nest routes, and these are not Nest routes.
+            .send({
+            statusCode: 503,
+            code: exports.OPENAPI_UNAVAILABLE_CODE,
+            message: exports.DOCS_UNAVAILABLE_MESSAGE,
+            timestamp: new Date().toISOString(),
+            path: request.url,
+        }),
+        page: (_req, reply) => reply.code(503).type('text/html').send(page),
+    };
+}
+/** The route table itself — identical whether the document built or not. */
+function mountDocsRoutes(app, handlers) {
+    const fastify = app.getHttpAdapter().getInstance();
+    fastify.get(exports.OPENAPI_JSON_PATH, handlers.json);
+    // Both spellings: a reader who types the path with a trailing slash should
+    // not get a 404 from the one page whose job is to orient them.
+    for (const path of [exports.DOCS_PATH, `${exports.DOCS_PATH}/`]) {
+        fastify.get(path, handlers.page);
+    }
+}
+/**
+ * Builds the app's OpenAPI document and mounts `/api/docs` and
+ * `/api/openapi.json`, degrading both to a 503 when generation throws (the
+ * rest of the API is unaffected). Call it once in `main.ts`, after
+ * `setGlobalPrefix('api')` and before `listen()`.
+ *
+ * @param app - the Fastify-backed application.
+ * @param openApi - the app's identity and version (the same object its
+ *   `PlatformHostCoreModule.forRoot({ openApi })` and its dump script use).
+ * @param logger - where a generation failure is logged.
+ * @returns `true` when the real reference was mounted, `false` when the degraded one was.
+ *
+ * @example
+ * ```ts
+ * app.setGlobalPrefix('api');
+ * const docsReady = registerPlatformDocs(app, APP_OPENAPI);
+ * await app.listen(port, '0.0.0.0');
+ * ```
+ *
+ * @extensionPoint option
+ * @stability experimental
+ */
+function registerPlatformDocs(app, openApi, logger = new common_1.Logger('OpenAPI')) {
+    return registerDocsRoutesOrDegrade(app, () => (0, document_1.createOpenApiDocument)(app, openApi), { appName: openApi.appName, version: (0, document_1.resolveOpenApiVersion)(openApi) }, logger);
+}
+//# sourceMappingURL=register-docs-routes.js.map

package/dist/host/openapi/register-docs-routes.js.map

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

package/dist/host/openapi/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * One operation of the document, structurally.
+ *
+ * @stability experimental
+ */
+export interface DocOperation {
+    /** The one-line summary. */
+    summary?: string;
+    /** The Markdown description. */
+    description?: string;
+    /** The generated operation id. */
+    operationId?: string;
+    /** The sidebar tags. */
+    tags?: string[];
+    /** Responses by status code. */
+    responses?: Record<string, unknown>;
+    /** Entries are alternatives (OR), not a conjunction. */
+    security?: Array<Record<string, string[]>>;
+    /** Vendor extensions, including the `x-rbac` stamped by `@Auth()`. */
+    [key: string]: unknown;
+}
+/**
+ * One path item: operations by method, plus siblings such as `parameters`.
+ *
+ * @stability experimental
+ */
+export type DocPathItem = Record<string, DocOperation | unknown>;
+/**
+ * The generated document, structurally, for the post-processing passes.
+ *
+ * @stability experimental
+ */
+export interface MutableDocument {
+    /** Path items by path. */
+    paths?: Record<string, DocPathItem | undefined>;
+    [key: string]: unknown;
+}
+/**
+ * HTTP methods an OpenAPI path item may carry, in spec order.
+ *
+ * @stability experimental
+ */
+export declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+/**
+ * Visits every operation in the document.
+ *
+ * Shared by the post-processing passes so the "which keys on a path item are
+ * operations" question is answered in exactly one place — `parameters` and
+ * `servers` are siblings of the methods and must not be treated as operations.
+ *
+ * @param document - the document.
+ * @param visit - called once per operation with its path and method.
+ * @stability experimental
+ */
+export declare function forEachOperation(document: MutableDocument, visit: (operation: DocOperation, path: string, method: string) => void): void;
+//# sourceMappingURL=types.d.ts.map

package/dist/host/openapi/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/types.ts"],"names":[],"mappings":"AAcA;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC3C,sEAAsE;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAAC,CAAC;IAChD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,gFASf,CAAC;AAEX;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,GACrE,IAAI,CASN"}

package/dist/host/openapi/types.js

@@ -0,0 +1,56 @@
+"use strict";
+// =============================================================================
+// Minimal structural types for post-processing the generated document
+// =============================================================================
+//
+// `@nestjs/swagger` exports `OpenAPIObject` from its root but not
+// `OperationObject`, and reaching into `@nestjs/swagger/dist/interfaces/...` to
+// get it couples this code to that package's build layout.
+//
+// The passes in this directory read and write a handful of fields on operations
+// and add vendor extensions, so a structural type with an index signature is
+// both sufficient and more honest than the package's own — whose `responses` is
+// required, which the generated object does not always satisfy mid-pass.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTP_METHODS = void 0;
+exports.forEachOperation = forEachOperation;
+/**
+ * HTTP methods an OpenAPI path item may carry, in spec order.
+ *
+ * @stability experimental
+ */
+exports.HTTP_METHODS = [
+    'get',
+    'put',
+    'post',
+    'delete',
+    'options',
+    'head',
+    'patch',
+    'trace',
+];
+/**
+ * Visits every operation in the document.
+ *
+ * Shared by the post-processing passes so the "which keys on a path item are
+ * operations" question is answered in exactly one place — `parameters` and
+ * `servers` are siblings of the methods and must not be treated as operations.
+ *
+ * @param document - the document.
+ * @param visit - called once per operation with its path and method.
+ * @stability experimental
+ */
+function forEachOperation(document, visit) {
+    for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+        if (!pathItem || typeof pathItem !== 'object')
+            continue;
+        for (const method of exports.HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation || typeof operation !== 'object')
+                continue;
+            visit(operation, path, method);
+        }
+    }
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/host/openapi/types.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,sEAAsE;AACtE,gFAAgF;AAChF,EAAE;AACF,kEAAkE;AAClE,gFAAgF;AAChF,2DAA2D;AAC3D,EAAE;AACF,gFAAgF;AAChF,6EAA6E;AAC7E,gFAAgF;AAChF,yEAAyE;AACzE,gFAAgF;;;AAqEhF,4CAYC;AAvCD;;;;GAIG;AACU,QAAA,YAAY,GAAG;IAC1B,KAAK;IACL,KAAK;IACL,MAAM;IACN,QAAQ;IACR,SAAS;IACT,MAAM;IACN,OAAO;IACP,OAAO;CACC,CAAC;AAEX;;;;;;;;;;GAUG;AACH,SAAgB,gBAAgB,CAC9B,QAAyB,EACzB,KAAsE;IAEtE,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;QACpE,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;YAAE,SAAS;QACxD,KAAK,MAAM,MAAM,IAAI,oBAAY,EAAE,CAAC;YAClC,MAAM,SAAS,GAAI,QAAoC,CAAC,MAAM,CAAC,CAAC;YAChE,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ;gBAAE,SAAS;YAC1D,KAAK,CAAC,SAAyB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/host/openapi/version.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Version stamped into `info.version`.
+ *
+ * Resolution order, and why:
+ *
+ *  1. `APP_VERSION` — set by the deploy pipeline on the built image. This is the
+ *     only source that knows about a release tag, so it wins.
+ *  2. `npm_package_version` — set when the process was started through an npm
+ *     script, which covers local `start:dev`.
+ *  3. the app's `package.json`, found by walking up from `startDir` (the app
+ *     passes its own `__dirname`). `require`ing it directly is not an option:
+ *     the relative depth differs between `src/` under ts-jest and `dist/`
+ *     under `node dist/main`. Walking up finds it from either.
+ *
+ * Never throws — a docs page is not worth failing a boot over, so an
+ * unresolvable version degrades to `'0.0.0'`.
+ *
+ * @param startDir - where the walk starts: a directory inside the APP (never
+ *   this package's, whose own `package.json` would be found first).
+ * @returns the version.
+ * @stability experimental
+ */
+export declare function resolveApiVersion(startDir: string): string;
+//# sourceMappingURL=version.d.ts.map