first commit

docs/api-stack/api/api-auth-jwt/src/security-scheme/security-scheme.md

@@ -0,0 +1,66 @@
+# `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.