@jinn-network/client 0.1.7 → 0.1.8

package/dist/observability/debug-report-assemble.js

@@ -0,0 +1,80 @@
+/**
+ * Pure debug-report bundle assembler (issue #420 §2).
+ *
+ * Takes already-gathered inputs (status snapshot, resolved config, config
+ * provenance, recent activity events, log files, optional screenshot) and
+ * produces a redacted `.tar.gz` support bundle. Pure — no I/O, no Store, no
+ * HTTP — so it is fully unit-testable. The HTTP endpoint
+ * (`api/debug-report-endpoint.ts`) gathers the inputs and calls this.
+ *
+ * Every JSON file is run through `redactValue` before serialization; log
+ * files are already redacted on disk by `FileLogger`, but are re-redacted
+ * here defensively (idempotent). The result is safe to share.
+ */
+import { redactValue, buildRedactionReport, REDACTION_VERSION } from './redact-secrets.js';
+import { writeTarGz } from './tar.js';
+/** The set of files a debug-report bundle always contains (relative names). */
+export const DEBUG_REPORT_FILES = [
+    'status.json',
+    'config.json',
+    'config-provenance.json',
+    'activity-events.json',
+    'redaction-report.md',
+    'bundle-meta.json',
+];
+function jsonFile(name, value) {
+    return {
+        name,
+        content: Buffer.from(`${JSON.stringify(redactValue(value), null, 2)}\n`, 'utf8'),
+    };
+}
+/** Filesystem-safe ISO timestamp for the bundle directory / filename. */
+export function bundleStamp(generatedAt) {
+    return generatedAt.replace(/[:.]/g, '-');
+}
+/**
+ * Assemble a redacted `.tar.gz` debug-report bundle. Returns the gzip buffer.
+ * Async because the gzip pass is offloaded to the libuv pool (see `writeTarGz`).
+ */
+export async function assembleDebugReport(input) {
+    const generatedAt = input.generatedAt ?? new Date().toISOString();
+    const root = `jinn-debug-report-${bundleStamp(generatedAt)}`;
+    const at = (rel) => `${root}/${rel}`;
+    const files = [
+        jsonFile(at('status.json'), input.status),
+        jsonFile(at('config.json'), input.config),
+        jsonFile(at('config-provenance.json'), input.configProvenance),
+        jsonFile(at('activity-events.json'), input.activityEvents),
+        {
+            name: at('redaction-report.md'),
+            content: Buffer.from(buildRedactionReport(), 'utf8'),
+        },
+        jsonFile(at('bundle-meta.json'), {
+            schemaVersion: 1,
+            generatedAt,
+            daemonVersion: input.daemonVersion,
+            redactionVersion: REDACTION_VERSION,
+        }),
+    ];
+    // Log files — re-redact defensively (FileLogger already redacts on write).
+    for (const log of input.logFiles) {
+        files.push({
+            name: at(`logs/${log.name}`),
+            content: Buffer.from(redactValue(log.content.toString('utf8')), 'utf8'),
+        });
+    }
+    // Screenshot — included verbatim when present, else a clear note.
+    if (input.screenshotPng && input.screenshotPng.length > 0) {
+        files.push({ name: at('dashboard-screenshot.png'), content: input.screenshotPng });
+    }
+    else {
+        files.push({
+            name: at('screenshot-unavailable.txt'),
+            content: Buffer.from('No dashboard screenshot was captured. The operator browser either '
+                + 'declined to capture the DOM (content-security policy, very large '
+                + 'page) or the bundle was generated without a browser.\n', 'utf8'),
+        });
+    }
+    return await writeTarGz(files);
+}
+//# sourceMappingURL=debug-report-assemble.js.map

package/dist/observability/debug-report-assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-report-assemble.js","sourceRoot":"","sources":["../../src/observability/debug-report-assemble.ts"],"names":[],"mappings":"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"}

package/dist/observability/emit-event.d.ts

@@ -1,12 +1,19 @@
 import type { Store } from '../store/store.js';
-export type LifecycleKind = 'task_posted' | 'intent_registry_failed' | 'request_claimed' | 'delivery_submitted' | 'evaluation_submitted' | 'reward_claimed' | 'balance_topup' | 'jinn_claim_emitted' | 'jinn_claim_ticket_recorded' | 'jinn_claim_submitted' | 'jinn_claim_canonical_skip' | 'engine_transition' | 'tick_error' | 'startup' | 'shutdown';
+export declare const ALLOWED_LIFECYCLE_KINDS: readonly ["task_posted", "intent_registry_failed", "request_claimed", "delivery_submitted", "evaluation_submitted", "reward_claimed", "balance_topup", "jinn_claim_emitted", "jinn_claim_ticket_recorded", "jinn_claim_submitted", "jinn_claim_canonical_skip", "engine_transition", "tick_error", "race_lost", "spend_cap_reached", "ai_units_cap_reached", "startup", "shutdown"];
+export type LifecycleKind = (typeof ALLOWED_LIFECYCLE_KINDS)[number];
 export interface LifecycleEvent {
     kind: LifecycleKind;
     requestId?: string;
     serviceIndex?: number;
     txHash?: string;
     solverType?: string;
-    outcome?: 'ok' | 'failed' | 'warn';
+    outcome?: 'ok' | 'failed' | 'warn' | 'paused';
     detail?: string;
+    /**
+     * Optional: when set, written to the row's `credential_id` column. The
+     * AI-units cap-reached event uses this so cross-restart memo hydration
+     * can query by credential (issue #815).
+     */
+    credentialId?: string;
 }
 export declare function emitEvent(store: Store, event: LifecycleEvent, component?: string): void;

package/dist/observability/emit-event.js

@@ -1,3 +1,24 @@
+import { getFileLogger } from './file-logger.js';
+export const ALLOWED_LIFECYCLE_KINDS = [
+    'task_posted',
+    'intent_registry_failed',
+    'request_claimed',
+    'delivery_submitted',
+    'evaluation_submitted',
+    'reward_claimed',
+    'balance_topup',
+    'jinn_claim_emitted',
+    'jinn_claim_ticket_recorded',
+    'jinn_claim_submitted',
+    'jinn_claim_canonical_skip',
+    'engine_transition',
+    'tick_error',
+    'race_lost',
+    'spend_cap_reached',
+    'ai_units_cap_reached',
+    'startup',
+    'shutdown',
+];
 export function emitEvent(store, event, component = 'lifecycle') {
     const ts = new Date().toISOString();
     store.recordActivityEvent({
@@ -9,10 +30,13 @@ export function emitEvent(store, event, component = 'lifecycle') {
         solverType: event.solverType ?? null,
         outcome: event.outcome ?? null,
         detail: event.detail ?? null,
+        credentialId: event.credentialId ?? null,
     });
     const payload = {
         ts,
-        level: event.outcome === 'failed' ? 'error' : event.outcome === 'warn' ? 'warn' : 'info',
+        level: event.outcome === 'failed' ? 'error'
+            : (event.outcome === 'warn' || event.outcome === 'paused') ? 'warn'
+                : 'info',
         component,
         msg: event.detail ?? event.kind,
         requestId: event.requestId ?? null,
@@ -22,6 +46,16 @@ export function emitEvent(store, event, component = 'lifecycle') {
         outcome: event.outcome ?? 'ok',
         kind: event.kind,
     };
-    process.stderr.write(`${JSON.stringify(payload)}\n`);
+    const line = JSON.stringify(payload);
+    process.stderr.write(`${line}\n`);
+    // Issue #420: tee every lifecycle event into the rotating daemon file
+    // logger so the one-click debug report has durable, pre-redacted logs.
+    // Best-effort — a logging failure must never affect event emission.
+    try {
+        getFileLogger().write(line);
+    }
+    catch {
+        /* ignore */
+    }
 }
 //# sourceMappingURL=emit-event.js.map

package/dist/observability/emit-event.js.map

@@ -1 +1 @@
-{"version":3,"file":"emit-event.js","sourceRoot":"","sources":["../../src/observability/emit-event.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,SAAS,CACvB,KAAY,EACZ,KAAqB,EACrB,SAAS,GAAG,WAAW;IAEvB,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,KAAK,CAAC,mBAAmB,CAAC;QACxB,EAAE;QACF,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;KAC7B,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG;QACd,EAAE;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QACxF,SAAS;QACT,GAAG,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI;QAC/B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC;IACF,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC"}
+{"version":3,"file":"emit-event.js","sourceRoot":"","sources":["../../src/observability/emit-event.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,aAAa;IACb,wBAAwB;IACxB,iBAAiB;IACjB,oBAAoB;IACpB,sBAAsB;IACtB,gBAAgB;IAChB,eAAe;IACf,oBAAoB;IACpB,4BAA4B;IAC5B,sBAAsB;IACtB,2BAA2B;IAC3B,mBAAmB;IACnB,YAAY;IACZ,WAAW;IACX,mBAAmB;IACnB,sBAAsB;IACtB,SAAS;IACT,UAAU;CACF,CAAC;AAoBX,MAAM,UAAU,SAAS,CACvB,KAAY,EACZ,KAAqB,EACrB,SAAS,GAAG,WAAW;IAEvB,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,KAAK,CAAC,mBAAmB,CAAC;QACxB,EAAE;QACF,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;KACzC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG;QACd,EAAE;QACF,KAAK,EAAE,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO;YACzC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,MAAM,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM;gBACnE,CAAC,CAAC,MAAM;QACV,SAAS;QACT,GAAG,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI;QAC/B,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;QAClC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,IAAI;QAC5B,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,IAAI;QACxC,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;QACpC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,IAAI;QAC9B,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC;IACF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;IAElC,sEAAsE;IACtE,uEAAuE;IACvE,oEAAoE;IACpE,IAAI,CAAC;QACH,aAAa,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,YAAY;IACd,CAAC;AACH,CAAC"}

package/dist/observability/file-logger.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Rotating, size-bounded daemon file logger (issue #420 §1).
+ *
+ * The daemon's logging today is unstructured and ephemeral — `console.*` to
+ * stdout/stderr, nothing durable. A support bundle needs durable logs, so
+ * this module appends a redacted log line per call to `~/.jinn-client/logs/`,
+ * rotates the active file when it crosses a size bound, and prunes both by
+ * file count and by age.
+ *
+ * Hand-rolled rather than pulling in a logging framework: a size-bounded
+ * rotator is ~120 lines and self-contained, and the bundle assembler only
+ * needs `listLogFiles()` to enumerate the rotation set.
+ *
+ * Redaction at write time: every line is run through `redactValue`'s string
+ * redactor before it hits disk, so the on-disk file is safe by construction
+ * and the bundle assembler does not need to re-scan log bytes.
+ */
+export interface FileLoggerOptions {
+    /** Log directory. Defaults to `~/.jinn-client/logs`. */
+    logDir?: string;
+    /** Rotate the active file once it crosses this many bytes. Default 5 MiB. */
+    maxBytes?: number;
+    /** Number of files to keep, including the active `daemon.log`. Default 5. */
+    maxFiles?: number;
+    /** Delete rotated files older than this many days on startup. Default 14. */
+    maxAgeDays?: number;
+}
+export declare class FileLogger {
+    private readonly logDir;
+    private readonly maxBytes;
+    private readonly maxFiles;
+    private readonly maxAgeDays;
+    private readonly activePath;
+    private bytesWritten;
+    private closed;
+    constructor(opts?: FileLoggerOptions);
+    /**
+     * Append a single log line. The line is redacted before it hits disk.
+     *
+     * Writes synchronously (`appendFileSync`) rather than via a `WriteStream`:
+     * a daemon emits at most a handful of lines per second, and a synchronous
+     * append avoids buffering races on shutdown / rotation.
+     */
+    write(line: string): void;
+    /**
+     * Ordered list of log files for the bundle assembler: the active
+     * `daemon.log` first, then `daemon.log.1`, `.2`, ... in age order.
+     * Only files that exist on disk are returned.
+     */
+    listLogFiles(): string[];
+    /** Mark the logger closed for clean daemon shutdown. */
+    close(): void;
+    /**
+     * Rotate: `daemon.log.{N-1}` -> `.N` shift (oldest dropped), then
+     * `daemon.log` -> `daemon.log.1`. The next `write` recreates the active
+     * file via `appendFileSync`.
+     */
+    private rotate;
+    /** Delete rotated `daemon.log.*` files older than the age bound. */
+    private sweepStaleFiles;
+}
+/**
+ * Process-wide file logger singleton. Mirrors `events/emitter.ts`'s
+ * `getEventBuffer()` pattern. Lazily constructed on first use so importing
+ * this module never touches the filesystem.
+ */
+export declare function getFileLogger(): FileLogger;
+/** Close the singleton logger (daemon shutdown). Safe to call when unset. */
+export declare function closeFileLogger(): void;

package/dist/observability/file-logger.js

@@ -0,0 +1,177 @@
+/**
+ * Rotating, size-bounded daemon file logger (issue #420 §1).
+ *
+ * The daemon's logging today is unstructured and ephemeral — `console.*` to
+ * stdout/stderr, nothing durable. A support bundle needs durable logs, so
+ * this module appends a redacted log line per call to `~/.jinn-client/logs/`,
+ * rotates the active file when it crosses a size bound, and prunes both by
+ * file count and by age.
+ *
+ * Hand-rolled rather than pulling in a logging framework: a size-bounded
+ * rotator is ~120 lines and self-contained, and the bundle assembler only
+ * needs `listLogFiles()` to enumerate the rotation set.
+ *
+ * Redaction at write time: every line is run through `redactValue`'s string
+ * redactor before it hits disk, so the on-disk file is safe by construction
+ * and the bundle assembler does not need to re-scan log bytes.
+ */
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync, readdirSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { redactValue } from './redact-secrets.js';
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_FILES = 5;
+const DEFAULT_MAX_AGE_DAYS = 14;
+const ACTIVE_FILE = 'daemon.log';
+/** Redact a single log line — strips secret-shaped substrings. */
+function redactLine(line) {
+    return redactValue(line);
+}
+export class FileLogger {
+    logDir;
+    maxBytes;
+    maxFiles;
+    maxAgeDays;
+    activePath;
+    bytesWritten = 0;
+    closed = false;
+    constructor(opts = {}) {
+        this.logDir = opts.logDir ?? join(homedir(), '.jinn-client', 'logs');
+        this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+        this.maxFiles = opts.maxFiles ?? DEFAULT_MAX_FILES;
+        this.maxAgeDays = opts.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS;
+        this.activePath = join(this.logDir, ACTIVE_FILE);
+        mkdirSync(this.logDir, { recursive: true });
+        this.sweepStaleFiles();
+        this.bytesWritten = existsSync(this.activePath)
+            ? statSync(this.activePath).size
+            : 0;
+    }
+    /**
+     * Append a single log line. The line is redacted before it hits disk.
+     *
+     * Writes synchronously (`appendFileSync`) rather than via a `WriteStream`:
+     * a daemon emits at most a handful of lines per second, and a synchronous
+     * append avoids buffering races on shutdown / rotation.
+     */
+    write(line) {
+        if (this.closed)
+            return;
+        const safe = `${redactLine(line)}\n`;
+        const size = Buffer.byteLength(safe);
+        if (this.bytesWritten > 0 && this.bytesWritten + size > this.maxBytes) {
+            this.rotate();
+        }
+        try {
+            appendFileSync(this.activePath, safe);
+            this.bytesWritten += size;
+        }
+        catch {
+            // Logging must never crash the daemon.
+        }
+    }
+    /**
+     * Ordered list of log files for the bundle assembler: the active
+     * `daemon.log` first, then `daemon.log.1`, `.2`, ... in age order.
+     * Only files that exist on disk are returned.
+     */
+    listLogFiles() {
+        const out = [];
+        if (existsSync(this.activePath))
+            out.push(this.activePath);
+        for (let i = 1; i < this.maxFiles; i++) {
+            const p = `${this.activePath}.${i}`;
+            if (existsSync(p))
+                out.push(p);
+        }
+        return out;
+    }
+    /** Mark the logger closed for clean daemon shutdown. */
+    close() {
+        this.closed = true;
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    /**
+     * Rotate: `daemon.log.{N-1}` -> `.N` shift (oldest dropped), then
+     * `daemon.log` -> `daemon.log.1`. The next `write` recreates the active
+     * file via `appendFileSync`.
+     */
+    rotate() {
+        // Drop the oldest rotated file.
+        const oldest = `${this.activePath}.${this.maxFiles - 1}`;
+        if (existsSync(oldest)) {
+            try {
+                unlinkSync(oldest);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        // Shift `.i` -> `.i+1` from oldest to newest.
+        for (let i = this.maxFiles - 2; i >= 1; i--) {
+            const from = `${this.activePath}.${i}`;
+            const to = `${this.activePath}.${i + 1}`;
+            if (existsSync(from)) {
+                try {
+                    renameSync(from, to);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        // Active -> .1.
+        if (existsSync(this.activePath)) {
+            try {
+                renameSync(this.activePath, `${this.activePath}.1`);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.bytesWritten = 0;
+    }
+    /** Delete rotated `daemon.log.*` files older than the age bound. */
+    sweepStaleFiles() {
+        const cutoffMs = Date.now() - this.maxAgeDays * 24 * 60 * 60 * 1000;
+        let entries;
+        try {
+            entries = readdirSync(this.logDir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!/^daemon\.log\.\d+$/.test(entry))
+                continue;
+            const p = join(this.logDir, entry);
+            try {
+                if (statSync(p).mtimeMs < cutoffMs) {
+                    unlinkSync(p);
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+// ── module singleton ─────────────────────────────────────────────────────────
+let SINGLETON = null;
+/**
+ * Process-wide file logger singleton. Mirrors `events/emitter.ts`'s
+ * `getEventBuffer()` pattern. Lazily constructed on first use so importing
+ * this module never touches the filesystem.
+ */
+export function getFileLogger() {
+    if (!SINGLETON) {
+        SINGLETON = new FileLogger();
+    }
+    return SINGLETON;
+}
+/** Close the singleton logger (daemon shutdown). Safe to call when unset. */
+export function closeFileLogger() {
+    SINGLETON?.close();
+    SINGLETON = null;
+}
+//# sourceMappingURL=file-logger.js.map

package/dist/observability/file-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-logger.js","sourceRoot":"","sources":["../../src/observability/file-logger.ts"],"names":[],"mappings":"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"}

package/dist/observability/redact-secrets.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Security-critical redaction for the one-click operator debug report
+ * (issue #420 §4).
+ *
+ * Single source of truth for stripping secrets from anything that lands in a
+ * support bundle or an on-disk log file. Reuses the existing redaction
+ * primitives (`trajectory/secret-scrub.ts`, `util/redact-rpc-urls.ts`) and
+ * extends them with the secret surfaces enumerated in the issue:
+ *
+ *   - keystore password / JINN_PASSWORD
+ *   - private keys / mnemonics / seed phrases
+ *   - daemon API token / UI token / handshake key
+ *   - harness API keys (Anthropic / OpenAI / OpenRouter / Nous Portal)
+ *   - RPC URLs with embedded credential segments
+ *
+ * Two redaction layers run together:
+ *   1. key-name redaction — values of keys matching a secret-name pattern.
+ *   2. string-shape redaction — values that *look* like a secret (a bare
+ *      0x-64 hex string, a JWT) regardless of their key name.
+ *
+ * Wallet addresses (0x-40), RPC hostnames/paths, contract/deployment
+ * addresses and file paths are intentionally KEPT — they are public or
+ * needed to reproduce a network issue. See `buildRedactionReport`.
+ */
+/**
+ * Bumped whenever the redaction logic changes in a way that affects what is
+ * stripped. Recorded in `bundle-meta.json` so a bundle can be read against
+ * the redaction rules that produced it.
+ */
+export declare const REDACTION_VERSION = "2";
+/**
+ * Keep the host (and a coarse path shape) of an RPC URL but strip any
+ * embedded credential: userinfo, `/v3/<key>`-style key segments, and
+ * `?key=`/`?apikey=`-style query credentials.
+ *
+ * RPC URLs are intentionally kept in the bundle (per the issue's acceptance
+ * criteria) so a network issue can be reproduced — only the secret part is
+ * removed.
+ */
+export declare function redactRpcUrl(url: string): string;
+/**
+ * Deep-clone `value` and redact every secret it contains. Pure — the input is
+ * never mutated.
+ *
+ * - Object keys matching a secret-name pattern -> value replaced with a marker.
+ * - Object keys holding an RPC URL -> value run through `redactRpcUrl`.
+ * - Object keys holding a public on-chain identifier (request id / tx hash) ->
+ *   value kept verbatim, exempt from string-shape `hex64` redaction.
+ * - Any other string value -> secret-shaped substrings stripped.
+ * - Arrays and nested objects are walked recursively.
+ */
+export declare function redactValue(value: unknown): unknown;
+/**
+ * Redact a resolved `JinnConfig` for inclusion in the bundle. Thin wrapper
+ * over `redactValue` — the deep walk already handles every secret surface,
+ * including `rpcUrl`, nested `ui.token`/`ui.handshakeKey`, and any future
+ * config key matching a secret-name pattern.
+ */
+export declare function redactConfig(config: unknown): unknown;
+/**
+ * Generate `redaction-report.md` — the human-readable record of what the
+ * debug-report bundle strips and what it intentionally keeps. This file is
+ * the "redaction coverage documented" acceptance criterion for issue #420.
+ */
+export declare function buildRedactionReport(): string;