skills/docs/testkit/testing/testing-integration-oauth-mock/README.md

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

Documentation tree

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

Quick start

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.