Initial Commit

openspec/specs/api-auth-anonymous/spec.md

@@ -0,0 +1,52 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-auth-anonymous (api-auth-anonymous)
+
+**Package**: `@suaveplan/api-auth-anonymous`
+**Status**: PROPOSED
+
+## ADDED Requirements
+
+### Requirement: resolveSession always returns null
+
+The package SHALL implement the session-resolver contract such that `resolveSession(request)` returns `null` for every input, synchronously decidable.
+
+#### Scenario: any request resolves to null
+
+- **WHEN** `resolveSession(request)` is called with any request shape (Authorization header, cookie, missing entirely)
+- **THEN** the resolver returns `null` AND no exception is thrown AND no network I/O occurs
+
+**Verified by:** `src/factory/create-anonymous-session-resolver.test.ts::"resolveSession returns null for every input"`
+
+---
+
+### Requirement: Direct and worker-proxy surfaces both pass conformance
+
+The adapter SHALL pass `runAuthSessionConformance` under BOTH the direct and worker-proxy surfaces. The conformance suite MUST tolerate a resolver that exclusively returns null (the "no auth configured" case is a valid host topology).
+
+#### Scenario: direct surface conforms
+
+- **WHEN** `runAuthSessionConformance("anonymous-direct", createAnonymousSessionResolver)` runs
+- **THEN** every invariant passes
+
+#### Scenario: worker-proxy surface conforms
+
+- **WHEN** `runAuthSessionConformance("anonymous-worker-proxy", () => createAnonymousSessionResolverWorkerProxy(channel.port2))` runs over a real `MessageChannel`
+- **THEN** every invariant passes
+
+**Verified by:** `src/factory/create-anonymous-session-resolver.spec-conformance.test.ts::"anonymous-direct conforms to AuthSession contract"` AND `src/proxy/create-anonymous-session-resolver-worker-proxy.spec-conformance.test.ts::"anonymous-worker-proxy conforms to AuthSession contract"`
+
+---
+
+### Requirement: Empty securitySchemes contribution
+
+`securitySchemeContribution()` SHALL return an empty `securitySchemes` block. OpenAPI documents assembled from a host using only this resolver MUST emit no `security` entry on routes.
+
+#### Scenario: contribution is empty
+
+- **WHEN** `securitySchemeContribution()` is called
+- **THEN** the returned value is `{ securitySchemes: {} }`
+
+**Verified by:** `src/security-scheme/security-scheme-contribution.test.ts::"contribution exposes no security schemes"`
+
+<!-- markdownlint-enable MD024 -->