73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# `adapter` — `ANONYMOUS_AUTH_ADAPTER`
|
|
|
|
<!-- begin:auto-docs -->
|
|
_(no submodules)_
|
|
<!-- end:auto-docs -->
|
|
|
|
## Purpose
|
|
|
|
Canonical `AuthAdapter` for fully public APIs. Pairs the trivial anonymous
|
|
resolver with the minimal adapter metadata the host needs to wire it into the
|
|
per-request pipeline. The adapter omits `securityScheme` on purpose:
|
|
`validateAuthAdapter` permits a missing scheme for the anonymous topology so
|
|
the emitted OpenAPI document contains no `security` entry on routes — the
|
|
correct shape for "no authentication required".
|
|
|
|
## Features
|
|
|
|
- Stateless singleton — safe to import once per host process.
|
|
- `csrf: false` baked in: anonymous traffic has no session to protect; the
|
|
generic CSRF middleware in `@suaveplan/api-auth/csrf-policy` skips routes
|
|
whose adapter pins `csrf: false`.
|
|
- Validates cleanly against `validateAuthAdapter` — no runtime error at host
|
|
registration time despite the omitted security scheme.
|
|
|
|
## Usage: Basic
|
|
|
|
```ts
|
|
import { ANONYMOUS_AUTH_ADAPTER } from "@suaveplan/api-auth-anonymous/adapter";
|
|
import { validateAuthAdapter } from "@suaveplan/api-auth";
|
|
|
|
const adapter = validateAuthAdapter(ANONYMOUS_AUTH_ADAPTER);
|
|
host.registerAuth(adapter);
|
|
```
|
|
|
|
## Usage: Advanced
|
|
|
|
For a chain that mixes typed resolvers with the anonymous tail, do not use
|
|
`ANONYMOUS_AUTH_ADAPTER` directly — assemble a `SessionResolverChain` so the
|
|
typed resolvers fire first:
|
|
|
|
```ts
|
|
import { SessionResolverChain } from "@suaveplan/api-auth";
|
|
import { createAnonymousResolver } from "@suaveplan/api-auth-anonymous/resolver";
|
|
|
|
const chain = new SessionResolverChain([
|
|
jwtResolver,
|
|
createAnonymousResolver(),
|
|
]);
|
|
const adapter = {
|
|
resolver: chain,
|
|
securityScheme: jwtSecurityScheme, // the typed resolver still emits its scheme
|
|
} as const;
|
|
```
|
|
|
|
## API Reference
|
|
|
|
| Symbol | Kind | Description |
|
|
|------------------------------|----------|------------------------------------------------|
|
|
| `ANONYMOUS_AUTH_ADAPTER` | const | `AuthAdapter` with anonymous resolver, no scheme, `csrf: false`. |
|
|
|
|
## Implementation Notes
|
|
|
|
- The constant is constructed once at module load and reused across requests
|
|
— the resolver itself is documented stateless, so a single instance is safe
|
|
to fan out across concurrent requests.
|
|
- `csrf: false` is deliberate. Anonymous requests carry no session cookie, so
|
|
applying CSRF defence would reject legitimate public traffic. Hosts that
|
|
want to additionally rate-limit anonymous traffic should layer
|
|
`api-rate-limit` (Stage 8) on top — that is not this package's concern.
|
|
- Test coverage exercises (a) `validateAuthAdapter(ANONYMOUS_AUTH_ADAPTER)`
|
|
returns the adapter unchanged, (b) the embedded resolver still resolves
|
|
null, and (c) the singleton survives repeated import without re-allocation.
|