@crvouga/mockingbird-service-oauth 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # Changelog — @crvouga/mockingbird-service-oauth
 
-## 3.3.0 (2026-10-11)
+## 3.5.0 (2026-10-15)
+
+### Features
+
+- finish durable run lifecycle ([725ea1a](https://github.com/crvouga/mockingbird/commit/725ea1a966dac65434e98f06a9c33aca0d6f32d7))
+- add management and portable archives ([0d2a6dd](https://github.com/crvouga/mockingbird/commit/0d2a6dd0f9fecb3a1ea7c1638f6639787395c2f4))
+
+### Fixes and improvements
+
+- correlate cross-namespace operations ([3457a4b](https://github.com/crvouga/mockingbird/commit/3457a4b7dbfd9ad9c8a10671a5744b7c8425d000))
+- harden HTTP stream handling ([674307a](https://github.com/crvouga/mockingbird/commit/674307a869f57907567d462c4f506c3b0a237e13))
+
+## 3.4.0 (2026-10-12)
+
+### Features
+
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+## 3.3.0 (2026-10-10)
 
 ### Features
 

package/DISCOVERY.md

@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
 designed for assertions and diagnosis by consuming test suites.
 
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,

package/README.md

@@ -13,8 +13,10 @@ npm install @crvouga/mockingbird-service-oauth
 ## Usage
 
 ```ts
+import * as oauth from "oauth4webapi"
 import { createRuntime } from "@crvouga/mockingbird-service-oauth"
 
+// Test setup: the identity provider, its test accounts and your registered client.
 const identity = createRuntime({
   provider: "google", // "apple", "microsoft", "github" or "oidc"
   accounts: [
@@ -29,10 +31,17 @@ const identity = createRuntime({
   }],
 })
 
-const discovery = await identity.fetch(
-  new Request("http://localhost:8810/.well-known/openid-configuration"),
+// Application code: the OIDC client it already uses (here oauth4webapi). Only its fetch
+// changes: requests reach the emulator in this process instead of the real issuer.
+const issuer = new URL("https://identity.test")
+const options = {
+  [oauth.customFetch]: (url: string, init: RequestInit) => identity.fetch(new Request(url, init)),
+}
+const as = await oauth.processDiscoveryResponse(
+  issuer,
+  await oauth.discoveryRequest(issuer, options),
 )
-console.log(await discovery.json())
+console.log(as.authorization_endpoint, as.token_endpoint, as.jwks_uri)
 
 // The same interface can be mounted in Bun, Deno, a worker or an HTTP adapter.
 // Browser execution needs a secure context for Web Crypto.
@@ -43,11 +52,20 @@ void fetchHandler
 Serve from Node (also works in Bun):
 
 ```ts
+import * as oauth from "oauth4webapi"
 import { createServer } from "@crvouga/mockingbird-service-oauth/server"
 
 const server = await createServer({ port: 8810, provider: "apple" })
-console.log(server.url)
 // Register clients and seed accounts through /__admin, or pass them to createServer.
+
+// Application code: its OIDC client, with the issuer set to server.url.
+const issuer = new URL(server.url)
+const as = await oauth.processDiscoveryResponse(
+  issuer,
+  // oauth4webapi requires HTTPS unless allowInsecureRequests is set; loopback needs it.
+  await oauth.discoveryRequest(issuer, { [oauth.allowInsecureRequests]: true }),
+)
+console.log(as.authorization_endpoint) // http://127.0.0.1:8810/auth/authorize
 await server.close()
 ```
 
@@ -78,6 +96,7 @@ The issuer defaults to the incoming origin (and `/__admin/ns/<name>` when used).
 `createMultiRuntime({ mounts })` and `createMultiServer({ mounts })` mount independent providers at exact paths on one origin. Discovery, endpoint URLs, token issuers, signing keys, clients, grants, sessions, faults, journals, and namespace state remain isolated per mount.
 
 ```ts
+import * as oauth from "oauth4webapi"
 import { createMultiServer } from "@crvouga/mockingbird-service-oauth/server"
 
 const accounts = [{ id: "ada", name: "Ada Lovelace", email: "ada@example.test" }]
@@ -91,6 +110,15 @@ const server = await createMultiServer({
     { path: "/oauth2", provider: "microsoft", clients, accounts },
   ],
 })
+
+// Application code: each mount is its own issuer for the app's OIDC client.
+const google = new URL(`${server.url}/google`)
+const as = await oauth.processDiscoveryResponse(
+  google,
+  await oauth.discoveryRequest(google, { [oauth.allowInsecureRequests]: true }),
+)
+console.log(as.token_endpoint) // http://127.0.0.1:<port>/google/token
+await server.close()
 ```
 
 Use `/__admin/ns/<name>/<mount>/…` for URL-selected namespaces. `GET /__admin/health` reports every mount; `POST /__admin/reset?all=1` resets them atomically. Other aggregate admin requests select a runtime with `?mount=/google`, while mount-scoped controls are also available at `/google/__admin/*`. Duplicate or unsafe mount paths, duplicate explicit issuers, and duplicate client/key IDs within a mount fail before the listener starts.