@yolk-sdk/emulators 0.1.0-canary.96

package/src/stateful-secrets.ts

@@ -0,0 +1,299 @@
+/**
+ * Credential guarding and the fail-closed ledger constants (internal; imported by the stateful
+ * wrapper, `src/stateful-emulator.ts`, and by the `src/r2-guard.ts` port guard, which uses only the
+ * predicate form of the closure, `textClosureOutcome`, without the shared minimum length). No Node
+ * builtin, no core import, and no wrapper import, so the R2 guard imports it without the wrapper.
+ *
+ * A guarded secret (a request-carried credential value the wrapper extracted from a recognised
+ * request shape) must never reach the ledger, a response, or `/_emulate/*`: `scrubSecrets` removes
+ * it from everything recorded or answered, and the `*RepeatsSecret` checks find it in request text
+ * so a request repeating it can be refused. `repeatsSecret` and `jsonRepeatsSecret` (raw, once
+ * percent-decoded, parsed JSON keys, strings, and numbers as JavaScript prints them) serve the
+ * wrapper's resolved mode (Todoist, Telegram), unchanged; its fail-closed mode uses
+ * `textRepeatsSecret`, the fixpoint closure of two total, lexical transforms that cannot fail
+ * (`tolerantPercentDecode`, `tolerantJsonUnescape`), failing closed when its work cap is hit, and
+ * recognises only RFC 6750 `b64token` bearers whose first character completes no escape and that
+ * lie outside the JSON-number alphabet (`isRecognisableBearerValue`).
+ *
+ * @experimental
+ */
+import { Predicate } from 'effect'
+import type * as Schema from 'effect/Schema'
+
+/** The ledgered path of every unrecognised request (constant: nothing from the request). */
+export const unrecognisedLedgerPath = '/<unrecognised>'
+
+const ledgerableMethods: ReadonlySet<string> = new Set([
+  'GET',
+  'HEAD',
+  'POST',
+  'PUT',
+  'PATCH',
+  'DELETE',
+  'OPTIONS'
+])
+
+/** The ledgered method of an unrecognised request: a standard method, or `<other>`. */
+export const unrecognisedMethod = (method: string): string =>
+  ledgerableMethods.has(method) ? method : '<other>'
+
+/** `value` percent-decoded once, or unchanged when it is not valid percent-encoding. */
+export const decodedOrRaw = (value: string): string => {
+  try {
+    return decodeURIComponent(value)
+  } catch {
+    return value
+  }
+}
+
+/** Secrets shorter than this are not scrubbed (they would redact ordinary text). */
+const minimumSecretLength = 4
+
+const meaningful = (secrets: ReadonlyArray<string>): ReadonlyArray<string> =>
+  secrets.filter(secret => secret.length >= minimumSecretLength)
+
+/** True when `text`, raw or percent-decoded, contains a secret. */
+export const repeatsSecret = (text: string, secrets: ReadonlyArray<string>): boolean => {
+  const decoded = decodedOrRaw(text.replaceAll('+', ' '))
+
+  return meaningful(secrets).some(secret => text.includes(secret) || decoded.includes(secret))
+}
+
+const isJsonRecord = (value: Schema.Json): value is Schema.JsonObject =>
+  value !== null && Predicate.isObject(value) && !Array.isArray(value)
+
+/**
+ * True when any object key, string value, or number of `value` (raw or percent-decoded) holds a
+ * secret. Numbers are checked as JavaScript prints them (`1.2345678e7` parses to `12345678`). Used
+ * by the wrapper's resolved mode (Todoist, Telegram), unchanged.
+ */
+export const jsonRepeatsSecret = (value: Schema.Json, secrets: ReadonlyArray<string>): boolean => {
+  if (Predicate.isString(value)) return repeatsSecret(value, secrets)
+
+  if (Predicate.isNumber(value)) return repeatsSecret(String(value), secrets)
+
+  if (Array.isArray(value)) return value.some(item => jsonRepeatsSecret(item, secrets))
+
+  if (isJsonRecord(value)) {
+    return Object.entries(value).some(
+      ([key, item]) => repeatsSecret(key, secrets) || jsonRepeatsSecret(item, secrets)
+    )
+  }
+
+  return false
+}
+
+/**
+ * The JSON-number alphabet. A fail-closed bearer must hold at least one character outside it
+ * (`isRecognisableBearerValue`), so no number's text can ever contain or equal it: numeric forms
+ * (`1.2345678e7`, any precision) need no normalisation.
+ */
+const jsonNumberAlphabet = /^[0-9.eE+-]+$/
+
+/**
+ * The RFC 6750 `b64token` syntax (`1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" ) *"="`),
+ * at least 8 characters: what every GitHub (`ghp_…`, `github_pat_…`, `gho_…`) and Google (`ya29.…`)
+ * token is made of. Why exactly this: it holds no escape introducer the closure's transforms
+ * recognise (`%`, `\`, nor `"`), so no escape can start inside a bearer; with `firstCharacter`,
+ * no escape starting to its left can complete with its first character either (see there).
+ */
+const b64token = /^[A-Za-z0-9\-._~+/]+=*$/
+
+/**
+ * The first character a fail-closed bearer may start with: `[G-Zg-z\-._~+/]` without the
+ * lower-case JSON escape letters `n`, `r`, `t`, `u`. Proof that no neighbour can then hide the
+ * bearer:
+ *
+ * 1. The bearer holds no escape introducer (a `b64token` has no `%`, `\`, or `"`), so no escape
+ *    the transforms recognise can start inside it.
+ * 2. An escape that starts to its left (a stray `%`, `%X`, `\`, `\u`, `\u0`, `\u00`, `\u006`, or
+ *    such an introducer produced by an earlier round, `%25` or `%5C` decoded) can only reach the
+ *    bearer by consuming its first character. That character completes no escape form: it is no
+ *    hex digit (so no `%X`, `%XX`, or `\uXXXX` prefix completes with it) and no short JSON escape
+ *    letter (`b` and `f` are hex; `n`, `r`, `t`, `u` are excluded). `/` is kept: `\/` decodes to
+ *    `/`, which leaves the character in place. When the first character is itself escaped, a stray
+ *    `\` can pair with the escape's leading `\`: the pair `\\` decodes to `\`, followed by the rest
+ *    of the escape, which decodes in a later step. That delays the decoding but never destroys it,
+ *    and the closure runs to a fixpoint, so delays do not matter.
+ * 3. So the bearer's characters always decode in place, and the closure finds the bearer once its
+ *    own encodings are undone.
+ *
+ * Upper-case `N`, `R`, `T`, `U` are allowed: the JSON escape letters are case-sensitive, and
+ * `tolerantJsonUnescape` recognises only the lower-case ones (`\N` stays as it is), so they
+ * complete no escape either.
+ */
+const firstCharacter = /^[G-Zg-mo-qsv-z\-._~+/]/
+
+/**
+ * True when a bearer value matches the RFC 6750 `b64token` syntax exactly (at least 8
+ * characters), starts with a character that completes no escape (`firstCharacter`), and holds a
+ * character outside the JSON-number alphabet `[0-9.eE+-]`, so it is never the text of a number
+ * and no escape can be shifted across its characters.
+ */
+export const isRecognisableBearerValue = (value: string): boolean =>
+  value.length >= 8 &&
+  b64token.test(value) &&
+  firstCharacter.test(value) &&
+  !jsonNumberAlphabet.test(value)
+
+/**
+ * The work caps of `textRepeatsSecret`. The closure runs to a fixpoint; these only bound the work
+ * of a pathological text, and hitting one counts as a credential repeat (uncertainty refuses, it
+ * never admits). Measured margins: every fixture converges in a few rounds and texts; a 64 KiB
+ * body of densely nested escapes converges in about 25 rounds, under 100 texts, and about 2.4 Mi
+ * characters read; a pathological 64 KiB body hits a cap in about 100 ms. The character cap is
+ * spent on reading too, so any part over 4 Mi characters is always refused, escapes or not (far
+ * above GitHub's 65 536-character body limit).
+ */
+export const secretClosureCaps = {
+  /** Rounds of the breadth-first walk. */
+  rounds: 64,
+  /** Distinct texts seen. */
+  texts: 1024,
+  /** Characters the transforms read, over all texts (keeps the worst large body near 100 ms). */
+  characters: 8 * 1024 * 1024
+} as const
+
+/**
+ * Tolerant percent-decode, total: every `%XX` whose value is below `0x80` becomes its ASCII
+ * character; every other `%` sequence (a stray `%`, `%E9`, `%zz`) is left as it is. It never
+ * throws, so an encoded fragment next to `100%` or `%E9` is still decoded.
+ */
+export const tolerantPercentDecode = (text: string): string =>
+  !text.includes('%')
+    ? text
+    : text.replace(/%([0-7][0-9A-Fa-f])/g, (_escape, hex: string) =>
+        String.fromCharCode(Number.parseInt(hex, 16))
+      )
+
+/** The short JSON escapes and the characters they stand for. */
+const jsonEscapes = new Map([
+  ['"', '"'],
+  ['\\', '\\'],
+  ['/', '/'],
+  ['b', '\b'],
+  ['f', '\f'],
+  ['n', '\n'],
+  ['r', '\r'],
+  ['t', '\t']
+])
+
+/**
+ * Tolerant JSON-unescape, total and lexical: within any text, whether or not it parses as JSON,
+ * `\uXXXX` below `\u0080` and `\"`, `\\`, `\/`, `\b`, `\f`, `\n`, `\r`, `\t` become their
+ * characters (one left-to-right pass); every other sequence is left as it is. Being lexical, it
+ * sees every string of a JSON text, duplicate keys and overwritten values included.
+ */
+export const tolerantJsonUnescape = (text: string): string =>
+  !text.includes('\\')
+    ? text
+    : text.replace(
+        /\\(?:u([0-9A-Fa-f]{4})|(["\\/bfnrt]))/g,
+        (escape, hex?: string, short?: string) => {
+          if (hex !== undefined) {
+            const code = Number.parseInt(hex, 16)
+
+            return code < 0x80 ? String.fromCharCode(code) : escape
+          }
+
+          return jsonEscapes.get(short ?? '') ?? escape
+        }
+      )
+
+/** What the closure of a text found: the secret, its fixpoint without the secret, or a cap. */
+export type SecretClosureOutcome = 'repeats' | 'clear' | 'capped'
+
+/** What the closure of a text found: a matching text, its fixpoint without one, or a cap. */
+export type TextClosureOutcome = 'matches' | 'clear' | 'capped'
+
+/**
+ * The closure of `text` against a predicate: starting from the raw text, a breadth-first walk
+ * applying either total transform (`tolerantPercentDecode`, `tolerantJsonUnescape`) to every text
+ * of the previous round, deduplicated, until no new text appears (a fixpoint); every text is
+ * tested with `matches`. Both transforms never lengthen a text and strictly shorten it when they
+ * change it, so every branch ends. `capped` when a cap of `secretClosureCaps` is hit first. No
+ * JSON is parsed and nothing can fail (unless `matches` throws).
+ */
+export const textClosureOutcome = (
+  text: string,
+  matches: (candidate: string) => boolean
+): TextClosureOutcome => {
+  const seen = new Set([text])
+  let characters = 0
+  let frontier: ReadonlyArray<string> = [text]
+
+  for (let round = 0; frontier.length > 0; round += 1) {
+    if (frontier.some(matches)) return 'matches'
+
+    if (round === secretClosureCaps.rounds) return 'capped'
+
+    const next: Array<string> = []
+
+    for (const candidate of frontier) {
+      // The work: every character each transform reads.
+      characters += 2 * candidate.length
+
+      if (characters > secretClosureCaps.characters) return 'capped'
+
+      for (const transformed of [
+        tolerantPercentDecode(candidate),
+        tolerantJsonUnescape(candidate)
+      ]) {
+        if (seen.has(transformed)) continue
+
+        if (seen.size >= secretClosureCaps.texts) return 'capped'
+
+        seen.add(transformed)
+        next.push(transformed)
+      }
+    }
+
+    frontier = next
+  }
+
+  return 'clear'
+}
+
+/**
+ * The closure of `text` against `secrets` (`textClosureOutcome`, every text checked for a secret
+ * as a substring). Numbers need no handling: a recognisable bearer never fits the JSON-number
+ * alphabet.
+ */
+export const secretClosureOutcome = (
+  text: string,
+  secrets: ReadonlyArray<string>
+): SecretClosureOutcome => {
+  const guarded = meaningful(secrets)
+
+  if (guarded.length === 0) return 'clear'
+
+  const outcome = textClosureOutcome(text, candidate =>
+    guarded.some(secret => candidate.includes(secret))
+  )
+
+  return outcome === 'matches' ? 'repeats' : outcome
+}
+
+/**
+ * True when `text` repeats a secret anywhere in its closure (`secretClosureOutcome`), or when the
+ * closure hits a work cap before its fixpoint: fail closed, uncertainty counts as a repeat.
+ */
+export const textRepeatsSecret = (text: string, secrets: ReadonlyArray<string>): boolean =>
+  secretClosureOutcome(text, secrets) !== 'clear'
+
+/**
+ * `text` with every secret (raw and percent-encoded) replaced by `<redacted>`; when a secret still
+ * shows after that (for example in another percent-encoding), the whole text is `<redacted>`.
+ * Applied to everything the ledger keeps or a refusal answers.
+ */
+export const scrubSecrets = (text: string, secrets: ReadonlyArray<string>): string => {
+  const variants = meaningful(secrets)
+    .flatMap(secret => [secret, encodeURIComponent(secret)])
+    .sort((left, right) => right.length - left.length)
+
+  let result = text
+
+  for (const variant of variants) result = result.replaceAll(variant, '<redacted>')
+
+  return repeatsSecret(result, secrets) ? '<redacted>' : result
+}

package/src/subscription-usage-recordings.ts

@@ -0,0 +1,77 @@
+/**
+ * Subscription-usage recordings the `/anthropic`, `/codex`, and `/xai` usage routes answer from.
+ *
+ * Copied as data from the committed (synthetic, unverified) conformance fixtures; never imported.
+ * `test/fixture-recordings.test.ts` fails when a fixture changes and this copy does not. Internal;
+ * not a package export.
+ */
+import type { FixtureRecording } from './fixture-route.ts'
+
+export const anthropicClaudeUsageRecording: FixtureRecording = {
+  fixtureId: 'anthropic.claude.usage.snapshot.synthetic',
+  caseId: 'anthropic.claude.usage.snapshot',
+  request: {
+    method: 'GET',
+    path: '/api/oauth/usage',
+    query: '',
+    headers: {
+      accept: 'application/json'
+    }
+  },
+  response: {
+    status: 200,
+    headers: {
+      'content-type': 'application/json'
+    },
+    streamed: false,
+    chunks: [
+      '{"five_hour":{"utilization":18,"resets_at":"2026-10-01T05:00:00.000Z"},"seven_day":{"utilization":42,"resets_at":"2026-10-06T00:00:00.000Z"}}'
+    ]
+  }
+}
+
+export const codexUsageRecording: FixtureRecording = {
+  fixtureId: 'openai.codex.usage.snapshot.synthetic',
+  caseId: 'openai.codex.usage.snapshot',
+  request: {
+    method: 'GET',
+    path: '/backend-api/wham/usage',
+    query: '',
+    headers: {
+      accept: 'application/json'
+    }
+  },
+  response: {
+    status: 200,
+    headers: {
+      'content-type': 'application/json'
+    },
+    streamed: false,
+    chunks: [
+      '{"rate_limit":{"primary_window":{"used_percent":23,"limit_window_seconds":18000,"reset_after_seconds":7200,"reset_at":1790007200},"secondary_window":{"used_percent":51,"limit_window_seconds":604800,"reset_after_seconds":259200,"reset_at":1790259200}}}'
+    ]
+  }
+}
+
+export const xAiGrokUsageRecording: FixtureRecording = {
+  fixtureId: 'xai.grok.usage.snapshot.synthetic',
+  caseId: 'xai.grok.usage.snapshot',
+  request: {
+    method: 'GET',
+    path: '/v1/billing',
+    query: '?format=credits',
+    headers: {
+      accept: 'application/json'
+    }
+  },
+  response: {
+    status: 200,
+    headers: {
+      'content-type': 'application/json'
+    },
+    streamed: false,
+    chunks: [
+      '{"config":{"creditUsagePercent":37.5,"currentPeriod":{"type":"monthly","start":"2026-09-01T00:00:00.000Z","end":"2026-10-01T00:00:00.000Z"}}}'
+    ]
+  }
+}

package/src/subscription-usage.ts

@@ -0,0 +1,68 @@
+/**
+ * Subscription-usage routes (internal; not a package export): one `GET` route per usage endpoint
+ * the SDK fetchers call (Claude, Codex, Grok, OpenCode Go), on the fixture-only core
+ * (`fixture-route.ts`). A request carrying the credential and headers the fetcher sends, on the
+ * recorded query, gets the recorded snapshot body; everything else answers 400 not-emulated. The
+ * body may be replaced (`subscriptionUsage` option, scripted `{ usage }` turn) only by a body with
+ * the recorded JSON shape.
+ *
+ * Usage routes live next to a model route on the same origin (`/anthropic`, `/codex`, `/xai`,
+ * `/opencode`), but keep their own manifest, ledger, faults, and turns, so the model route's
+ * manifest and coverage are unchanged; `emulator-compose.ts` dispatches to them.
+ */
+import type * as Schema from 'effect/Schema'
+import {
+  FixtureRouteFault,
+  makeFixtureRouteEmulator,
+  type FixtureRecording,
+  type FixtureRouteEmulator,
+  type FixtureRouteFaultKind,
+  type FixtureRouteHeaderRule,
+  type FixtureRouteLedgerEntry,
+  type FixtureRouteScriptedTurn
+} from './fixture-route.ts'
+import { parseJson } from './emulator-kernel.ts'
+import type { EmulatorRouteEvidence } from './route-evidence.ts'
+
+/** Usage-route faults: `status`, `error-after-chunks`, `truncate-after-chunks` (one-chunk body). */
+export const SubscriptionUsageFault = FixtureRouteFault
+
+export type SubscriptionUsageFault = FixtureRouteFault
+
+export type SubscriptionUsageFaultKind = FixtureRouteFaultKind
+
+/** A usage turn: `{ usage }` (a body with the recorded JSON shape) or `{ error }`. */
+export type SubscriptionUsageScriptedTurn = FixtureRouteScriptedTurn
+
+export type SubscriptionUsageLedgerEntry = FixtureRouteLedgerEntry
+
+export type SubscriptionUsageEmulator = FixtureRouteEmulator
+
+export type SubscriptionUsageEmulatorConfig = {
+  readonly path: string
+  readonly routes: ReadonlyArray<EmulatorRouteEvidence>
+  readonly recording: FixtureRecording
+  /** Headers the SDK fetcher sends besides `Authorization: Bearer` and `accept`, in order. */
+  readonly headers: ReadonlyArray<FixtureRouteHeaderRule>
+  /** Replacement default body; must have the recorded JSON shape. */
+  readonly subscriptionUsage: Schema.Json | undefined
+  readonly inputInvalid: (input: 'fault' | 'turn', reason: string) => Error
+}
+
+/** The recorded snapshot body of a usage recording, parsed. */
+export const recordedUsageBody = (recording: FixtureRecording): Schema.Json =>
+  parseJson(recording.response.chunks.join('')) ?? null
+
+export const makeSubscriptionUsageEmulator = (
+  config: SubscriptionUsageEmulatorConfig
+): SubscriptionUsageEmulator =>
+  makeFixtureRouteEmulator({
+    method: 'GET',
+    path: config.path,
+    routes: config.routes,
+    recordings: [config.recording],
+    credential: 'bearer',
+    headers: config.headers,
+    replaceableBody: { defaultBody: config.subscriptionUsage },
+    inputInvalid: config.inputInvalid
+  })