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

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.