@yolk-sdk/emulators 0.1.0-canary.96

package/dist/stateful-secrets.mjs

@@ -0,0 +1,216 @@
+import { Predicate } from "effect";
+//#region src/stateful-secrets.ts
+/**
+* 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
+*/
+/** The ledgered path of every unrecognised request (constant: nothing from the request). */
+const unrecognisedLedgerPath = "/<unrecognised>";
+const ledgerableMethods = new Set([
+	"GET",
+	"HEAD",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE",
+	"OPTIONS"
+]);
+/** The ledgered method of an unrecognised request: a standard method, or `<other>`. */
+const unrecognisedMethod = (method) => ledgerableMethods.has(method) ? method : "<other>";
+/** `value` percent-decoded once, or unchanged when it is not valid percent-encoding. */
+const decodedOrRaw = (value) => {
+	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) => secrets.filter((secret) => secret.length >= minimumSecretLength);
+/** True when `text`, raw or percent-decoded, contains a secret. */
+const repeatsSecret = (text, secrets) => {
+	const decoded = decodedOrRaw(text.replaceAll("+", " "));
+	return meaningful(secrets).some((secret) => text.includes(secret) || decoded.includes(secret));
+};
+const isJsonRecord = (value) => 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.
+*/
+const jsonRepeatsSecret = (value, secrets) => {
+	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.
+*/
+const isRecognisableBearerValue = (value) => 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).
+*/
+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
+};
+/**
+* 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.
+*/
+const tolerantPercentDecode = (text) => !text.includes("%") ? text : text.replace(/%([0-7][0-9A-Fa-f])/g, (_escape, hex) => 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", "	"]
+]);
+/**
+* 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.
+*/
+const tolerantJsonUnescape = (text) => !text.includes("\\") ? text : text.replace(/\\(?:u([0-9A-Fa-f]{4})|(["\\/bfnrt]))/g, (escape, hex, short) => {
+	if (hex !== void 0) {
+		const code = Number.parseInt(hex, 16);
+		return code < 128 ? String.fromCharCode(code) : escape;
+	}
+	return jsonEscapes.get(short ?? "") ?? escape;
+});
+/**
+* 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).
+*/
+const textClosureOutcome = (text, matches) => {
+	const seen = new Set([text]);
+	let characters = 0;
+	let frontier = [text];
+	for (let round = 0; frontier.length > 0; round += 1) {
+		if (frontier.some(matches)) return "matches";
+		if (round === secretClosureCaps.rounds) return "capped";
+		const next = [];
+		for (const candidate of frontier) {
+			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.
+*/
+const secretClosureOutcome = (text, secrets) => {
+	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.
+*/
+const textRepeatsSecret = (text, secrets) => 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.
+*/
+const scrubSecrets = (text, secrets) => {
+	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;
+};
+//#endregion
+export { decodedOrRaw, isRecognisableBearerValue, jsonRepeatsSecret, repeatsSecret, scrubSecrets, secretClosureCaps, secretClosureOutcome, textClosureOutcome, textRepeatsSecret, tolerantJsonUnescape, tolerantPercentDecode, unrecognisedLedgerPath, unrecognisedMethod };
+
+//# sourceMappingURL=stateful-secrets.mjs.map

package/dist/stateful-secrets.mjs.map

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

package/dist/subscription-usage-recordings.d.mts

@@ -0,0 +1,9 @@
+import { FixtureRecording } from "./fixture-route.mjs";
+
+//#region src/subscription-usage-recordings.d.ts
+declare const anthropicClaudeUsageRecording: FixtureRecording;
+declare const codexUsageRecording: FixtureRecording;
+declare const xAiGrokUsageRecording: FixtureRecording;
+//#endregion
+export { anthropicClaudeUsageRecording, codexUsageRecording, xAiGrokUsageRecording };
+//# sourceMappingURL=subscription-usage-recordings.d.mts.map

package/dist/subscription-usage-recordings.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-usage-recordings.d.mts","names":[],"sources":["../src/subscription-usage-recordings.ts"],"mappings":";;;cASa,6BAAA,EAA+B,gBAqB3C;AAAA,cAEY,mBAAA,EAAqB,gBAqBjC;AAAA,cAEY,qBAAA,EAAuB,gBAqBnC"}

package/dist/subscription-usage-recordings.mjs

@@ -0,0 +1,53 @@
+//#region src/subscription-usage-recordings.ts
+const anthropicClaudeUsageRecording = {
+	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\"}}"]
+	}
+};
+const codexUsageRecording = {
+	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}}}"]
+	}
+};
+const xAiGrokUsageRecording = {
+	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\"}}}"]
+	}
+};
+//#endregion
+export { anthropicClaudeUsageRecording, codexUsageRecording, xAiGrokUsageRecording };
+
+//# sourceMappingURL=subscription-usage-recordings.mjs.map

package/dist/subscription-usage-recordings.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-usage-recordings.mjs","names":[],"sources":["../src/subscription-usage-recordings.ts"],"sourcesContent":["/**\n * Subscription-usage recordings the `/anthropic`, `/codex`, and `/xai` usage routes answer from.\n *\n * Copied as data from the committed (synthetic, unverified) conformance fixtures; never imported.\n * `test/fixture-recordings.test.ts` fails when a fixture changes and this copy does not. Internal;\n * not a package export.\n */\nimport type { FixtureRecording } from './fixture-route.ts'\n\nexport const anthropicClaudeUsageRecording: FixtureRecording = {\n  fixtureId: 'anthropic.claude.usage.snapshot.synthetic',\n  caseId: 'anthropic.claude.usage.snapshot',\n  request: {\n    method: 'GET',\n    path: '/api/oauth/usage',\n    query: '',\n    headers: {\n      accept: 'application/json'\n    }\n  },\n  response: {\n    status: 200,\n    headers: {\n      'content-type': 'application/json'\n    },\n    streamed: false,\n    chunks: [\n      '{\"five_hour\":{\"utilization\":18,\"resets_at\":\"2026-10-01T05:00:00.000Z\"},\"seven_day\":{\"utilization\":42,\"resets_at\":\"2026-10-06T00:00:00.000Z\"}}'\n    ]\n  }\n}\n\nexport const codexUsageRecording: FixtureRecording = {\n  fixtureId: 'openai.codex.usage.snapshot.synthetic',\n  caseId: 'openai.codex.usage.snapshot',\n  request: {\n    method: 'GET',\n    path: '/backend-api/wham/usage',\n    query: '',\n    headers: {\n      accept: 'application/json'\n    }\n  },\n  response: {\n    status: 200,\n    headers: {\n      'content-type': 'application/json'\n    },\n    streamed: false,\n    chunks: [\n      '{\"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}}}'\n    ]\n  }\n}\n\nexport const xAiGrokUsageRecording: FixtureRecording = {\n  fixtureId: 'xai.grok.usage.snapshot.synthetic',\n  caseId: 'xai.grok.usage.snapshot',\n  request: {\n    method: 'GET',\n    path: '/v1/billing',\n    query: '?format=credits',\n    headers: {\n      accept: 'application/json'\n    }\n  },\n  response: {\n    status: 200,\n    headers: {\n      'content-type': 'application/json'\n    },\n    streamed: false,\n    chunks: [\n      '{\"config\":{\"creditUsagePercent\":37.5,\"currentPeriod\":{\"type\":\"monthly\",\"start\":\"2026-09-01T00:00:00.000Z\",\"end\":\"2026-10-01T00:00:00.000Z\"}}}'\n    ]\n  }\n}\n"],"mappings":";AASA,MAAa,gCAAkD;CAC7D,WAAW;CACX,QAAQ;CACR,SAAS;EACP,QAAQ;EACR,MAAM;EACN,OAAO;EACP,SAAS,EACP,QAAQ,mBACV;CACF;CACA,UAAU;EACR,QAAQ;EACR,SAAS,EACP,gBAAgB,mBAClB;EACA,UAAU;EACV,QAAQ,CACN,+JACF;CACF;AACF;AAEA,MAAa,sBAAwC;CACnD,WAAW;CACX,QAAQ;CACR,SAAS;EACP,QAAQ;EACR,MAAM;EACN,OAAO;EACP,SAAS,EACP,QAAQ,mBACV;CACF;CACA,UAAU;EACR,QAAQ;EACR,SAAS,EACP,gBAAgB,mBAClB;EACA,UAAU;EACV,QAAQ,CACN,mRACF;CACF;AACF;AAEA,MAAa,wBAA0C;CACrD,WAAW;CACX,QAAQ;CACR,SAAS;EACP,QAAQ;EACR,MAAM;EACN,OAAO;EACP,SAAS,EACP,QAAQ,mBACV;CACF;CACA,UAAU;EACR,QAAQ;EACR,SAAS,EACP,gBAAgB,mBAClB;EACA,UAAU;EACV,QAAQ,CACN,iKACF;CACF;AACF"}

package/dist/subscription-usage.d.mts

@@ -0,0 +1,53 @@
+import { EmulatorRouteEvidence } from "./route-evidence.mjs";
+import { FixtureRecording, FixtureRouteEmulator, FixtureRouteFault, FixtureRouteFaultKind, FixtureRouteHeaderRule, FixtureRouteLedgerEntry, FixtureRouteScriptedTurn } from "./fixture-route.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/subscription-usage.d.ts
+/** Usage-route faults: `status`, `error-after-chunks`, `truncate-after-chunks` (one-chunk body). */
+declare const SubscriptionUsageFault: Schema.Union<readonly [Schema.Struct<{
+  readonly status: Schema.Int;
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"status">;
+  readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+  readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"error-after-chunks">;
+  readonly chunks: Schema.Int;
+}>, Schema.Struct<{
+  readonly match: Schema.optionalKey<Schema.Struct<{
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly model: Schema.optionalKey<Schema.String>;
+  }>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly kind: Schema.Literal<"truncate-after-chunks">;
+  readonly chunks: Schema.Int;
+}>]>;
+type SubscriptionUsageFault = FixtureRouteFault;
+type SubscriptionUsageFaultKind = FixtureRouteFaultKind;
+/** A usage turn: `{ usage }` (a body with the recorded JSON shape) or `{ error }`. */
+type SubscriptionUsageScriptedTurn = FixtureRouteScriptedTurn;
+type SubscriptionUsageLedgerEntry = FixtureRouteLedgerEntry;
+type SubscriptionUsageEmulator = FixtureRouteEmulator;
+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. */
+declare const recordedUsageBody: (recording: FixtureRecording) => Schema.Json;
+declare const makeSubscriptionUsageEmulator: (config: SubscriptionUsageEmulatorConfig) => SubscriptionUsageEmulator;
+//#endregion
+export { SubscriptionUsageEmulator, SubscriptionUsageEmulatorConfig, SubscriptionUsageFault, SubscriptionUsageFaultKind, SubscriptionUsageLedgerEntry, SubscriptionUsageScriptedTurn, makeSubscriptionUsageEmulator, recordedUsageBody };
+//# sourceMappingURL=subscription-usage.d.mts.map

package/dist/subscription-usage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-usage.d.mts","names":[],"sources":["../src/subscription-usage.ts"],"mappings":";;;;;;cA2Ba,sBAAA,EAAsB,MAAA,CAAA,KAAA,WAAA,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;KAEvB,sBAAA,GAAyB,iBAAiB;AAAA,KAE1C,0BAAA,GAA6B,qBAAqB;;KAGlD,6BAAA,GAAgC,wBAAwB;AAAA,KAExD,4BAAA,GAA+B,uBAAuB;AAAA,KAEtD,yBAAA,GAA4B,oBAAoB;AAAA,KAEhD,+BAAA;EAAA,SACD,IAAA;EAAA,SACA,MAAA,EAAQ,aAAA,CAAc,qBAAA;EAAA,SACtB,SAAA,EAAW,gBAAA,EAhBa;EAAA,SAkBxB,OAAA,EAAS,aAAA,CAAc,sBAAA,GAlBC;EAAA,SAoBxB,iBAAA,EAAmB,MAAA,CAAO,IAAA;EAAA,SAC1B,YAAA,GAAe,KAAA,oBAAyB,MAAA,aAAmB,KAAA;AAAA;;cAIzD,iBAAA,GAAqB,SAAA,EAAW,gBAAA,KAAmB,MAAA,CAAO,IAChB;AAAA,cAE1C,6BAAA,GACX,MAAA,EAAQ,+BAAA,KACP,yBAUC"}

package/dist/subscription-usage.mjs

@@ -0,0 +1,21 @@
+import { parseJson } from "./emulator-kernel.mjs";
+import { FixtureRouteFault, makeFixtureRouteEmulator } from "./fixture-route.mjs";
+//#region src/subscription-usage.ts
+/** Usage-route faults: `status`, `error-after-chunks`, `truncate-after-chunks` (one-chunk body). */
+const SubscriptionUsageFault = FixtureRouteFault;
+/** The recorded snapshot body of a usage recording, parsed. */
+const recordedUsageBody = (recording) => parseJson(recording.response.chunks.join("")) ?? null;
+const makeSubscriptionUsageEmulator = (config) => makeFixtureRouteEmulator({
+	method: "GET",
+	path: config.path,
+	routes: config.routes,
+	recordings: [config.recording],
+	credential: "bearer",
+	headers: config.headers,
+	replaceableBody: { defaultBody: config.subscriptionUsage },
+	inputInvalid: config.inputInvalid
+});
+//#endregion
+export { SubscriptionUsageFault, makeSubscriptionUsageEmulator, recordedUsageBody };
+
+//# sourceMappingURL=subscription-usage.mjs.map

package/dist/subscription-usage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-usage.mjs","names":[],"sources":["../src/subscription-usage.ts"],"sourcesContent":["/**\n * Subscription-usage routes (internal; not a package export): one `GET` route per usage endpoint\n * the SDK fetchers call (Claude, Codex, Grok, OpenCode Go), on the fixture-only core\n * (`fixture-route.ts`). A request carrying the credential and headers the fetcher sends, on the\n * recorded query, gets the recorded snapshot body; everything else answers 400 not-emulated. The\n * body may be replaced (`subscriptionUsage` option, scripted `{ usage }` turn) only by a body with\n * the recorded JSON shape.\n *\n * Usage routes live next to a model route on the same origin (`/anthropic`, `/codex`, `/xai`,\n * `/opencode`), but keep their own manifest, ledger, faults, and turns, so the model route's\n * manifest and coverage are unchanged; `emulator-compose.ts` dispatches to them.\n */\nimport type * as Schema from 'effect/Schema'\nimport {\n  FixtureRouteFault,\n  makeFixtureRouteEmulator,\n  type FixtureRecording,\n  type FixtureRouteEmulator,\n  type FixtureRouteFaultKind,\n  type FixtureRouteHeaderRule,\n  type FixtureRouteLedgerEntry,\n  type FixtureRouteScriptedTurn\n} from './fixture-route.ts'\nimport { parseJson } from './emulator-kernel.ts'\nimport type { EmulatorRouteEvidence } from './route-evidence.ts'\n\n/** Usage-route faults: `status`, `error-after-chunks`, `truncate-after-chunks` (one-chunk body). */\nexport const SubscriptionUsageFault = FixtureRouteFault\n\nexport type SubscriptionUsageFault = FixtureRouteFault\n\nexport type SubscriptionUsageFaultKind = FixtureRouteFaultKind\n\n/** A usage turn: `{ usage }` (a body with the recorded JSON shape) or `{ error }`. */\nexport type SubscriptionUsageScriptedTurn = FixtureRouteScriptedTurn\n\nexport type SubscriptionUsageLedgerEntry = FixtureRouteLedgerEntry\n\nexport type SubscriptionUsageEmulator = FixtureRouteEmulator\n\nexport type SubscriptionUsageEmulatorConfig = {\n  readonly path: string\n  readonly routes: ReadonlyArray<EmulatorRouteEvidence>\n  readonly recording: FixtureRecording\n  /** Headers the SDK fetcher sends besides `Authorization: Bearer` and `accept`, in order. */\n  readonly headers: ReadonlyArray<FixtureRouteHeaderRule>\n  /** Replacement default body; must have the recorded JSON shape. */\n  readonly subscriptionUsage: Schema.Json | undefined\n  readonly inputInvalid: (input: 'fault' | 'turn', reason: string) => Error\n}\n\n/** The recorded snapshot body of a usage recording, parsed. */\nexport const recordedUsageBody = (recording: FixtureRecording): Schema.Json =>\n  parseJson(recording.response.chunks.join('')) ?? null\n\nexport const makeSubscriptionUsageEmulator = (\n  config: SubscriptionUsageEmulatorConfig\n): SubscriptionUsageEmulator =>\n  makeFixtureRouteEmulator({\n    method: 'GET',\n    path: config.path,\n    routes: config.routes,\n    recordings: [config.recording],\n    credential: 'bearer',\n    headers: config.headers,\n    replaceableBody: { defaultBody: config.subscriptionUsage },\n    inputInvalid: config.inputInvalid\n  })\n"],"mappings":";;;;AA2BA,MAAa,yBAAyB;;AAyBtC,MAAa,qBAAqB,cAChC,UAAU,UAAU,SAAS,OAAO,KAAK,EAAE,CAAC,KAAK;AAEnD,MAAa,iCACX,WAEA,yBAAyB;CACvB,QAAQ;CACR,MAAM,OAAO;CACb,QAAQ,OAAO;CACf,YAAY,CAAC,OAAO,SAAS;CAC7B,YAAY;CACZ,SAAS,OAAO;CAChB,iBAAiB,EAAE,aAAa,OAAO,kBAAkB;CACzD,cAAc,OAAO;AACvB,CAAC"}

package/dist/telegram/api.d.mts

@@ -0,0 +1,34 @@
+import { StatefulResolution, StatefulRoute } from "../stateful-emulator.mjs";
+import { TelegramEmulatorState } from "./state.mjs";
+
+//#region src/telegram/api.d.ts
+/** Drill knobs (tests only): each makes the emulator disagree with one conformance claim. */
+type TelegramEmulatorDrills = {
+  /** `true`: `getChat` of a member chat answers 200 with `ok: false`. */readonly getChatOkFalse?: boolean; /** `true`: the `getChat` errors (absent chat, token naming no bot) answer 200, not 4xx. */
+  readonly errorsAs200?: boolean; /** `true`: `getFile` reports a `file_size` one byte larger than the file. */
+  readonly fileSizeOffByOne?: boolean; /** `true`: `sendMessage` answers 200 with `ok: false` (the message is still recorded as sent). */
+  readonly sendOkFalse?: boolean;
+};
+type TelegramApiEnv = {
+  /** Clock in epoch milliseconds (`date` of sent messages). */readonly now: () => number;
+  readonly drills: Required<TelegramEmulatorDrills>;
+};
+type TelegramApiRoute = {
+  readonly route: StatefulRoute<TelegramEmulatorState, TelegramApiEnv>;
+  readonly queryKeys: ReadonlyArray<string>; /** The token-free path the request must not repeat the token in (the method, or `/file`). */
+  readonly guardedPath: string;
+};
+/** The route table: evidence plus handler. `telegramEmulatorRoutes` is its evidence part. */
+declare const telegramApiRoutes: ReadonlyArray<TelegramApiRoute>;
+/**
+ * Resolve one Bot API request, failing closed. Only a request whose raw path is exactly an
+ * emulated route shape (`/bot<token>/<method>` or `/file/bot<token>/<file_path>`, the strict token
+ * on the raw segment, an emulated method, and no other path text) under that route's HTTP method
+ * is recognised; the token is extracted from that exact segment, never searched for elsewhere.
+ * Every other request is `unrecognised`: the wrapper ledgers and answers it with constant text
+ * only, so nothing it carries can leak.
+ */
+declare const resolveTelegramRequest: (request: Request, url: URL) => StatefulResolution<TelegramEmulatorState, TelegramApiEnv>;
+//#endregion
+export { TelegramApiEnv, TelegramEmulatorDrills, resolveTelegramRequest, telegramApiRoutes };
+//# sourceMappingURL=api.d.mts.map

package/dist/telegram/api.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.mts","names":[],"sources":["../../src/telegram/api.ts"],"mappings":";;;;;KAmCY,sBAAA;EAAA,gFAED,cAAA;WAEA,WAAA,YAFA;EAAA,SAIA,gBAAA;EAAA,SAEA,WAAA;AAAA;AAAA,KAGC,cAAA;EAAA,sEAED,GAAA;EAAA,SACA,MAAA,EAAQ,QAAQ,CAAC,sBAAA;AAAA;AAAA,KA2BvB,gBAAA;EAAA,SACM,KAAA,EAAO,aAAA,CAAc,qBAAA,EAAuB,cAAA;EAAA,SAC5C,SAAA,EAAW,aAAA,UA7BM;EAAA,SA+BjB,WAAA;AAAA;AA9BV;AAAA,cA8QY,iBAAA,EAAmB,aAAa,CAAC,gBAAA;;;;;;;;;cAuCjC,sBAAA,GACX,OAAA,EAAS,OAAA,EACT,GAAA,EAAK,GAAA,KACJ,kBAAA,CAAmB,qBAAA,EAAuB,cAAA"}