@crvouga/mockingbird-service-oauth 3.7.0 → 3.8.0

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog — @crvouga/mockingbird-service-oauth
 
-## 3.7.0 (2026-10-17)
+## 3.8.0 (2026-10-19)
+
+### Features
+
+- resolve the agent-reported issue queue in one batch ([25c52b6](https://github.com/crvouga/mockingbird/commit/25c52b668a53ddb80b968419601a20abf33f956b))
+
+## 3.7.0 (2026-10-16)
 
 ### Features
 

package/README.md

@@ -172,7 +172,7 @@ tapping `oauth-mock-form-post-continue`; with scripts, the page submits the form
 
 ### Fidelity and lifecycle
 
-- Authorization-code flow with exact redirect matching, including explicitly registered private-use URI schemes for native apps, state and nonce; duplicate parameters rejected. Invalid clients/callbacks never redirect. Public native clients require S256 PKCE.
+- Authorization-code flow with exact redirect matching, including explicitly registered private-use URI schemes for native apps, state and nonce; duplicate parameters rejected. Invalid clients/callbacks never redirect. Public native clients require S256 PKCE unless the client opts in with `pkceOptional`.
 - Real RSA-2048 / RS256 ID tokens and independent public JWKS; correct issuer, audience, expiry, auth time and scope-filtered claims. Keys remain stable until explicitly rotated.
 - Codes expire after 5 minutes and are consumed atomically, including concurrent PKCE redemption. Access/ID tokens last 1 hour. Generic OIDC refresh tokens default to 30 days; Microsoft defaults to 90 days. Apple/Google refresh tokens have no fixed deadline by default; Google inactivity, testing mode and issuance limits still apply. GitHub OAuth app access tokens have no fixed deadline in the emulator. The injected emulator clock controls expiry.
 - Google `access_type=offline` issues refresh tokens on first consent or `prompt=consent`; generic/Microsoft `offline_access` and Apple issue refresh tokens. Refresh cannot expand scopes. Revocation invalidates related access and refresh tokens; unknown tokens succeed idempotently. Refresh tokens are reusable by default; Microsoft returns a replacement without invalidating the old token. Opt-in strict rotation detects reuse and revokes the token family.
@@ -306,13 +306,26 @@ no grants or account changes. Interactive vendor flows cannot be run unattended
 provider applications, so the focused contract tests use the official behavior documented in the
 references below.
 
+## Per-client opt-ins
+
+Defaults stay strict; these `Client` fields (also accepted by `POST /__admin/clients`) relax one rule each, for one client.
+
+| Field | Effect |
+| --- | --- |
+| `pkceOptional: true` | A public client (no `secret`, no `apple`) may omit PKCE, as a [Cognito public app client](https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html) can. A challenge that is sent must still be S256 and is verified at the token endpoint. Conflicts with `requirePkce: true` and with `secret`/`apple`. |
+| `alwaysIssueRefreshToken: true` | Every authorization-code exchange returns a `refresh_token` without `offline_access`, as [Cognito's token endpoint](https://docs.aws.amazon.com/cognito/latest/developerguide/token-endpoint.html) does. `oidc` and `microsoft` profiles only; Google, Apple and GitHub keep their own rules. |
+| `redirectPolicy: { loopbackAnyPort: true }` | RFC 8252 section 7.3: an `http://` loopback redirect (`127.0.0.1`, `[::1]`, `localhost`) may use any port. It must match a registered loopback URI on the same host, path and query. |
+| `redirectPolicy: { schemes: ["exp:"] }` | For the listed custom schemes the host and port may vary (a dev client's LAN address). The request must still match a registered URI with the same scheme, path and query. `http:`, `https:` and executable schemes are rejected. |
+
+A Cognito-shaped public client is `{ id, name, redirectUris, pkceOptional: true, alwaysIssueRefreshToken: true }` on an `oidc` mount (for example `/oauth2`). Extra authorize parameters such as `identity_provider` are ignored. The token exchange still requires the exact `redirect_uri` that authorized the code. These are matching rules for registered URIs, not wildcards: a URI that is not a variant of a registered one is still refused without a redirect.
+
 ## Deliberately not modelled
 
 This is a ready-to-use local/test identity provider, **not a production authentication server or a claim that every proprietary provider feature is implemented**. Its ready tier covers the documented OAuth/OIDC login, identity, consent, token, provider-edge-case, and UI surface. Applications should still run a small final check against each real provider before release.
 
 Vendor-hosted Google Identity Services/One Tap, native Apple AuthenticationServices, passkeys, MFA, CAPTCHA, password recovery, email delivery/relay forwarding (only Apple's notification of a forwarding change is sent), app-transfer migration, vendor risk engines, tokeninfo/introspection, logout, GitHub Apps installation/device flows, and Microsoft Graph/tenant administration are not implemented. Other configurable OIDC providers can use the generic profile, but their proprietary scopes and claims are not emulated. Scopes are limited to each profile plus explicitly configured additional scopes. Microsoft uses the configured emulator issuer, not real Entra tenant routing. GitHub is the OAuth app login surface, not the full REST API.
 
-No implicit flow, dynamic client registration, wildcard redirect matching, persistent signing-key storage (keys are held in memory; supply them through `signingKeys` or derive them from a seed), or distributed-session coordination is provided. Private-use redirect schemes work only when their complete URI is explicitly registered; executable/local schemes such as `javascript:`, `data:` and `file:` are rejected. Sign-in and consent pages extend CSP `form-action` with the transaction's redirect origin (or custom scheme). Browser navigation responses use a provider-owned handoff document so the callback can relay through another origin without inheriting the consent form's policy; direct programmatic interaction requests retain their HTTP redirect response. The `form_post` hand-off page sends no `form-action` at all: browsers apply that directive to every redirect after the submit, and the callback that receives the POST may redirect to an application origin the provider never sees, so no allow-list can cover it. The rest of that page's policy (`default-src 'none'`, nonce-only scripts and styles, `base-uri 'none'`, `frame-ancestors 'none'`) is unchanged. Discovery, JWKS, token, userinfo and revoke answer `OPTIONS` preflights and reflect the request `Origin`, so browser (SPA + PKCE) clients can redeem codes directly; the interaction pages send no CORS headers. Snapshot restore is for the same runtime/instance; signing keys are not serialized. The default backing store is in-memory and state disappears when the process exits. A secure browser context and Web Crypto, Fetch and standard Web APIs are required; Node 22+, Bun and modern browsers provide them.
+No implicit flow, dynamic client registration, wildcard redirect matching (beyond the opt-in `redirectPolicy`), persistent signing-key storage (keys are held in memory; supply them through `signingKeys` or derive them from a seed), or distributed-session coordination is provided. Private-use redirect schemes work only when their complete URI is explicitly registered; executable/local schemes such as `javascript:`, `data:` and `file:` are rejected. Sign-in and consent pages extend CSP `form-action` with the transaction's redirect origin (or custom scheme). Browser navigation responses use a provider-owned handoff document so the callback can relay through another origin without inheriting the consent form's policy; direct programmatic interaction requests retain their HTTP redirect response. The `form_post` hand-off page sends no `form-action` at all: browsers apply that directive to every redirect after the submit, and the callback that receives the POST may redirect to an application origin the provider never sees, so no allow-list can cover it. The rest of that page's policy (`default-src 'none'`, nonce-only scripts and styles, `base-uri 'none'`, `frame-ancestors 'none'`) is unchanged. Discovery, JWKS, token, userinfo and revoke answer `OPTIONS` preflights and reflect the request `Origin`, so browser (SPA + PKCE) clients can redeem codes directly; the interaction pages send no CORS headers. Snapshot restore is for the same runtime/instance; signing keys are not serialized. The default backing store is in-memory and state disappears when the process exits. A secure browser context and Web Crypto, Fetch and standard Web APIs are required; Node 22+, Bun and modern browsers provide them.
 
 References: [Google OpenID Connect](https://developers.google.com/identity/openid-connect/openid-connect), [Apple authorization request](https://developer.apple.com/documentation/signinwithapplerestapi/request-an-authorization-to-the-sign-in-with-apple-server.), and [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html).
 

package/dist/{chunk-4GFNDUAY.js → chunk-AAKIJOPV.js}

@@ -5,12 +5,13 @@ import {
   createRuntime,
   normalizeBootControls,
   normalizeControls,
+  normalizeIdBase,
   ownedTransport,
   parseDuration,
   parseFaultHeader,
   resolveAdminPrefix,
   restoreClock
-} from "./chunk-ANDSQ2HK.js";
+} from "./chunk-VAXKCT3L.js";
 
 // src/server.ts
 import { readFile as readFile6 } from "node:fs/promises";
@@ -19,6 +20,19 @@ import { readFile as readFile6 } from "node:fs/promises";
 import { readFile as readFile5 } from "node:fs/promises";
 import { parseArgs } from "node:util";
 
+// ../../adapters/node/dist/boot-settings.js
+var checkSettings = (target, settings, label) => {
+  if (!target.parseSettings)
+    throw new Error(`${label}: ${target.name} takes no boot settings`);
+  try {
+    return target.parseSettings(settings);
+  } catch (error) {
+    throw new Error(`${label}: ${error instanceof Error ? error.message : String(error)}`, {
+      cause: error
+    });
+  }
+};
+
 // ../../adapters/node/dist/fleet.js
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
 import { createHash as createHash4, randomUUID as randomUUID4 } from "node:crypto";
@@ -2668,6 +2682,9 @@ var fleet_config_schema_default = {
     adminControls: {
       $ref: "#/$defs/controls"
     },
+    idBase: {
+      $ref: "#/$defs/idBase"
+    },
     namespace: {
       type: "string",
       pattern: "^[A-Za-z0-9_.-]{1,64}$"
@@ -2757,6 +2774,12 @@ var fleet_config_schema_default = {
         adminControls: {
           $ref: "#/$defs/controls"
         },
+        idBase: {
+          $ref: "#/$defs/idBase"
+        },
+        settings: {
+          type: "object"
+        },
         fixtures: {
           type: "object"
         },
@@ -2803,6 +2826,18 @@ var fleet_config_schema_default = {
         }
       }
     },
+    idBase: {
+      anyOf: [
+        {
+          type: "integer",
+          minimum: 0
+        },
+        {
+          type: "string",
+          pattern: "^(boot|[0-9]+)$"
+        }
+      ]
+    },
     controls: {
       type: "object",
       additionalProperties: false,
@@ -2952,6 +2987,8 @@ async function preflightFleet(config, options) {
     throw new Error("protected archive policy requires a protected repository; configure its protector before startup");
   resolveAdminPrefix(config.adminPrefix);
   normalizeBootControls(config.adminControls);
+  if (config.idBase !== void 0)
+    normalizeIdBase(config.idBase, "idBase");
   const targets = /* @__PURE__ */ new Map();
   const ports = /* @__PURE__ */ new Set();
   for (const [name, entry] of Object.entries(config.services)) {
@@ -2983,6 +3020,13 @@ async function preflightFleet(config, options) {
             throw new Error("invalid protocol namespace selector");
         }
       }
+      if (entry.idBase !== void 0)
+        normalizeIdBase(entry.idBase, "idBase");
+      if (entry.settings !== void 0) {
+        if (protocol !== "http" || !("create" in target))
+          throw new Error("settings: only HTTP services take boot settings");
+        checkSettings(target, entry.settings, "settings");
+      }
       const port = entry.port ?? target.defaultPort;
       if (port !== 0) {
         const key = `${entry.host ?? "127.0.0.1"}:${port}`;
@@ -3018,7 +3062,7 @@ async function preflightFleet(config, options) {
             break;
         }
       }
-      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.7.0" });
+      targets.set(name, { ...target, packageVersion: packageVersion ?? "3.8.0" });
     } catch (error) {
       throw new Error(`service ${name}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
@@ -3338,6 +3382,7 @@ var httpChild = async (target, entry, options, admission, generation, privateAcc
       options.onLog?.(entry2);
     },
     ...entry.adminControls !== void 0 ? { adminControls: entry.adminControls } : {},
+    ...entry.settings !== void 0 ? { settings: checkSettings(target, entry.settings, "settings") } : {},
     ...entry.fixtures !== void 0 ? { fixtures: entry.fixtures } : {},
     ...(advertisedHttpBase(entry) ?? entry.baseUrl) !== void 0 ? { baseUrl: advertisedHttpBase(entry) ?? entry.baseUrl } : {}
   });
@@ -3356,6 +3401,8 @@ var httpChild = async (target, entry, options, admission, generation, privateAcc
   ].some((method) => typeof created[method] !== "function"))
     throw new Error("HTTP target does not implement the fleet runtime protocol; build/install matching supported service versions");
   const runtime = created;
+  if (entry.idBase !== void 0)
+    runtime.setIdBase?.(entry.idBase);
   const unobserve = runtime.webhooks?.observeDeliveries(observer.delivery);
   if (options.outbound && runtime.webhooks)
     runtime.webhooks.setTransportPolicy(ownedTransport(options.outbound));
@@ -3954,6 +4001,7 @@ async function startFleet(config, options) {
           ...entry,
           adminPrefix: resolveAdminPrefix(entry.adminPrefix ?? adminPrefix),
           ...adminKey !== void 0 ? { adminKey } : {},
+          ...(entry.idBase ?? config.idBase) !== void 0 ? { idBase: entry.idBase ?? config.idBase } : {},
           // Fleet-wide controls, with the service's own keys replacing them.
           ...config.adminControls !== void 0 || entry.adminControls !== void 0 ? { adminControls: { ...config.adminControls, ...entry.adminControls } } : {}
         }, options, (namespace, request) => management?.admit(namespace, request), (namespace) => management?.generation(namespace), (namespace, request) => management?.privateRequest(namespace, request) ?? false, {
@@ -4638,6 +4686,16 @@ var COMMON_SERVE_OPTIONS = {
     value: "<seed>",
     description: "Seed for every random choice (env MOCKINGBIRD_SEED)"
   },
+  "id-base": {
+    type: "string",
+    value: "<n|boot>",
+    description: "Start generated ids at this base so a restart does not reissue the last boot's ids; boot derives one from the clock (env MOCKINGBIRD_ID_BASE; default 0, the same ids every boot)"
+  },
+  settings: {
+    type: "string",
+    value: "<json|file>",
+    description: "Service settings to boot with, as JSON or a JSON file; every namespace starts from them (env MOCKINGBIRD_SETTINGS; only for services that declare settings)"
+  },
   "admin-controls": {
     type: "string",
     value: "<json|file>",
@@ -4732,19 +4790,40 @@ var readJsonFile = async (path, label) => {
   }
 };
 var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var readJsonOption = async (source, label) => {
+  const trimmed = source.trim();
+  if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      throw new Error(`${label}: not valid JSON`);
+    }
+  }
+  return readJsonFile(source, label);
+};
+var resolveServeIdBase = (values, env = process.env) => {
+  const source = asString(values["id-base"]) ?? env.MOCKINGBIRD_ID_BASE;
+  if (source === void 0 || source.trim() === "")
+    return void 0;
+  normalizeIdBase(source.trim(), "--id-base");
+  return source.trim();
+};
+var resolveServeSettings = async (target, values, env = process.env) => {
+  const flag = asString(values.settings);
+  const source = flag ?? env.MOCKINGBIRD_SETTINGS;
+  if (source === void 0 || source.trim() === "")
+    return void 0;
+  const label = flag !== void 0 ? "--settings" : "MOCKINGBIRD_SETTINGS";
+  const parsed = await readJsonOption(source, label);
+  if (!isObject2(parsed))
+    throw new Error(`${label}: expected a JSON object`);
+  return checkSettings(target, parsed, label);
+};
 var resolveServeControls = async (values, env = process.env, base) => {
   const source = asString(values["admin-controls"]) ?? env.MOCKINGBIRD_ADMIN_CONTROLS;
   let document = isObject2(base) ? { ...base } : {};
   if (source !== void 0 && source.trim() !== "") {
-    let parsed;
-    if (source.trim().startsWith("{")) {
-      try {
-        parsed = JSON.parse(source);
-      } catch {
-        throw new Error("--admin-controls: not valid JSON");
-      }
-    } else
-      parsed = await readJsonFile(source, "--admin-controls");
+    const parsed = source.trim().startsWith("{") ? await readJsonOption(source, "--admin-controls") : await readJsonFile(source, "--admin-controls");
     if (!isObject2(parsed))
       throw new Error("--admin-controls: expected a JSON object");
     document = { ...document, ...parsed };
@@ -4794,8 +4873,11 @@ var start = async (target, values, config) => {
     adminKey: config.adminKey,
     seed: config.seed,
     onLog: formatLog(config.log),
+    ...config.settings !== void 0 ? { settings: config.settings } : {},
     ...config.adminControls !== void 0 ? { adminControls: config.adminControls } : {}
   });
+  if (config.idBase !== void 0)
+    runtime.setIdBase?.(config.idBase);
   const listening = await listen(runtime, { port: config.port, host: config.host });
   target.listening?.(listening);
   console.log(`${target.name} emulator listening on ${listening.url}`);
@@ -4841,6 +4923,11 @@ var serveCommand = (target) => ({
         const adminControls = await resolveServeControls(values, process.env, config.adminControls);
         if (adminControls !== void 0)
           config.adminControls = adminControls;
+        if (values.settings !== void 0)
+          throw new Error("--settings serves a single service; give each service its own `settings` in the config");
+        const idBase = config.idBase ?? resolveServeIdBase(values);
+        if (idBase !== void 0)
+          config.idBase = idBase;
         const fleet = await startFleet(config, {
           load: (name) => loadTarget(name, target),
           onLog: formatLog(config.log ?? log),
@@ -4870,8 +4957,12 @@ var serveCommand = (target) => ({
     let listening;
     try {
       const adminControls = await resolveServeControls(values);
+      const idBase = resolveServeIdBase(values);
+      const settings = await resolveServeSettings(target, values);
       listening = await start(target, values, {
         ...adminControls !== void 0 ? { adminControls } : {},
+        ...idBase !== void 0 ? { idBase } : {},
+        ...settings !== void 0 ? { settings } : {},
         adminPrefix: resolveAdminPrefix(asString(values["admin-prefix"]) ?? process.env.MOCKINGBIRD_ADMIN_PREFIX),
         port: port === void 0 ? target.defaultPort : Number.parseInt(port, 10),
         host: asString(values.host) ?? "127.0.0.1",
@@ -4962,4 +5053,4 @@ export {
   createMultiServer,
   serveTarget
 };
-//# sourceMappingURL=chunk-4GFNDUAY.js.map
+//# sourceMappingURL=chunk-AAKIJOPV.js.map