expediate 1.0.5 → 1.0.6

package/dist/openapi.d.ts

@@ -1,4 +1,4 @@
-import type { ServiceMethod, ServiceInstance, ServiceDefinition } from './apis.js';
+import type { ServiceMethod, ServiceInstance, ServiceDefinition, Guard, AuthBinding, ApiBuilderOptions } from './apis.js';
 /**
  * A JSON Schema object (subset of draft-07 / OpenAPI 3.1 Schema Object).
  *
@@ -96,6 +96,21 @@ export interface OperationMeta {
     responses?: Record<string, ResponseObject>;
     /** Mark as deprecated in the generated spec. */
     deprecated?: boolean;
+    /**
+     * Guards run before this handler, after the API-level and controller-level
+     * guards.  Ignored by spec generation — this is the natural per-route
+     * metadata slot for the request pipeline.
+     */
+    guards?: Guard[];
+    /**
+     * Permission(s) required to call this operation.
+     *
+     * Overrides the controller-level `permission`.  When set, the pipeline
+     * runs `auth.check(ctx, required)` before the guards, and the generated
+     * spec emits `security: [{ bearerAuth: [] }]` plus an
+     * `x-required-permissions` vendor extension on the operation.
+     */
+    permission?: string | string[];
     /** Additional vendor extensions (keys should start with `x-`). */
     [key: string]: unknown;
 }
@@ -125,6 +140,101 @@ export interface OpenApiServiceMeta {
      */
     responses?: Record<string, ResponseObject>;
 }
+/**
+ * A route map for spec-only documentation: keys are Express-style path
+ * patterns, values are {@link OperationMeta} objects directly. There is no
+ * handler to call here — only something to describe.
+ */
+export type RouteOpenApi = Record<string, OperationMeta>;
+/**
+ * A spec-only counterpart to `ControllerDefinition`: groups documented
+ * routes under a shared path prefix, default tags, and a default permission
+ * requirement, without any of the request-handling fields (`guards`).
+ */
+export interface ControllerOpenApi {
+    /** Path prefix prepended to every route in this controller (may contain params). */
+    prefix?: string;
+    /** Default OpenAPI tags applied to routes that do not declare their own. */
+    tags?: string[];
+    /** Default permission requirement for every route of this controller. */
+    permission?: string | string[];
+    /** Documented `GET` operations (paths relative to `prefix`). */
+    GET?: RouteOpenApi;
+    /** Documented `POST` operations (paths relative to `prefix`). */
+    POST?: RouteOpenApi;
+    /** Documented `PUT` operations (paths relative to `prefix`). */
+    PUT?: RouteOpenApi;
+    /** Documented `DELETE` operations (paths relative to `prefix`). */
+    DELETE?: RouteOpenApi;
+    /** Documented `PATCH` operations (paths relative to `prefix`). */
+    PATCH?: RouteOpenApi;
+}
+/**
+ * A spec-only counterpart to {@link ServiceDefinition}, for documenting
+ * routes that have no `ServiceDefinition` of their own — most notably the
+ * JWT plugin's `/auth/login`, `/auth/refresh`, and `/auth/logout` endpoints,
+ * which are mounted directly with `app.post(...)` rather than through
+ * `apiBuilder`.
+ *
+ * It carries the same OpenAPI-relevant shape as `ServiceDefinition`
+ * (controllers, root route maps, schemas, auth binding, service-level
+ * `openapi` metadata) but route map values are {@link OperationMeta} objects
+ * instead of handler functions, and there is no instance lifecycle
+ * (`scope` / `data` / `setup` / `methods`) to run.
+ *
+ * `guards` and `validate` are accepted only for structural parity with
+ * {@link ServiceDefinition}; spec generation ignores both — there is no
+ * request pipeline here to run them against.
+ */
+export interface ServiceOpenApi {
+    /** Sub-controllers merged into this source, same merge rules as `ServiceDefinition.controllers`. */
+    controllers?: ControllerOpenApi[];
+    /** Ignored by spec generation; accepted for structural parity with `ServiceDefinition.guards`. */
+    guards?: Guard[];
+    /** Authentication binding — `scheme` and `permissionsExtension` affect the generated spec. */
+    auth?: AuthBinding;
+    /** Ignored by spec generation; accepted for structural parity with `ServiceDefinition.validate`. */
+    validate?: boolean | ApiBuilderOptions;
+    /**
+     * Reusable JSON Schema components merged into `components.schemas`
+     * (see {@link ServiceDefinition.schemas}).
+     */
+    schemas?: Record<string, JsonSchema>;
+    /** Service-level OpenAPI metadata (default tag, shared schemas/responses). */
+    openapi?: OpenApiServiceMeta;
+    /** Documented `GET` operations. */
+    GET?: RouteOpenApi;
+    /** Documented `POST` operations. */
+    POST?: RouteOpenApi;
+    /** Documented `PUT` operations. */
+    PUT?: RouteOpenApi;
+    /** Documented `DELETE` operations. */
+    DELETE?: RouteOpenApi;
+    /** Documented `PATCH` operations. */
+    PATCH?: RouteOpenApi;
+}
+/**
+ * Anything {@link openApiSpec} can document: a real {@link ServiceDefinition}
+ * (the kind built by `apiBuilder`) or a spec-only {@link ServiceOpenApi}
+ * describing routes that aren't backed by a service at all.
+ *
+ * `openApiSpec` accepts a single source or an array of sources, so a real API
+ * and hand-documented routes can be merged into one document:
+ *
+ * ```ts
+ * const authDocs: ServiceOpenApi = {
+ *   openapi: { tag: 'auth' },
+ *   POST: {
+ *     '/auth/login':   { summary: 'Log in',         requestBody: loginBody },
+ *     '/auth/refresh': { summary: 'Refresh a token', requestBody: refreshBody },
+ *     '/auth/logout':  { summary: 'Log out' },
+ *   },
+ * };
+ *
+ * const spec = openApiSpec([authDocs, todoService], { title: 'Todo API', version: '1.0.0' });
+ * ```
+ */
+export type OpenApiSource = ServiceDefinition<any> | ServiceOpenApi;
 /**
  * Top-level options passed to {@link openApiSpec}.
  *
@@ -144,10 +254,10 @@ export interface SpecOptions {
      */
     basePath?: string;
     /** Server list (defaults to `[{ url: '/' }]` when absent). */
-    servers?: Array<{
+    servers?: {
         url: string;
         description?: string;
-    }>;
+    }[];
     /**
      * Additional schemas merged into `components.schemas` (takes precedence
      * over service-level `openapi.schemas` of the same name).
@@ -167,18 +277,24 @@ export interface OpenApiDocument {
         version: string;
         description?: string;
     };
-    servers?: Array<{
+    servers?: {
         url: string;
         description?: string;
-    }>;
-    tags?: Array<{
+    }[];
+    tags?: {
         name: string;
         description?: string;
-    }>;
+    }[];
     paths: Record<string, Record<string, unknown>>;
     components: {
         schemas: Record<string, JsonSchema>;
         responses: Record<string, ResponseObject>;
+        /**
+         * Security schemes — emitted when at least one operation declares a
+         * `permission` (the scheme comes from `AuthBinding.scheme`, defaulting
+         * to HTTP bearer / JWT).
+         */
+        securitySchemes?: Record<string, Record<string, unknown>>;
     };
 }
 /**
@@ -240,22 +356,35 @@ export declare const DESCRIBE_META: unique symbol;
  */
 export declare function describe<TInstance extends ServiceInstance = ServiceInstance>(handler: ServiceMethod<TInstance>, meta: OperationMeta): ServiceMethod<TInstance>;
 /**
- * Generate an OpenAPI 3.1.0 document from a {@link ServiceDefinition}.
+ * Generate an OpenAPI 3.1.0 document from one or more {@link OpenApiSource}
+ * values — real {@link ServiceDefinition}s, spec-only {@link ServiceOpenApi}
+ * descriptions, or a mix of both in a single array.
  *
  * Route handlers that have been annotated with {@link describe} contribute
  * rich operation metadata (summary, description, parameters, requestBody,
  * responses).  Unannotated handlers receive sensible defaults automatically.
+ * `ServiceOpenApi` route maps provide that same {@link OperationMeta} shape
+ * directly, since there is no handler to annotate.
  *
  * The generated document always includes:
  * - An `ApiError` schema (shape: `{ status?, message?, data? }`) in
  *   `components.schemas`.
  * - An `ApiError` response (`500` reference) in `components.responses`.
  *
- * Caller-supplied `opts.schemas` and service-level `openapi.schemas` are
- * deep-merged on top of the built-in components (caller schemas take
- * precedence over service schemas, which take precedence over built-ins).
+ * Caller-supplied `opts.schemas` and each source's `openapi.schemas` /
+ * `schemas` are merged on top of the built-in components, source by source
+ * in array order — for a single source this preserves the original
+ * precedence exactly: built-ins ← `openapi.schemas` ← `opts.schemas` ←
+ * `schemas`.
+ *
+ * Routes are merged and duplicate-checked **across all sources** (see
+ * {@link collectOpenApiRoutes}), so passing several sources still produces
+ * ONE document. Each route's default tag and permissions vendor-extension
+ * name are resolved from its own originating source; the
+ * `components.securitySchemes.bearerAuth` value comes from the first source
+ * in array order that declares a custom `auth.scheme`, else the default.
  *
- * @param service - The service definition to document.
+ * @param service - The source(s) to document.
  * @param opts    - Top-level spec options (title, version, basePath, …).
  * @returns A fully-formed OpenAPI 3.1.0 document object.
  *
@@ -271,8 +400,22 @@ export declare function describe<TInstance extends ServiceInstance = ServiceInst
  *   res.json(spec);
  * });
  * ```
+ *
+ * @example Merging a real service with hand-documented auth routes
+ * ```ts
+ * const authDocs: ServiceOpenApi = {
+ *   openapi: { tag: 'auth' },
+ *   POST: {
+ *     '/auth/login':   { summary: 'Log in' },
+ *     '/auth/refresh': { summary: 'Refresh a token' },
+ *     '/auth/logout':  { summary: 'Log out' },
+ *   },
+ * };
+ *
+ * const spec = openApiSpec([authDocs, todoDefinition], { title: 'Todo API', version: '1.0.0' });
+ * ```
  */
-export declare function openApiSpec<TInstance extends ServiceInstance = ServiceInstance>(service: ServiceDefinition<TInstance>, opts: SpecOptions): OpenApiDocument;
+export declare function openApiSpec(service: OpenApiSource | OpenApiSource[], opts: SpecOptions): OpenApiDocument;
 declare module './apis.js' {
     interface ServiceDefinition<TInstance extends ServiceInstance> {
         /**

package/dist/openapi.d.ts.map

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

package/dist/openapi.js

@@ -19,6 +19,7 @@
  * DEALINGS IN THE SOFTWARE.
  */
 'use strict';
+import { joinPath, routeScore, normalizePermission } from './apis.js';
 // ── YAML serialiser (zero-dependency, block-style) ────────────────────────────
 /**
  * YAML reserved keywords that must be quoted as scalars so that YAML parsers
@@ -27,15 +28,6 @@
 const YAML_KW = new Set([
     'true', 'false', 'yes', 'no', 'on', 'off', 'null', '~',
 ]);
-/**
- * Pattern for "safe" plain scalars: they can be represented without quoting.
- * A scalar is safe when it:
- * - contains only letters, digits, `_`, `-`, `.` or `/`
- * - starts with a letter, `_`, `/`, or `$`
- * - is not a YAML reserved keyword
- * - does not look like a number
- */
-const SAFE_SCALAR = /^[a-zA-Z$_/][a-zA-Z0-9$_\-./]*$/;
 /** Pattern matching integer and floating-point number strings. */
 const LOOKS_LIKE_NUMBER = /^[-+]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$|^0x[0-9a-fA-F]+$|^0o[0-7]+$/;
 /**
@@ -68,7 +60,7 @@ function yamlString(s) {
         s !== s.trim() ||
         // Flow indicator characters anywhere — present in path patterns such as
         // `/items/{id}` and must be quoted to avoid flow-collection ambiguity.
-        /[{}\[\]]/.test(s) ||
+        /[{}[\]]/.test(s) ||
         // Control characters.
         /[\x00-\x1f\x7f]/.test(s);
     if (!needsQuote)
@@ -159,6 +151,10 @@ function toYamlLines(value) {
         }
         return lines;
     }
+    // Defensive fallback: every JSON value type (null, boolean, number, string,
+    // array, object) is handled above, so `value` here is only reachable for
+    // bigint/symbol/function — none of which occur in a JSON-derived spec.
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
     return [String(value)];
 }
 /**
@@ -344,27 +340,130 @@ function buildAnnotatedResponses(responses) {
     return result;
 }
 // ---------------------------------------------------------------------------
-// Core spec generator
+// Multi-source route collection (spec-generation counterpart to `collectRoutes`)
 // ---------------------------------------------------------------------------
-/** The five HTTP verbs supported by `apiBuilder`. */
+/**
+ * The five HTTP verbs `openApiSpec` looks for route maps under.
+ *
+ * Kept as a private duplicate of `apis.ts`'s internal `VERBS` (only the
+ * derived {@link ApiVerb} type is exported from there) — not worth exporting
+ * a const for.
+ */
 const VERBS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
 /**
- * Generate an OpenAPI 3.1.0 document from a {@link ServiceDefinition}.
+ * Build the merged, globally-sorted route table for one or more
+ * {@link OpenApiSource} values — the spec-generation counterpart to
+ * `apis.ts`'s `collectRoutes`.
+ *
+ * Deliberately kept separate from `collectRoutes` so the real request
+ * pipeline (`apiBuilder`) is never affected by spec-only concerns: this
+ * function only inspects route *shapes* to produce documentation and never
+ * invokes a handler. A route value is resolved as `describe()`-attached
+ * metadata when it is a function, or used directly as an {@link OperationMeta}
+ * object when it is not (the {@link ServiceOpenApi} case).
+ *
+ * Duplicate `(verb, path)` pairs are detected **across all sources**, not
+ * just within one — extending `collectRoutes`'s single-service duplicate
+ * check to the merged multi-source document.
+ *
+ * @throws Error on a duplicate `(verb, path)` pair across any of the sources.
+ */
+function collectOpenApiRoutes(sources) {
+    const routes = [];
+    /** Duplicate detection across ALL sources: `"VERB /joined/path"` → declarer label. */
+    const seen = new Map();
+    sources.forEach((source, sourceIndex) => {
+        const defaultTag = source.openapi?.tag;
+        const permissionsExtension = source.auth?.permissionsExtension ?? 'x-required-permissions';
+        // Root route maps form an implicit, anonymous controller — same trick as
+        // `collectRoutes`'s `rootController`.
+        const rootController = {
+            prefix: '',
+            GET: source.GET,
+            POST: source.POST,
+            PUT: source.PUT,
+            DELETE: source.DELETE,
+            PATCH: source.PATCH,
+        };
+        const controllers = [rootController, ...(source.controllers ?? [])];
+        controllers.forEach((controller, controllerIndex) => {
+            const label = controllerIndex === 0
+                ? `source #${sourceIndex}`
+                : (controller.tags?.[0] ?? controller.prefix ?? `source #${sourceIndex} controller #${controllerIndex}`);
+            const prefix = controller.prefix ?? '';
+            for (const verb of VERBS) {
+                const routeMap = controller[verb];
+                if (!routeMap)
+                    continue;
+                for (const [pattern, value] of Object.entries(routeMap)) {
+                    const path = joinPath(prefix, pattern);
+                    // Loud failure on duplicates, across the whole merged document.
+                    const dupKey = `${verb} ${path}`;
+                    const declarer = seen.get(dupKey);
+                    if (declarer !== undefined) {
+                        throw new Error(`openApiSpec: duplicate route ${verb} ${path}\n` +
+                            `  declared by '${declarer}' and '${label}'`);
+                    }
+                    seen.set(dupKey, label);
+                    const meta = typeof value === 'function'
+                        ? value[DESCRIBE_META]
+                        : value;
+                    routes.push({
+                        verb,
+                        path,
+                        meta,
+                        tags: meta?.tags ?? controller.tags,
+                        permission: normalizePermission(meta?.permission ?? controller.permission),
+                        defaultTag,
+                        permissionsExtension,
+                    });
+                }
+            }
+        });
+    });
+    // Global specificity sort across all sources and controllers.
+    routes.sort((a, b) => routeScore(b.path) - routeScore(a.path) || b.path.localeCompare(a.path));
+    return routes;
+}
+// ---------------------------------------------------------------------------
+// Core spec generator
+// ---------------------------------------------------------------------------
+/** Default OpenAPI security scheme when `AuthBinding.scheme` is absent. */
+const DEFAULT_SECURITY_SCHEME = {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+};
+/**
+ * Generate an OpenAPI 3.1.0 document from one or more {@link OpenApiSource}
+ * values — real {@link ServiceDefinition}s, spec-only {@link ServiceOpenApi}
+ * descriptions, or a mix of both in a single array.
  *
  * Route handlers that have been annotated with {@link describe} contribute
  * rich operation metadata (summary, description, parameters, requestBody,
  * responses).  Unannotated handlers receive sensible defaults automatically.
+ * `ServiceOpenApi` route maps provide that same {@link OperationMeta} shape
+ * directly, since there is no handler to annotate.
  *
  * The generated document always includes:
  * - An `ApiError` schema (shape: `{ status?, message?, data? }`) in
  *   `components.schemas`.
  * - An `ApiError` response (`500` reference) in `components.responses`.
  *
- * Caller-supplied `opts.schemas` and service-level `openapi.schemas` are
- * deep-merged on top of the built-in components (caller schemas take
- * precedence over service schemas, which take precedence over built-ins).
+ * Caller-supplied `opts.schemas` and each source's `openapi.schemas` /
+ * `schemas` are merged on top of the built-in components, source by source
+ * in array order — for a single source this preserves the original
+ * precedence exactly: built-ins ← `openapi.schemas` ← `opts.schemas` ←
+ * `schemas`.
+ *
+ * Routes are merged and duplicate-checked **across all sources** (see
+ * {@link collectOpenApiRoutes}), so passing several sources still produces
+ * ONE document. Each route's default tag and permissions vendor-extension
+ * name are resolved from its own originating source; the
+ * `components.securitySchemes.bearerAuth` value comes from the first source
+ * in array order that declares a custom `auth.scheme`, else the default.
  *
- * @param service - The service definition to document.
+ * @param service - The source(s) to document.
  * @param opts    - Top-level spec options (title, version, basePath, …).
  * @returns A fully-formed OpenAPI 3.1.0 document object.
  *
@@ -380,11 +479,24 @@ const VERBS = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
  *   res.json(spec);
  * });
  * ```
+ *
+ * @example Merging a real service with hand-documented auth routes
+ * ```ts
+ * const authDocs: ServiceOpenApi = {
+ *   openapi: { tag: 'auth' },
+ *   POST: {
+ *     '/auth/login':   { summary: 'Log in' },
+ *     '/auth/refresh': { summary: 'Refresh a token' },
+ *     '/auth/logout':  { summary: 'Log out' },
+ *   },
+ * };
+ *
+ * const spec = openApiSpec([authDocs, todoDefinition], { title: 'Todo API', version: '1.0.0' });
+ * ```
  */
 export function openApiSpec(service, opts) {
+    const sources = Array.isArray(service) ? service : [service];
     const basePath = opts.basePath ?? '';
-    const svcMeta = service.openapi;
-    const defaultTag = svcMeta?.tag;
     // ── Components ──────────────────────────────────────────────────────────────
     const builtinSchemas = {
         ApiError: {
@@ -404,64 +516,86 @@ export function openApiSpec(service, opts) {
             },
         },
     };
-    // Merge schemas: built-ins ← service-level ← caller-level (last wins).
-    const schemas = {
-        ...builtinSchemas,
-        ...svcMeta?.schemas,
-        ...opts.schemas,
-    };
-    const responses = {
-        ...builtinResponses,
-        ...svcMeta?.responses,
-    };
+    // Merge schemas: built-ins ← each source's openapi.schemas (array order)
+    // ← caller-level opts.schemas ← each source's own `schemas` (array order,
+    // last wins).  For a single source this is exactly the original order:
+    // built-ins, service-level openapi meta, caller-level, service-definition
+    // `schemas` — which supersedes `opts.schemas`.
+    let schemas = { ...builtinSchemas };
+    for (const source of sources)
+        schemas = { ...schemas, ...source.openapi?.schemas };
+    schemas = { ...schemas, ...opts.schemas };
+    for (const source of sources)
+        schemas = { ...schemas, ...source.schemas };
+    let responses = { ...builtinResponses };
+    for (const source of sources)
+        responses = { ...responses, ...source.openapi?.responses };
     // ── Tags ─────────────────────────────────────────────────────────────────────
     const tags = [];
-    if (defaultTag) {
-        tags.push({ name: defaultTag, description: svcMeta?.tagDescription });
+    const seenTags = new Set();
+    for (const source of sources) {
+        const tag = source.openapi?.tag;
+        if (tag && !seenTags.has(tag)) {
+            seenTags.add(tag);
+            tags.push({ name: tag, description: source.openapi?.tagDescription });
+        }
     }
+    // ── Security scheme ──────────────────────────────────────────────────────────
+    // First source in array order that declares a custom scheme wins; falls
+    // back to the default HTTP bearer/JWT scheme.
+    const securityScheme = sources.find(s => s.auth?.scheme)?.auth?.scheme ?? DEFAULT_SECURITY_SCHEME;
     // ── Paths ────────────────────────────────────────────────────────────────────
+    // Operates on the merged route table (all sources' root route maps and
+    // controllers), so multiple sources still produce ONE document. Controller
+    // `tags` fill in `OperationMeta.tags` when a route declares none.
     const paths = {};
-    for (const verb of VERBS) {
-        const routeMap = service[verb];
-        if (!routeMap)
-            continue;
-        for (const [pattern, handler] of Object.entries(routeMap)) {
-            const openApiPath = toOpenApiPath(pattern, basePath);
-            if (!paths[openApiPath])
-                paths[openApiPath] = {};
-            // Retrieve attached metadata (if any).
-            const meta = handler[DESCRIBE_META];
-            // ── Parameters ─────────────────────────────────────────────────────────
-            const annotatedParams = meta?.parameters ?? [];
-            const inferredParams = extractPathParams(pattern, annotatedParams);
-            const parameters = [...annotatedParams, ...inferredParams];
-            // ── Responses ──────────────────────────────────────────────────────────
-            const operationResponses = meta?.responses
-                ? buildAnnotatedResponses(meta.responses)
-                : buildDefaultResponses(verb);
-            // ── Operation object ───────────────────────────────────────────────────
-            const operation = {
-                operationId: meta?.operationId ?? buildOperationId(verb, pattern),
-                ...(meta?.summary && { summary: meta.summary }),
-                ...(meta?.description && { description: meta.description }),
-                ...(meta?.deprecated && { deprecated: true }),
-                ...(parameters.length > 0 && { parameters }),
-                ...(meta?.requestBody && { requestBody: meta.requestBody }),
-                responses: operationResponses,
-            };
-            // Apply default tag when the operation has no explicit tags.
-            const opTags = meta?.tags ?? (defaultTag ? [defaultTag] : undefined);
-            if (opTags)
-                operation['tags'] = opTags;
-            // Carry through any vendor extensions (x-* keys).
-            if (meta) {
-                for (const [k, v] of Object.entries(meta)) {
-                    if (k.startsWith('x-'))
-                        operation[k] = v;
-                }
+    const routes = collectOpenApiRoutes(sources);
+    let securedRoutes = false;
+    for (const route of routes) {
+        const { verb, path: pattern, meta } = route;
+        const openApiPath = toOpenApiPath(pattern, basePath);
+        if (!paths[openApiPath])
+            paths[openApiPath] = {};
+        // ── Parameters ─────────────────────────────────────────────────────────
+        const annotatedParams = meta?.parameters ?? [];
+        const inferredParams = extractPathParams(pattern, annotatedParams);
+        const parameters = [...annotatedParams, ...inferredParams];
+        // ── Responses ──────────────────────────────────────────────────────────
+        const operationResponses = meta?.responses
+            ? buildAnnotatedResponses(meta.responses)
+            : buildDefaultResponses(verb);
+        // ── Operation object ───────────────────────────────────────────────────
+        const operation = {
+            operationId: meta?.operationId ?? buildOperationId(verb, pattern),
+            ...(meta?.summary && { summary: meta.summary }),
+            ...(meta?.description && { description: meta.description }),
+            ...(meta?.deprecated && { deprecated: true }),
+            ...(parameters.length > 0 && { parameters }),
+            ...(meta?.requestBody && { requestBody: meta.requestBody }),
+            responses: operationResponses,
+        };
+        // Apply route tags (meta-level, else controller-level), then this route's
+        // source default tag when neither is declared.
+        const opTags = route.tags ?? (route.defaultTag ? [route.defaultTag] : undefined);
+        if (opTags)
+            operation.tags = opTags;
+        // Carry through any vendor extensions (x-* keys).
+        if (meta) {
+            for (const [k, v] of Object.entries(meta)) {
+                if (k.startsWith('x-'))
+                    operation[k] = v;
             }
-            paths[openApiPath][verb.toLowerCase()] = operation;
         }
+        // ── Security ───────────────────────────────────────────────────────────
+        // Routes carrying a permission requirement (route- or controller-level)
+        // are marked with the bearerAuth scheme and the vendor extension listing
+        // the required permissions.
+        if (route.permission) {
+            securedRoutes = true;
+            operation.security = [{ bearerAuth: [] }];
+            operation[route.permissionsExtension] = route.permission;
+        }
+        paths[openApiPath][verb.toLowerCase()] = operation;
     }
     // ── Assemble document ────────────────────────────────────────────────────────
     const doc = {
@@ -474,7 +608,16 @@ export function openApiSpec(service, opts) {
         ...(opts.servers && { servers: opts.servers }),
         ...(tags.length > 0 && { tags }),
         paths,
-        components: { schemas, responses },
+        components: {
+            schemas,
+            responses,
+            // Emitted once when at least one operation declares a permission.
+            ...(securedRoutes && {
+                securitySchemes: {
+                    bearerAuth: securityScheme,
+                },
+            }),
+        },
     };
     return doc;
 }