skills/docs/api-stack/api/api-auth-anonymous/README.md

@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.

Documentation tree

• adapter — Canonical AuthAdapter for fully public APIs. Pairs the trivial anonymous resolver with the minimal adapter metadata t…
  • adapter — Canonical AuthAdapter for fully public APIs. Pairs the trivial anonymous resolver with the minimal adapter metadata t…
• error-codes — Stable error-code registry for @suaveplan/api-auth-anonymous. The anonymous resolver has no per-request failure modes…
  • error-codes — Stable error-code registry for @suaveplan/api-auth-anonymous. The anonymous resolver has no per-request failure modes…
• resolver — Factory for the trivial SessionResolver that always returns null. This is the canonical tail-of-chain resolver ever…
  • resolver — Factory for the trivial SessionResolver that always returns null. This is the canonical tail-of-chain resolver ever…

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

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.