dsh-dlp 0.1.0

package/lib/types/paths.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The two classifications the guard floor runs on: which paths are credential
+ * material, and which tools can move data off the machine.
+ *
+ * Both tables are security invariants. Neither is settable from `cordis.yml`;
+ * the repo-local policy tier may only add to them.
+ * @module dsh-dlp/paths
+ */
+/** One credential-path pattern. */
+export interface CredentialPathRule {
+    readonly id: string;
+    readonly version: number;
+    /** Matched against a normalized, forward-slash path. */
+    readonly pattern: RegExp;
+}
+/**
+ * Paths whose contents are credentials. Reading any of them through a tool is
+ * denied unconditionally.
+ *
+ * Order matters only for reporting: the first match wins, so the specific
+ * rules precede the filename heuristic and an operator sees the precise rule
+ * id in the audit record.
+ *
+ * `$DSH_HOME/.credentials.yaml` is here because core permits it: the harness
+ * has no file-read restriction in any mode ("Reads pass through untouched:
+ * every mode permits reading"), so the provider token the agent itself
+ * authenticates with is agent-readable. That is the gap this table closes.
+ */
+export declare const CREDENTIAL_PATH_RULES: readonly CredentialPathRule[];
+/**
+ * Normalize one candidate path for matching: Windows separators become
+ * forward slashes, surrounding quotes come off, `~` expands to a
+ * root-anchored marker, `..` segments collapse so a traversal cannot hide a
+ * credential path from the table, and a trailing slash is dropped so `.env/`
+ * matches the same rule as `.env`.
+ * @param candidate - a raw string from tool arguments.
+ * @returns the normalized form the rules are matched against.
+ */
+export declare function normalizeCandidatePath(candidate: string): string;
+/**
+ * Whether one string names credential material. Pure: it never touches the
+ * filesystem, so a symlink is matched by the name it was given. The guard
+ * calls {@link matchPathArgument} instead, which resolves first.
+ * @param candidate - a raw string from tool arguments.
+ * @param rules - the rule table; defaults to {@link CREDENTIAL_PATH_RULES}.
+ * @returns the first matching rule, or `undefined`.
+ */
+export declare function matchCredentialPath(candidate: string, rules?: readonly CredentialPathRule[]): CredentialPathRule | undefined;
+/**
+ * Resolve one candidate through the filesystem so a symlink cannot rename a
+ * credential file out of the table.
+ * @param candidate - a raw string from tool arguments.
+ * @returns the canonical path, or `undefined` when it does not resolve.
+ */
+export declare function resolveCandidatePath(candidate: string): string | undefined;
+/**
+ * Match one path-typed argument against the credential table, by the name the
+ * caller used and by what that name resolves to.
+ * @param candidate - a raw string from a path-typed tool argument.
+ * @param rules - the rule table; defaults to {@link CREDENTIAL_PATH_RULES}.
+ * @returns the first matching rule, or `undefined`.
+ */
+export declare function matchPathArgument(candidate: string, rules?: readonly CredentialPathRule[]): CredentialPathRule | undefined;
+/**
+ * Split one shell command into the substrings worth testing as paths: the
+ * whole string, plus each shell-ish token. A `bash` command is a single string
+ * argument, so without tokenization `cat ~/.ssh/id_rsa && echo ok` would not
+ * match a rule anchored at the end of a path.
+ *
+ * This is advisory only. A shell command is a program, not a path, and any
+ * quoting, globbing, substitution or encoding defeats the split — see the
+ * "what this is not" section of README.md.
+ * @param text - one shell command line taken from tool arguments.
+ * @returns the whole string followed by its tokens.
+ */
+export declare function pathCandidates(text: string): string[];
+/**
+ * Argument keys whose values name filesystem paths.
+ *
+ * The guard tests these and nothing else. Running the credential-path table
+ * over every string argument matches file *content* — a `.gitignore` listing
+ * `.env`, an edit that mentions `id_rsa`, a grep pattern — and denies ordinary
+ * work with a message saying it cannot be overridden.
+ */
+export declare const PATH_ARGUMENT_KEYS: ReadonlySet<string>;
+/**
+ * Argument keys whose values are shell command lines. Their tokens are tested
+ * as paths; see {@link pathCandidates} for why that is advisory.
+ */
+export declare const SHELL_ARGUMENT_KEYS: ReadonlySet<string>;
+/** One string worth testing as a path, and how to split it. */
+export interface PathArgument {
+    readonly text: string;
+    /** Whether the string is a shell command line rather than a single path. */
+    readonly shell: boolean;
+}
+/**
+ * Collect the path-typed strings inside one tool's arguments, at any depth.
+ *
+ * A key names paths for every tool that uses it: the tool registry is open, so
+ * a per-tool table would abstain on every plugin and MCP tool this build has
+ * never heard of.
+ * @param args - the pending call's parsed arguments.
+ * @returns each path-typed string, labelled with whether it is a command line.
+ */
+export declare function pathArguments(args: unknown): PathArgument[];
+/**
+ * Tools that provably cannot move data off the machine: they read local
+ * state, edit local files, or talk only to the session itself.
+ *
+ * Anything absent from this set — every shell, `run_code`, the web tools,
+ * every `mcp__*` tool, and any plugin tool this build has never heard of — is
+ * treated as egress-capable. Unknown defaults to the safe side.
+ */
+export declare const LOCAL_TOOLS: ReadonlySet<string>;
+/**
+ * Whether a tool can move data off the machine.
+ * @param toolName - the executing tool's registered name.
+ * @param extraEgressTools - names the repo-local policy tier added.
+ * @returns `true` when the tool is not a known local-only tool.
+ */
+export declare function isEgressCapable(toolName: string, extraEgressTools?: ReadonlySet<string>): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/lib/types/policy.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Deployment configuration, the repo-local policy tier, and the tighten-only
+ * merge between them.
+ *
+ * Trust ranking, highest first:
+ *
+ * 1. invariants compiled into this package — the guard floor's tables; not configurable;
+ * 2. `cordis.yml` / bundle patch config — deployment-controlled; sets every field;
+ * 3. `policyFile` — a repo-local YAML file; **attacker-controlled**, may only tighten.
+ *
+ * Rank 3 is a file inside the workspace, so a hostile repository ships one and
+ * a prompt-injected agent can write one. It may add deny patterns, add egress
+ * tools, raise a severity, and switch a redaction pass on. Every other key,
+ * and every downgrade, is a load-time error rather than a silent ignore.
+ * @module dsh-dlp/policy
+ */
+import z from '@deepseek-ai/schemastery';
+import { type Severity, type SyncRule } from './detectors.ts';
+import { type CredentialPathRule } from './paths.ts';
+/** Deployment configuration, validated from `cordis.yml`. */
+export interface Config {
+    /** Absolute path of this plugin's own JSONL audit sink. Never the session log. */
+    auditLog: string;
+    /** Absolute path of the installation's redaction key; created with 32 random bytes if absent. */
+    redactionKeyFile: string;
+    /** Optional repo-local policy file; the lowest-trust source. */
+    policyFile?: string;
+    /** Cap on characters handed to a detector in one scan. */
+    maxScanBytes: number;
+    /** Whether the async `tools/pre-execute` secretlint pass runs. */
+    breadthTier: boolean;
+    /** Whether `tools/post-execute` redaction runs. */
+    resultRedaction: boolean;
+    /** Whether `session-telemetry/record` redaction runs. */
+    telemetryRedaction: boolean;
+    /** Whether telemetry's `session.cwd` attribute is replaced with a keyed hash. */
+    redactTelemetryWorkspacePaths: boolean;
+}
+export declare const Config: z<Config>;
+/** Config toggles a repo-local policy may switch on, and never off. */
+declare const ENABLEABLE: readonly ["breadthTier", "resultRedaction", "telemetryRedaction", "redactTelemetryWorkspacePaths"];
+/** One toggle name a repo-local policy may name in `enable`. */
+export type EnableableToggle = typeof ENABLEABLE[number];
+/** Payload version this package writes and accepts for repo-local policy files. */
+export declare const POLICY_VERSION = 1;
+/** A repo-local policy file after parsing and validation. */
+export interface RepoPolicy {
+    readonly addCredentialPaths: readonly CredentialPathRule[];
+    readonly addEgressTools: readonly string[];
+    readonly raiseSeverity: ReadonlyMap<string, Severity>;
+    readonly enable: readonly EnableableToggle[];
+}
+/** Everything the seams read after both tiers have been merged. */
+export interface ResolvedPolicy {
+    readonly credentialPathRules: readonly CredentialPathRule[];
+    readonly extraEgressTools: ReadonlySet<string>;
+    readonly syncRules: readonly SyncRule[];
+    readonly maxScanBytes: number;
+    readonly breadthTier: boolean;
+    readonly resultRedaction: boolean;
+    readonly telemetryRedaction: boolean;
+    readonly redactTelemetryWorkspacePaths: boolean;
+}
+/** Thrown when a policy file is malformed or attempts to loosen the policy. */
+export declare class PolicyError extends Error {
+    /**
+     * @param message - what the file did and why it is rejected.
+     */
+    constructor(message: string);
+}
+/**
+ * Parse and validate one repo-local policy document.
+ *
+ * Loaded under `js-yaml`'s `JSON_SCHEMA`, so a `!!js/function` tag is a parse
+ * error rather than code execution. This path deliberately never touches the
+ * Cordis loader, whose `!!js` support is the whole reason it must not see
+ * workspace-authored files.
+ * @param text - the file's contents.
+ * @returns the validated policy.
+ * @throws PolicyError on an unknown key, a bad value, or any attempt to loosen.
+ */
+export declare function parseRepoPolicy(text: string): RepoPolicy;
+/** Outcome of reading the file named by `policyFile`. */
+export type RepoPolicyLoad = 
+/** No file at that path: the workspace ships no policy. */
+{
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'loaded';
+    readonly policy: RepoPolicy;
+}
+/** Present but unreadable or invalid; `problem` is what to log. */
+ | {
+    readonly kind: 'invalid';
+    readonly problem: string;
+};
+/**
+ * Read a repo-local policy file from disk.
+ *
+ * Absence is not a misconfiguration here, which is the one place this package
+ * departs from "never silently skip a missing referent": `policyFile` names a
+ * path inside the *workspace*, and the recommended value is workspace-relative,
+ * so most repositories will not have one. Failing the mount would refuse to
+ * start `dsh` in every repository lacking the file — and would hand a hostile
+ * repository a way to remove the guard floor by deleting or breaking it.
+ * A malformed file is loud and ignored, never obeyed in part.
+ * @param path - the file to read.
+ * @returns the validated policy, its absence, or the problem to report.
+ */
+export declare function loadRepoPolicy(path: string): RepoPolicyLoad;
+/**
+ * Resolve the harness home the same way the harness does: `$DSH_HOME` when it
+ * is set to something other than whitespace, otherwise `~/.dsh`. Read here
+ * rather than through `@deepseek-ai/dsh-home-paths` to keep the plugin's
+ * runtime imports to the ones a profile is guaranteed to resolve.
+ * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
+ * @returns the absolute harness home.
+ */
+export declare function resolveDshHome(env?: NodeJS.ProcessEnv): string;
+/**
+ * Merge the deployment config with an optional repo-local policy.
+ * @param config - the deployment-controlled configuration.
+ * @param repo - the repo-local policy, when one is mounted.
+ * @returns the effective policy every seam reads.
+ */
+export declare function resolvePolicy(config: Config, repo?: RepoPolicy): ResolvedPolicy;
+export {};
+//# sourceMappingURL=policy.d.ts.map

package/lib/types/redaction.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Turning {@link Detection}s into redacted text, and the keyed hash that lets
+ * an operator correlate two placeholders without the plugin ever writing the
+ * secret.
+ *
+ * Two properties this module exists to hold:
+ *
+ * - **Spans are expanded before they are spliced.** Tier-2 spans are advisory
+ *   and verified to under-cover a secret, so every span grows outward to
+ *   whitespace boundaries and overlapping spans merge. Over-redaction is the
+ *   safe direction.
+ * - **The placeholder is deterministic.** `HMAC-SHA256(key, span)` truncated
+ *   to 12 hex characters — stable for the same secret under the same
+ *   installation key, useless to anyone without the key.
+ * @module dsh-dlp/redaction
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+import type { JsonValue } from '@deepseek-ai/dsh-session';
+import { type Detection, type Severity } from './detectors.ts';
+/** One replaced region, described without disclosing what it held. */
+export interface RedactedSpan {
+    /** Rule that justified the replacement; the strictest one when spans merged. */
+    readonly ruleId: string;
+    readonly ruleVersion: number;
+    readonly severity: Severity;
+    readonly start: number;
+    readonly end: number;
+    /** Keyed hash of the replaced text; never the text itself. */
+    readonly hash: string;
+    /** JSON pointer to the string this span came from, when the scan walked a structure. */
+    readonly path?: string;
+}
+/** Result of redacting one string. */
+export interface RedactedText {
+    readonly text: string;
+    readonly spans: readonly RedactedSpan[];
+}
+/**
+ * Mints the keyed hashes that appear in placeholders and audit records. Holds
+ * the installation key; the key never leaves this object.
+ */
+export declare class SpanHasher {
+    #private;
+    /**
+     * @param key - installation secret, at least 16 bytes, read from `redactionKeyFile`.
+     */
+    constructor(key: Buffer);
+    /**
+     * Keyed hash of one replaced region.
+     * @param text - the exact text being replaced.
+     * @returns 12 lowercase hex characters.
+     */
+    hash(text: string): string;
+}
+/**
+ * Shorten a rule id for the placeholder. Secretlint's package-qualified ids
+ * are long enough to dominate the replacement text.
+ * @param ruleId - the full rule identity.
+ * @returns the readable tail of the id.
+ */
+export declare function shortRuleId(ruleId: string): string;
+/**
+ * The text substituted for one redacted span.
+ * @param span - the span being replaced.
+ * @returns a stable placeholder carrying the rule and the keyed hash.
+ */
+export declare function placeholderFor(span: Pick<RedactedSpan, 'ruleId' | 'hash'>): string;
+/**
+ * Replace every detected region of one string with its placeholder.
+ * @param text - the string to redact.
+ * @param detections - matches reported by either detection tier.
+ * @param hasher - mints each span's keyed hash.
+ * @param path - JSON pointer recorded on every span, when scanning a structure.
+ * @returns the redacted string and the spans that were replaced.
+ */
+export declare function redactText(text: string, detections: readonly Detection[], hasher: SpanHasher, path?: string): RedactedText;
+/**
+ * Every string reachable inside a value, at any depth. Object keys are not
+ * included: a key is structure, not payload.
+ * @param value - parsed tool arguments, a tool's canonical output, or any JSON value.
+ * @returns each string found, in traversal order.
+ */
+export declare function nestedStrings(value: unknown): string[];
+/**
+ * Redact every string inside a JSON value, at any depth.
+ *
+ * Object *keys* are left alone: a key is structure, not payload, and renaming
+ * one would break the owning tool's `output.schema` on re-validation.
+ * @param value - the structure to redact.
+ * @param scan - synchronous detector applied to each string.
+ * @param hasher - mints each span's keyed hash.
+ * @returns the redacted structure, the spans replaced, and whether anything changed.
+ */
+export declare function redactJson(value: JsonValue, scan: (text: string) => readonly Detection[], hasher: SpanHasher): {
+    value: JsonValue;
+    spans: readonly RedactedSpan[];
+    changed: boolean;
+};
+/**
+ * Redact the text blocks of one model-facing content array. Non-text blocks
+ * pass through: this plugin has no detector for image or audio payloads and
+ * silently dropping them would be worse than leaving them.
+ * @param blocks - the content blocks to redact.
+ * @param scan - synchronous detector applied to each block's text.
+ * @param hasher - mints each span's keyed hash.
+ * @returns the redacted blocks, the spans replaced, and whether anything changed.
+ */
+export declare function redactContent(blocks: readonly ContentBlock[], scan: (text: string) => readonly Detection[], hasher: SpanHasher): {
+    content: ContentBlock[];
+    spans: readonly RedactedSpan[];
+    changed: boolean;
+};
+//# sourceMappingURL=redaction.d.ts.map

package/lib/types/results.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 type { PostToolDecision, PreToolDecision, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+import type { ResolvedPolicy } from './policy.ts';
+import { type RedactedSpan, type SpanHasher } from './redaction.ts';
+/** What a redaction pass produced, before an arm is chosen. */
+export interface ResultRedaction {
+    readonly decision: PostToolDecision;
+    readonly spans: readonly RedactedSpan[];
+    readonly truncatedScan: boolean;
+}
+/**
+ * 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 declare function redactDecision(decision: PostToolDecision, result: Readonly<ToolExecutionResult>, policy: ResolvedPolicy, hasher: SpanHasher): Promise<ResultRedaction>;
+/**
+ * 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 declare function evaluateBreadthTier(exec: Pick<ToolExecution, 'name' | 'arguments'>, policy: ResolvedPolicy, hasher: SpanHasher): Promise<{
+    reason: string;
+    spans: readonly RedactedSpan[];
+} | undefined>;
+/** A `PreToolDecision` denial built from a breadth-tier finding. */
+export declare function breadthTierDenial(reason: string): PreToolDecision;
+//# sourceMappingURL=results.d.ts.map

package/lib/types/sink.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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 type { RedactedSpan } from './redaction.ts';
+declare const decisionIdBrand: unique symbol;
+/** Producer-minted id correlating one decision across records. */
+export type DecisionId = string & {
+    readonly [decisionIdBrand]: true;
+};
+/**
+ * Mint a decision id.
+ * @returns an id unique to one guard verdict or redaction pass.
+ */
+export declare function newDecisionId(): DecisionId;
+/** Payload version carried inside every record this plugin writes. */
+export declare const RECORD_VERSION = 1;
+/** What produced one audit record. */
+export type AuditKind = 'guard-deny' | 'pre-execute-deny' | 'result-redaction' | 'telemetry-redaction' | 'audit-failure';
+/** One durable record. Never carries matched secret text. */
+export interface AuditRecord {
+    readonly v: number;
+    /** ISO-8601 capture time. */
+    readonly time: string;
+    readonly kind: AuditKind;
+    readonly decisionId: DecisionId;
+    readonly sessionId?: string;
+    readonly turn?: number;
+    readonly step?: number;
+    readonly callId?: string;
+    readonly rootCallId?: string;
+    readonly tool?: string;
+    /**
+     * Redacted or denied regions: rule identity, offsets, and a keyed hash only.
+     *
+     * This is the whole description of what matched. The model-facing denial
+     * text is deliberately not recorded: it names a tool and quotes nothing, but
+     * a reason built from a candidate would put the candidate — a shell command
+     * line, a tenant directory — into a durable file, which is exactly what this
+     * sink exists to avoid.
+     */
+    readonly spans?: readonly RedactedSpan[];
+    /** Set when the scanned input exceeded the byte cap. */
+    readonly truncatedScan?: boolean;
+    /** Telemetry record channel, for `telemetry-redaction`. */
+    readonly channel?: string;
+}
+/** Append-only JSONL sink for this plugin's decisions. */
+export declare class AuditSink {
+    #private;
+    /**
+     * @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: string, onFailure: (error: unknown) => void);
+    /**
+     * 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: AuditRecord): void;
+}
+/** Turn and step of one in-flight tool call. */
+export interface CallPosition {
+    readonly turn: number;
+    readonly step: number;
+}
+/**
+ * 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 declare class CallCorrelator {
+    #private;
+    /**
+     * @param limit - maximum remembered calls; the oldest entry is dropped past it.
+     */
+    constructor(limit?: number);
+    /**
+     * 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: string, position: CallPosition): void;
+    /**
+     * Forget one call.
+     * @param callId - the call whose result has been committed.
+     */
+    forget(callId: string): void;
+    /**
+     * 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: string): CallPosition | undefined;
+}
+export {};
+//# sourceMappingURL=sink.d.ts.map

package/lib/types/telemetry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 type { SessionTelemetryRecord } from '@deepseek-ai/dsh-session-telemetry';
+import type { ResolvedPolicy } from './policy.ts';
+import { type RedactedSpan, type SpanHasher } from './redaction.ts';
+/** Rule identity recorded when a workspace path is replaced. */
+export declare const WORKSPACE_PATH_RULE = "dsh-dlp/telemetry-workspace-path";
+/** One redacted telemetry record and what was replaced in it. */
+export interface RedactedRecord {
+    readonly record: SessionTelemetryRecord;
+    readonly spans: readonly RedactedSpan[];
+}
+/**
+ * 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 declare function redactRecord(record: SessionTelemetryRecord, policy: ResolvedPolicy, hasher: SpanHasher): RedactedRecord;
+//# sourceMappingURL=telemetry.d.ts.map