dsh-dlp 0.1.0

package/lib/results.js

@@ -0,0 +1,238 @@
+/**
+ * The two result-side seams: the async argument breadth tier at
+ * `tools/pre-execute`, and result redaction at `tools/post-execute`.
+ *
+ * Both are best-effort by construction. A `tools/pre-execute` listener
+ * registered ahead of ours can return without calling `next()` and neutralize
+ * the breadth tier; a `tools/post-execute` listener ahead of ours can replace a
+ * result after we redacted it. Only `ctx.tools.guard()` is order-independent.
+ * What these seams buy is breadth: they can await, so `@secretlint/core`'s
+ * whole rule set applies here and not in the guard.
+ * @module dsh-dlp/results
+ */
+import { DENY_SEVERITY, scanAll, scanSync, severityRank, } from "./detectors.js";
+import { isEgressCapable } from "./paths.js";
+import { nestedStrings, redactContent, redactJson } from "./redaction.js";
+/**
+ * Separator the strings of one result are rendered with before the
+ * cross-string scan. A newline is what the reader of a tool result sees
+ * between two lines of a file, and it keeps every `\b` and `^` anchor a
+ * per-string scan would have honoured.
+ */
+const RENDER_SEPARATOR = '\n';
+/**
+ * Scan a set of strings once and hand back a synchronous lookup, so the
+ * redaction walkers stay synchronous while detection stays async.
+ *
+ * The strings are scanned twice over: each on its own by tier 1, and all of
+ * them joined by both tiers. The joined pass is what finds a secret split
+ * across strings — a PEM block arriving as one `lines[i].text` per line, a
+ * token spanning two content blocks — which no per-string walk can see; its
+ * offsets are then mapped back onto the individual strings, because that is
+ * what the redaction walkers splice.
+ *
+ * Tier 2 runs once, over the joined text, and is budgeted by characters
+ * through `maxScanBytes`. One `lintSource` call per string would multiply a
+ * fixed per-call cost by however many pieces the tool happened to split its
+ * output into, and a budget counted in strings would make how much of a result
+ * is scanned depend on the same accident.
+ * @param strings - every string that will be redacted, in render order.
+ * @param policy - the effective policy.
+ * @returns a memoized lookup and whether tier 2 saw less than the whole rendering.
+ */
+async function prepareScan(strings, policy) {
+    const rendered = strings.join(RENDER_SEPARATOR);
+    const { detections, truncated } = await scanAll(rendered, policy.syncRules, policy.maxScanBytes);
+    const memo = new Map();
+    const found = (text) => {
+        const existing = memo.get(text);
+        if (existing !== undefined)
+            return existing;
+        const created = [...scanSync(text, policy.syncRules).detections];
+        memo.set(text, created);
+        return created;
+    };
+    let offset = 0;
+    for (const text of strings) {
+        const start = offset;
+        const end = start + text.length;
+        offset = end + RENDER_SEPARATOR.length;
+        const local = found(text);
+        for (const detection of detections) {
+            if (detection.end <= start || detection.start >= end)
+                continue;
+            local.push({
+                ...detection,
+                start: Math.max(0, detection.start - start),
+                end: Math.min(text.length, detection.end - start),
+            });
+        }
+    }
+    /* v8 ignore next -- every string handed to the walkers was collected for this memo. */
+    return { scan: text => memo.get(text) ?? [], truncated };
+}
+/** Text carried by a content array's text blocks. */
+function contentStrings(blocks) {
+    return blocks.flatMap(block => block.type === 'text' ? [block.text] : []);
+}
+/**
+ * Strings the harness keeps in the durable result when the decision does not
+ * replace the canonical value.
+ *
+ * `tools/post-execute` returning `accept{content}` leaves `{...result}` in
+ * place, so both `value` and the `presentationMeta()` projection reach
+ * `session.append('tool/result', ...)` exactly as the tool produced them. They
+ * are never model-visible and therefore never redacted by a content
+ * replacement — which is why a content arm is not an option for a dirty
+ * success.
+ * @param result - the dispatch outcome the waterfall was called with.
+ * @returns every string that would be persisted verbatim.
+ */
+function persistedStrings(result) {
+    return [
+        ...result.isError ? [] : nestedStrings(result.value),
+        ...result.meta === undefined ? [] : nestedStrings(result.meta),
+    ];
+}
+/** Feedback for a result this plugin refuses to let through in any arm. */
+function withheldFeedback(spans) {
+    const rules = [...new Set(spans.map(span => span.ruleId))].join(', ');
+    const hashes = [...new Set(spans.map(span => span.hash))].join(', ');
+    return [{
+            type: 'text',
+            text: 'dsh-dlp withheld this tool result: it carries credential material '
+                + `(rule ${rules}, keyed hash ${hashes}) in a part of the result that cannot be rewritten without `
+                + 'discarding it. Do not retry the same call. Ask the user for the value you need, or work from a source '
+                + 'that is not a credential store.',
+        }];
+}
+/**
+ * Redact whatever the downstream decision settled on.
+ *
+ * Arm selection follows what each arm can actually clean:
+ *
+ * - `accept{value}` re-validates `output.schema`, re-runs `output.render()`
+ *   and re-derives `presentationMeta()`, so one replacement redacts the
+ *   canonical value, the model-facing content and the persisted meta together.
+ *   It is the only arm that keeps a secret out of the durable log, so every
+ *   successful result with anything to redact takes it.
+ * - `accept{content}` replaces presentation only. It is used when the
+ *   persisted surfaces are already clean — a failed result, which has no
+ *   value, or a success whose secret exists only in the rendered content.
+ * - `block` is the fallback when neither works: a failed result whose `meta`
+ *   carries a secret, or a value that still scans dirty after redaction.
+ *   Blocking replaces the whole result, which is the only way to drop `meta`.
+ *
+ * Replacing the value can fail: the placeholder is re-validated against the
+ * tool's `output.schema`, and a schema that constrains the string rejects it,
+ * which the registry reports as a `ToolOutputError`. A failed call is the
+ * intended outcome there — see README.md.
+ *
+ * A downstream `accept{content}` over a dirty value is overruled by the value
+ * arm, which discards that listener's presentation choice. Keeping it would
+ * put the value in the session log; the harness re-renders from the redacted
+ * value instead.
+ * @param decision - what the rest of the waterfall returned.
+ * @param result - the dispatch outcome the waterfall was called with.
+ * @param policy - the effective policy.
+ * @param hasher - mints each span's keyed hash.
+ * @returns the decision to return, the spans replaced, and scan completeness.
+ */
+export async function redactDecision(decision, result, policy, hasher) {
+    if (decision.kind === 'block') {
+        const prepared = await prepareScan(contentStrings(decision.feedback), policy);
+        const redacted = redactContent(decision.feedback, prepared.scan, hasher);
+        return {
+            decision: redacted.changed ? { ...decision, feedback: redacted.content } : decision,
+            spans: redacted.spans,
+            truncatedScan: prepared.truncated,
+        };
+    }
+    const replacedValue = Object.hasOwn(decision, 'value') ? decision.value : undefined;
+    const replacedContent = Object.hasOwn(decision, 'content') ? decision.content : undefined;
+    const contexts = decision.additionalContexts === undefined
+        ? {}
+        : { additionalContexts: decision.additionalContexts };
+    // The value the harness will persist: a downstream replacement when there is
+    // one, otherwise the tool's own. A failed result has no value at all.
+    const value = replacedValue ?? (result.isError ? undefined : result.value);
+    const visible = contentStrings(replacedContent ?? result.content);
+    const persisted = replacedValue === undefined
+        ? persistedStrings(result)
+        : [...nestedStrings(replacedValue), ...result.meta === undefined ? [] : nestedStrings(result.meta)];
+    const prepared = await prepareScan([...persisted, ...visible], policy);
+    const dirty = (strings) => strings.some(text => prepared.scan(text).length > 0);
+    if (value !== undefined && dirty(nestedStrings(value))) {
+        const redacted = redactJson(value, prepared.scan, hasher);
+        const remaining = nestedStrings(redacted.value);
+        const residual = await prepareScan(remaining, policy);
+        if (remaining.some(text => residual.scan(text).length > 0)) {
+            return {
+                decision: { kind: 'block', feedback: withheldFeedback(redacted.spans) },
+                spans: redacted.spans,
+                truncatedScan: prepared.truncated || residual.truncated,
+            };
+        }
+        return {
+            decision: { kind: 'accept', value: redacted.value, ...contexts },
+            spans: redacted.spans,
+            truncatedScan: prepared.truncated,
+        };
+    }
+    // The value is clean, so the durable result is clean unless `meta` — which
+    // no accept arm can rewrite — carries something of its own.
+    if (result.meta !== undefined && dirty(nestedStrings(result.meta))) {
+        const spans = redactJson(result.meta, prepared.scan, hasher).spans;
+        return {
+            decision: { kind: 'block', feedback: withheldFeedback(spans) },
+            spans,
+            truncatedScan: prepared.truncated,
+        };
+    }
+    const blocks = replacedContent ?? result.content;
+    const redacted = redactContent(blocks, prepared.scan, hasher);
+    if (!redacted.changed) {
+        return { decision, spans: [], truncatedScan: prepared.truncated };
+    }
+    return {
+        decision: { kind: 'accept', content: redacted.content, ...contexts },
+        spans: redacted.spans,
+        truncatedScan: prepared.truncated,
+    };
+}
+/**
+ * Decide whether the breadth tier denies one call before dispatch.
+ *
+ * Only ever narrows: the caller has already delegated, and a decision that is
+ * not `allow` is returned untouched.
+ * @param exec - the pending call.
+ * @param policy - the effective policy.
+ * @param hasher - mints the keyed hashes quoted in a denial reason.
+ * @returns the denial reason and its spans, or `undefined` to leave the call allowed.
+ */
+export async function evaluateBreadthTier(exec, policy, hasher) {
+    if (!isEgressCapable(exec.name, policy.extraEgressTools))
+        return undefined;
+    const spans = [];
+    for (const text of new Set(nestedStrings(exec.arguments))) {
+        const { detections } = await scanAll(text, policy.syncRules, policy.maxScanBytes);
+        for (const detection of detections) {
+            if (severityRank(detection.severity) < severityRank(DENY_SEVERITY))
+                continue;
+            spans.push({ ...detection, hash: hasher.hash(text.slice(detection.start, detection.end)) });
+        }
+    }
+    if (spans.length === 0)
+        return undefined;
+    const ruleIds = [...new Set(spans.map(span => span.ruleId))];
+    return {
+        reason: `dsh-dlp denied ${JSON.stringify(exec.name)}: its arguments contain credential material matching `
+            + `${ruleIds.join(', ')} (keyed hash ${spans.map(span => span.hash).join(', ')}). `
+            + 'Remove the credential from the call.',
+        spans,
+    };
+}
+/** A `PreToolDecision` denial built from a breadth-tier finding. */
+export function breadthTierDenial(reason) {
+    return { kind: 'deny', reason };
+}

package/lib/sink.js

@@ -0,0 +1,105 @@
+/**
+ * This plugin's own durable output, and the call correlation that makes a
+ * record locatable.
+ *
+ * Nothing here touches the session log. `Session.append()` offers no way to
+ * set the envelope's `ignorable` flag, so an out-of-repo event type is written
+ * without it and the user's next resume throws `SessionFormatUnsupportedError`
+ * and refuses the whole session. The plugin is therefore read-side with
+ * respect to the log, and every durable record goes to the JSONL file named by
+ * `auditLog`.
+ *
+ * Because the `SessionEvent` envelope carries only `type`, `seq`, `time` and
+ * `data`, each record carries its own identity: `sessionId`, `turn`, `step`,
+ * `callId`, and a producer-minted `decisionId`.
+ * @module dsh-dlp/sink
+ */
+import { appendFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+/**
+ * Mint a decision id.
+ * @returns an id unique to one guard verdict or redaction pass.
+ */
+export function newDecisionId() {
+    return `dlp-${randomUUID()}`;
+}
+/** Payload version carried inside every record this plugin writes. */
+export const RECORD_VERSION = 1;
+/** Append-only JSONL sink for this plugin's decisions. */
+export class AuditSink {
+    #path;
+    #onFailure;
+    /**
+     * @param path - absolute path of the JSONL file to append to.
+     * @param onFailure - notified when a write fails; a broken sink never changes a verdict.
+     */
+    constructor(path, onFailure) {
+        this.#path = path;
+        this.#onFailure = onFailure;
+    }
+    /**
+     * Append one record.
+     *
+     * A write failure is reported and swallowed on purpose: the sink is
+     * evidence, not enforcement, and letting a full disk turn every tool call
+     * into a denial trades a confidentiality control for an availability
+     * outage. A guard that throws would also skip `tools/post-execute` and so
+     * disable redaction for that call.
+     * @param record - the decision to record.
+     */
+    write(record) {
+        try {
+            appendFileSync(this.#path, `${JSON.stringify(record)}\n`);
+        }
+        catch (error) {
+            this.#onFailure(error);
+        }
+    }
+}
+/**
+ * Remembers where each in-flight tool call sits in the session.
+ *
+ * `Agent` exposes no turn or step, and the tool pipeline hands listeners only
+ * a `ToolExecution`. The `tool/call` session event carries `turn`, `step` and
+ * `callId` together, so following the session firehose is the only way to
+ * label a record with its position.
+ */
+export class CallCorrelator {
+    #positions = new Map();
+    #limit;
+    /**
+     * @param limit - maximum remembered calls; the oldest entry is dropped past it.
+     */
+    constructor(limit = 512) {
+        this.#limit = limit;
+    }
+    /**
+     * Record one call's position.
+     * @param callId - the call's id from the `tool/call` event.
+     * @param position - the turn and step that event reported.
+     */
+    note(callId, position) {
+        this.#positions.set(callId, position);
+        if (this.#positions.size > this.#limit) {
+            const oldest = this.#positions.keys().next();
+            /* v8 ignore next -- reached only past the limit, so the map is never empty here. */
+            if (!oldest.done)
+                this.#positions.delete(oldest.value);
+        }
+    }
+    /**
+     * Forget one call.
+     * @param callId - the call whose result has been committed.
+     */
+    forget(callId) {
+        this.#positions.delete(callId);
+    }
+    /**
+     * Look one call's position up.
+     * @param callId - the call to locate.
+     * @returns its turn and step, or `undefined` when the call was never seen.
+     */
+    lookup(callId) {
+        return this.#positions.get(callId);
+    }
+}

package/lib/telemetry.js

@@ -0,0 +1,80 @@
+/**
+ * Fail-closed redaction for exported telemetry.
+ *
+ * `DSH_TELEMETRY_MODE=FULL` mounts the OTel backend with a live coordinator
+ * that exports a deep copy of every session event's `data` — user and
+ * assistant message text, tool arguments, tool results — plus identity
+ * attributes including `session.cwd`. The `session-telemetry/record` waterfall
+ * is the documented redaction seam and it ships **no rules of its own**: with
+ * nothing mounted, records reach the exporter exactly as captured. This
+ * listener is the missing rule set.
+ *
+ * The waterfall is synchronous (`next: () => SessionTelemetryRecord`), so only
+ * tier 1 is reachable here — there is no seam on this path that can await, and
+ * a secret only `@secretlint/core` recognises survives it. It is fail-closed
+ * by construction: the coordinator dispatches inside its own containment, and a
+ * throwing listener withholds that one record and never reaches the agent
+ * loop. This module therefore throws rather than returning a record it could
+ * not fully process.
+ *
+ * Records mirroring `tool/result` have already been through
+ * `tools/post-execute` redaction, which runs before the event is appended —
+ * but only for what that seam could reach, so this listener re-scans every
+ * record rather than trusting the event type. The value it adds beyond that is
+ * on `user/message`, `assistant/message`, `tool/call` arguments, and the
+ * workspace path.
+ * @module dsh-dlp/telemetry
+ */
+import { scanSync } from "./detectors.js";
+import { placeholderFor, redactJson, redactText } from "./redaction.js";
+/** Attribute keys whose values are filesystem paths rather than payload text. */
+const PATH_ATTRIBUTES = ['session.cwd'];
+/** Rule identity recorded when a workspace path is replaced. */
+export const WORKSPACE_PATH_RULE = 'dsh-dlp/telemetry-workspace-path';
+/**
+ * Redact one outbound telemetry record.
+ *
+ * The record is treated as data, not as a typed structure: `body` is the
+ * event's own `data`, whose shape is owned by whichever package declared the
+ * event, and new event types appear without this plugin knowing them. Walking
+ * it as JSON is what makes the listener total.
+ * @param record - the candidate record, already the coordinator's own deep copy.
+ * @param policy - the effective policy.
+ * @param hasher - mints each span's keyed hash.
+ * @returns the record to hand onward and the spans replaced.
+ */
+export function redactRecord(record, policy, hasher) {
+    const spans = [];
+    const scan = (text) => scanSync(text, policy.syncRules).detections;
+    // `body` is `unknown` on the seam but is always the append-time-validated,
+    // JSON-serializable `data` of a session event.
+    const body = redactJson(record.body, scan, hasher);
+    spans.push(...body.spans);
+    const attributes = {};
+    for (const [key, value] of Object.entries(record.attributes)) {
+        if (typeof value !== 'string') {
+            attributes[key] = value;
+            continue;
+        }
+        if (policy.redactTelemetryWorkspacePaths && PATH_ATTRIBUTES.includes(key)) {
+            const span = {
+                ruleId: WORKSPACE_PATH_RULE,
+                ruleVersion: 1,
+                severity: 'medium',
+                start: 0,
+                end: value.length,
+                hash: hasher.hash(value),
+                path: `/attributes/${key}`,
+            };
+            spans.push(span);
+            attributes[key] = placeholderFor(span);
+            continue;
+        }
+        const redacted = redactText(value, scan(value), hasher, `/attributes/${key}`);
+        spans.push(...redacted.spans);
+        attributes[key] = redacted.text;
+    }
+    if (spans.length === 0)
+        return { record, spans };
+    return { record: { ...record, body: body.value, attributes }, spans };
+}

package/lib/types/detectors.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Two detection tiers and the vocabulary they share.
+ *
+ * Tier 1 is a synchronous table of prefix-anchored token formats, owned here
+ * because two of the three seams this plugin uses are synchronous:
+ * `ToolGuard` returns `string | undefined` and the `session-telemetry/record`
+ * waterfall returns a record, neither of which can await. Tier 2 wraps
+ * `@secretlint/core`, which runs in-process with no subprocess but resolves a
+ * promise, so it is reachable only from `tools/pre-execute` and
+ * `tools/post-execute`.
+ *
+ * Neither tier ever returns the matched text. A {@link Detection} carries
+ * offsets; turning offsets into a keyed hash is `redaction.ts`'s job.
+ * @module dsh-dlp/detectors
+ */
+/**
+ * How badly a match should be treated. Ordered: {@link severityRank} compares
+ * two values, and the repo-local policy tier may only move a rule upward.
+ */
+export type Severity = 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Position of a severity in the ordering.
+ * @param severity - the value to rank.
+ * @returns its index in the ascending order; higher means stricter.
+ */
+export declare function severityRank(severity: Severity): number;
+/** Severity at or above which the guard floor denies rather than only redacting. */
+export declare const DENY_SEVERITY: Severity;
+/** One match, described without disclosing what matched. */
+export interface Detection {
+    /** Rule identity, stable across versions of this package. */
+    readonly ruleId: string;
+    /** Bumped whenever the rule's pattern changes, so an old audit record stays interpretable. */
+    readonly ruleVersion: number;
+    readonly severity: Severity;
+    /** Inclusive start offset into the scanned string. */
+    readonly start: number;
+    /** Exclusive end offset into the scanned string. */
+    readonly end: number;
+}
+/** Outcome of one scan. */
+export interface ScanResult {
+    readonly detections: readonly Detection[];
+    /** Whether tier 2 saw only part of the input because of the byte cap. */
+    readonly truncated: boolean;
+}
+/** One synchronous rule in tier 1. */
+export interface SyncRule {
+    readonly id: string;
+    readonly version: number;
+    readonly severity: Severity;
+    /** Global-flagged; matched through `matchAll`, which never mutates this instance's `lastIndex`. */
+    readonly pattern: RegExp;
+}
+/**
+ * Tier 1's rule table. Deliberately narrow: only formats whose prefix or
+ * delimiters make a match structurally unambiguous, plus PEM blocks and
+ * credential-bearing URLs. Anything requiring entropy heuristics is left to
+ * tier 2, where a false positive costs a redaction rather than a denial.
+ */
+export declare const SYNC_RULES: readonly SyncRule[];
+/**
+ * Scan text with tier 1. Pure, synchronous, no I/O, and never capped: a table
+ * of anchored regular expressions costs a linear pass, so there is no reason
+ * to stop scanning where tier 2 has to. `truncated` is therefore always
+ * `false` here and only tier 2 can set it.
+ * @param text - the string to scan.
+ * @param rules - the rule table to apply; defaults to {@link SYNC_RULES}.
+ * @returns every match, ordered by start offset.
+ */
+export declare function scanSync(text: string, rules?: readonly SyncRule[]): ScanResult;
+/**
+ * Major version of the pinned `@secretlint/core` rule set, recorded as the
+ * rule version of every tier-2 detection. The exact dependency version is
+ * pinned in this package's manifest; the major is what changes a rule's
+ * meaning.
+ */
+export declare const SECRETLINT_RULE_VERSION = 13;
+/**
+ * Scan text with tier 2 (`@secretlint/core`, recommended preset). Runs
+ * in-process; no subprocess and no network.
+ *
+ * The reported spans are advisory. `@secretlint/secretlint-rule-aws` reports
+ * `[0, 40]` for `aws_secret_access_key = <40 chars>`, which covers the
+ * assignment prefix rather than the whole secret, so a caller must never
+ * splice a reported span directly — {@link redactText} expands every span to
+ * whitespace boundaries first.
+ * @param text - the string to scan.
+ * @param maxScanBytes - cap on scanned characters; input beyond it is not examined.
+ * @returns every match, ordered by start offset, and whether the input was capped.
+ */
+export declare function scanWithSecretlint(text: string, maxScanBytes?: number): Promise<ScanResult>;
+/**
+ * Run both tiers over one string and merge their detections. Tier 1 sees the
+ * whole string; only tier 2 is capped.
+ * @param text - the string to scan.
+ * @param rules - tier-1 rule table.
+ * @param maxScanBytes - cap on characters handed to tier 2.
+ * @returns the union of both tiers, ordered by start offset.
+ */
+export declare function scanAll(text: string, rules?: readonly SyncRule[], maxScanBytes?: number): Promise<ScanResult>;
+//# sourceMappingURL=detectors.d.ts.map

package/lib/types/guard.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The guard floor: the one part of this plugin that holds under attack.
+ *
+ * It tests the path-typed arguments of a call — never file content — against
+ * the credential table, resolving symlinks first, and the whole argument set
+ * against the tier-1 detectors when the tool can move data off the machine.
+ * The `command` arm inside that is advisory pattern-matching: tokenising a
+ * shell command line catches `cat ~/.ssh/id_rsa` and loses to one glob
+ * character. README.md says so plainly and so does this comment.
+ *
+ * `ctx.tools.guard()` takes a synchronous `(exec) => string | undefined`. It
+ * has no allow arm, so no registration order can turn a denial back into
+ * permission, and the first denial wins. It runs after the whole
+ * `tools/pre-execute` waterfall and after `ctx.approval`, which is why the
+ * floor lives here rather than in a listener: `exec.arguments` is deep-frozen
+ * but `exec` itself is not frozen until after execution, so a pre-execute
+ * listener can reassign `exec.arguments` or `exec.name` and succeed. The guard
+ * reads what every listener finally left behind.
+ *
+ * Registered on a plain context, never through `agent.ctx`: a global guard
+ * covers every agent, every `run_code` inner sub-call, and every subagent
+ * child, while an agent-scoped listener never sees a subagent child's calls
+ * because a child agent is a sibling, not a descendant.
+ *
+ * The floor is not configurable. Per CONVENTIONS, security invariants stay
+ * fixed; the repo-local policy tier may only add to its tables.
+ * @module dsh-dlp/guard
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { ResolvedPolicy } from './policy.ts';
+import { type RedactedSpan, type SpanHasher } from './redaction.ts';
+/** Why the floor denied one call. */
+export interface GuardVerdict {
+    readonly kind: 'credential-path' | 'secret-argument' | 'internal-fault';
+    /** Model-facing text; carries rule identities and keyed hashes, never matched values. */
+    readonly reason: string;
+    /** The offending regions, described by rule identity, offsets, and keyed hash only. */
+    readonly spans: readonly RedactedSpan[];
+}
+/**
+ * Decide whether the floor denies one call.
+ *
+ * Credential paths are denied for every tool, not only readers: a shell that
+ * can `cat` a key can also copy it. Only path-typed arguments are tested —
+ * running the table over every string matches file content and denies writing
+ * a `.gitignore` that mentions `.env`. Argument secrets are denied only for
+ * egress-capable tools, because denying a local editor for holding the text it
+ * was asked to write would break ordinary work without closing an exfiltration
+ * path.
+ * @param exec - the pending call as the guard stage sees it.
+ * @param policy - the effective policy after the tighten-only merge.
+ * @param hasher - mints the keyed hashes quoted in a denial reason.
+ * @returns the denial, or `undefined` to abstain.
+ */
+export declare function evaluateGuard(exec: Pick<ToolExecution, 'name' | 'arguments'>, policy: ResolvedPolicy, hasher: SpanHasher): GuardVerdict | undefined;
+/**
+ * Wrap {@link evaluateGuard} so an internal fault becomes a denial.
+ *
+ * A guard that throws fails the call closed *and* skips `tools/post-execute`,
+ * which would silently disable result redaction for that call. Converting the
+ * fault into a denial string keeps the post-execute stage running.
+ * @param exec - the pending call.
+ * @param policy - the effective policy.
+ * @param hasher - mints the keyed hashes quoted in a denial reason.
+ * @returns the denial, or `undefined` to abstain.
+ */
+export declare function safeEvaluateGuard(exec: Pick<ToolExecution, 'name' | 'arguments'>, policy: ResolvedPolicy, hasher: SpanHasher): GuardVerdict | undefined;
+//# sourceMappingURL=guard.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `dsh-dlp` — data-loss prevention for DeepSeek Harness.
+ *
+ * Four registrations, in descending order of how much they can be trusted:
+ *
+ * 1. `ctx.tools.guard()` — an unconditional, non-configurable deny floor for
+ *    credential paths named in a path-typed argument and for secrets heading
+ *    into an egress-capable tool. Order-independent, because the guard seam
+ *    has no allow arm.
+ * 2. `tools/pre-execute` — the async breadth tier, which can await
+ *    `@secretlint/core`. Neutralizable by any listener registered ahead of it.
+ * 3. `tools/post-execute` — result redaction, applied before the `tool/result`
+ *    session event is appended, so the durable log records the redacted copy;
+ *    a result that cannot be cleaned is withheld rather than accepted.
+ * 4. `session-telemetry/record` — fail-closed redaction of exported telemetry,
+ *    reaching tier 1 only because the waterfall is synchronous.
+ *
+ * This plugin is not a containment boundary. It runs in-process at the agent's
+ * own uid; anything the agent can execute can read the same files the guard
+ * denies. See README.md.
+ * @module dsh-dlp
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type Config } from './policy.ts';
+export { Config } from './policy.ts';
+/** Display metadata; labels the plugin in Cordis diagnostics. */
+export declare const name = "dsh-dlp";
+/** Services required before `apply` runs. */
+export declare const inject: string[];
+/**
+ * Read the installation's redaction key, creating it on first mount.
+ *
+ * The key makes every placeholder a keyed hash rather than a bare digest:
+ * without it, anyone holding a candidate secret could confirm it against the
+ * audit log.
+ * @param path - the key file named by `redactionKeyFile`.
+ * @returns the key bytes.
+ * @throws when an existing key file is too short to be a key.
+ */
+export declare function loadOrCreateKey(path: string): Buffer;
+/**
+ * Mount the plugin.
+ * @param ctx - the plugin's context; every registration is undone on unload.
+ * @param config - validated `cordis.yml` configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map