@crvouga/mockingbird-service-oauth 1.1.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog — @crvouga/mockingbird-service-oauth
 
+## 1.2.1 (2026-09-29)
+
+### Fixes and improvements
+
+- sign and retry webhooks on the injected clock ([1091bde](https://github.com/crvouga/mockingbird/commit/1091bde0df69d9cc3eba2062d8523755e6caca14))
+
+## 1.2.0 (2026-09-29)
+
+### Features
+
+- add id token faults for issuer clock skew and unpublished signing key ([7a014f2](https://github.com/crvouga/mockingbird/commit/7a014f2d0e5beeb458a056f092b1b62ccbf504d4))
+- send Sign in with Apple server-to-server notifications ([681348e](https://github.com/crvouga/mockingbird/commit/681348e5ef0b4cf87067f013e3d0703339d608c1))
+
 ## 1.1.0 (2026-09-29)
 
 ### Features

package/README.md

@@ -186,9 +186,9 @@ Identity/consent decisions are sampled once per authorization and kept with the
 | GitHub | OAuth app endpoints, JSON or form token responses, no ID token, and a nullable `/user.email` even with email scope. `/user/emails` returns primary/secondary and verified/unverified addresses and requires `user:email` or `user`. Resource responses expose `X-OAuth-Scopes` and `X-Accepted-OAuth-Scopes`. An unverified primary account fails token exchange with `unverified_user_email`. Incorrect credentials/code/redirect produce GitHub error names. |
 | Any | Missing/unverified email, missing names, denied consent, partial scopes, configurable token/code expiry, transient token failures, revoked grants, strict refresh rotation/reuse detection, and signing-key rotation. Non-Apple account email changes retain the subject. Additional scopes can be accepted via `additionalScopes`; associated resource APIs are not implied. |
 
-The complete typed controls are `OAuthBehavior`. `probabilities` accepts `hideEmail`, `omitEmail`, `omitName`, `unverifiedEmail`, `denyConsent`, `tokenUnavailable`, and `invalidGrant`, each in `[0,1]`. Static `claims` flags force omissions or unverified email. `consent.error` supports `access_denied`, `interaction_required`, or `temporarily_unavailable`. `tokens` accepts positive integer `accessTtlSeconds`, `codeTtlSeconds`, `refreshTtlSeconds`, `refreshRotation: "reuse" | "rotate"`, and `refreshError`. These controls are local testing overrides, not claims that all providers implement every variation.
+The complete typed controls are `OAuthBehavior`. `probabilities` accepts `hideEmail`, `omitEmail`, `omitName`, `unverifiedEmail`, `denyConsent`, `tokenUnavailable`, and `invalidGrant`, each in `[0,1]`. Static `claims` flags force omissions or unverified email. `consent.error` supports `access_denied`, `interaction_required`, or `temporarily_unavailable`. `tokens` accepts positive integer `accessTtlSeconds`, `codeTtlSeconds`, `refreshTtlSeconds`, `refreshRotation: "reuse" | "rotate"`, `refreshError`, and two ID-token faults for testing a relying party's verification: `idTokenClockSkewSeconds` (an integer, forward or backward) sets `iat = now + skew`, `exp = iat + accessTtlSeconds` and offsets `auth_time` by the same skew, and `idTokenSigningKey: "unpublished"` signs ID tokens with a key whose `kid` no JWKS response ever contains, even after `rotateSigningKey`. Both apply to authorization-code, refresh-grant and `code id_token` ID tokens and compose with each other. These controls are local testing overrides, not claims that all providers implement every variation.
 
-`OAUTH_SCENARIOS` supplies: `apple_private_relay`, `apple_share_email`, `apple_returning_user`, `apple_boolean_claims`, `microsoft_missing_email`, `microsoft_spa_expiry`, `github_unverified_email`, `missing_email`, `missing_name`, `unverified_email`, `google_no_refresh_token`, `google_reauthentication`, `revoked_refresh_token`, `rotating_refresh_tokens`, `short_lived_tokens`, `consent_denied`, `intermittent_token_failure`. Explicit fields override the chosen preset's fields. Unknown keys and invalid values fail validation.
+`OAUTH_SCENARIOS` supplies: `apple_private_relay`, `apple_share_email`, `apple_returning_user`, `apple_boolean_claims`, `microsoft_missing_email`, `microsoft_spa_expiry`, `github_unverified_email`, `missing_email`, `missing_name`, `unverified_email`, `google_no_refresh_token`, `google_reauthentication`, `revoked_refresh_token`, `rotating_refresh_tokens`, `short_lived_tokens`, `consent_denied`, `intermittent_token_failure`, `id_token_clock_ahead` (+600 s), `id_token_stale` (-7200 s, expired an hour ago), `id_token_unknown_key`. Explicit fields override the chosen preset's fields. Unknown keys and invalid values fail validation.
 
 ```sh
 npx mockingbird-oauth serve --provider apple --seed regression-42 --scenario apple_private_relay
@@ -198,17 +198,33 @@ curl -X PUT http://localhost:8810/__admin/behavior -H 'content-type: application
 curl http://localhost:8810/__admin/behavior
 curl -X POST http://localhost:8810/__admin/consents/revoke -H 'content-type: application/json' \
   -d '{"clientId":"app","accountId":"ada"}'
+curl -X POST http://localhost:8810/__admin/accounts/delete -H 'content-type: application/json' \
+  -d '{"accountId":"ada"}'
+curl -X POST http://localhost:8810/__admin/relay-forwarding -H 'content-type: application/json' \
+  -d '{"accountId":"ada","forwarding":false}'
 curl -X POST http://localhost:8810/__admin/keys/rotate -H 'content-type: application/json' \
   -d '{"retainPrevious":true}'
 ```
 
-These routes use the shared admin-key and namespace controls. `revokeConsent(clientId, accountId)` removes that client's grants and resets first-use disclosure; it does not disable the account. `rotateSigningKey(true)` retains up to four previous public keys so existing tokens still verify; `false` withdraws them to test stale JWKS caches. Keys themselves are not included in snapshots, so restoring state does not undo a key rotation.
+These routes use the shared admin-key and namespace controls. `revokeConsent(clientId, accountId)` removes that client's grants and resets first-use disclosure; it does not disable the account. It is async because it can deliver a [server-to-server notification](#sign-in-with-apple-server-to-server-notifications). `rotateSigningKey(true)` retains up to four previous public keys so existing tokens still verify; `false` withdraws them to test stale JWKS caches. Keys themselves are not included in snapshots, so restoring state does not undo a key rotation.
+
+### Sign in with Apple server-to-server notifications
+
+Register an Apple client with `apple.notificationUrl` (an HTTP(S) URL; requires the JWT `apple` client form) and the mock behaves like Apple's [server-to-server notification endpoint](https://developer.apple.com/documentation/signinwithapplerestapi/processing-changes-for-sign-in-with-apple-accounts): it POSTs `{"payload": "<JWS>"}` as JSON. The JWS is signed by the current signing key (verify it against the JWKS) with `iss` = the issuer, `aud` = the client id, `iat` from the mock clock and a random `jti`. `events` is a JSON string of `{ type, sub, event_time }`, where `sub` is the client's identity for the account and `event_time` is milliseconds from the mock clock.
+
+| Trigger | Event `type` | Sent to |
+| --- | --- | --- |
+| `revokeConsent(clientId, accountId)` / `POST /__admin/consents/revoke` | `consent-revoked` | that client, when it held the consent |
+| `deleteAccount(accountId)` / `POST /__admin/accounts/delete {"accountId"}` | `account-delete` | every client holding a consent; then the account, its grants, sessions and pending sign-ins are removed |
+| `setRelayForwarding(accountId, forwarding)` / `POST /__admin/relay-forwarding {"accountId","forwarding"}` | `email-disabled` / `email-enabled`, with `email` (the relay address) and `is_private_email: "true"` | every client holding a consent whose identity is a private relay address |
+
+Delivery is awaited by the call that caused it, through `webhooks.fetch` (`createRuntime({ webhooks: { fetch } })`, default global `fetch`), so an in-process suite can route it through its own network model. The admin routes and methods return one `{ clientId, type, delivered, status?, error? }` per notification; a non-2xx response or a thrown error is reported there and never fails the call, and Apple's retries are not modelled. Without an `issuer` option, direct method calls need an `issuer` argument (admin routes derive it from the request). Unknown accounts return 404 from the admin routes and reject from the methods.
 
 ### Shared service controls
 
 The runtime supplies `/health`, `/__admin/reset`, snapshots, mock clock, request journal, metrics, fault injection and namespace isolation. Use `x-mockingbird-namespace` for in-process tests or `/ns/<name>/…` for complete browser flows. Header-selected namespaces alone cannot persist across ordinary browser navigation. State, grants, sessions and consent live in the shared SQLite abstraction; there are no filesystem or Node imports in the main entry.
 
-`OAUTH_PRESETS` includes `token_unavailable` and `access_denied`. Fault rules can also target a provider-specific path, e.g. `POST /__admin/faults` with `{"pathPrefix":"/auth/token","status":503,"body":{"error":"temporarily_unavailable"}}`. No outbound webhooks are modeled. Journals contain request metadata, never passwords or request bodies.
+`OAUTH_PRESETS` includes `token_unavailable` and `access_denied`. Fault rules can also target a provider-specific path, e.g. `POST /__admin/faults` with `{"pathPrefix":"/auth/token","status":503,"body":{"error":"temporarily_unavailable"}}`. The only outbound requests are the Apple notifications above. Journals contain request metadata, never passwords or request bodies.
 
 ## API
 
@@ -238,7 +254,7 @@ references below.
 
 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, 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 mock issuer, not real Entra tenant routing. GitHub is the OAuth app login surface, not the full REST API.
+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 mock 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 import, 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) so browsers follow the redirect back to the client. 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.
 

package/dist/{chunk-FZKITSDL.js → chunk-2JIADQOV.js}

@@ -2,7 +2,7 @@ import {
   OAUTH_SCENARIOS,
   createMultiRuntime,
   createRuntime
-} from "./chunk-JA62N2QU.js";
+} from "./chunk-XP2AEPEJ.js";
 
 // src/server.ts
 import { readFile as readFile2 } from "node:fs/promises";
@@ -377,4 +377,4 @@ export {
   createMultiServer,
   serveTarget
 };
-//# sourceMappingURL=chunk-FZKITSDL.js.map
+//# sourceMappingURL=chunk-2JIADQOV.js.map

package/dist/{chunk-JA62N2QU.js → chunk-XP2AEPEJ.js}

@@ -1384,7 +1384,7 @@ var restoreNamespace = (sqlite, namespace, snapshot) => {
 };
 
 // ../core/dist/version.js
-var PACKAGE_VERSION = true ? "1.1.0" : UNRELEASED_VERSION;
+var PACKAGE_VERSION = true ? "1.2.1" : UNRELEASED_VERSION;
 
 // ../core/dist/webhooks.js
 var json2 = (status, body) => new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
@@ -2069,7 +2069,10 @@ var OAUTH_SCENARIOS = {
   rotating_refresh_tokens: { tokens: { refreshRotation: "rotate" } },
   short_lived_tokens: { tokens: { accessTtlSeconds: 5, codeTtlSeconds: 5, refreshTtlSeconds: 30 } },
   consent_denied: { consent: { error: "access_denied" } },
-  intermittent_token_failure: { probabilities: { tokenUnavailable: 0.25 } }
+  intermittent_token_failure: { probabilities: { tokenUnavailable: 0.25 } },
+  id_token_clock_ahead: { tokens: { idTokenClockSkewSeconds: 600 } },
+  id_token_stale: { tokens: { idTokenClockSkewSeconds: -7200 } },
+  id_token_unknown_key: { tokens: { idTokenSigningKey: "unpublished" } }
 };
 var object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 var keys = (value, allowed) => {
@@ -2154,10 +2157,16 @@ function validateBehavior(input) {
       "codeTtlSeconds",
       "refreshTtlSeconds",
       "refreshRotation",
-      "refreshError"
+      "refreshError",
+      "idTokenClockSkewSeconds",
+      "idTokenSigningKey"
     ]);
     enumeration(tokens.refreshRotation, ["reuse", "rotate"]);
     enumeration(tokens.refreshError, ["invalid_grant", "invalid_rapt"]);
+    enumeration(tokens.idTokenSigningKey, ["published", "unpublished"]);
+    const skew = tokens.idTokenClockSkewSeconds;
+    if (skew !== void 0 && (typeof skew !== "number" || !Number.isSafeInteger(skew) || Math.abs(skew) > 31536e4))
+      throw new Error("idTokenClockSkewSeconds must be an integer in [-315360000,315360000]");
     for (const key of ["accessTtlSeconds", "codeTtlSeconds", "refreshTtlSeconds"]) {
       const v = tokens[key];
       if (v !== void 0 && (typeof v !== "number" || !Number.isSafeInteger(v) || v < 1 || v > 31536e4))
@@ -2424,12 +2433,44 @@ function createRuntime2(options = {}) {
           return Response.json({ error: String(error) }, { status: 400 });
         }
       },
-      "POST /consents/revoke": ({ namespace, body }) => {
+      "POST /consents/revoke": async ({ namespace, body, request }) => {
         const input = body;
         if (!input || typeof input.clientId !== "string" || typeof input.accountId !== "string")
           return Response.json({ error: "clientId and accountId are required" }, { status: 400 });
-        runtime.instance(namespace).revokeConsent(input.clientId, input.accountId);
-        return Response.json({ revoked: true });
+        const api = runtime.instance(namespace);
+        const notifications = await api.revokeConsent(
+          input.clientId,
+          input.accountId,
+          api.issuer(request)
+        );
+        return Response.json({ revoked: true, notifications });
+      },
+      "POST /accounts/delete": async ({ namespace, body, request }) => {
+        const input = body;
+        if (!input || typeof input.accountId !== "string")
+          return Response.json({ error: "accountId is required" }, { status: 400 });
+        const api = runtime.instance(namespace);
+        if (!api.accounts.has(input.accountId))
+          return Response.json({ error: "Unknown account" }, { status: 404 });
+        const notifications = await api.deleteAccount(input.accountId, api.issuer(request));
+        return Response.json({ deleted: true, notifications });
+      },
+      "POST /relay-forwarding": async ({ namespace, body, request }) => {
+        const input = body;
+        if (!input || typeof input.accountId !== "string" || typeof input.forwarding !== "boolean")
+          return Response.json(
+            { error: "accountId and boolean forwarding are required" },
+            { status: 400 }
+          );
+        const api = runtime.instance(namespace);
+        if (!api.accounts.has(input.accountId))
+          return Response.json({ error: "Unknown account" }, { status: 404 });
+        const notifications = await api.setRelayForwarding(
+          input.accountId,
+          input.forwarding,
+          api.issuer(request)
+        );
+        return Response.json({ forwarding: input.forwarding, notifications });
       },
       "POST /keys/rotate": ({ namespace, body }) => {
         const input = body;
@@ -2641,6 +2682,8 @@ var OAuthAPI = class {
   consents;
   signer = new Signer();
   previousSigners = [];
+  /** Never published: signs ID tokens for `tokens.idTokenSigningKey: "unpublished"`. */
+  unpublishedSigner;
   behavior;
   identities;
   appleDisclosures;
@@ -2684,6 +2727,10 @@ var OAuthAPI = class {
       throw new Error(
         "Apple client requires teamId, keyId and a public P-256 JWK, without a static secret"
       );
+    if (client.apple?.notificationUrl !== void 0 && !(typeof client.apple.notificationUrl === "string" && safeRedirect(client.apple.notificationUrl) && WEB_SCHEMES.has(new URL(client.apple.notificationUrl).protocol)))
+      throw new Error(
+        "apple.notificationUrl must be an HTTP(S) URL without fragment or credentials"
+      );
     this.clients.insert(client.id, structuredClone(client));
     return client;
   }
@@ -2704,7 +2751,95 @@ var OAuthAPI = class {
     this.signer = new Signer();
     return { kid: this.signer.kid };
   }
-  revokeConsent(clientId, accountId) {
+  /**
+   * Withdraws one client's consent. When the client registered `apple.notificationUrl` and held
+   * the consent, Apple's `consent-revoked` notification is delivered before this resolves.
+   */
+  async revokeConsent(clientId, accountId, issuer) {
+    const targets = this.notifiable(accountId).filter((t) => t.client.id === clientId);
+    this.forget(clientId, accountId);
+    return this.notify(targets, "consent-revoked", issuer);
+  }
+  /**
+   * Deletes an account with its grants and sessions, after telling every client that held a
+   * consent (`account-delete`).
+   */
+  async deleteAccount(accountId, issuer) {
+    if (!this.accounts.has(accountId)) throw new Error("Unknown account");
+    const targets = this.notifiable(accountId);
+    for (const { value: client } of this.clients.list()) this.forget(client.id, accountId);
+    for (const row of this.codes.list({ where: (c) => c.accountId === accountId }))
+      this.codes.delete(row.id);
+    for (const row of this.tokens.list({ where: (t) => t.accountId === accountId }))
+      this.tokens.delete(row.id);
+    for (const row of this.transactions.list({ where: (t) => t.accountId === accountId }))
+      this.transactions.delete(row.id);
+    for (const row of this.sessions.list({ where: (s) => s.accountId === accountId }))
+      this.sessions.delete(row.id);
+    this.accounts.delete(accountId);
+    return this.notify(targets, "account-delete", issuer);
+  }
+  /**
+   * Tells every client whose identity for the account is a private relay address that the user
+   * turned forwarding off (`email-disabled`) or on (`email-enabled`).
+   */
+  async setRelayForwarding(accountId, forwarding, issuer) {
+    if (!this.accounts.has(accountId)) throw new Error("Unknown account");
+    return this.notify(
+      this.notifiable(accountId).filter((t) => t.relay),
+      forwarding ? "email-enabled" : "email-disabled",
+      issuer,
+      true
+    );
+  }
+  /** Clients with a notification endpoint that hold a consent for the account. */
+  notifiable(accountId) {
+    return this.clients.list({ order: "oldest" }).flatMap(({ value: client }) => {
+      const identity = this.identities.get(this.identityKey(client, accountId));
+      return client.apple?.notificationUrl && identity && this.consents.has(JSON.stringify([client.id, accountId])) ? [{ client, sub: identity.sub, email: identity.email, relay: identity.privateEmail }] : [];
+    });
+  }
+  async notify(targets, type, issuer, withEmail = false) {
+    if (!targets.length) return [];
+    const iss = issuer ?? this.options.issuer;
+    if (!iss) throw new Error("A notification needs the issuer option or an issuer argument");
+    const send = this.options.webhooks?.fetch ?? ((r) => fetch(r));
+    const deliveries = [];
+    for (const { client, sub, email } of targets) {
+      const payload = await this.signer.sign({
+        iss: iss.replace(/\/$/, ""),
+        aud: client.id,
+        iat: Math.floor(this.now() / 1e3),
+        jti: random(),
+        events: JSON.stringify({
+          type,
+          sub,
+          ...withEmail ? { email, is_private_email: "true" } : {},
+          event_time: this.now()
+        })
+      });
+      try {
+        const response = await send(
+          new Request(client.apple?.notificationUrl ?? "", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ payload })
+          })
+        );
+        deliveries.push({
+          clientId: client.id,
+          type,
+          delivered: response.ok,
+          status: response.status
+        });
+      } catch (error) {
+        deliveries.push({ clientId: client.id, type, delivered: false, error: String(error) });
+      }
+    }
+    return deliveries;
+  }
+  /** Drops one client's grant for an account: consent, identity, first-use disclosure, codes, tokens. */
+  forget(clientId, accountId) {
     const key = JSON.stringify([clientId, accountId]);
     this.consents.delete(key);
     this.refreshIssued.delete(key);
@@ -2847,13 +2982,18 @@ var OAuthAPI = class {
   async idToken(grant, issuer, extra = {}) {
     const account = this.accounts.get(grant.accountId);
     if (!account) throw new Error("Account no longer exists");
-    return this.signer.sign({
+    const tokens = this.behavior.config.tokens;
+    const skew = tokens?.idTokenClockSkewSeconds ?? 0;
+    const iat = Math.floor(this.now() / 1e3) + skew;
+    const unpublished = tokens?.idTokenSigningKey === "unpublished";
+    if (unpublished) this.unpublishedSigner ??= new Signer();
+    return (unpublished && this.unpublishedSigner || this.signer).sign({
       ...this.profile(account, grant),
       iss: issuer,
       aud: grant.clientId,
-      iat: Math.floor(this.now() / 1e3),
-      exp: Math.floor(this.now() / 1e3) + (this.behavior.config.tokens?.accessTtlSeconds ?? 3600),
-      auth_time: Math.floor(grant.authTime / 1e3),
+      iat,
+      exp: iat + (tokens?.accessTtlSeconds ?? 3600),
+      auth_time: Math.floor(grant.authTime / 1e3) + skew,
       ...grant.nonce ? { nonce: grant.nonce } : {},
       ...extra
     });
@@ -3595,4 +3735,4 @@ export {
   createMultiRuntime,
   OAuthAPI
 };
-//# sourceMappingURL=chunk-JA62N2QU.js.map
+//# sourceMappingURL=chunk-XP2AEPEJ.js.map