# `adapter` — composite `AuthAdapter` factory

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

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

```ts
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:

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