dsh-dlp 0.2.0 → 0.4.0

package/lib/types/detectors.d.ts

@@ -64,6 +64,11 @@ export interface SyncRule {
  * 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.
+ *
+ * Prefix-anchored is the whole membership criterion, and the reason this table
+ * keeps growing rather than deferring to tier 2: the `session-telemetry/record`
+ * waterfall is synchronous and cannot reach tier 2 at all, so a format missing
+ * here is exported in the clear when telemetry is on.
  */
 export declare const SYNC_RULES: readonly SyncRule[];
 /**
@@ -72,8 +77,14 @@ export declare const SYNC_RULES: readonly SyncRule[];
  *
  * `strip` classes have no legitimate use in tool output, so they are replaced
  * like any other detection. `report` classes do: `U+200D` joins an emoji
- * sequence and a variation selector chooses a glyph, so replacing them would
- * corrupt ordinary text. They are counted and never rewritten.
+ * sequence, a variation selector chooses a glyph, and a CSI sequence colours
+ * the output of `git diff`, so replacing them would corrupt ordinary text.
+ * They are counted and never rewritten.
+ *
+ * The split is per class and per lane both: {@link stripControlSequences}
+ * applies the `strip` treatment to a `report` class on the audit and
+ * approval-facing lanes, where colour buys nothing and a forged record costs
+ * everything.
  */
 export type UnicodeAction = 'strip' | 'report';
 /** One class of invisible or direction-changing characters. */
@@ -84,12 +95,37 @@ export interface UnicodeRule {
     readonly action: UnicodeAction;
     /** Global, unicode-flagged, matching one run of this class. */
     readonly pattern: RegExp;
-    /** The class's ranges as a character-class body, for the combined run pattern. */
-    readonly ranges: string;
+    /**
+     * The class's ranges as a character-class body, for the combined run pattern.
+     *
+     * Absent for a class whose matches are not a run of one character class —
+     * a terminal control sequence has an ASCII body — which is scanned over the
+     * whole input instead of within a combined run.
+     */
+    readonly ranges?: string;
 }
+/**
+ * Text substituted for a stripped control sequence. Visible on purpose: the
+ * lanes that strip are the ones an operator reads as evidence, and silently
+ * deleting the bytes would hide that a forgery was attempted.
+ */
+export declare const CONTROL_SEQUENCE_PLACEHOLDER = "[REDACTED:dsh-dlp:control-sequence]";
+/**
+ * Remove every terminal control sequence from one string.
+ *
+ * This is the `strip` half of {@link CONTROL_SEQUENCE_RULE}, applied on the
+ * lanes that must never carry forgeable bytes: an audit record and the strings
+ * an operator or an approval prompt reads back. Ordinary tool-result text takes
+ * the `report` half instead, because `git diff`, `rg` and `pytest` legitimately
+ * colourise their output.
+ * @param text - the string to clean.
+ * @returns the string with each control sequence replaced by a visible marker.
+ */
+export declare function stripControlSequences(text: string): string;
 /**
  * Character classes that hide text from the reader while the model still reads
- * it, verified against the Unicode character database.
+ * it, verified against the Unicode character database, plus the terminal
+ * control sequences that show the reader something other than what is there.
  *
  * Every class is `medium`. These are injection *indicators*, not credentials:
  * the guard floor denies at `high` and above, so an argument carrying one is

package/lib/types/images.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Neutralising remote markdown images in assistant output, on the `llm/stream`
+ * waterfall.
+ *
+ * The web UI renders any absolute `http:`/`https:` markdown image a model
+ * emits as a real `<img src>`, and the harness sets no Content-Security-Policy,
+ * so the fetch happens in the user's browser where no host-side listener can
+ * see it. This module rewrites the destination out of the assistant's text
+ * before it becomes an `assistant/chunk` or `assistant/message` session event,
+ * so the log and the rendered answer stay in agreement.
+ *
+ * Two properties this module exists to hold:
+ *
+ * - **A destination split across chunks is still caught.** The mock and real
+ *   adapters both emit text in small deltas, so `![alt](https://host/x)` is
+ *   routinely spread over several of them and the browser renders the
+ *   accumulation. Text that could still be the start of an image is held back
+ *   until it either completes or exceeds {@link MAX_HELD_CHARACTERS}.
+ * - **Only the destination is replaced.** The alt text survives, so the
+ *   sentence the model wrote still reads, and the renderer's own
+ *   non-absolute-URL arm shows that alt text instead of fetching anything.
+ *
+ * This does not close the channel. It matches inline image syntax only:
+ * reference-style images, an alt text carrying a `]`, and any destination form
+ * the pattern does not model still reach the renderer. Raw HTML needs no
+ * handling — the renderer keeps it as literal text and no HTML enters the DOM
+ * (`packages/client/ui-primitives/src/markdown/render.tsx:261-263`). The
+ * upstream fix is one `img-src` directive.
+ * @module dsh-dlp/images
+ */
+import type { StreamChunk } from '@deepseek-ai/dsh-llm';
+/**
+ * Destination substituted for a remote image URL.
+ *
+ * It is deliberately not a URL: `new URL()` throws on it, which is the
+ * renderer's own "not an absolute destination" arm, and that arm renders the
+ * alt text as a `<span>` instead of emitting an `<img>`.
+ */
+export declare const BLOCKED_IMAGE_DESTINATION = "dsh-dlp-blocked-remote-image";
+/**
+ * Longest suffix held back waiting for an image to complete.
+ *
+ * Held text is text the user cannot see yet, so the wait is bounded: past this
+ * many characters the suffix is emitted as it stands and a destination that
+ * completes later is caught only by the assembled block. A protocol bound on
+ * this module's own buffering, not a deployment choice.
+ */
+export declare const MAX_HELD_CHARACTERS = 4096;
+/** One string after its remote image destinations were replaced. */
+export interface NeutralizedText {
+    readonly text: string;
+    /** Hostnames of the replaced destinations, in match order; never the full URL. */
+    readonly hosts: readonly string[];
+}
+/**
+ * Replace every absolute HTTP(S) inline image destination in one string.
+ * @param text - assistant text, whole or partial.
+ * @returns the rewritten text and the hosts whose destinations were replaced.
+ */
+export declare function neutralizeRemoteImages(text: string): NeutralizedText;
+/**
+ * Where the held suffix of a partially streamed string starts.
+ * @param text - everything accumulated for one block and not yet emitted.
+ * @returns the offset to emit up to; the string's length when nothing is held.
+ */
+export declare function heldSuffixStart(text: string): number;
+/**
+ * Wrap one model stream, replacing remote image destinations in its text.
+ *
+ * Text deltas are rewritten as they pass, with a possible image start held
+ * back until it resolves, and the assembled block on `block-end` — which is
+ * what the agent loop turns into the assistant message — is rewritten too. A
+ * held suffix is always flushed as a delta before the block closes and before
+ * the terminal finish, so no text is lost and the emitted chunks still satisfy
+ * the stream grammar.
+ * @param source - the stream from the rest of the waterfall.
+ * @param onNeutralized - notified once per host per text block.
+ * @returns the rewritten stream.
+ */
+export declare function neutralizeImageStream(source: AsyncIterable<StreamChunk>, onNeutralized: (host: string) => void): AsyncIterable<StreamChunk>;
+//# sourceMappingURL=images.d.ts.map

package/lib/types/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * `dsh-dlp` — data-loss prevention for DeepSeek Harness.
  *
- * Four registrations, in descending order of how much they can be trusted:
+ * Six 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
@@ -9,11 +9,24 @@
  *    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.
+ * 2b. `tools/pre-execute` — the `ask` tier for writes to behaviour-changing
+ *    config paths. Deliberately here rather than on the floor: its rules have a
+ *    real false-positive rate and the floor cannot ask. Neutralizable, and it
+ *    abstains entirely when no approval service is mounted.
  * 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.
+ * 5. `llm/stream` — neutralising remote markdown image destinations in
+ *    assistant output, before the text becomes a session event.
+ *
+ * Three of those registrations mitigate defects in the harness rather than in
+ * a deployment's own configuration: the missing Content-Security-Policy behind
+ * (5), the mutable execution object behind the guard's mutation check, and the
+ * silently inert telemetry seam behind the notice reported at mount. Each one
+ * is partial, none closes its channel, and README.md says so beside the
+ * feature.
  *
  * 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

package/lib/types/mutation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Detecting a tool call that was rewritten after it was logged.
+ *
+ * The registry deep-freezes `exec.arguments` but does not freeze the execution
+ * object until results are notified, so a `tools/pre-execute` listener can
+ * reassign `exec.arguments` or `exec.name` — and reassigning `exec.name`
+ * changes which tool body runs. The agent loop appended `tool/call` from the
+ * model's own response block before the waterfall ran, so nothing in the
+ * session log records the change: the durable record then describes a
+ * different call than the one about to execute.
+ *
+ * This module snapshots the call as early in the waterfall as it can and
+ * compares in the guard, which runs after the whole waterfall and cannot be
+ * out-ordered. It is detection, not prevention: preventing the rewrite would
+ * mean freezing an object this plugin does not own, and the snapshot itself is
+ * best-effort — a later `{ prepend: true }` registration runs ahead of ours and
+ * would be snapshotted after its own rewrite.
+ * @module dsh-dlp/mutation
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { SpanHasher } from './redaction.ts';
+/** The parts of an execution this module compares. */
+type Comparable = Pick<ToolExecution, 'name' | 'arguments'>;
+/** One rewritten field. */
+export type MutatedField = 'name' | 'arguments';
+/** A call whose identity changed between the snapshot and the guard. */
+export interface ExecutionMutation {
+    /** Which fields differ, in a stable order. */
+    readonly fields: readonly MutatedField[];
+    /** The tool name the session log recorded. */
+    readonly originalTool: string;
+}
+/**
+ * Render a JSON value with object keys in a fixed order, so two equal argument
+ * sets hash equally whatever order a listener rebuilt them in.
+ * @param value - the argument value; JSON-serializable by the registry's own snapshot step.
+ * @returns a canonical string for hashing.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Remembers what each pending call looked like before the rest of the
+ * `tools/pre-execute` waterfall ran.
+ *
+ * Keyed by the execution object's identity in a `WeakMap`, the way the
+ * registry keys its own per-execution state, so the entry is found again in
+ * the guard and released with the execution.
+ */
+export declare class ExecutionSnapshots {
+    #private;
+    /**
+     * @param hasher - mints the keyed digest of the arguments; the values themselves are never stored.
+     */
+    constructor(hasher: SpanHasher);
+    /**
+     * Snapshot one pending call.
+     * @param exec - the execution as the earliest listener sees it.
+     */
+    record(exec: Comparable): void;
+    /**
+     * Compare one call against its snapshot.
+     *
+     * A call with no snapshot is not a finding: the listener may never have run
+     * for it, and reporting absence as mutation would deny calls this plugin
+     * simply did not observe.
+     * @param exec - the execution as the guard stage sees it.
+     * @returns what changed, or `undefined` when nothing did.
+     */
+    detect(exec: Comparable): ExecutionMutation | undefined;
+}
+/**
+ * Denial text for a rewritten call.
+ *
+ * Both tool names are named: a tool name is already in the session log and in
+ * every other denial this plugin writes, and naming them is the whole point —
+ * the operator needs to know which call the log describes and which one was
+ * about to run. No argument value appears.
+ * @param exec - the call as the guard sees it, after the rewrite.
+ * @param mutation - the fields that changed and the recorded tool name.
+ * @returns the model-facing reason.
+ */
+export declare function mutationReason(exec: Comparable, mutation: ExecutionMutation): string;
+export {};
+//# sourceMappingURL=mutation.d.ts.map

package/lib/types/paths.d.ts

@@ -40,6 +40,31 @@ export interface CredentialPathRule {
  * authenticates with is agent-readable. That is the gap this table closes.
  */
 export declare const CREDENTIAL_PATH_RULES: readonly CredentialPathRule[];
+/**
+ * Escape one literal path so it can anchor a regular expression.
+ * @param literal - the path to quote.
+ * @returns the same text with every metacharacter escaped.
+ */
+export declare function escapePathPattern(literal: string): string;
+/**
+ * Credential-path rules anchored at the user's home directory, resolved at
+ * mount because the directory is not known until then.
+ *
+ * A coding agent's *home* configuration decides how every future session in
+ * every repository behaves: the Miasma worm's `SessionStart` hooks went into
+ * exactly these files. Writing one is never ordinary repository work, so it is
+ * on the floor. Reading one is — a user asking the agent why its own
+ * configuration behaves a certain way is a normal request — so the rule is
+ * `writes-only` rather than `every-call`, unlike the `auth.json` and `mcp.json`
+ * stores in {@link CREDENTIAL_PATH_RULES}, which hold nothing but credentials.
+ *
+ * The *repository-local* copies of these same file names are a different
+ * question with a different answer: they are edited legitimately and often, so
+ * they sit in the neutralizable `ask` tier rather than on the floor.
+ * @param home - the user's home directory.
+ * @returns rules appended after the built-in table.
+ */
+export declare function homeCredentialPathRules(home: string): readonly CredentialPathRule[];
 /**
  * Normalize one candidate path for matching: Windows separators become
  * forward slashes, surrounding quotes come off, `~` expands to a

package/lib/types/policy.d.ts

@@ -33,12 +33,20 @@ export interface Config {
     resultRedaction: boolean;
     /** Whether `session-telemetry/record` redaction runs. */
     telemetryRedaction: boolean;
+    /** Whether remote markdown image destinations are neutralised in assistant output. */
+    remoteImageNeutralization: boolean;
     /** Whether telemetry's `session.cwd` attribute is replaced with a keyed hash. */
     redactTelemetryWorkspacePaths: boolean;
+    /**
+     * Whether a write to a behaviour-changing config path asks the user first.
+     * Needs an approval service; without one the tier abstains rather than
+     * letting an `ask` degrade into a denial.
+     */
+    configWriteAsk: 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"];
+declare const ENABLEABLE: readonly ["breadthTier", "resultRedaction", "telemetryRedaction", "remoteImageNeutralization", "redactTelemetryWorkspacePaths", "configWriteAsk"];
 /** 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. */
@@ -59,7 +67,9 @@ export interface ResolvedPolicy {
     readonly breadthTier: boolean;
     readonly resultRedaction: boolean;
     readonly telemetryRedaction: boolean;
+    readonly remoteImageNeutralization: boolean;
     readonly redactTelemetryWorkspacePaths: boolean;
+    readonly configWriteAsk: boolean;
 }
 /** Thrown when a policy file is malformed or attempts to loosen the policy. */
 export declare class PolicyError extends Error {

package/lib/types/sink.d.ts

@@ -28,7 +28,7 @@ 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';
+export type AuditKind = 'guard-deny' | 'pre-execute-deny' | 'pre-execute-ask' | 'execution-mutation' | 'result-redaction' | 'telemetry-redaction' | 'assistant-image-neutralized' | 'audit-failure';
 /** One durable record. Never carries matched secret text. */
 export interface AuditRecord {
     readonly v: number;
@@ -60,8 +60,25 @@ export interface AuditRecord {
      * instruction is exactly the content this file must not repeat.
      */
     readonly unicode?: Readonly<Record<string, number>>;
+    /**
+     * The single rule behind a decision that has no matched region to describe,
+     * which is every `pre-execute-ask`: the finding is that a path names a
+     * behaviour-changing file, not that any part of it matched a secret.
+     */
+    readonly ruleId?: string;
     /** Telemetry record channel, for `telemetry-redaction`. */
     readonly channel?: string;
+    /** Fields another plugin rewrote after the call was logged, for `execution-mutation`. */
+    readonly mutatedFields?: readonly string[];
+    /** Tool name the session log recorded, when a rewrite changed it. */
+    readonly originalTool?: string;
+    /**
+     * Hostname of a neutralised remote image destination, for
+     * `assistant-image-neutralized`. The hostname only: a path and a query
+     * string are where an exfiltration payload rides, and this file must not
+     * carry it.
+     */
+    readonly host?: string;
 }
 /** Append-only JSONL sink for this plugin's decisions. */
 export declare class AuditSink {

package/lib/types/telemetry.d.ts

@@ -25,9 +25,24 @@
  * workspace path.
  * @module dsh-dlp/telemetry
  */
-import type { SessionTelemetryRecord } from '@deepseek-ai/dsh-session-telemetry';
+import type { SessionTelemetryRecord, SessionTelemetrySharingStatus } from '@deepseek-ai/dsh-session-telemetry';
 import type { ResolvedPolicy } from './policy.ts';
 import { type RedactedSpan, type SpanHasher } from './redaction.ts';
+/**
+ * What to tell the operator when the redaction seam will never dispatch.
+ *
+ * A `session-telemetry/record` listener mounts successfully and never runs
+ * unless a backend built a coordinator, and the shipped default builds none:
+ * the mode is `DISABLED`, so nothing is exported and nothing is dispatched.
+ * That is the safe posture, not a leak — but an operator who mounts a redactor
+ * under it sees every signal of success and has verified nothing. The
+ * backend's own `sharing` disclosure is the resolved answer, so this never
+ * guesses at `DSH_TELEMETRY_MODE`, which is only the base patch's default
+ * expression for a `mode` a deployment can also set directly.
+ * @param sharing - the mounted backend's disclosure, or `undefined` when no backend is mounted.
+ * @returns the line to report, or `undefined` when the seam does dispatch.
+ */
+export declare function telemetrySeamNotice(sharing: SessionTelemetrySharingStatus | undefined): string | undefined;
 /** 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dlp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Data-loss-prevention plugin for DeepSeek Harness: a non-configurable tool guard floor, tool-result redaction, and fail-closed telemetry redaction",
   "license": "MIT",
   "author": "Ivan Tyshchenko <nsof@protonmail.com>",