82 lines
3.0 KiB
Markdown
82 lines
3.0 KiB
Markdown
# `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.
|