@crvouga/mockingbird-service-clerk 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — @crvouga/mockingbird-service-clerk
 
-## 0.1.0 (2026-10-11)
+## 0.3.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))
+
+## 0.2.0 (2026-10-12)
+
+### Features
+
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+## 0.1.0 (2026-10-08)
 
 Initial release.

package/DISCOVERY.md

@@ -34,6 +34,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`
@@ -44,6 +45,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,11 +13,29 @@ npm install @crvouga/mockingbird-service-clerk
 ## Usage
 
 ```ts
-import { createRuntime } from "@crvouga/mockingbird-service-clerk"
-const runtime = createRuntime({ seed: 1 })
-const response = await runtime.fetch(new Request("https://api.clerk.com"))
+import { createServer } from "@crvouga/mockingbird-service-clerk/server"
+
+const server = await createServer({ seed: 1 })
+
+// The app's Backend API calls, with the emulator's URL in place of https://api.clerk.com.
+const headers = { authorization: "Bearer sk_test_fixture", "content-type": "application/json" }
+const created = await fetch(`${server.url}/v1/users`, {
+  method: "POST",
+  headers,
+  body: JSON.stringify({ email_address: ["ada@example.com"], first_name: "Ada" }),
+})
+const user = (await created.json()) as { id: string; first_name: string }
+const listed = await fetch(`${server.url}/v1/users?email_address=ada@example.com`, { headers })
+const { data } = (await listed.json()) as { data: { id: string }[] }
+console.log(data[0]?.id === user.id) // true
+await server.close()
 ```
 
+The example uses plain `fetch` because `@clerk/backend` only parses a response whose
+`content-type` is exactly `application/json`, and the emulator answers
+`application/json; charset=UTF-8`. With `createClerkClient({ secretKey, apiUrl: server.url })` the
+requests succeed but resources come back as unparsed JSON strings.
+
 ## API
 
 - `ClerkAPI`: portable provider instance; accepts SQLite, namespace, clock, fixtures and baseUrl.

package/dist/{chunk-M73LWCCP.js → chunk-6Z2MR3PO.js}

@@ -42,11 +42,38 @@ function createHmac(algorithm, key) {
   };
   return hash;
 }
+var source;
+function useRandom(next) {
+  source = next;
+}
+function withRandom(next, run) {
+  const previous = source;
+  source = next;
+  try {
+    return run();
+  } finally {
+    source = previous;
+  }
+}
+function random() {
+  return source ? source() : Math.random();
+}
 function randomBytes(length) {
-  return Buffer.from(crypto.getRandomValues(new Uint8Array(length)));
+  if (!source)
+    return Buffer.from(crypto.getRandomValues(new Uint8Array(length)));
+  const out = new Uint8Array(length);
+  for (let i = 0; i < length; i++)
+    out[i] = Math.floor(source() * 256);
+  return Buffer.from(out);
 }
 function randomUUID() {
-  return crypto.randomUUID();
+  if (!source)
+    return crypto.randomUUID();
+  const b = randomBytes(16);
+  b[6] = b[6] & 15 | 64;
+  b[8] = b[8] & 63 | 128;
+  const hex = b.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
 }
 function timingSafeEqual(a, b) {
   if (a.length !== b.length)
@@ -60,8 +87,11 @@ function timingSafeEqual(a, b) {
 export {
   createHash,
   createHmac,
+  useRandom,
+  withRandom,
+  random,
   randomBytes,
   randomUUID,
   timingSafeEqual
 };
-//# sourceMappingURL=chunk-M73LWCCP.js.map
+//# sourceMappingURL=chunk-6Z2MR3PO.js.map

package/dist/{chunk-M73LWCCP.js.map → chunk-6Z2MR3PO.js.map}

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../http/provider/src/vendor/core/crypto.ts"],
-  "sourcesContent": ["import { hmac } from \"@noble/hashes/hmac.js\"\nimport { sha1 } from \"@noble/hashes/legacy.js\"\nimport { md5 } from \"@noble/hashes/legacy.js\"\nimport { sha256 } from \"@noble/hashes/sha2.js\"\nimport { Buffer } from \"buffer\"\n\nconst digest = (algorithm: string) => {\n  if (algorithm === \"sha256\") return sha256\n  if (algorithm === \"sha1\") return sha1\n  if (algorithm === \"md5\") return md5\n  throw new Error(`Unsupported digest ${algorithm}`)\n}\nconst bytes = (input: string | Uint8Array) => typeof input === \"string\" ? new TextEncoder().encode(input) : input\ninterface Hash {\n  update(input: string | Uint8Array): Hash\n  digest(): Buffer\n  digest(encoding: string): string\n}\nexport function createHash(algorithm: string): Hash {\n  const parts: Uint8Array[] = []\n  const hash = {\n    update(input: string | Uint8Array) { parts.push(bytes(input)); return hash },\n    digest(encoding?: string): Buffer | string {\n      const result = Buffer.from(digest(algorithm)(Buffer.concat(parts)))\n      return encoding === \"base64url\" ? result.toString(\"base64\").replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\") : encoding ? result.toString(encoding as BufferEncoding) : result\n    },\n  }\n  return hash as Hash\n}\nexport function createHmac(algorithm: string, key: string | Uint8Array): Hash {\n  const parts: Uint8Array[] = []\n  const hash = {\n    update(input: string | Uint8Array) { parts.push(bytes(input)); return hash },\n    digest(encoding?: string): Buffer | string {\n      const result = Buffer.from(hmac(digest(algorithm), bytes(key), Buffer.concat(parts)))\n      return encoding === \"base64url\" ? result.toString(\"base64\").replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\") : encoding ? result.toString(encoding as BufferEncoding) : result\n    },\n  }\n  return hash as Hash\n}\nexport function randomBytes(length: number): Buffer {\n  return Buffer.from(crypto.getRandomValues(new Uint8Array(length)))\n}\nexport function randomUUID(): string { return crypto.randomUUID() }\nexport function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) throw new Error(\"Buffers must have equal lengths\")\n  let difference = 0\n  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i]\n  return difference === 0\n}\n"],
-  "mappings": ";AAAA,SAAS,YAAY;AACrB,SAAS,YAAY;AACrB,SAAS,WAAW;AACpB,SAAS,cAAc;AACvB,SAAS,cAAc;AAEvB,IAAM,SAAS,CAAC,cAAqB;AACnC,MAAI,cAAc;AAAU,WAAO;AACnC,MAAI,cAAc;AAAQ,WAAO;AACjC,MAAI,cAAc;AAAO,WAAO;AAChC,QAAM,IAAI,MAAM,sBAAsB,SAAS,EAAE;AACnD;AACA,IAAM,QAAQ,CAAC,UAA+B,OAAO,UAAU,WAAW,IAAI,YAAW,EAAG,OAAO,KAAK,IAAI;AAMtG,SAAU,WAAW,WAAiB;AAC1C,QAAM,QAAsB,CAAA;AAC5B,QAAM,OAAO;IACX,OAAO,OAA0B;AAAI,YAAM,KAAK,MAAM,KAAK,CAAC;AAAG,aAAO;IAAK;IAC3E,OAAO,UAAiB;AACtB,YAAM,SAAS,OAAO,KAAK,OAAO,SAAS,EAAE,OAAO,OAAO,KAAK,CAAC,CAAC;AAClE,aAAO,aAAa,cAAc,OAAO,SAAS,QAAQ,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE,IAAI,WAAW,OAAO,SAAS,QAA0B,IAAI;IACpL;;AAEF,SAAO;AACT;AACM,SAAU,WAAW,WAAmB,KAAwB;AACpE,QAAM,QAAsB,CAAA;AAC5B,QAAM,OAAO;IACX,OAAO,OAA0B;AAAI,YAAM,KAAK,MAAM,KAAK,CAAC;AAAG,aAAO;IAAK;IAC3E,OAAO,UAAiB;AACtB,YAAM,SAAS,OAAO,KAAK,KAAK,OAAO,SAAS,GAAG,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,CAAC,CAAC;AACpF,aAAO,aAAa,cAAc,OAAO,SAAS,QAAQ,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,EAAE,IAAI,WAAW,OAAO,SAAS,QAA0B,IAAI;IACpL;;AAEF,SAAO;AACT;AACM,SAAU,YAAY,QAAc;AACxC,SAAO,OAAO,KAAK,OAAO,gBAAgB,IAAI,WAAW,MAAM,CAAC,CAAC;AACnE;AACM,SAAU,aAAU;AAAa,SAAO,OAAO,WAAU;AAAG;AAC5D,SAAU,gBAAgB,GAAe,GAAa;AAC1D,MAAI,EAAE,WAAW,EAAE;AAAQ,UAAM,IAAI,MAAM,iCAAiC;AAC5E,MAAI,aAAa;AACjB,WAAS,IAAI,GAAG,IAAI,EAAE,QAAQ;AAAK,kBAAc,EAAE,CAAC,IAAI,EAAE,CAAC;AAC3D,SAAO,eAAe;AACxB;",
+  "sourcesContent": ["import { hmac } from \"@noble/hashes/hmac.js\"\nimport { sha1 } from \"@noble/hashes/legacy.js\"\nimport { md5 } from \"@noble/hashes/legacy.js\"\nimport { sha256 } from \"@noble/hashes/sha2.js\"\nimport { Buffer } from \"buffer\"\n\nconst digest = (algorithm: string) => {\n  if (algorithm === \"sha256\") return sha256\n  if (algorithm === \"sha1\") return sha1\n  if (algorithm === \"md5\") return md5\n  throw new Error(`Unsupported digest ${algorithm}`)\n}\nconst bytes = (input: string | Uint8Array) => typeof input === \"string\" ? new TextEncoder().encode(input) : input\ninterface Hash {\n  update(input: string | Uint8Array): Hash\n  digest(): Buffer\n  digest(encoding: string): string\n}\nexport function createHash(algorithm: string): Hash {\n  const parts: Uint8Array[] = []\n  const hash = {\n    update(input: string | Uint8Array) { parts.push(bytes(input)); return hash },\n    digest(encoding?: string): Buffer | string {\n      const result = Buffer.from(digest(algorithm)(Buffer.concat(parts)))\n      return encoding === \"base64url\" ? result.toString(\"base64\").replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\") : encoding ? result.toString(encoding as BufferEncoding) : result\n    },\n  }\n  return hash as Hash\n}\nexport function createHmac(algorithm: string, key: string | Uint8Array): Hash {\n  const parts: Uint8Array[] = []\n  const hash = {\n    update(input: string | Uint8Array) { parts.push(bytes(input)); return hash },\n    digest(encoding?: string): Buffer | string {\n      const result = Buffer.from(hmac(digest(algorithm), bytes(key), Buffer.concat(parts)))\n      return encoding === \"base64url\" ? result.toString(\"base64\").replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\") : encoding ? result.toString(encoding as BufferEncoding) : result\n    },\n  }\n  return hash as Hash\n}\n/**\n * Mockingbird: where ids and tokens come from. With a seeded stream in place, everything the\n * vendor code mints replays from the seed; without one it is the platform's own randomness.\n */\nlet source: (() => number) | undefined\n/** Mint from `next` (a seeded stream of `[0, 1)`) until told otherwise. */\nexport function useRandom(next: (() => number) | undefined): void { source = next }\n/** Mint from `next` for one synchronous section, then put the previous source back. */\nexport function withRandom<T>(next: (() => number) | undefined, run: () => T): T {\n  const previous = source\n  source = next\n  try { return run() } finally { source = previous }\n}\n/** `Math.random`, from the seeded stream when one is in place. */\nexport function random(): number { return source ? source() : Math.random() }\nexport function randomBytes(length: number): Buffer {\n  if (!source) return Buffer.from(crypto.getRandomValues(new Uint8Array(length)))\n  const out = new Uint8Array(length)\n  for (let i = 0; i < length; i++) out[i] = Math.floor(source() * 256)\n  return Buffer.from(out)\n}\nexport function randomUUID(): string {\n  if (!source) return crypto.randomUUID()\n  const b = randomBytes(16)\n  b[6] = (b[6] & 0x0f) | 0x40\n  b[8] = (b[8] & 0x3f) | 0x80\n  const hex = b.toString(\"hex\")\n  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`\n}\nexport function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.length !== b.length) throw new Error(\"Buffers must have equal lengths\")\n  let difference = 0\n  for (let i = 0; i < a.length; i++) difference |= a[i] ^ b[i]\n  return difference === 0\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/{chunk-YR65VVP4.js → chunk-ASGMRJQK.js}

@@ -1,6 +1,6 @@
 import {
   randomUUID
-} from "./chunk-M73LWCCP.js";
+} from "./chunk-6Z2MR3PO.js";
 
 // ../../http/provider/dist/vendor/clerk/helpers.js
 function generateClerkId(prefix) {
@@ -84,4 +84,4 @@ export {
   userDisplayName
 };
 /*! Adapted from vercel-labs/emulate (Apache-2.0), modified for Mockingbird. See port.json, LICENSE_EMULATE and THIRD_PARTY_NOTICES.md. */
-//# sourceMappingURL=chunk-YR65VVP4.js.map
+//# sourceMappingURL=chunk-ASGMRJQK.js.map