65 lines
3.8 KiB
Markdown
65 lines
3.8 KiB
Markdown
# @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.
|
|
|