`adapter` — composite `AuthAdapter` factory

(no submodules)

Purpose

Bundles the static-principal resolver, the (absent) security-scheme contribution, and a pinned csrf: false into a single AuthAdapter value. This is the call-site shape for the canonical "test host with a known Principal" wiring — host.registerAuth(createStaticPrincipalAdapter({...})) gives the test the entire auth pipeline without further plumbing.

The factory delegates construction-time validation to createStaticPrincipalResolver, so misconfigured options surface as the same typed AuthStaticPrincipalError they do at the resolver level. The adapter holds no state of its own.

Features

Single-call construction of the resolver + scheme + csrf triple.
Pins csrf: false because the static-principal layer has no session cookie to forge against — every request carries the configured Principal by construction.
securityScheme omitted (matching api-auth-anonymous topology) so the generated OpenAPI document doesn't advertise a real auth flow for routes wired to this adapter.

Usage: Basic

import { createStaticPrincipalAdapter } from "@suaveplan/api-auth-static-principal/adapter";

const adapter = createStaticPrincipalAdapter({
    principal: {
        id: "u1",
        scopes: ["billing:write"],
        tenantId: "acme",
        claims: { sub: "u1" },
    },
});

host.registerAuth(adapter);

Usage: Advanced

Compose with applyTo / nullForPaths to skip auth on test-only routes:

import { createStaticPrincipalAdapter } from "@suaveplan/api-auth-static-principal/adapter";

const adapter = createStaticPrincipalAdapter({
    principal: { id: "u1", scopes: [], claims: {} },
    nullForPaths: ["/healthz", "/webhooks/*"],
});

// host.registerAuth(adapter) — /healthz and /webhooks/* resolve to null;
// every other route gets the configured Principal.

API Reference

Symbol	Kind	Description
`createStaticPrincipalAdapter(opts)`	function	Returns `AuthAdapter` composed from the four building blocks.

Implementation Notes

csrf: false is the load-bearing pin: a static-principal host can't honour a real CSRF check (there's no session cookie carrying a synchronizer token), so the host should skip CSRF entirely for routes wired to this adapter. If a downstream test needs CSRF behaviour exercised in isolation, compose with a separate adapter that pins csrf: true and let the host's adapter-chain merge rule pick the safer value (the host's policy is to use the strictest csrf flag in the chain).

validateAuthAdapter accepts this adapter's shape (security scheme absent; csrf set to a boolean). The package's adapter test asserts the validation contract is satisfied without re-implementing the validator.

3.0 KiB Raw Blame History

adapter — composite AuthAdapter factory