@ultimat3/core 23.0.0 → 24.0.0

package/src/cookie.ts

@@ -0,0 +1,35 @@
+// The one `Cookie:` request-header reader. At tier 0 because three packages need it — auth and http
+// at tier 2 cannot import each other, i18n sits below both — and each copy had to rediscover the
+// same thrown `URIError` on its own (`bun run flight-copies` refuses a fourth).
+
+/**
+ * A `Cookie:` header is attacker-controlled, and `decodeURIComponent('%')` throws a bare
+ * `URIError` — which escapes every coded path that reads through here: an OAuth callback would
+ * answer 500 instead of `X_OAUTH_STATE_INVALID`, and `curl -H 'Cookie: x-locale=%'` paged the
+ * on-call from the `locale` stage. The raw value is returned instead, so the caller's own
+ * rejection stays the readable failure; a raw value is still checked against a signature, a stored
+ * hash or a `supported` list, and none of them match a mangled one.
+ */
+const decodeCookieValue = (raw: string): string => {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+};
+
+/**
+ * The value of cookie `name` in a `Cookie:` header, or `null` when the header or the cookie is
+ * absent. Never throws: the header is client-authored, so an unreadable value is the raw value and
+ * a header that is not a string at all is no cookie.
+ */
+export function readCookie(header: string | null | undefined, name: string): string | null {
+  if (typeof header !== 'string') return null;
+  for (const part of header.split(';')) {
+    const equals = part.indexOf('=');
+    if (equals === -1) continue;
+    if (part.slice(0, equals).trim() !== name) continue;
+    return decodeCookieValue(part.slice(equals + 1).trim());
+  }
+  return null;
+}

package/src/cursor.ts

@@ -49,7 +49,10 @@ let configured: string | undefined;
  * warned and nothing failed.
  */
 function currentSecret(): string {
-  return configured ?? Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
+  // `||`, never `??`: `ULTIMATE_CURSOR_SECRET=` (a blank compose or chart value) is the EMPTY
+  // string, which `??` keeps — an HMAC keyed by '' that anyone can forge, while
+  // `usesDevCursorSecret()` answered `false` and the boot check passed. Empty is unset.
+  return configured || Bun.env['ULTIMATE_CURSOR_SECRET'] || DEV_SECRET;
 }
 
 /**

package/src/decimal-order.ts

@@ -10,10 +10,11 @@
  * and a keyset page boundary was cut where the database never cuts one.
  *
  * It answers `undefined` rather than guessing, and that is the whole of its contract: a caller
- * that knows the column's declared kind (`@ultimat3/entity`'s `compareByKind`) asks; a caller that
- * does NOT know it — `@ultimat3/query`, whose `OrderKey` is a name and a direction — must not,
- * because Postgres orders a `text` column holding `"10"` and `"9"` lexically and a comparator
- * guessing "both sides look like decimals" would disagree with the SQL it printed.
+ * that knows the column's declared kind asks — `@ultimat3/entity`'s `numericOrder`, behind
+ * `compareByKind`, which `@ultimat3/query` calls with the kind it resolves from the entity — and a
+ * caller with NO kind in hand must not, because Postgres orders a `text` column holding `"10"` and
+ * `"9"` lexically and a comparator guessing "both sides look like decimals" would disagree with
+ * the SQL it printed.
  */
 
 /** A decimal, split so two of them can be compared exactly however long the digits run. */

package/src/dev-secrets.ts

@@ -19,7 +19,7 @@ export class CursorSecretDevError extends UltimateError {
     super({
       code: CursorSecretDevError.code,
       cause:
-        'ULTIMATE_CURSOR_SECRET is unset, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
+        'ULTIMATE_CURSOR_SECRET is unset or empty, so this process signs cursors with the development key the framework ships — anyone can forge a page position',
       fix: "x secrets set ULTIMATE_CURSOR_SECRET — or export ULTIMATE_CURSOR_SECRET from the platform's secret store",
       meta: { variable: 'ULTIMATE_CURSOR_SECRET' },
     });

package/src/error-reporter-sentry.ts

@@ -7,7 +7,7 @@ import { renderThrowable } from './error-render';
 import type { ErrorReport, ErrorReporter, ErrorSeverity } from './error-reporter';
 import { type CodedErrorInit, UltimateError } from './errors';
 import { traceId } from './ids';
-import { logger } from './logger';
+import { logger, redactFields } from './logger';
 
 export class ErrorReporterDsnInvalidError extends UltimateError {
   static readonly code = 'X_ERROR_REPORTER_DSN_INVALID';
@@ -108,6 +108,10 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
           },
         }),
     extra: {
+      // The caller's two records go through `redactFields`, and FIRST. Spread raw and last, a
+      // `bigint` or a cycle in `meta` made `JSON.stringify` throw — that error was never reported
+      // — `meta: { fix, stack }` replaced the framework's own, and `meta.password` left the box.
+      ...redactFields(report.scope.extra ?? {}),
       // The whole point of reporting the framework's contract instead of a message: whoever is
       // paged reads the runnable fix next to the failure.
       fix: report.fix,
@@ -115,8 +119,8 @@ function payloadOf(report: ErrorReport, eventId: string): Record<string, unknown
       ...(report.scope.requestId === undefined ? {} : { requestId: report.scope.requestId }),
       ...(report.scope.actorId === undefined ? {} : { actorId: report.scope.actorId }),
       ...(report.stack === undefined ? {} : { stack: report.stack }),
-      ...(report.meta ?? {}),
-      ...(report.scope.extra ?? {}),
+      // Under its own key, so no name an error author picks can collide with one above.
+      ...(report.meta === undefined ? {} : { meta: redactFields(report.meta) }),
     },
     exception: { values: [{ type: report.code, value: `${report.title} — ${report.cause}` }] },
   };

package/src/flight-gate.ts

@@ -8,6 +8,7 @@
 // memory fault and answers it minutes late.
 
 import { UltimateError } from './errors';
+import { finiteCount } from './finite-option';
 
 export interface FlightGateLimits {
   /** Work running at once. */
@@ -53,23 +54,34 @@ export function createFlightGate(
   options?: FlightGateOptions,
 ): FlightGate {
   const subject = options?.subject ?? 'in-flight work';
+  // Refused at CONSTRUCTION, because this pair wedges rather than fails: `active < NaN` and
+  // `waiters.length >= NaN` are both false, so every caller parks in a queue with no bound. Zero
+  // is a real value at both — "never wait" and, at the width, "refuse everything".
+  const maxConcurrent = finiteCount(
+    `createFlightGate (${subject})`,
+    'maxConcurrent',
+    limits.maxConcurrent,
+  );
+  const maxQueued = finiteCount(`createFlightGate (${subject})`, 'maxQueued', limits.maxQueued);
   const waiters: Array<() => void> = [];
   let active = 0;
 
   const state = (): FlightGateState => ({
-    maxConcurrent: limits.maxConcurrent,
-    maxQueued: limits.maxQueued,
+    maxConcurrent,
+    maxQueued,
     active,
     queued: waiters.length,
     subject,
   });
 
   const acquire = async (): Promise<void> => {
-    if (active < limits.maxConcurrent) {
+    if (active < maxConcurrent) {
       active += 1;
       return;
     }
-    if (waiters.length >= limits.maxQueued) {
+    // A width of zero has no slot to hand over, so a waiter would never be resumed: the queue is
+    // for work that WILL run, and here none will.
+    if (maxConcurrent === 0 || waiters.length >= maxQueued) {
       const current = state();
       throw options?.overflow?.(current) ?? gateOverloaded(current);
     }

package/src/fnv1a.ts

@@ -0,0 +1,19 @@
+// 32-bit FNV-1a: a BUCKET, never a key. Rollout buckets and factory seeds need a hash every process
+// computes identically and synchronously; anything that decides who shares what is `fingerprint`
+// (`canonical-json.ts`), because 2^32 values collide offline in seconds.
+
+const FNV_OFFSET_BASIS = 0x811c_9dc5;
+const FNV_PRIME = 0x0100_0193;
+
+/**
+ * The published 32-bit FNV-1a over UTF-16 code units, unsigned. Pure and dependency-free, which is
+ * the property its two callers need: two nodes place one subject in one bucket without talking.
+ */
+export function fnv1a(text: string): number {
+  let hash = FNV_OFFSET_BASIS;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, FNV_PRIME);
+  }
+  return hash >>> 0;
+}

package/src/health-disclosure.ts

@@ -0,0 +1,43 @@
+// What `/healthz` and `/readyz` say, and to whom — ONE rule for every role's listener. Both answer
+// outside every pipeline, so the body is a stranger's to read: everyone gets the verdict, and the
+// build id, the in-flight count and the readiness check names go only to a listed peer.
+
+import { classifyAddress } from './address-class';
+import type { HealthReport } from './lifecycle';
+import type { Role } from './roles';
+
+/** The box itself: `kubectl exec`, a port-forward, a compose healthcheck, a sidecar scraper. */
+export const DEFAULT_HEALTH_DETAIL_PEERS: readonly string[] = ['loopback'];
+
+/** The verdict a stranger gets. An allow-list, so a field `HealthReport` gains is withheld by default. */
+export interface PublicHealthBody {
+  readonly state: HealthReport['state'];
+  readonly ready: boolean;
+  readonly role: Role;
+}
+
+/** The body for one caller: the whole report for a listed peer, the verdict for anyone else. */
+export function healthBody(
+  report: HealthReport,
+  role: Role,
+  detailed: boolean,
+): PublicHealthBody | (HealthReport & { readonly role: Role }) {
+  return detailed ? { ...report, role } : { state: report.state, ready: report.ready, role };
+}
+
+/**
+ * Whether `address` is one the list names: an entry is an address CLASS (`loopback`, `private`, …)
+ * or one exact IP literal. Pure, and total — it runs on an unauthenticated probe path, so a list
+ * that is not a list, an entry that is not a string and an address that is not a literal all
+ * answer `false` rather than throw: nothing can vouch for them, whatever the list says.
+ */
+export function healthPeerListed(peers: readonly string[], address: string | null): boolean {
+  if (address === null || !Array.isArray(peers)) return false;
+  const kind = classifyAddress(address);
+  if (kind === undefined) return false;
+  const literal = address.trim().toLowerCase();
+  return peers.some(
+    (entry: unknown) =>
+      typeof entry === 'string' && (entry === kind || entry.trim().toLowerCase() === literal),
+  );
+}

package/src/host-rules.ts

@@ -4,6 +4,8 @@
 // read. In core because two tier-5 packages drive a browser (`scraping`, and `cli`'s `x shot`) and
 // neither may import the other; two copies of this rule would be two answers to "may it leave".
 
+import { classifyAddress } from './address-class';
+
 export type HostRule = string;
 
 /** The one spelling that means "every host", written out so it is visible in review. */
@@ -51,6 +53,31 @@ export function hostMatches(host: string, rule: HostRule): boolean {
   return normalised === cleaned;
 }
 
+/** A rule that names a CLASS of hosts rather than one — the two spellings `hostMatches` widens. */
+const isWildcard = (rule: HostRule): boolean => {
+  const cleaned = rule.trim();
+  return cleaned === ANY_HOST || cleaned.startsWith('*.');
+};
+
+/**
+ * The address-class FLOOR. A wildcard means "any site", and an address literal inside the network
+ * — loopback, RFC 1918, link-local, the metadata endpoint — is not a site: it is the request this
+ * module's header names. So a wildcard never admits one, and the opt-out is NAMING it: an exact
+ * rule (`'127.0.0.1'`, `'[::1]'`) is a line a reviewer can see, which `'*'` is not.
+ *
+ * What this cannot do is see through a NAME. `allowHosts: ['*']` still admits a hostname that
+ * resolves inward, because this function is synchronous and has no resolver — pinning the
+ * resolved address belongs to the driver that opens the connection, as `@ultimat3/jobs`'
+ * `webhook-target.ts` does for a webhook. The URL parser has already folded the numeric
+ * spellings (`2130706433`, `0x7f.1`) to dotted form, so they are classified as what they are.
+ */
+function admits(host: string, rule: HostRule): boolean {
+  if (!hostMatches(host, rule)) return false;
+  if (!isWildcard(rule)) return true;
+  const kind = classifyAddress(host);
+  return kind === undefined || kind === 'public';
+}
+
 /**
  * Fails CLOSED: a URL that cannot be parsed is refused. A driver handed a malformed request has
  * no way to know where it would have gone, and "we could not tell, so we let it through" is the
@@ -67,5 +94,5 @@ export function hostDecision(url: string, allowHosts: readonly HostRule[]): Host
     return { allowed: false, host: '' };
   }
   if (host === '') return { allowed: false, host };
-  return { allowed: allowHosts.some((rule) => hostMatches(host, rule)), host };
+  return { allowed: allowHosts.some((rule) => admits(host, rule)), host };
 }

package/src/html-escape.ts

@@ -0,0 +1,24 @@
+// The one HTML character table: how an untrusted value becomes inert text or attribute content.
+// At tier 0 because every package that writes markup — http, mail, render, seo, the dashboards —
+// can reach it, and a second table is one character away from a hole (`bun run flight-copies`).
+
+/** A `Map`, so a lookup never reaches `Object.prototype` (`bun run proto-index`). */
+const HTML_ESCAPES: ReadonlyMap<string, string> = new Map([
+  ['&', '&amp;'],
+  ['<', '&lt;'],
+  ['>', '&gt;'],
+  ['"', '&quot;'],
+  ["'", '&#39;'],
+]);
+
+const HTML_SPECIAL = /[&<>"']/g;
+
+/**
+ * Text content AND attribute values, in any quoting — one set for both, deliberately. A text-only
+ * subset is correct exactly until someone uses it for an attribute, and a no-`'` set until someone
+ * writes a single-quoted one. `&#39;` rather than `&apos;`: it is a numeric reference, so it means
+ * the same thing in HTML 4, HTML 5 and XML. One pass, so `&` is never escaped twice.
+ */
+export function escapeHtml(value: string): string {
+  return value.replace(HTML_SPECIAL, (char) => HTML_ESCAPES.get(char) ?? char);
+}

package/src/image/errors.ts

@@ -55,7 +55,9 @@ export const imageTooLarge = (
 ): ImageTooLargeError =>
   new ImageTooLargeError(
     cause,
-    'downscale the source before it reaches the pipeline, or raise MAX_IMAGE_PIXELS deliberately',
+    // No "or lift the ceiling": `MAX_IMAGE_PIXELS` is a constant, so a fix naming it as a knob
+    // sent a reader looking for a setting that does not exist.
+    'downscale the source below the 64-megapixel ceiling before it reaches the pipeline, or route it through an ImageTransformDriver (a CDN or an external encoder) — MAX_IMAGE_PIXELS is fixed, not a setting',
     meta,
   );
 

package/src/image/png-pixels.ts

@@ -3,6 +3,14 @@
 // safe zone `@ultimat3/pwa` promises is a composite. So this file exists for exactly that one hop:
 // Bun re-encodes to PNG, this reads the pixels back, `canvas.ts` blits, this writes them again.
 
+// why: `Bun.inflateSync` takes no output bound — measured, it ignores `maxOutputLength` and
+// returns the whole stream — and `DecompressionStream` is async where this seam is synchronous.
+// `node:zlib` is the one inflate here that can be told when to stop. A NAMESPACE import, never a
+// named one: the browser polyfill of this module has no `inflateRawSync`, and a named import of a
+// missing export fails the BUNDLE of every browser graph that reaches the barrel
+// (`async-context.test.ts` builds one) — for a function no browser ever calls.
+import * as zlib from 'node:zlib';
+import { stringField } from '../error-render';
 import { imageDecodeFailed, imageUnsupported } from './errors';
 import {
   adler32,
@@ -14,7 +22,7 @@ import {
   unshared,
   writeU32,
 } from './png-bytes';
-import { type Raster, rasterFrom } from './raster';
+import { assertPixelBudget, type Raster, rasterFrom } from './raster';
 
 /** Truecolour with alpha, 8 bits per channel — the ONE shape `Raster` is. */
 const RGBA_COLOR_TYPE = 8 << 4;
@@ -105,8 +113,13 @@ function readHeader(bytes: Uint8Array): PngHeader {
   return { width: readU32(bytes, 16), height: readU32(bytes, 20) };
 }
 
-/** Every IDAT concatenated: a PNG may split its stream across any number of them. */
-function idatStream(bytes: Uint8Array): Uint8Array {
+/**
+ * Every IDAT concatenated — a PNG may split its stream across any number of them — and inflated
+ * to AT MOST `limit` bytes, which is what the header says the pixels need. Inflating first and
+ * measuring after is the decompression bomb: deflate packs zeros ~1000:1, so a file of a few
+ * hundred kilobytes declaring 1x1 allocated hundreds of megabytes before anything compared it to 5.
+ */
+function idatStream(bytes: Uint8Array, limit: number): Uint8Array {
   const parts: Uint8Array[] = [];
   let at = 8;
   while (at + 12 <= bytes.length) {
@@ -123,8 +136,16 @@ function idatStream(bytes: Uint8Array): Uint8Array {
   try {
     // The 2-byte zlib header and the 4-byte Adler-32 trailer are PNG's envelope, stripped here
     // so the payload inflates as RAW deflate — see the encoder above for the mirror image.
-    return Bun.inflateSync(unshared(stream.subarray(2, stream.length - 4)), { windowBits: -15 });
-  } catch {
+    return zlib.inflateRawSync(unshared(stream.subarray(2, stream.length - 4)), {
+      maxOutputLength: limit,
+    });
+  } catch (error) {
+    if (stringField(error, 'code') === 'ERR_BUFFER_TOO_LARGE') {
+      throw imageDecodeFailed(
+        `the PNG IDAT stream inflates to more than the ${limit} bytes its header's size needs`,
+        { length: stream.length, limit },
+      );
+    }
     throw imageDecodeFailed(`the PNG IDAT stream (${stream.length} bytes) could not be inflated`, {
       length: stream.length,
     });
@@ -171,8 +192,10 @@ function unfilter(raw: Uint8Array, width: number, height: number): Uint8ClampedA
 /** PNG bytes to RGBA pixels. Refuses anything but 8-bit RGBA, naming the pipeline that reads it. */
 export function decodeImage(bytes: Uint8Array): Raster {
   const { width, height } = readHeader(bytes);
-  const raw = idatStream(bytes);
+  // From the HEADER, before the stream is touched: it bounds `expected`, which bounds the inflate.
+  assertPixelBudget(width, height, 'PNG');
   const expected = (width * BYTES_PER_PIXEL + 1) * height;
+  const raw = idatStream(bytes, expected);
   if (raw.length !== expected) {
     throw imageDecodeFailed(
       `the PNG inflates to ${raw.length} bytes but ${width}x${height} RGBA needs ${expected}`,

package/src/image/probe.ts

@@ -66,8 +66,13 @@ function requireBytes(bytes: Uint8Array, needed: number, format: string, missing
 
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const;
 
-/** `mif1` is the generic HEIF brand AVIF files carry; `avis` is an image sequence. */
-const AVIF_BRANDS: ReadonlySet<string> = new Set(['avif', 'avis', 'mif1']);
+/**
+ * `avif` is a still, `avis` an image sequence. NOT `mif1`: that is the generic HEIF brand, which
+ * an AVIF file lists as a COMPATIBLE brand and a HEIC file lists too — counting it sniffed every
+ * iPhone photo as AVIF, and the probe then read (or failed to read) it as one. An AVIF whose major
+ * brand is `mif1` still names `avif` among its compatible brands, which the scan below reads.
+ */
+const AVIF_BRANDS: ReadonlySet<string> = new Set(['avif', 'avis']);
 
 function isAvif(bytes: Uint8Array): boolean {
   if (!ascii(bytes, 4, 'ftyp')) return false;

package/src/image/raster.ts

@@ -25,7 +25,9 @@ export const MAX_IMAGE_PIXELS = 64_000_000;
 /** Checked from the header before a single byte is allocated. */
 export function assertPixelBudget(width: number, height: number, source: string): void {
   if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
-    throw imageTooLarge(`${source} declares a ${width}x${height} image, which is not a size`, {
+    // Decode-failed, not too-large: a header declaring zero, a fraction or `NaN` pixels is
+    // inconsistent bytes, and the too-large fix — downscale it — has nothing to act on.
+    throw imageDecodeFailed(`${source} declares a ${width}x${height} image, which is not a size`, {
       width,
       height,
       source,

package/src/index.ts

@@ -165,6 +165,8 @@ export {
   useService,
   withChildContext,
 } from './context';
+/** The one `Cookie:` reader — auth, http and i18n each parsed the header and could not share it. */
+export { readCookie } from './cookie';
 export type { CursorPayload } from './cursor';
 export {
   CursorInvalidError,
@@ -465,11 +467,15 @@ export type {
   FlightGateState,
 } from './flight-gate';
 export { createFlightGate, gateOverloaded } from './flight-gate';
+export { fnv1a } from './fnv1a';
 export { formatBytes } from './format-bytes';
 export type { GenerationFence } from './generation-fence';
 export { createFence, isSuperseded } from './generation-fence';
+export type { PublicHealthBody } from './health-disclosure';
+export { DEFAULT_HEALTH_DETAIL_PEERS, healthBody, healthPeerListed } from './health-disclosure';
 export type { HostDecision, HostRule } from './host-rules';
 export { ANY_HOST, hostDecision, hostMatches } from './host-rules';
+export { escapeHtml } from './html-escape';
 export type { Brand, Id } from './ids';
 export {
   isSpanId,
@@ -614,8 +620,11 @@ export {
   CLIENT_SYNC_META,
   CLIENT_SYNC_WORKER_META,
 } from './page-meta';
+/** The structural Postgres seam http, auth, action and jobs share without a `@ultimat3/db` edge. */
+export type { PgExecutor } from './pg-executor';
 export type { ProcessMetricsOptions, ProcessReading } from './process-metrics';
 export { readProcess, resetProcessMetrics, startProcessMetrics } from './process-metrics';
+export { hasPublicCause, registerPublicCause, resetPublicCauses } from './public-cause';
 export { type CappedBody, readWithinLimit } from './read-capped';
 export type { RecordEnvelope, RecordRows } from './record-envelope';
 export { decodeRecordEnvelope, encodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
@@ -646,6 +655,7 @@ export { retry, retryDecision } from './retry';
 export { isRetryableStatus, RETRYABLE_STATUSES } from './retryable-status';
 export type { ResolveRoleOptions, Role, RoleInfo, ScalingSignal } from './roles';
 export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
+export { routeRank } from './route-rank';
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
@@ -678,6 +688,8 @@ export {
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
 export { createSingleFlight } from './single-flight';
 export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
+export type { StoreMode } from './store-mode';
+export { STORE_MODES, storeMode } from './store-mode';
 export { timingSafeEqual } from './timing-safe-equal';
 export {
   frameworkVersion,

package/src/logger.ts

@@ -54,11 +54,10 @@ export interface LoggerOptions {
 }
 
 /**
- * LOWERCASE, always: `isRedactedKey` lowercases its lookup, so `apiKey`/`accessToken`/
- * `refreshToken` sat here for three releases matching nothing — and those are the exact field
- * names on `@ultimat3/auth`'s `OAuthTokens`. Matching is exact-key and never substring, so a
- * spelling that is not in this set is not redacted: both the camel and the snake wire spelling of
- * each credential is listed. Add through `redactKeys()` (which lowercases) rather than here.
+ * The exact-key FAST PATH. LOWERCASE, always: `isRedactedKey` lowercases its lookup, so
+ * `apiKey`/`accessToken`/`refreshToken` sat here for three releases matching nothing — and those
+ * are the exact field names on `@ultimat3/auth`'s `OAuthTokens`. Add through `redactKeys()` (which
+ * lowercases) rather than here. A name this set misses still meets `CREDENTIAL_NAME` below.
  */
 const redactedKeys = new Set<string>([
   'password',
@@ -81,15 +80,69 @@ const redactedKeys = new Set<string>([
   'client_secret',
   'privatekey',
   'private_key',
+  // The framework's own columns (`@ultimat3/auth`): a hash is what an offline guess runs against.
+  'passwordhash',
+  'tokenhash',
+  'keyhash',
 ]);
 
+/**
+ * The second half, for the names no list can enumerate. Exact-key matching alone let every
+ * COMPOUND credential through — `currentPassword`, `mfaSecret`, `resetToken`, `recoveryCode` — and
+ * `@ultimat3/action`'s audit walk asks this same predicate, so each was persisted in clear.
+ *
+ * Tested against the key lowercased with `_` and `-` removed, so one pattern covers the camel, the
+ * snake and the header spelling. It names what BEARS a credential and nothing wider, because a
+ * redacted field is one an operator cannot correlate on:
+ *
+ * - `password` / `passphrase` anywhere — no ordinary field carries the word.
+ * - `secret` as the LAST word (`mfaSecret`, `webhookSecret`, `appSecrets`, `secretAccessKey`), so
+ *   `clientSecretEnv` and `secretsPath` — a variable name and a path — stay readable.
+ * - a `token` is a bearer UNLESS its qualifier says it is not: fail closed, with the exceptions
+ *   named. `idempotencyToken`, `pageToken`, `continuationToken`, `cursorToken`, `syncToken` are
+ *   dedupe and paging keys an operator greps for; everything else ending in `token` — `resetToken`,
+ *   `githubToken`, `NPM_TOKEN` — is redacted without a provider list to keep current. The PLURAL
+ *   is the reverse: `maxTokens` / `inputTokens` are counts on every `@ultimat3/ai` usage line, so
+ *   `tokens` is redacted only behind a bearer qualifier (`accessTokens`).
+ * - key MATERIAL by its qualifier (`apiKey`, `privateKey`, `signingKey`, `encryptionKey`,
+ *   `masterKey`, `hmacKey`, `secretsKey`, `accessKey`, `retiredKeys`) and the id half of a key
+ *   pair (`accessKeyId`). A LOOKUP key — `cacheKey`, `primaryKey`, `idempotencyKey` — and a key's
+ *   own id (`signingKeyId`) carry no qualifier on this list and stay readable.
+ * - a value that EMBEDS a credential: `connectionString`, `dsn`, a registry `authConfig`, and the
+ *   service URLs that carry `user:password@` (`databaseUrl`, `REDIS_URL`). A bare `url` does not.
+ * - the one-time codes by name. Never a `code` suffix: that is the error contract's own field.
+ * - a stored hash of any of them: it is what an offline guess runs against.
+ *
+ * Built from constant alternatives with no nested quantifier, so there is no input it backtracks on.
+ */
+const CREDENTIAL_NAME = new RegExp(
+  [
+    'passw(?:or)?d|passphrase',
+    'secrets?$',
+    '(?:api|private|signing|encryption|master|hmac|secrets?|access|retired)keys?$|accesskeyid$',
+    '(?:token|key)hash(?:es)?$',
+    '(?<!idempotency|page|continuation|cursor|sync)token$',
+    '(?:access|refresh|id|session|reset|bearer|auth|api|csrf|xsrf|captcha|card|verification|invite|magic|magiclink|device|push|workload|oauth)tokens$',
+    'authconfig$|connectionstring$|dsn$',
+    '(?:database|db|redis|replication|nats|smtp|amqp|mongo)ur[li]s?$',
+    '^totp$|totpcode$|otp$|otpcode$',
+    '(?:recovery|backup|mfa)codes?(?:hash(?:es)?)?$',
+  ].join('|'),
+);
+
 /** Mark keys as secret everywhere. `defineEnv()` calls this for every `secret: true` var. */
 export function redactKeys(keys: Iterable<string>): void {
   for (const key of keys) redactedKeys.add(key.toLowerCase());
 }
 
+/**
+ * The framework's ONE answer to "is this field a credential?" — the log line, the error monitor's
+ * envelope and `@ultimat3/action`'s audit row all ask it, so a value that is `[redacted]` in one
+ * cannot be plaintext in another.
+ */
 export function isRedactedKey(key: string): boolean {
-  return redactedKeys.has(key.toLowerCase());
+  const lower = key.toLowerCase();
+  return redactedKeys.has(lower) || CREDENTIAL_NAME.test(lower.replace(/[_-]/g, ''));
 }
 
 /**
@@ -224,7 +277,12 @@ function entryValue(source: Record<string, unknown>, key: string, depth: number)
   }
 }
 
-function redactFields(fields: LogFields): Record<string, unknown> {
+/**
+ * A caller's record made safe to SERIALISE and safe to SHIP: credentials replaced by key and by
+ * value, a bigint / cycle / hostile getter degraded per field. Exported for the one other sink
+ * that sends a caller's record off the box — `error-reporter-sentry.ts`.
+ */
+export function redactFields(fields: LogFields): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   const source = fields as Record<string, unknown>;
   // `Object.keys` before the values, so the read of each value is its own guarded step: a field
@@ -304,9 +362,18 @@ function timestamp(clock: Clock): string {
  */
 function envLevel(): LogLevel {
   const raw = typeof process === 'undefined' ? undefined : process.env['LOG_LEVEL'];
-  return raw !== undefined && (LOG_LEVELS as readonly string[]).includes(raw)
-    ? (raw as LogLevel)
-    : 'info';
+  // Unset and EMPTY are the same answer — `LOG_LEVEL=` is how a compose file spells "not set".
+  if (raw === undefined || raw === '') return 'info';
+  // REFUSED, as `resolveLevel` refuses the same value from `createLogger({ level })`. It fell back
+  // to `info` in silence, so `LOG_LEVEL=verbose` — or `DEBUG`, the spelling half the ecosystem
+  // uses — gave an operator who asked for MORE lines fewer, and nothing said the variable was the
+  // reason. This runs at module init, so the refusal is the first thing the process prints.
+  assert(
+    (LOG_LEVELS as readonly string[]).includes(raw),
+    `LOG_LEVEL=${renderCauseValue(raw)} is not a log level`,
+    `set LOG_LEVEL=info (one of ${LOG_LEVELS.join(', ')}, lowercase), or unset LOG_LEVEL`,
+  );
+  return raw as LogLevel;
 }
 
 /**

package/src/nearest-name.ts

@@ -27,7 +27,16 @@ const distance = (a: string, b: string): number => {
 const MAX_EDITS = 3;
 
 /**
- * The nearest candidate within `MAX_EDITS`, or `undefined` when nothing is close enough. Ties keep
+ * The cutoff for one pair: `MAX_EDITS`, but never as many edits as the longer name has
+ * characters. A fixed 3 is a typo in `migrate` and a different word in `db` — replacing ALL of a
+ * one- or two-letter input costs at most its length, so `nearestName('a', ['db', 'gen'])`
+ * answered `db` with nothing typed in common.
+ */
+const cutoff = (input: string, candidate: string): number =>
+  Math.min(MAX_EDITS, Math.max(input.length, candidate.length) - 1);
+
+/**
+ * The nearest candidate within its cutoff, or `undefined` when nothing is close enough. Ties keep
  * the FIRST candidate, which is the order the caller declared them in — `definePermissions([...])`
  * and a `CommandSpec` list are both authored orders, and a stable answer is what lets a test pin one.
  */
@@ -36,7 +45,7 @@ export const nearestName = (input: string, candidates: readonly string[]): strin
   let bestScore = MAX_EDITS + 1;
   for (const candidate of candidates) {
     const score = distance(input, candidate);
-    if (score < bestScore) {
+    if (score < bestScore && score <= cutoff(input, candidate)) {
       best = candidate;
       bestScore = score;
     }

package/src/otlp-metric-exporter.ts

@@ -118,7 +118,7 @@ export interface OtlpMetricExporter extends MetricExporter {
  */
 export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): OtlpMetricExporter {
   const url = otlpEndpoint('metrics', options.endpoint);
-  const headers = otlpHeaders(options.headers);
+  const headers = otlpHeaders(options.headers, process.env, 'metrics');
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
   let startedAtMs = options.startedAtMs;

package/src/otlp-span-exporter.ts

@@ -126,7 +126,7 @@ export interface OtlpSpanExporter extends SpanExporter {
  */
 export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpanExporter {
   const url = otlpEndpoint('traces', options.endpoint);
-  const headers = otlpHeaders(options.headers);
+  const headers = otlpHeaders(options.headers, process.env, 'traces');
   const maxBatchSize = assertFiniteOtlpBound('maxBatchSize', options.maxBatchSize ?? 512);
   const maxQueueSize = assertFiniteOtlpBound('maxQueueSize', options.maxQueueSize ?? 2048);
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);