first commit

docs/api-stack/api/api-auth-rolled/src/security-schemes/security-schemes.md

@@ -0,0 +1,73 @@
+# `security-schemes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Contributes OpenAPI 3.1 `securitySchemes` entries describing both
+transports the rolled session resolver accepts — `Authorization: Bearer
+<token>` and a `Cookie` carrying the same JWT. Keeping the two entries
+co-located means a single source of truth describes what the resolver
+accepts on the wire; the `api-openapi` emitter (Stage 8.6) walks the
+adapter's `securityScheme` slot AND its `.schemes` map so both are
+surfaced in the generated document.
+
+## Features
+
+- Bearer entry: OpenAPI 3.1 `http` / `bearer` form with `bearerFormat:
+  "JWT"` — the canonical Bearer-JWT shape consumers expect.
+- Cookie entry: `apiKey` / `in: cookie` form whose `name` is the
+  caller-configured cookie name, so the doc matches the adapter's
+  runtime behaviour exactly.
+- `createRolledSecuritySchemes({ cookieName })` returns a single value
+  that satisfies the `SecuritySchemeContribution` contract (its `name`
+  and `scheme` point at the bearer entry) AND exposes both contributions
+  on `.schemes` — the emitter can pull either or both.
+
+## Usage: Basic
+
+```ts
+import { createRolledSecuritySchemes } from "@suaveplan/api-auth-rolled";
+
+const contribution = createRolledSecuritySchemes({
+    cookieName: "suaveplan.session",
+});
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    createRolledBearerSecurityScheme,
+    createRolledCookieSecurityScheme,
+} from "@suaveplan/api-auth-rolled";
+
+// Multi-resolver host — name the contributions to disambiguate.
+const userBearer = createRolledBearerSecurityScheme("userBearer");
+const serviceBearer = createRolledBearerSecurityScheme("serviceBearer");
+const cookie = createRolledCookieSecurityScheme({
+    name: "userCookie",
+    cookieName: "acme.session",
+});
+```
+
+## API Reference
+
+- `createRolledBearerSecurityScheme(name?: string): SecuritySchemeContribution`
+- `createRolledCookieSecurityScheme({ name?, cookieName }): SecuritySchemeContribution`
+- `createRolledSecuritySchemes({ cookieName }): RolledSecurityContribution`
+  — convenience bundle.
+
+## Implementation Notes
+
+The combined `RolledSecurityContribution` is structurally a
+`SecuritySchemeContribution` (so old emitters that only read `name` +
+`scheme` keep working) but adds a `.schemes` map for emitters aware of
+the dual-transport shape. This keeps the contribution drop-in for both
+single-transport and dual-transport emitters without forcing every
+caller to choose. The cookie scheme's `apiKey/in:cookie` representation
+matches OpenAPI 3.1 §4.8.27.4 — there is no first-class cookie-JWT
+shape in OAS 3.1 so `apiKey` with the configured name is the canonical
+form.