`security-schemes`

(no submodules)

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

import { createRolledSecuritySchemes } from "@suaveplan/api-auth-rolled";

const contribution = createRolledSecuritySchemes({
    cookieName: "suaveplan.session",
});

Usage: Advanced

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.

2.6 KiB Raw Permalink Blame History

security-schemes