61 lines
3.1 KiB
Markdown
61 lines
3.1 KiB
Markdown
# @suaveplan/api-auth-anonymous — trivial session resolver for @suaveplan/api: always returns null Principal. Used as the tail of resolver chains for fully public APIs and as the foundation conformance seed for every other session-resolver in the stack.
|
|
|
|
Stage-4 trivial session resolver for `@suaveplan/api`.
|
|
Always returns `null` for every request. Use this as the tail of resolver
|
|
chains for public endpoints, and as the canonical adapter for fully public
|
|
APIs. The package also serves as the foundation conformance seed exercised by
|
|
every other concrete session-resolver in Stages 4 / 6 / 8.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [adapter](./src/adapter/adapter.md) — Canonical `AuthAdapter` for fully public APIs. Pairs the trivial anonymous resolver with the minimal adapter metadata t…
|
|
- [adapter](./src/adapter/adapter.md) — Canonical `AuthAdapter` for fully public APIs. Pairs the trivial anonymous resolver with the minimal adapter metadata t…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-auth-anonymous`. The anonymous resolver has no per-request failure modes…
|
|
- [error-codes](./src/error-codes/error-codes.md) — Stable error-code registry for `@suaveplan/api-auth-anonymous`. The anonymous resolver has no per-request failure modes…
|
|
- [resolver](./src/resolver/resolver.md) — Factory for the trivial `SessionResolver` that always returns `null`. This is the canonical tail-of-chain resolver ever…
|
|
- [resolver](./src/resolver/resolver.md) — Factory for the trivial `SessionResolver` that always returns `null`. This is the canonical tail-of-chain resolver ever…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Why does "no auth" need its own package?
|
|
|
|
Per the API foundation design doc §2.3, every host configures a session
|
|
resolver — even fully public APIs. Configuring `ANONYMOUS_AUTH_ADAPTER`
|
|
explicitly makes the "no auth" choice visible in `host.json` and lets the rest
|
|
of the host (RBAC gate, error envelope, OpenAPI emission) operate uniformly:
|
|
the principal is simply `null`, never `undefined`.
|
|
|
|
## Surface
|
|
|
|
| Subpath | Export |
|
|
|----------------|---------------------------------------------------|
|
|
| `./resolver` | `createAnonymousResolver(opts?): SessionResolver` |
|
|
| `./adapter` | `ANONYMOUS_AUTH_ADAPTER: AuthAdapter` |
|
|
| `./error-codes`| `AUTH_ANON_CODES`, `AuthAnonError` |
|
|
|
|
## Usage
|
|
|
|
```ts
|
|
import { ANONYMOUS_AUTH_ADAPTER } from "@suaveplan/api-auth-anonymous/adapter";
|
|
|
|
host.registerAuth(ANONYMOUS_AUTH_ADAPTER);
|
|
// every request now produces `principal: null`; public routes proceed,
|
|
// non-public routes 401 via the host's `publicRoutes` decision.
|
|
```
|
|
|
|
For mixed chains, see `createAnonymousResolver()` + `SessionResolverChain`
|
|
in `@suaveplan/api-auth/chain`.
|
|
|
|
## Conformance
|
|
|
|
The resolver passes `runAuthSessionConformance` (null-only mode) from
|
|
`@suaveplan/api-auth/testing`. See
|
|
`src/resolver/resolver.test.ts`.
|
|
|
|
## Errors
|
|
|
|
`AUTH_ANON.INVALID_OPTIONS` — thrown only when the factory is handed a
|
|
non-object or unknown-key options bag. No per-request error paths exist by
|
|
design.
|
|
|