`security-scheme` — OpenAPI Bearer JWT contribution

(no submodules)

Purpose

Builds the SecuritySchemeContribution this adapter contributes to the generated OpenAPI document. The shape is the canonical OAS 3.1 http / bearer scheme with bearerFormat: "JWT". Stage-8 @suaveplan/api-openapi consumes the contribution and inlines it under components.securitySchemes[name], then references it from operation security blocks for non-public routes.

Features

Canonical Bearer-JWT scheme — no surprise extensions, no proprietary fields.
Configurable contribution name (bearerAuth default) so multiple JWT resolvers can coexist (e.g. user-side bearerAuth + service-side serviceBearerAuth).
JWT_BEARER_SCHEME constant for callers that only ever expose one JWT resolver.
Human-readable description field that links the scheme back to the adapter so docs readers understand where verification happens.

Usage: Basic

import { JWT_BEARER_SCHEME } from "@suaveplan/api-auth-jwt/security-scheme";

const adapter = {
    resolver: createJwtSessionResolver(...).resolver,
    securityScheme: JWT_BEARER_SCHEME,
};

Usage: Advanced

Rename the contribution for a dual-resolver host:

import { createJwtBearerSecurityScheme } from "@suaveplan/api-auth-jwt/security-scheme";

const userScheme = createJwtBearerSecurityScheme("userAuth");
const serviceScheme = createJwtBearerSecurityScheme("serviceAuth");

API Reference

createJwtBearerSecurityScheme(name = "bearerAuth") → SecuritySchemeContribution from @suaveplan/api-auth.
JWT_BEARER_SCHEME — pre-built bearerAuth-named contribution.

Implementation Notes

The http / bearer form is the only OAS 3.1 scheme that documents "this endpoint accepts a Bearer JWT" without forcing the OpenAPI emitter to inline OAuth-flow metadata that this adapter does not own. The bearerFormat field is documentation-only per the spec, but populating it as "JWT" is the convention every OAS reader (Swagger UI, Redoc, Stoplight) recognises. Tenant or scope expectations are expressed by individual route handlers, not the scheme itself — keeping the scheme orthogonal to the route catalogue keeps it stable across plugin upgrades.

2.3 KiB Raw Blame History

security-scheme — OpenAPI Bearer JWT contribution