first commit

docs/api-stack/api/api-auth-anonymous/src/adapter/adapter.md

@@ -0,0 +1,72 @@
+# `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.