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