first commit

docs/api-stack/api/api-auth-static-principal/src/adapter/adapter.md

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