Initial Commit

openspec/archive/2026-05-26-testing-integration-oauth-mock/proposal.md

@@ -0,0 +1,28 @@
+# testing-integration-oauth-mock
+
+**Package**: `@suaveplan/testing-integration-oauth-mock`
+**Status**: PROPOSED
+**Type**: new-package
+
+## Why
+
+Stage 6.3 (`api-auth-better-auth`) requires an end-to-end GitHub OAuth flow exercised against a controllable IdP. Stage 8's `api-plugin-example` and a future `api-plugin-auth` GitHub flow will need the same fixture. Stand-up belongs once in `testkit/`, reusable across packages and conformance suites.
+
+## What changes
+
+Add a new testing-infrastructure package at `packages/testkit/testing/testing-integration-oauth-mock/`. Like its `testing-integration-*` siblings (rule 8), it has zero `@suaveplan/*` runtime deps except types-only consumption.
+
+The package SHALL expose:
+
+- `createMockOauthIdp(opts)` — returns a `{ url, port, stop, primeUser, primeError, lastRequest, allRequests }` handle backing a real HTTP server (Bun.serve) implementing OAuth 2.0 + PKCE.
+- Endpoints: `GET /authorize`, `POST /token`, `GET /userinfo`, `GET /.well-known/openid-configuration` (when `openid: true`), `GET /jwks.json` (when `openid: true`).
+- Test-control levers: `primeUser({ id, email, ... })` seeds the next callback's user; `primeError(...)` forces a specific RFC-6749 error; `lastRequest()` and `allRequests()` for assertion.
+- Deterministic state/code generation via injectable `rng` (defaults to `crypto.getRandomValues`).
+- Per-test isolation: each `createMockOauthIdp` listens on a fresh ephemeral port.
+- Full GitHub-shaped user payload (`id`, `login`, `email`, `avatar_url`, …) as the default user shape; arbitrary providers via `userShape: "github" | "google" | "generic"` or custom mapper.
+
+## Out of scope
+
+- Real OAuth provider discovery / token introspection beyond what the spec mandates.
+- OIDC ID-token signing with arbitrary algorithms (HS256 + RS256 only).
+- Multi-tenant OAuth app registration; one app per IdP instance.