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