suaveplan/openspec/archive/2026-05-26-api-auth-anonymous/proposal.md

@suaveplan/api-auth-anonymous — Null-principal session resolver

Package: @suaveplan/api-auth-anonymous Status: PROPOSED Type: new-package Stage: 4 (Base adapters) — see umbrella openspec/changes/api-plugin-foundation/

Why

Per design doc §2.3, every API host MUST configure a session resolver — even fully public APIs. api-auth-anonymous is the trivial session resolver that always returns null. Configuring it explicitly makes the "no auth" choice visible in host.json and lets the rest of the host (RBAC gate, error envelope, OpenAPI) operate uniformly: the principal is simply null, never undefined.

Stage 4 invariant: both direct and worker-proxy surfaces ship and pass runAuthSessionConformance (§5.2a, §13.4). The proxy is trivial here (no network/state) but its presence keeps the adapter table uniform — every adapter has both surfaces, no exceptions.

What changes

Net-new package depending on @suaveplan/api-auth, @suaveplan/api-types, @suaveplan/api-worker-rpc.

• ADDED: createAnonymousSessionResolver() — direct-surface factory returning an AuthAdapter whose resolveSession always returns null.
• ADDED: createAnonymousSessionResolverWorkerProxy(port) — proxy-surface factory.
• ADDED: securitySchemeContribution() — returns an empty OpenAPI securitySchemes block. Routes without publicRoutes declaration still emit the host's default security entry list (which is empty for anonymous).
• ADDED: AnonymousResolverOptions — currently empty; reserved for future flags (e.g. logAnonymousAccess: boolean).

Out of scope

• Policy on whether a route requires auth — the host enforces publicRoutes from each plugin's manifest; this resolver only ever supplies null.
• Rate limiting based on IP / fingerprint — api-rate-limit Stage 8.

Source mapping

Genesis-original. Source of design intent: docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md.

Requirement	Design doc section
Always returns null principal	§2.3 (api-auth-anonymous bullet)
Worker-proxy variant required	§5.2a
Conformance both surfaces	§13.4

Verification approach

• src/factory/create-anonymous-session-resolver.test.ts — direct surface always returns null.
• src/factory/create-anonymous-session-resolver.spec-conformance.test.ts — runAuthSessionConformance("anonymous-direct", ...) (the suite must accept resolvers that always return null).
• src/proxy/create-anonymous-session-resolver-worker-proxy.test.ts — proxy unit tests.
• src/proxy/create-anonymous-session-resolver-worker-proxy.spec-conformance.test.ts — runAuthSessionConformance("anonymous-worker-proxy", ...).

Migration impact

None — additive only.