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

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

@@ -0,0 +1,107 @@
+import type { INestApplication } from '@nestjs/common';
+import type { OpenAPIObject } from '@nestjs/swagger';
+import { DocOperation, MutableDocument } from './types';
+/**
+ * Security scheme names. `JWT_AUTH` is referenced by name from `@Auth()`.
+ *
+ * Exactly two, because exactly two credentials exist: a session access token
+ * and a personal access token. There is no third, narrower credential to
+ * declare, and inventing a scheme for one would document an authentication this
+ * server cannot perform.
+ *
+ * @stability experimental
+ */
+export declare const SECURITY_SCHEMES: {
+    /** The session access token scheme, named by `@Auth()`. */
+    readonly JWT_AUTH: "JWT-auth";
+    /** The personal access token scheme. */
+    readonly PAT_AUTH: "PAT-auth";
+};
+/**
+ * What the app tells the document builder about itself.
+ *
+ * @stability experimental
+ */
+export interface PlatformOpenApiOptions {
+    /** The product name: the title is `<appName> API`, and the contact's name. */
+    appName: string;
+    /** The source repository URL: the contact URL and the `docs/` external doc. */
+    repoUrl: string;
+    /**
+     * The application version (`info.version`), or a function resolving it per
+     * build (the reference app passes its `resolveApiVersion`).
+     */
+    version: string | (() => string);
+    /**
+     * The Markdown intro, given the resolved version. Default: the platform's
+     * getting-started guide ({@link buildApiDescription}).
+     */
+    description?: (version: string) => string;
+}
+/**
+ * The resolved version of {@link PlatformOpenApiOptions.version}.
+ *
+ * @param options - the app's OpenAPI options.
+ * @returns the version string.
+ * @stability experimental
+ */
+export declare function resolveOpenApiVersion(options: Pick<PlatformOpenApiOptions, 'version'>): string;
+/**
+ * The `DocumentBuilder` configuration.
+ *
+ * @param options - the app's identity and version.
+ * @param version - resolved application version; injectable so a test can assert
+ *   the shape without depending on what the build happens to be stamped with.
+ * @returns the OpenAPI document's configuration.
+ * @stability experimental
+ */
+export declare function buildOpenApiConfig(options: PlatformOpenApiOptions, version?: string): Omit<OpenAPIObject, 'paths'>;
+/**
+ * Builds the finished document: Nest's introspection, then the passes that turn
+ * it into something worth reading. Call it after `setGlobalPrefix`: the
+ * introspection reads the prefix off the application.
+ *
+ * @param app - the Nest application (a `preview: true` one is enough).
+ * @param options - the app's identity and version.
+ * @returns the OpenAPI 3.1 document.
+ * @stability experimental
+ */
+export declare function createOpenApiDocument(app: INestApplication, options: PlatformOpenApiOptions): OpenAPIObject;
+/**
+ * The post-processing passes, split out from `createOpenApiDocument` so they can
+ * be exercised against a hand-built document without booting an application.
+ *
+ * @typeParam T - the document type.
+ * @param document - the generated document, edited in place.
+ * @returns the same document.
+ * @stability experimental
+ */
+export declare function enrichOpenApiDocument<T extends MutableDocument>(document: T): T;
+/**
+ * `UsersController.listUsers` → `users_listUsers`.
+ *
+ * Keeps the controller as a namespace (so two `list` handlers cannot collide)
+ * while dropping the noise a generator would otherwise bake into every method
+ * name. Uniqueness is asserted in `test/openapi/openapi-document.spec.ts`.
+ *
+ * @param controllerKey - the controller class name.
+ * @param methodKey - the handler name.
+ * @returns the operation id.
+ * @stability experimental
+ */
+export declare function buildOperationId(controllerKey: string, methodKey: string): string;
+/**
+ * Whether an operation requires a bearer token.
+ *
+ * Two signals, because two things put one there. `@Auth()` stamps `x-rbac`,
+ * which is the richer marker. A handful of routes instead compose
+ * `@UseGuards(JwtAuthGuard)` with a bare `@ApiBearerAuth('JWT-auth')` — on the
+ * auth controller, where the RBAC guards would have nothing to check, and on
+ * the device-authorization controller — and those are just as authenticated.
+ *
+ * @param operation - one operation of the document.
+ * @returns whether it requires a bearer token.
+ * @stability experimental
+ */
+export declare function isAuthenticatedOperation(operation: DocOperation): boolean;
+//# sourceMappingURL=document.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/document.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQrD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;IAC3B,2DAA2D;;IAE3D,wCAAwC;;CAEhC,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IACjC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,IAAI,CAAC,sBAAsB,EAAE,SAAS,CAAC,GAAG,MAAM,CAE9F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,EAC/B,OAAO,GAAE,MAAuC,GAC/C,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAuE9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,gBAAgB,EAAE,OAAO,EAAE,sBAAsB,GAAG,aAAa,CAuB3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,eAAe,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAiB/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,YAAY,GAAG,OAAO,CAKzE"}

package/dist/host/openapi/document.js

@@ -0,0 +1,328 @@
+"use strict";
+// =============================================================================
+// OpenAPI document construction (issue #53)
+// =============================================================================
+//
+// Everything that shapes `/api/openapi.json` lives here rather than in
+// `main.ts`, for one concrete reason: the spec is now asserted by tests and
+// dumped by a CI script, and neither of those can boot a listening server. A
+// pure `buildOpenApiConfig()` / `createOpenApiDocument(app)` pair can be called
+// from a test harness, from `scripts/dump-openapi.ts`, and from `main.ts`
+// alike, so the document CI lints is the document users get.
+//
+// Packaged in the host slice by #867. The app supplies its identity and
+// version as `PlatformOpenApiOptions` (the reference app's binding is
+// `apps/api/src/openapi/document.ts`) and registers its tag taxonomy into
+// core's `openApiTags` before building.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECURITY_SCHEMES = void 0;
+exports.resolveOpenApiVersion = resolveOpenApiVersion;
+exports.buildOpenApiConfig = buildOpenApiConfig;
+exports.createOpenApiDocument = createOpenApiDocument;
+exports.enrichOpenApiDocument = enrichOpenApiDocument;
+exports.buildOperationId = buildOperationId;
+exports.isAuthenticatedOperation = isAuthenticatedOperation;
+const swagger_1 = require("@nestjs/swagger");
+const nestjs_zod_1 = require("nestjs-zod");
+const index_1 = require("../../core/index");
+const index_2 = require("../../identity/index");
+const data_envelope_1 = require("./data-envelope");
+const description_1 = require("./description");
+const nullable_1 = require("./nullable");
+const rbac_docs_1 = require("./rbac-docs");
+const types_1 = require("./types");
+/**
+ * Security scheme names. `JWT_AUTH` is referenced by name from `@Auth()`.
+ *
+ * Exactly two, because exactly two credentials exist: a session access token
+ * and a personal access token. There is no third, narrower credential to
+ * declare, and inventing a scheme for one would document an authentication this
+ * server cannot perform.
+ *
+ * @stability experimental
+ */
+exports.SECURITY_SCHEMES = {
+    /** The session access token scheme, named by `@Auth()`. */
+    JWT_AUTH: 'JWT-auth',
+    /** The personal access token scheme. */
+    PAT_AUTH: 'PAT-auth',
+};
+/**
+ * The resolved version of {@link PlatformOpenApiOptions.version}.
+ *
+ * @param options - the app's OpenAPI options.
+ * @returns the version string.
+ * @stability experimental
+ */
+function resolveOpenApiVersion(options) {
+    return typeof options.version === 'function' ? options.version() : options.version;
+}
+/**
+ * The `DocumentBuilder` configuration.
+ *
+ * @param options - the app's identity and version.
+ * @param version - resolved application version; injectable so a test can assert
+ *   the shape without depending on what the build happens to be stamped with.
+ * @returns the OpenAPI document's configuration.
+ * @stability experimental
+ */
+function buildOpenApiConfig(options, version = resolveOpenApiVersion(options)) {
+    const { appName: APP_NAME, repoUrl: REPO_URL } = options;
+    const describe = options.description ?? ((v) => (0, description_1.buildApiDescription)(v, options));
+    const builder = new swagger_1.DocumentBuilder()
+        .setTitle(`${APP_NAME} API`)
+        .setDescription(describe(version))
+        .setVersion(version)
+        // OpenAPI 3.1, not the 3.0 default. This is required, not a preference:
+        // zod v4 emits JSON Schema 2020-12, which 3.1 adopts wholesale and 3.0
+        // rejects — under 3.0 the zod-derived DTOs publish numeric
+        // `exclusiveMinimum` and `propertyNames` keywords that are invalid there,
+        // so a schema-validating consumer (and Spectral) rightly fails on them.
+        // Scalar renders 3.1 natively.
+        .setOpenAPIVersion('3.1.0')
+        // The name is the product's and follows `APP_NAME`; the URL is the
+        // repository's and deliberately does not derive from the name — a fork
+        // renames its product long before (or without ever) moving its source, so
+        // building the URL out of the name would point readers at a repository that
+        // does not exist. `REPO_URL` is the separate fact, from `@app/shared`.
+        //
+        // Derived rather than restated because this pair is PUBLISHED: both land in
+        // `/api/openapi.json`, which is what a consumer imports into Postman or
+        // generates an SDK from. A literal left behind by a fork does not merely go
+        // stale locally — it hands that fork's API consumers somebody else's
+        // repository as the place to read the docs and file issues.
+        .setContact(APP_NAME, REPO_URL, '')
+        .setExternalDoc('Architecture and operations documentation', `${REPO_URL}/tree/main/docs`)
+        // Same-origin: the UI is served at `/`, this API under `/api`, so a
+        // relative server URL is correct for every deployment without templating.
+        .addServer('/', 'This deployment (same-origin)')
+        .addBearerAuth({
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'JWT',
+        description: 'Short-lived session access token from `POST /api/auth/refresh` or the OAuth callback. ' +
+            'On this page, use "Authorize with my session" to load one automatically.',
+    }, exports.SECURITY_SCHEMES.JWT_AUTH)
+        .addBearerAuth({
+        type: 'http',
+        scheme: 'bearer',
+        description: 'Personal access token (`pat_…`) from `POST /api/pat`. Long-lived, carries the full ' +
+            'permission set of the user that minted it, and is accepted on every authenticated route.',
+    }, exports.SECURITY_SCHEMES.PAT_AUTH);
+    for (const tag of index_1.openApiTags.list()) {
+        builder.addTag(tag.name, tag.description);
+    }
+    const config = builder.build();
+    // `setContact` takes all three fields positionally, so an omitted email is an
+    // empty string — which is not a valid `email`, and a schema-validating
+    // consumer rejects the whole document over it. A contact with a name and a URL
+    // is perfectly valid; fabricating an address to satisfy the field would be
+    // worse than not having one.
+    if (config.info.contact && !config.info.contact.email) {
+        delete config.info.contact.email;
+    }
+    return config;
+}
+/**
+ * Builds the finished document: Nest's introspection, then the passes that turn
+ * it into something worth reading. Call it after `setGlobalPrefix`: the
+ * introspection reads the prefix off the application.
+ *
+ * @param app - the Nest application (a `preview: true` one is enough).
+ * @param options - the app's identity and version.
+ * @returns the OpenAPI 3.1 document.
+ * @stability experimental
+ */
+function createOpenApiDocument(app, options) {
+    const document = swagger_1.SwaggerModule.createDocument(app, buildOpenApiConfig(options), {
+        // Namespaced but readable: `users_listUsers`, not `UsersController_listUsers`.
+        // Stable across refactors that do not rename the controller or handler, which
+        // is what makes generated SDK method names survive a release.
+        operationIdFactory: buildOperationId,
+        // ErrorDto is only ever referenced from a `$ref` this file writes, so it
+        // would otherwise never be emitted into `components.schemas`.
+        extraModels: [index_1.ErrorDto],
+    });
+    // nestjs-zod's recommended post-processing for zod-derived DTOs. Without it
+    // every `createZodDto` class publishes an empty `{}` schema — which is what
+    // the scaffold's `main.ts` did, and the single largest defect this module
+    // exists to fix.
+    const cleaned = (0, nestjs_zod_1.cleanupOpenApiDoc)(document);
+    // `OpenAPIObject` has no index signature, so it is not structurally a
+    // `MutableDocument` even though every field the passes touch is present.
+    // Widening here is the one place that conversion happens.
+    enrichOpenApiDocument(cleaned);
+    return cleaned;
+}
+/**
+ * The post-processing passes, split out from `createOpenApiDocument` so they can
+ * be exercised against a hand-built document without booting an application.
+ *
+ * @typeParam T - the document type.
+ * @param document - the generated document, edited in place.
+ * @returns the same document.
+ * @stability experimental
+ */
+function enrichOpenApiDocument(document) {
+    (0, rbac_docs_1.applyRbacDocs)(document);
+    applyAlternativeAuthSchemes(document);
+    // Order matters: the envelope pass targets 2xx JSON responses only, and the
+    // error pass writes a `default` response — running the envelope first keeps
+    // the two from ever meeting, but relying on that would be fragile, so the
+    // envelope pass filters on the status code explicitly as well.
+    (0, data_envelope_1.applyDataEnvelope)(document);
+    applyDefaultErrorResponse(document);
+    applyErrorCodeExamples(document);
+    applyTagGroups(document);
+    // LAST, and it must stay last: every earlier pass may introduce schemas of
+    // its own, and this one has to see all of them. A `nullable` that slips
+    // through is not ignored by a 3.1 consumer — it reads `type: "string"` and
+    // generates a non-nullable field.
+    (0, nullable_1.applyNullableFor31)(document);
+    return document;
+}
+/**
+ * `UsersController.listUsers` → `users_listUsers`.
+ *
+ * Keeps the controller as a namespace (so two `list` handlers cannot collide)
+ * while dropping the noise a generator would otherwise bake into every method
+ * name. Uniqueness is asserted in `test/openapi/openapi-document.spec.ts`.
+ *
+ * @param controllerKey - the controller class name.
+ * @param methodKey - the handler name.
+ * @returns the operation id.
+ * @stability experimental
+ */
+function buildOperationId(controllerKey, methodKey) {
+    const namespace = controllerKey.replace(/Controller$/, '');
+    const lowerFirst = namespace.charAt(0).toLowerCase() + namespace.slice(1);
+    return `${lowerFirst}_${methodKey}`;
+}
+/**
+ * Whether an operation requires a bearer token.
+ *
+ * Two signals, because two things put one there. `@Auth()` stamps `x-rbac`,
+ * which is the richer marker. A handful of routes instead compose
+ * `@UseGuards(JwtAuthGuard)` with a bare `@ApiBearerAuth('JWT-auth')` — on the
+ * auth controller, where the RBAC guards would have nothing to check, and on
+ * the device-authorization controller — and those are just as authenticated.
+ *
+ * @param operation - one operation of the document.
+ * @returns whether it requires a bearer token.
+ * @stability experimental
+ */
+function isAuthenticatedOperation(operation) {
+    if (operation[index_2.RBAC_EXTENSION_KEY] !== undefined)
+        return true;
+    return (operation.security ?? []).some((entry) => exports.SECURITY_SCHEMES.JWT_AUTH in entry);
+}
+/**
+ * Adds the PAT scheme to every operation it actually works on.
+ *
+ * `@Auth()` can only declare the session scheme, because that is the one it
+ * names. But a PAT authenticates every authenticated route, and that is a fact
+ * a reader needs.
+ *
+ * The claim is universal because the mechanism is: `JwtAuthGuard.canActivate`
+ * intercepts any `Authorization: Bearer pat_…` header and resolves it through
+ * `PatService.validateToken` BEFORE delegating to the JWT passport strategy,
+ * setting the same `AuthenticatedUser` shape on the request that the strategy
+ * would. `RolesGuard` and `PermissionsGuard` therefore see identical input
+ * either way. Since every authenticated route in this API is guarded by
+ * `JwtAuthGuard` — via `@Auth()` or a direct `@UseGuards(JwtAuthGuard)` — there
+ * is no authenticated route a PAT is rejected on.
+ *
+ * Deriving it here from the `x-rbac` marker and the declared security keeps the
+ * claim accurate as routes are added, where a hand-applied `@ApiSecurity()`
+ * would quietly go stale. If a future route ever authenticates through some
+ * other guard, `isAuthenticatedOperation` will not match it and it will not be
+ * given a claim this pass cannot back up.
+ *
+ * Multiple entries in an operation's `security` array are alternatives (OR), so
+ * appending never tightens a requirement.
+ */
+function applyAlternativeAuthSchemes(document) {
+    (0, types_1.forEachOperation)(document, (operation) => {
+        if (!isAuthenticatedOperation(operation))
+            return;
+        const security = (operation.security ??= []);
+        const has = (name) => security.some((entry) => name in entry);
+        if (!has(exports.SECURITY_SCHEMES.PAT_AUTH)) {
+            security.push({ [exports.SECURITY_SCHEMES.PAT_AUTH]: [] });
+        }
+    });
+}
+/**
+ * Attaches the shared error envelope as each operation's `default` response.
+ *
+ * A `default` rather than an enumerated 400/404/409 list per operation: every
+ * error from every route passes through one `HttpExceptionFilter` and comes
+ * back in one shape, so `default` states exactly that — without asserting on
+ * each route's behalf which statuses it can produce, which nobody could keep
+ * true as controllers change.
+ *
+ * Operations that document a specific status keep it; this only fills the gap.
+ */
+function applyDefaultErrorResponse(document) {
+    (0, types_1.forEachOperation)(document, (operation) => {
+        const responses = (operation.responses ??= {});
+        if (responses.default)
+            return;
+        responses.default = {
+            description: 'Error. Every failure is rendered by the shared exception filter into this envelope; ' +
+                'endpoint-specific data appears under `details`.',
+            content: {
+                'application/json': { schema: { $ref: '#/components/schemas/ErrorDto' } },
+            },
+        };
+    });
+}
+/**
+ * Lists every REGISTERED error code (the platform's and the app's, then the
+ * `ERROR` fallback) as the `examples` of `ErrorDto.code`, so the published
+ * document documents the same open vocabulary the filter enforces. `code` is a
+ * plain string schema, not an enum: a client must tolerate a code it does not
+ * know.
+ */
+function applyErrorCodeExamples(document) {
+    const schemas = document.components
+        ?.schemas;
+    const code = schemas?.ErrorDto?.properties?.code;
+    if (!code)
+        return;
+    code.examples = [...index_1.errorCodeRegistry.ids(), index_1.FALLBACK_ERROR_CODE];
+}
+/**
+ * Emits `x-tagGroups`, the vendor extension Scalar and Redoc read to render a
+ * sectioned sidebar. Renderers without support fall back to the flat `tags`
+ * array, which `buildOpenApiConfig` emits in the same order.
+ *
+ * Tags no operation uses are pruned from both. The taxonomy is declared for the
+ * whole application, but not every module is registered in every environment —
+ * `app.module.ts` registers `TestAuthModule` only when
+ * `NODE_ENV !== 'production'` — and a declared-but-unused tag renders as an
+ * empty sidebar section. Pruning is what makes one static taxonomy correct in
+ * both environments.
+ *
+ * The taxonomy is the OpenAPI tag registry of `@marinoscar/platform-api/core`
+ * (issue #698): this app's tags (`./tags.ts`) plus any a slice registered.
+ * Only `name` and `description` are published per tag; `group` becomes
+ * `x-tagGroups`.
+ */
+function applyTagGroups(document) {
+    const used = new Set();
+    (0, types_1.forEachOperation)(document, (operation) => {
+        for (const tag of operation.tags ?? [])
+            used.add(tag);
+    });
+    const tags = index_1.openApiTags.list();
+    document.tags = tags
+        .filter((tag) => used.has(tag.name))
+        .map(({ name, description }) => ({ name, description }));
+    document['x-tagGroups'] = (0, index_1.openApiTagGroups)(tags).map((group) => ({
+        name: group.name,
+        tags: group.tags.filter((tag) => used.has(tag)),
+    })).filter((group) => group.tags.length > 0);
+}
+//# sourceMappingURL=document.js.map

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

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

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

@@ -0,0 +1,9 @@
+import { MutableDocument } from './types';
+/**
+ * Rewrites every `nullable: true` in the document into a 3.1 type union.
+ *
+ * Walks the whole document rather than just `components.schemas`: inline
+ * parameter and response schemas carry the keyword too.
+ */
+export declare function applyNullableFor31(document: MutableDocument): MutableDocument;
+//# sourceMappingURL=nullable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nullable.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/nullable.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI1C;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAG7E"}

package/dist/host/openapi/nullable.js

@@ -0,0 +1,78 @@
+"use strict";
+// =============================================================================
+// OpenAPI 3.0 `nullable` → 3.1 type union (issue #53)
+// =============================================================================
+//
+// The document is published as OpenAPI 3.1, because zod v4 emits JSON Schema
+// 2020-12 and 3.0 rejects several of its keywords outright.
+//
+// But `@nestjs/swagger`'s `@ApiProperty({ nullable: true })` still emits the
+// 3.0 spelling — a sibling `nullable: true` next to `type` — and 3.1 removed
+// that keyword entirely. A 3.1 consumer does not "mostly ignore" it: it reads
+// `type: "string"` and generates a non-nullable field, so a client is wrong
+// about exactly the values most likely to break it.
+//
+// 3.1's spelling is a type union, `type: ["string", "null"]`, which is what this
+// pass rewrites to. It runs over the whole document rather than being fixed at
+// ~28 `@ApiProperty` call sites, because the next one written will use the 3.0
+// spelling too — `nullable` is what the decorator's own types document.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyNullableFor31 = applyNullableFor31;
+/**
+ * Rewrites every `nullable: true` in the document into a 3.1 type union.
+ *
+ * Walks the whole document rather than just `components.schemas`: inline
+ * parameter and response schemas carry the keyword too.
+ */
+function applyNullableFor31(document) {
+    walk(document, new Set());
+    return document;
+}
+function walk(node, seen) {
+    if (!node || typeof node !== 'object')
+        return;
+    if (seen.has(node))
+        return;
+    seen.add(node);
+    if (Array.isArray(node)) {
+        for (const item of node)
+            walk(item, seen);
+        return;
+    }
+    const schema = node;
+    if (schema.nullable === true) {
+        rewrite(schema);
+    }
+    for (const value of Object.values(schema))
+        walk(value, seen);
+}
+function rewrite(schema) {
+    const type = schema.type;
+    if (typeof type === 'string') {
+        schema.type = type === 'null' ? type : [type, 'null'];
+        delete schema.nullable;
+        return;
+    }
+    if (Array.isArray(type)) {
+        if (!type.includes('null'))
+            type.push('null');
+        delete schema.nullable;
+        return;
+    }
+    // No `type` to widen — the schema is a bare `$ref`, a composition, or
+    // untyped. 3.1 expresses "this or null" as a one-of, which is also the only
+    // form that works alongside a `$ref` (a `$ref` sibling is ignored in 3.0 and
+    // merged in 3.1, so neither spelling of a sibling keyword is dependable).
+    const ref = schema.$ref;
+    if (typeof ref === 'string') {
+        delete schema.$ref;
+        schema.oneOf = [{ $ref: ref }, { type: 'null' }];
+        delete schema.nullable;
+        return;
+    }
+    // Nothing meaningful to rewrite into; drop the keyword rather than leave a
+    // 3.0-only field in a 3.1 document.
+    delete schema.nullable;
+}
+//# sourceMappingURL=nullable.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nullable.js","sourceRoot":"","sources":["../../../src/host/openapi/nullable.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,sDAAsD;AACtD,gFAAgF;AAChF,EAAE;AACF,6EAA6E;AAC7E,4DAA4D;AAC5D,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,4EAA4E;AAC5E,oDAAoD;AACpD,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,+EAA+E;AAC/E,wEAAwE;AACxE,gFAAgF;;AAYhF,gDAGC;AATD;;;;;GAKG;AACH,SAAgB,kBAAkB,CAAC,QAAyB;IAC1D,IAAI,CAAC,QAAsB,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;IACxC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,IAAI,CAAC,IAAa,EAAE,IAAiB;IAC5C,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO;IAC9C,IAAI,IAAI,CAAC,GAAG,CAAC,IAAc,CAAC;QAAE,OAAO;IACrC,IAAI,CAAC,GAAG,CAAC,IAAc,CAAC,CAAC;IAEzB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,MAAM,IAAI,IAAI,IAAI;YAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1C,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,IAAkB,CAAC;IAClC,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED,SAAS,OAAO,CAAC,MAAkB;IACjC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IAEzB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,GAAG,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtD,OAAO,MAAM,CAAC,QAAQ,CAAC;QACvB,OAAO;IACT,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,OAAO,MAAM,CAAC,QAAQ,CAAC;QACvB,OAAO;IACT,CAAC;IAED,sEAAsE;IACtE,4EAA4E;IAC5E,6EAA6E;IAC7E,0EAA0E;IAC1E,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC;IACxB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,MAAM,CAAC,IAAI,CAAC;QACnB,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;QACjD,OAAO,MAAM,CAAC,QAAQ,CAAC;QACvB,OAAO;IACT,CAAC;IAED,2EAA2E;IAC3E,oCAAoC;IACpC,OAAO,MAAM,CAAC,QAAQ,CAAC;AACzB,CAAC"}

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

@@ -0,0 +1,30 @@
+import { DocOperation, MutableDocument } from './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
+ */
+export declare const 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.
+ */
+export declare function applyRbacDocs(document: MutableDocument): MutableDocument;
+/**
+ * The one-line requirements sentence for an operation, or `null` when the
+ * operation is something this pass has nothing to say about.
+ */
+export declare function describeRequirements(operation: DocOperation): string | null;
+//# sourceMappingURL=rbac-docs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rbac-docs.d.ts","sourceRoot":"","sources":["../../../src/host/openapi/rbac-docs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,eAAe,EAAoB,MAAM,SAAS,CAAC;AAE1E;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,CAYxE;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAmD3E"}