# `security-scheme` — OpenAPI Bearer JWT contribution

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

```ts
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:

```ts
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.