@wtfalch/reporting 0.1.2 → 0.3.0

package/dist/errors/capture.js

@@ -0,0 +1,187 @@
+import { sql } from 'drizzle-orm';
+import { ERROR_RUNTIMES, KIND_PATTERN, LIMITS } from '../schema.js';
+import { reportingErrors } from '../tables.js';
+import { describe } from '../writer.js';
+import { errorKind, fingerprint } from './fingerprint.js';
+import { heldSecrets, redactText } from './redact.js';
+const CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+const INVALID_KIND_CHARS = /[^a-z0-9_]+/g;
+/** camelCase/PascalCase/anything, folded down to what `KIND_PATTERN` allows. */
+function snakeCase(name) {
+    const lowered = name.replace(CAMEL_BOUNDARY, '$1_$2').toLowerCase();
+    return lowered
+        .replace(INVALID_KIND_CHARS, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+/**
+ * `error.<snake_case class name>` for the timeline row's `kind`. Falls back
+ * to `error.unknown` rather than refuse the capture: a class name that
+ * cannot become a valid `namespace.name` once lower-cased (it leads with a
+ * digit, or is nothing but punctuation) is itself informative, but not worth
+ * losing the whole report over.
+ */
+function eventKindFor(kind) {
+    const candidate = `error.${snakeCase(kind)}`;
+    return KIND_PATTERN.test(candidate) ? candidate : 'error.unknown';
+}
+/** `errorKind(error)`, unless the caller already knows the class better than the thrown value can say (a JSON-serialised browser report, say). */
+function resolveKind(error, override) {
+    const trimmed = override?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed.slice(0, 100) : errorKind(error);
+}
+/** Safe for every throw JavaScript actually allows: a string, `null`, an object with no message at all. Never empty, so it always clears the table's and the schema's non-empty checks. */
+function messageOf(error, kind) {
+    if (error instanceof Error)
+        return error.message || error.name || kind;
+    if (typeof error === 'string')
+        return error || kind;
+    if (error === null)
+        return 'null';
+    if (error === undefined)
+        return 'undefined';
+    try {
+        return String(error) || kind;
+    }
+    catch {
+        return kind;
+    }
+}
+/** Only a real `Error` has a stack worth keeping; everything else groups on `kind` and the message alone (fingerprint.ts). */
+function stackOf(error) {
+    return error instanceof Error && typeof error.stack === 'string' ? error.stack : null;
+}
+/** Keeps the top of the text — the start, where the throw site and its callers are — and drops the rest. */
+function truncateEnd(text, max) {
+    return text.length > max ? text.slice(0, max) : text;
+}
+/**
+ * `reporting_errors.tenant_id` is a uuid column and the event row's schema
+ * refuses anything else, so a caller that hands over a slug, an empty string
+ * or a number loses the whole group row rather than just the attribution.
+ * Callers are not all trusted to the same degree -- `./next`'s client ingest
+ * takes what a browser posted -- so the guard lives here, at the one door
+ * every capture goes through.
+ */
+function validTenant(value) {
+    return typeof value === 'string' && UUID.test(value) ? value : null;
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function normaliseRuntime(runtime) {
+    return runtime && ERROR_RUNTIMES.includes(runtime) ? runtime : 'server';
+}
+/**
+ * `insert ... on conflict (fingerprint) do update`, one round trip so two
+ * occurrences arriving at once still land as one row: bump `occurrences`,
+ * move `last_seen_at`, overwrite the sample fields with the newest
+ * occurrence. `first_seen_at` is left out of `set` entirely, so a conflict
+ * never moves it.
+ *
+ * A resolved or ignored group reopens: the pair the table's own CHECK
+ * enforces (`reporting_errors_resolved_pair_check`, 0003_errors.sql) means
+ * `state` can only move back to 'open' by clearing `resolved_at` and
+ * `resolved_by` in the same statement, never one alone.
+ */
+async function upsertGroup(db, site, s) {
+    const reopened = sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then 'open' else ${reportingErrors.state} end`;
+    await db
+        .insert(reportingErrors)
+        .values({
+        fingerprint: s.fingerprint,
+        site,
+        kind: s.kind,
+        message: s.message,
+        stack: s.stack,
+        runtime: s.runtime,
+        release: s.release,
+        firstSeenAt: s.at,
+        lastSeenAt: s.at,
+        occurrences: 1,
+        tenantId: s.tenantId,
+        requestId: s.requestId,
+    })
+        .onConflictDoUpdate({
+        target: reportingErrors.fingerprint,
+        set: {
+            occurrences: sql `${reportingErrors.occurrences} + 1`,
+            lastSeenAt: s.at,
+            message: s.message,
+            stack: s.stack,
+            tenantId: s.tenantId,
+            requestId: s.requestId,
+            release: s.release,
+            state: reopened,
+            resolvedAt: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedAt} end`,
+            resolvedBy: sql `case when ${reportingErrors.state} in ('resolved', 'ignored') then null else ${reportingErrors.resolvedBy} end`,
+        },
+    });
+}
+/**
+ * `captureError(error, context?)`: the class from `errorKind` (or the
+ * context's own, when the caller already knows it), the message and stack
+ * from the value itself — never assuming it is an `Error` — redacted before
+ * anything else touches them, bounded to what the table accepts, then
+ * fingerprinted on that same redacted, bounded text so a secret can never
+ * reach the digest either.
+ *
+ * Writes the timeline row synchronously through `o.event()` (the writer
+ * queues and logs it), then schedules the group upsert through `o.defer` —
+ * no timer of its own, same as the writer's flush. The whole body is one
+ * try/catch: nothing here may throw back into the code that threw the
+ * original error.
+ */
+export function createCapture(o) {
+    return function captureError(error, context = {}) {
+        try {
+            const kind = resolveKind(error, context.kind);
+            const secrets = heldSecrets(process.env);
+            const message = truncateEnd(redactText(messageOf(error, kind), secrets), LIMITS.message);
+            const rawStack = stackOf(error);
+            const stack = rawStack === null ? null : truncateEnd(redactText(rawStack, secrets), LIMITS.stack);
+            const fp = fingerprint({ kind, message, stack });
+            const runtime = normaliseRuntime(context.runtime);
+            // A tenant id that is not a uuid would be refused by the event row's
+            // own zod check (schema.ts: `tenantId: z.uuid().nullish()`) and would
+            // fail the group upsert at Postgres's cast, which is caught, logged and
+            // dropped -- leaving an occurrence with a timeline row and no group.
+            // The attribution is worth less than the report, so a malformed id is
+            // dropped and the capture goes on.
+            const tenantId = validTenant(context.tenantId);
+            const requestId = context.requestId ?? null;
+            const release = context.release ?? o.release ?? null;
+            const at = o.now();
+            o.event({
+                kind: eventKindFor(kind),
+                level: 'error',
+                message,
+                tenantId,
+                requestId,
+                data: { fingerprint: fp, runtime },
+            });
+            const sample = {
+                fingerprint: fp,
+                kind,
+                message,
+                stack,
+                runtime,
+                release,
+                tenantId,
+                requestId,
+                at,
+            };
+            try {
+                o.defer(() => upsertGroup(o.db, o.site, sample).catch((err) => {
+                    o.log.error({ err: describe(err), fingerprint: fp }, 'reporting: error group upsert failed');
+                }));
+            }
+            catch (err) {
+                // A host's defer that throws (called outside a request scope, say)
+                // must not take the report with it, same as writer.ts's schedule().
+                o.log.warn({ err: describe(err) }, 'reporting: defer threw; the error group upsert was dropped');
+            }
+        }
+        catch (err) {
+            o.log.error({ err: describe(err) }, 'reporting: captureError failed');
+        }
+    };
+}

package/dist/errors/fingerprint.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One V8 stack frame to its stable identity: the function name (if any) and
+ * the location, with everything that drifts for reasons unrelated to the
+ * bug removed.
+ *
+ * Handles both formats Node/V8 produce:
+ *   at functionName (/path/to/file.ts:10:5)
+ *   at /path/to/file.ts:10:5
+ */
+export declare function normaliseFrame(frame: string): string;
+/**
+ * The group an error belongs to: sha256 over the kind and the top five
+ * normalised frames, truncated to 32 lower-case hex characters. Five frames
+ * because the throw site and its immediate callers are what identifies a
+ * bug; frames further up are shared by every request and add nothing but
+ * noise a coincidental match in them could exploit.
+ *
+ * Falls back to `kind + masked message` when there is no stack at all, or
+ * the stack has no line this package recognises as a frame (a non-V8
+ * runtime, or a stack someone already stripped).
+ */
+export declare function fingerprint(input: {
+    kind: string;
+    message: string;
+    stack?: string | null;
+}): string;
+/**
+ * The class name a `kind` column and a fingerprint are built from —
+ * `TypeError`, `ZodError` — bounded so a pathological name cannot blow out
+ * the 512-character message column it eventually contributes to, and safe
+ * for the throws JavaScript actually allows: a string, `null`, an object
+ * with no prototype at all. None of those may throw out of this function;
+ * an error reporter that itself throws while reporting an error is the one
+ * failure mode worse than not reporting it.
+ */
+export declare function errorKind(error: unknown): string;

package/dist/errors/fingerprint.js

@@ -0,0 +1,211 @@
+import { createHash } from 'node:crypto';
+/**
+ * Turning an exception into a group, without a database and without a
+ * database of known errors: `sha256(kind + top five normalised frames)`,
+ * truncated to 32 hex characters (docs/plans/errors.md, "Fingerprint").
+ *
+ * The whole design is one constraint: the same bug, thrown a thousand
+ * times across deploys, must fingerprint the same every time, and a
+ * different bug must not collide with it. That is why every normalisation
+ * below throws away information that varies for reasons unrelated to which
+ * bug this is — a line number, a package's patch version, a machine's
+ * absolute filesystem path — while keeping what actually names the bug: the
+ * error's class, the call chain's function names, and which files they are
+ * in relative to the project.
+ */
+/** node_modules/<pkg>, node_modules/@scope/pkg — a scoped package's name is two segments. */
+const SCOPED_PACKAGE = /^(@[^/]+\/[^/]+)/;
+const PLAIN_PACKAGE = /^([^/]+)/;
+/** webpack, webpack-internal and turbopack all prefix a location with a scheme and a fake "host". */
+const BUNDLER_SCHEME_PREFIX = /^[a-zA-Z][\w+.-]*:\/\/[^/]*\//;
+/** Trailing `:<line>:<column>` or, more rarely, just `:<line>`. */
+const TRAILING_LINE_COL = /:\d+:\d+$/;
+const TRAILING_LINE = /:\d+$/;
+/** `at fn (location)` — the parenthesised form. Function-only frames have no match. */
+const FRAME_WITH_FUNCTION = /^(.*)\s\((.+)\)$/;
+/**
+ * One V8 stack frame to its stable identity: the function name (if any) and
+ * the location, with everything that drifts for reasons unrelated to the
+ * bug removed.
+ *
+ * Handles both formats Node/V8 produce:
+ *   at functionName (/path/to/file.ts:10:5)
+ *   at /path/to/file.ts:10:5
+ */
+export function normaliseFrame(frame) {
+    let s = frame.trim();
+    if (s.startsWith('at '))
+        s = s.slice(3).trim();
+    const withFunction = s.match(FRAME_WITH_FUNCTION);
+    const functionName = withFunction ? withFunction[1]?.trim() : undefined;
+    const location = withFunction ? (withFunction[2]?.trim() ?? '') : s;
+    const normalisedLocation = normaliseLocation(location);
+    return functionName ? `${functionName} (${normalisedLocation})` : normalisedLocation;
+}
+function normaliseLocation(rawLocation) {
+    // Next.js emits webpack-internal:///, webpack://_N_E/ and turbopack://[project]/
+    // ahead of the real path; a bundled build and a plain `node file.js` run of
+    // the same source must fingerprint the same, so the scheme goes first.
+    let location = rawLocation.replace(BUNDLER_SCHEME_PREFIX, '');
+    location = location.replace(/^file:\/\//, '');
+    // A dependency's own file layout is not this app's bug: two patch releases
+    // of the same package rename nothing an app author can act on, and pnpm's
+    // content-addressed store puts the version number in the path itself
+    // (node_modules/.pnpm/lodash@4.17.20/node_modules/lodash/index.js). Taking
+    // the LAST node_modules/ segment lands on the package's own copy of
+    // itself, past any version-numbered store directory, so both versions
+    // collapse to the same "node_modules/lodash".
+    const nodeModulesIndex = location.lastIndexOf('node_modules/');
+    if (nodeModulesIndex !== -1) {
+        const afterNodeModules = location.slice(nodeModulesIndex + 'node_modules/'.length);
+        const scoped = afterNodeModules.match(SCOPED_PACKAGE);
+        const plain = afterNodeModules.match(PLAIN_PACKAGE);
+        const pkg = scoped?.[1] ?? plain?.[1];
+        return pkg ? `node_modules/${pkg}` : 'node_modules';
+    }
+    // Line and column drift on every edit to the file, even ones nowhere near
+    // the throw (a comment added above it shifts every line below). Keeping
+    // them would turn one bug into a new group on every deploy, which is the
+    // exact failure mode a grouped error list exists to avoid.
+    location = location.replace(TRAILING_LINE_COL, '').replace(TRAILING_LINE, '');
+    // A bundler names its output after a build-varying token — a chunk id
+    // (8471.js) or a content hash appended for cache-busting (main-abc123.js).
+    // Neither identifies the bug; both identify the build, so a browser or
+    // Next.js chunk stack would otherwise open a brand new group on every
+    // deploy — the exact failure line numbers were already excluded to avoid.
+    location = maskBasenameHash(location);
+    return stripAbsolutePrefix(location);
+}
+/** A run of 6+ hex characters straight after the last `-` or `.` in a name. */
+const HASH_SUFFIX = /[-.][0-9a-fA-F]{6,}$/;
+/**
+ * Masks a build-varying token in the FILENAME only — never a directory name
+ * — so `chunks/8471.js` and `chunks/main-abc123.js` both collapse to a form
+ * that survives a rebuild, while `dashboard/page.js` is untouched because
+ * there is nothing in it to mask.
+ */
+function maskBasenameHash(path) {
+    const lastSlash = path.lastIndexOf('/');
+    const dir = lastSlash === -1 ? '' : path.slice(0, lastSlash + 1);
+    const basename = lastSlash === -1 ? path : path.slice(lastSlash + 1);
+    return `${dir}${maskBuildHash(basename)}`;
+}
+function maskBuildHash(basename) {
+    const lastDot = basename.lastIndexOf('.');
+    // No extension, or a dotfile (".env"): nothing to anchor an extension on,
+    // so there is no safe way to tell a hash from the rest of the name.
+    if (lastDot <= 0)
+        return basename;
+    const ext = basename.slice(lastDot);
+    const stem = basename.slice(0, lastDot);
+    // A chunk named after nothing but its id: "8471.js", "9032.js". The whole
+    // stem changes on every build even though it is the same chunk.
+    if (/^\d+$/.test(stem))
+        return `#${ext}`;
+    // A real name with a hash tacked on for cache-busting: "main-abc123.js",
+    // "page.4f2a91b.js". Anchored on the LAST separator so it only ever
+    // consumes a trailing suffix, and constrained to hex characters so an
+    // ordinary multi-word filename is never mistaken for one — "component" in
+    // "my-component.tsx" contains 'o', 'p', 'n', 't', none of them hex digits,
+    // so it does not match and the name survives untouched.
+    const masked = stem.replace(HASH_SUFFIX, (match) => `${match[0]}#`);
+    return `${masked}${ext}`;
+}
+/**
+ * The same file has a different absolute path in every environment it
+ * runs in — a developer's home directory, the CI runner's workspace, the
+ * container's /app — so keeping it would fragment one bug into one group
+ * per place it was seen. `src/` is the one directory name this monorepo's
+ * own code always sits under, so anything from there on is kept in full.
+ * Failing that (a frame with no recognisable project root, e.g. a bare
+ * dependency-free script), the last two path segments are kept: enough to
+ * tell apart two files that happen to share a name, without the
+ * environment-specific parent directories.
+ */
+function stripAbsolutePrefix(path) {
+    const marker = '/src/';
+    const markerIndex = path.indexOf(marker);
+    if (markerIndex !== -1)
+        return path.slice(markerIndex + 1);
+    if (path.startsWith('src/'))
+        return path;
+    const segments = path.split('/').filter((segment) => segment.length > 0);
+    return segments.slice(-2).join('/');
+}
+const FRAME_LINE = /^at /;
+function parseFrames(stack) {
+    if (!stack)
+        return [];
+    return stack
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => FRAME_LINE.test(line));
+}
+/**
+ * A message differs by the one thing that made this particular occurrence
+ * unique — a user id, a filename, a value that failed validation — so a
+ * fallback that used the raw message would give one group per occurrence,
+ * which is exactly the firehose grouping exists to prevent. Digits and
+ * quoted substrings are the two shapes that carry that kind of unique data
+ * in practice, so both are masked before hashing: "user 4821 not found" and
+ * "user 9913 not found" become the same "user # not found".
+ */
+function maskMessage(message) {
+    return message
+        .replace(/"[^"]*"/g, '"…"')
+        .replace(/'[^']*'/g, "'…'")
+        .replace(/`[^`]*`/g, '`…`')
+        .replace(/\d+/g, '#');
+}
+/**
+ * The group an error belongs to: sha256 over the kind and the top five
+ * normalised frames, truncated to 32 lower-case hex characters. Five frames
+ * because the throw site and its immediate callers are what identifies a
+ * bug; frames further up are shared by every request and add nothing but
+ * noise a coincidental match in them could exploit.
+ *
+ * Falls back to `kind + masked message` when there is no stack at all, or
+ * the stack has no line this package recognises as a frame (a non-V8
+ * runtime, or a stack someone already stripped).
+ */
+export function fingerprint(input) {
+    const frames = parseFrames(input.stack).slice(0, 5).map(normaliseFrame);
+    const basis = frames.length > 0
+        ? `${input.kind}\n${frames.join('\n')}`
+        : `${input.kind}\n${maskMessage(input.message)}`;
+    return createHash('sha256').update(basis).digest('hex').slice(0, 32);
+}
+/**
+ * The class name a `kind` column and a fingerprint are built from —
+ * `TypeError`, `ZodError` — bounded so a pathological name cannot blow out
+ * the 512-character message column it eventually contributes to, and safe
+ * for the throws JavaScript actually allows: a string, `null`, an object
+ * with no prototype at all. None of those may throw out of this function;
+ * an error reporter that itself throws while reporting an error is the one
+ * failure mode worse than not reporting it.
+ */
+export function errorKind(error) {
+    if (error instanceof Error) {
+        return bound(error.constructor?.name || error.name || 'Error');
+    }
+    if (error === null)
+        return 'null';
+    if (error === undefined)
+        return 'undefined';
+    if (Array.isArray(error))
+        return 'array';
+    if (typeof error === 'object') {
+        // Object.create(null) has no `.constructor` at all; a plain `{}` has one
+        // whose name is the unhelpful "Object". Either way there is no class
+        // name worth keeping, so it is grouped as a plain object rather than
+        // risking a crash reading a property that may not exist.
+        const ctorName = error.constructor?.name;
+        return bound(ctorName && ctorName !== 'Object' ? ctorName : 'object');
+    }
+    // string, number, boolean, symbol, bigint, function.
+    return bound(typeof error);
+}
+function bound(name) {
+    const trimmed = name.trim();
+    return trimmed.length > 0 ? trimmed.slice(0, 100) : 'Error';
+}

package/dist/errors/reader.d.ts

@@ -0,0 +1,19 @@
+import type { ErrorState } from '../schema.js';
+import type { ReportingErrorRow } from '../tables.js';
+import type { Actor, Db, ErrorsPage, ErrorsPageOptions } from '../types.js';
+/**
+ * Newest first, keyset-paged on `(last_seen_at, fingerprint)`, the table's
+ * index. Every filter is an equality on an indexed column. No permission is
+ * applied here: the host gates, and this returns rows as stored.
+ */
+export declare function errorsPage(db: Db, opts?: ErrorsPageOptions): Promise<ErrorsPage>;
+/** One row by fingerprint, or null when it is unknown. */
+export declare function errorDetail(db: Db, fingerprint: string): Promise<ReportingErrorRow | null>;
+/**
+ * Moves an error's state. 'resolved' and 'ignored' stamp `resolved_at` and
+ * `resolved_by` with this instant and who did it; moving back to 'open'
+ * clears both, never one alone — `reporting_errors_resolved_pair_check`
+ * (0003_errors.sql) refuses a row with only one of the pair set. Returns the
+ * updated row, or null when the fingerprint is unknown.
+ */
+export declare function setErrorState(db: Db, fingerprint: string, state: ErrorState, by: Actor): Promise<ReportingErrorRow | null>;

package/dist/errors/reader.js

@@ -0,0 +1,66 @@
+import { and, desc, eq, lt, or, sql } from 'drizzle-orm';
+import { reportingErrors } from '../tables.js';
+/**
+ * Newest first, keyset-paged on `(last_seen_at, fingerprint)`, the table's
+ * index. Every filter is an equality on an indexed column. No permission is
+ * applied here: the host gates, and this returns rows as stored.
+ */
+export async function errorsPage(db, opts = {}) {
+    const limit = Math.max(1, Math.min(opts.limit ?? 50, 200));
+    const conditions = [];
+    if (opts.site)
+        conditions.push(eq(reportingErrors.site, opts.site));
+    if (opts.state)
+        conditions.push(eq(reportingErrors.state, opts.state));
+    if (opts.runtime)
+        conditions.push(eq(reportingErrors.runtime, opts.runtime));
+    if (opts.after) {
+        const { lastSeenAt, fingerprint } = opts.after;
+        const keyset = or(lt(reportingErrors.lastSeenAt, lastSeenAt), and(eq(reportingErrors.lastSeenAt, lastSeenAt), lt(reportingErrors.fingerprint, fingerprint)));
+        if (keyset)
+            conditions.push(keyset);
+    }
+    const rows = await db
+        .select()
+        .from(reportingErrors)
+        .where(conditions.length > 0 ? and(...conditions) : undefined)
+        .orderBy(desc(reportingErrors.lastSeenAt), desc(reportingErrors.fingerprint))
+        .limit(limit + 1);
+    const items = rows.slice(0, limit);
+    const last = items.at(-1);
+    return {
+        items,
+        next: rows.length > limit && last
+            ? { lastSeenAt: last.lastSeenAt, fingerprint: last.fingerprint }
+            : null,
+    };
+}
+/** One row by fingerprint, or null when it is unknown. */
+export async function errorDetail(db, fingerprint) {
+    const rows = await db
+        .select()
+        .from(reportingErrors)
+        .where(eq(reportingErrors.fingerprint, fingerprint))
+        .limit(1);
+    return rows[0] ?? null;
+}
+/**
+ * Moves an error's state. 'resolved' and 'ignored' stamp `resolved_at` and
+ * `resolved_by` with this instant and who did it; moving back to 'open'
+ * clears both, never one alone — `reporting_errors_resolved_pair_check`
+ * (0003_errors.sql) refuses a row with only one of the pair set. Returns the
+ * updated row, or null when the fingerprint is unknown.
+ */
+export async function setErrorState(db, fingerprint, state, by) {
+    const closing = state === 'resolved' || state === 'ignored';
+    const rows = await db
+        .update(reportingErrors)
+        .set({
+        state,
+        resolvedAt: closing ? sql `now()` : null,
+        resolvedBy: closing ? `${by.class}:${by.id}` : null,
+    })
+        .where(eq(reportingErrors.fingerprint, fingerprint))
+        .returning();
+    return rows[0] ?? null;
+}

package/dist/errors/redact.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Keeping the wrapping keys out of anything this package captures.
+ *
+ * **Why this is worth a file.** The store's whole promise is that a database
+ * dump is ciphertext, and that promise has exactly one premise: the wrapping
+ * key is not where the ciphertext is. An error report is the most likely way
+ * for it to end up somewhere else — a crash during boot with the environment
+ * attached, a configuration error whose message quotes the value it could not
+ * parse, a breadcrumb from a library that logs what it was given. None of
+ * those is a bug in this module; all of them would hand the key to whoever
+ * can read the error.
+ *
+ * So the rule is stated once, here, and applied on the capture path rather
+ * than trusted to every path in. `scrub` walks a structure and replaces any
+ * exact occurrence of a held key with a marker; `redactText` does the same
+ * for the plain-string case — a captured `message` or `stack` — without
+ * walking a structure that does not exist yet.
+ *
+ * **It cannot cover stored values**, and does not pretend to: those are not in
+ * the environment, so there is nothing to enumerate. What protects them is
+ * that no code path writes one anywhere but the response that asked for it.
+ *
+ * No `server-only`: the edge runtime captures errors too, and this reaches
+ * nothing but its arguments and `process.env`.
+ */
+export declare const REDACTED = "[redacted: wrapping key]";
+/**
+ * The exact strings that must never appear in anything sent anywhere: both
+ * environment variables in full, and each key's base64 half on its own, since
+ * a parser that split on the colon would report only that part.
+ */
+export declare function heldSecrets(env: Readonly<Record<string, string | undefined>>): string[];
+/**
+ * The string case alone: a captured `message` and `stack` are strings before
+ * they are anything else, so the capture path scrubs them directly rather
+ * than wrapping each in an object just to hand it to `scrub`.
+ */
+export declare function redactText(text: string, secrets: readonly string[]): string;
+/**
+ * The same structure with every held secret replaced.
+ *
+ * Walks rather than serialising and string-replacing, so the shape a caller
+ * expects survives. Cycles are tracked because an error object graph has them
+ * and a scrubber that hangs is worse than one that missed something.
+ */
+export declare function scrub<T>(value: T, secrets: readonly string[]): T;

package/dist/errors/redact.js

@@ -0,0 +1,93 @@
+/**
+ * Keeping the wrapping keys out of anything this package captures.
+ *
+ * **Why this is worth a file.** The store's whole promise is that a database
+ * dump is ciphertext, and that promise has exactly one premise: the wrapping
+ * key is not where the ciphertext is. An error report is the most likely way
+ * for it to end up somewhere else — a crash during boot with the environment
+ * attached, a configuration error whose message quotes the value it could not
+ * parse, a breadcrumb from a library that logs what it was given. None of
+ * those is a bug in this module; all of them would hand the key to whoever
+ * can read the error.
+ *
+ * So the rule is stated once, here, and applied on the capture path rather
+ * than trusted to every path in. `scrub` walks a structure and replaces any
+ * exact occurrence of a held key with a marker; `redactText` does the same
+ * for the plain-string case — a captured `message` or `stack` — without
+ * walking a structure that does not exist yet.
+ *
+ * **It cannot cover stored values**, and does not pretend to: those are not in
+ * the environment, so there is nothing to enumerate. What protects them is
+ * that no code path writes one anywhere but the response that asked for it.
+ *
+ * No `server-only`: the edge runtime captures errors too, and this reaches
+ * nothing but its arguments and `process.env`.
+ */
+export const REDACTED = '[redacted: wrapping key]';
+/**
+ * The exact strings that must never appear in anything sent anywhere: both
+ * environment variables in full, and each key's base64 half on its own, since
+ * a parser that split on the colon would report only that part.
+ */
+export function heldSecrets(env) {
+    const specs = [env.KEYSTORE_KEK ?? '', ...(env.KEYSTORE_KEK_PREVIOUS ?? '').split(',')]
+        .map((spec) => spec.trim())
+        .filter((spec) => spec.length > 0);
+    const secrets = new Set();
+    for (const spec of specs) {
+        secrets.add(spec);
+        const separator = spec.indexOf(':');
+        // A short tail is not worth replacing: it would be a common substring
+        // rather than a secret, and a scrubber that rewrites ordinary text is one
+        // somebody turns off.
+        if (separator > 0 && spec.length - separator > 16)
+            secrets.add(spec.slice(separator + 1));
+    }
+    return [...secrets];
+}
+/**
+ * The string case alone: a captured `message` and `stack` are strings before
+ * they are anything else, so the capture path scrubs them directly rather
+ * than wrapping each in an object just to hand it to `scrub`.
+ */
+export function redactText(text, secrets) {
+    let out = text;
+    for (const secret of secrets) {
+        if (out.includes(secret))
+            out = out.split(secret).join(REDACTED);
+    }
+    return out;
+}
+/**
+ * The same structure with every held secret replaced.
+ *
+ * Walks rather than serialising and string-replacing, so the shape a caller
+ * expects survives. Cycles are tracked because an error object graph has them
+ * and a scrubber that hangs is worse than one that missed something.
+ */
+export function scrub(value, secrets) {
+    if (secrets.length === 0)
+        return value;
+    return walk(value, secrets, new WeakMap());
+}
+function walk(value, secrets, seen) {
+    if (typeof value === 'string')
+        return redactText(value, secrets);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (Array.isArray(value)) {
+        const copy = [];
+        seen.set(value, copy);
+        for (const item of value)
+            copy.push(walk(item, secrets, seen));
+        return copy;
+    }
+    const copy = {};
+    seen.set(value, copy);
+    for (const [key, item] of Object.entries(value))
+        copy[key] = walk(item, secrets, seen);
+    return copy;
+}