@ultimat3/core 4.0.0 → 4.1.0

package/CLAUDE.md

@@ -8,6 +8,7 @@ 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` |
+| Rendering the 3-line format | `singleLine()` on every interpolated field. A `string` renders fine and can still carry a newline, which writes a line an operator reads as a genuine message |
 | 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 |
 | New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
@@ -32,6 +33,23 @@ parameters typed `unknown` that reach a `cause:` / `fix:`, and it cannot see a v
 through a local helper first (`packages/ui/src/components/ErrorState.tsx` builds a `message`
 const, then assigns it).
 
+`singleLine` is the escape that keeps the 3-line contract to three lines, and it exists because
+`scripts/error-render.ts` **cannot see this class**. That gate refuses a parameter typed
+`unknown`/`any` reaching a `cause:`; a value that is already a `string` renders without throwing, so
+there is nothing for it to object to — while a newline in one adds a line to a format that is
+line-oriented in the terminal, in CI logs and inside the dev overlay's `<pre>`. Three holes shipped
+in `@ultimat3/auth` under a green check, the worst reachable by an unauthenticated stranger with one
+crafted OIDC token (issue #97). It is applied at the SIX renderers of that format and never at the
+call sites — `UltimateError.format()` here, `SchemaError.format()` in `@ultimat3/schema`,
+`renderErrorLines` in `@ultimat3/http`, `renderFrameworkError` in `@ultimat3/mcp`, and
+`renderFinding` / `detailLines` in `@ultimat3/cli` — because a rule every author must remember is a
+rule the next author forgets. It is not a general sanitiser: a cause is prose and keeps its quotes,
+its backslashes and its percent signs — only the control range is touched. Line breaks are the
+structural half; the rest of C0 and DEL ride along because a terminal reads a raw `\u001b` as an ANSI
+escape, so a cause could repaint the screen or hide the line above it. `@ultimat3/schema` carries a
+deliberate duplicate for the tier-0 reason below, pinned behaviourally by
+`single-line-pin.test.ts` in `@ultimat3/cli`.
+
 `describeValue` in `error-render.ts` is a character-for-character duplicate of `describeValue` in
 `packages/schema/src/describe-value.ts`, for the same tier-0 reason `SCHEMA_ERROR_CODE_TITLES` is
 one: schema and core are both tier 0 and `core → schema` is **not** a declared edge in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/core",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",

package/src/error-render.ts

@@ -64,6 +64,53 @@ export function renderCauseValue(value: unknown): string {
   }
 }
 
+/**
+ * One line, always. Escapes every character that a line-oriented reader would treat as a line
+ * break, leaving everything else byte-identical.
+ *
+ * WHY this exists at all: `renderCauseValue` above is safe against a value that THROWS while
+ * rendering, and safe against a value that LEAKS. It is not safe against a value that is already
+ * a `string` — a `string` renders fine, so nothing objected to it — and a caller-controlled
+ * string can carry a newline. The 3-line contract format (`<code>` / `  cause: …` / `  fix:   …`)
+ * is line-oriented in the terminal, in CI logs and inside the dev overlay's `<pre>`, so one
+ * newline in a `cause` writes a second line an operator reads as a genuine framework message.
+ * Reproduced with a forged OIDC `iss` claim: an unauthenticated stranger with one crafted token.
+ *
+ * At the RENDERER, not at the call site, deliberately. `bun run error-render` cannot see this
+ * class — its rule is about `unknown` reaching a `cause:` — and three holes shipped in
+ * `@ultimat3/auth` alone under a green check. A rule every call site must remember is a rule the
+ * 296th call site forgets; there are six renderers of this format and no more, so escaping there
+ * is one place instead of every place (issue #97, option 3).
+ *
+ * `\u2028` and `\u2029` are included because they terminate a line for a JavaScript parser and
+ * for several log viewers, while `String.prototype.split('\n')` never sees them.
+ *
+ * The set is every C0 control, DEL, and `\u2028`/`\u2029`. Line breaks are the structural half —
+ * they add a line to a line-oriented format — and the rest ride along because a terminal reads them
+ * as commands of its own: a raw `\u001b` in a cause is an ANSI escape, so a value could repaint the
+ * screen, hide the line above it or move the cursor over what a reader had already been shown.
+ *
+ * NOT a general sanitiser. A `cause` is prose and keeps its quotes, its backslashes, its percent
+ * signs and every printable character it arrived with; only the control range is touched.
+ */
+export function singleLine(text: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: escaping them is the point.
+  return text.replace(/[\u0000-\u001f\u007f\u2028\u2029]/g, (char) => {
+    const known = CONTROL_ESCAPES[char];
+    if (known !== undefined) return known;
+    return `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`;
+  });
+}
+
+/** The spellings a reader already knows from a JSON string, so the escape reads as an escape. */
+const CONTROL_ESCAPES: Readonly<Record<string, string>> = {
+  '\n': String.raw`\n`,
+  '\r': String.raw`\r`,
+  '\t': String.raw`\t`,
+  '\b': String.raw`\b`,
+  '\f': String.raw`\f`,
+};
+
 /**
  * `value instanceof Error`, made total. The test itself can throw: a `Proxy`'s `getPrototypeOf`
  * trap runs during `instanceof`, and the one place this question is asked is a `catch` block that

package/src/errors.ts

@@ -3,7 +3,13 @@
 // overlay and `--json`. Never throw a bare Error anywhere in the framework.
 
 import { describeErrorCode } from './error-codes';
-import { isThrownError, renderCauseValue, renderMetaRecord, renderThrowable } from './error-render';
+import {
+  isThrownError,
+  renderCauseValue,
+  renderMetaRecord,
+  renderThrowable,
+  singleLine,
+} from './error-render';
 import { DEFAULT_ERROR_RETRY, type ErrorRetry, isErrorRetry, retryFor } from './error-retry';
 
 /**
@@ -89,8 +95,14 @@ export class UltimateError extends Error {
    * ```
    */
   format(options?: FormatErrorOptions): string {
-    const lines = [`${this.code}: ${this.title}`, `  cause: ${this.cause}`, `  fix:   ${this.fix}`];
-    if (options?.docs === true) lines.push(`  docs:  ${this.docs}`);
+    // `singleLine`, because this format is line-oriented and `cause` may hold a caller's string:
+    // one newline in it writes a second line an operator reads as a genuine framework message.
+    const lines = [
+      `${singleLine(this.code)}: ${singleLine(this.title)}`,
+      `  cause: ${singleLine(this.cause)}`,
+      `  fix:   ${singleLine(this.fix)}`,
+    ];
+    if (options?.docs === true) lines.push(`  docs:  ${singleLine(this.docs)}`);
     return lines.join('\n');
   }
 

package/src/exports/error-contract.ts

@@ -27,6 +27,7 @@ export {
   renderCauseValue,
   renderFixLiteral,
   renderThrowable,
+  singleLine,
   stringField,
 } from '../error-render';
 export type { ErrorRetry } from '../error-retry';

package/src/index.ts

@@ -159,6 +159,7 @@ export {
   resetErrorRetry,
   retryFor,
   SCHEMA_ERROR_CODE_TITLES,
+  singleLine,
   stringField,
   toUltimateError,
   ULTIMATE_ERROR_BRAND,