# @suaveplan/testing-integration-oauth-mock - Real-HTTP mock OAuth 2.0 IdP fixture with PKCE, primeUser/primeError control, and full request audit

Real-HTTP mock OAuth 2.0 Identity Provider for integration tests.

`createMockOauthIdp(opts)` boots a real `node:http` listener on an
ephemeral `127.0.0.1` port and implements:

- `GET /authorize` — issues an authorization code, captures PKCE
  challenge, echoes state.
- `POST /token` — `authorization_code` and `refresh_token` grants;
  PKCE `plain` + `S256` verification with rotated refresh tokens.
- `GET /userinfo` — Bearer-authenticated user payload shaped as
  `github` (default), `google`, `generic`, or via a custom `userMapper`.
- `GET /.well-known/openid-configuration` + `GET /jwks.json` — gated
  on `openid: true`.

Test-control levers:

- `primeUser({ … })` — FIFO queue of user payloads for the next
  `/userinfo` response.
- `primeError("access_denied" | …)` — FIFO queue of RFC-6749 error
  codes for the next `/authorize`.
- `lastRequest()` / `allRequests()` — frozen audit records of every
  served HTTP request.

<!-- begin:auto-docs -->
## Documentation tree

- [audit](./src/control/audit.md) — `AuditLog` is the request-recorder that backs the `lastRequest()` and `allRequests()` accessors on the mock IdP handle.…
- [primer](./src/control/primer.md) — `Primer` is the in-memory control surface that lets a test author tell the mock IdP "the next user-info response should…
- [authorize](./src/endpoints/authorize.md) — `handleAuthorize` implements the OAuth 2.0 authorization-code endpoint (RFC-6749 §4.1.1) for the mock IdP. It issues a…
- [openid](./src/endpoints/openid.md) — `handleOpenIdConfig` serves the `/.well-known/openid-configuration` discovery document and `handleJwks` serves the matc…
- [token](./src/endpoints/token.md) — `handleToken` implements the OAuth 2.0 token endpoint (RFC-6749 §4.1.3 and §6) for the mock IdP. It supports two grant…
- [userinfo](./src/endpoints/userinfo.md) — `handleUserInfo` implements the OAuth/OIDC userinfo endpoint. Given a `Bearer` authorization header, it looks up the as…
- [error-codes](./src/error-codes/error-codes.md) — This module defines the closed registry of error codes raised by `@suaveplan/testing-integration-oauth-mock`. The packa…
  - [error-codes](./src/error-codes/error-codes.md) — This module defines the closed registry of error codes raised by `@suaveplan/testing-integration-oauth-mock`. The packa…
- [server](./src/server/server.md) — `createMockOauthIdp` boots a real HTTP listener (Node's `http.createServer`) on an ephemeral port and routes OAuth 2.0…
  - [server](./src/server/server.md) — `createMockOauthIdp` boots a real HTTP listener (Node's `http.createServer`) on an ephemeral port and routes OAuth 2.0…
- [generic](./src/shapes/generic.md) — `buildGenericUser` produces an OIDC-flavoured userinfo payload with the common `sub` / `email` / `name` claims. It is t…
- [github](./src/shapes/github.md) — `buildGithubUser` produces a userinfo payload that closely mirrors the `GET https://api.github.com/user` response GitHu…
- [google](./src/shapes/google.md) — `buildGoogleUser` produces a Google OIDC-style userinfo payload that matches the response Google's `/oauth2/v3/userinfo…
<!-- end:auto-docs -->

## Quick start

```ts
import { createMockOauthIdp } from "@suaveplan/testing-integration-oauth-mock";

const idp = await createMockOauthIdp({ userShape: "github" });
idp.primeUser({ id: 42, login: "alice" });

// drive a Better-Auth / next-auth GitHub provider against `idp.url`

await idp.stop();
```

## Compliance

- Rule 8 — testing-infrastructure: no `@suaveplan/*` runtime
  dependencies; only `node:*` builtins.
- Rule 11 — test-runner imports go through
  `@suaveplan/testing/runner`.
- Rule 2 — real HTTP, no mocking libraries.