dsh-dlp 0.1.0 → 0.2.0

package/lib/types/detectors.d.ts

@@ -37,6 +37,13 @@ export interface Detection {
     readonly start: number;
     /** Exclusive end offset into the scanned string. */
     readonly end: number;
+    /**
+     * Set when the offsets cover exactly what must be replaced, so redaction
+     * must not widen them to the surrounding delimiters. Only the Unicode
+     * indicators set it: their matches are the characters themselves, while a
+     * secret's reported span is advisory and verified to under-cover (ADR §4).
+     */
+    readonly exact?: true;
 }
 /** Outcome of one scan. */
 export interface ScanResult {
@@ -59,11 +66,70 @@ export interface SyncRule {
  * tier 2, where a false positive costs a redaction rather than a denial.
  */
 export declare const SYNC_RULES: readonly SyncRule[];
+/**
+ * What the scan does with one class of invisible or direction-changing
+ * characters.
+ *
+ * `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.
+ */
+export type UnicodeAction = 'strip' | 'report';
+/** One class of invisible or direction-changing characters. */
+export interface UnicodeRule {
+    readonly id: string;
+    readonly version: number;
+    readonly severity: Severity;
+    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;
+}
+/**
+ * Character classes that hide text from the reader while the model still reads
+ * it, verified against the Unicode character database.
+ *
+ * Every class is `medium`. These are injection *indicators*, not credentials:
+ * the guard floor denies at `high` and above, so an argument carrying one is
+ * never denied on that basis. What they buy is a redaction and an audit record
+ * on a path the harness does not cover — it strips directional controls in
+ * exactly one place, session titles, and never on the tool-result path.
+ *
+ * Not attempted here: UTS #39 confusables. A Cyrillic `а` needs a data table
+ * to detect and is a different cost class, and it defeats every rule in this
+ * file. README.md says so rather than implying coverage.
+ */
+export declare const UNICODE_RULES: readonly UnicodeRule[];
+/** One indicator match and what the caller should do with it. */
+export interface UnicodeFinding extends Detection {
+    readonly action: UnicodeAction;
+}
+/**
+ * Find every invisible or direction-changing character in one string.
+ *
+ * Offsets are UTF-16 indices into `text`, so a caller can splice them
+ * directly; they are exact rather than advisory, and {@link Detection.exact}
+ * says so.
+ * @param text - the string to scan.
+ * @returns every indicator run, ordered by start offset.
+ */
+export declare function scanUnicode(text: string): UnicodeFinding[];
+/**
+ * How many runs of each indicator class one string carries.
+ * @param text - the string to scan.
+ * @returns a count per rule id; absent means none were found.
+ */
+export declare function countUnicodeIndicators(text: string): Record<string, number>;
 /**
  * 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.
+ *
+ * The `strip` half of {@link UNICODE_RULES} is included, so every seam reading
+ * tier 1 — including the synchronous telemetry waterfall — gets 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.

package/lib/types/guard.d.ts

@@ -43,10 +43,12 @@ export interface GuardVerdict {
  * 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.
+ * a `.gitignore` that mentions `.env`. The one exception is a `writes-only`
+ * rule, which a tool classified read-only is exempt from; that is how
+ * `$DSH_HOME` stays readable while every write to it is denied. 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.

package/lib/types/home.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where the harness keeps its state, and where this plugin's audit sink lands
+ * by default.
+ *
+ * Its own module so the `dsh-dlp report` command can resolve the sink without
+ * importing the plugin: `policy.ts` pulls in `@secretlint/core`, `js-yaml` and
+ * the schema library, none of which a reader of a JSONL file needs.
+ * @module dsh-dlp/home
+ */
+/**
+ * File name the bundle patch gives the audit sink under the harness home.
+ * `cordis.patch.yml` spells the same name; a deployment that sets `auditLog`
+ * itself must tell `dsh-dlp report` where it put it.
+ */
+export declare const DEFAULT_AUDIT_LOG_NAME = "dsh-dlp.audit.jsonl";
+/**
+ * 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;
+/**
+ * Where the audit sink sits when the deployment did not name one.
+ * @param env - environment consulted for `DSH_HOME`; defaults to `process.env`.
+ * @returns the absolute path the bundle patch configures.
+ */
+export declare function defaultAuditLog(env?: NodeJS.ProcessEnv): string;
+//# sourceMappingURL=home.d.ts.map

package/lib/types/paths.d.ts

@@ -6,12 +6,25 @@
  * the repo-local policy tier may only add to them.
  * @module dsh-dlp/paths
  */
+/**
+ * Which calls a credential-path rule is enforced for.
+ *
+ * `every-call` is the default and the only setting a rule protecting
+ * credential *contents* may use. `writes-only` exempts the tools
+ * {@link READ_ONLY_TOOLS} classifies as unable to change anything: it exists
+ * for a directory whose contents are ordinary work to read and dangerous to
+ * modify, which is `$DSH_HOME` — it holds the installed plugin tree and every
+ * profile's `cordis.yml`.
+ */
+export type RuleEnforcement = 'every-call' | 'writes-only';
 /** One credential-path pattern. */
 export interface CredentialPathRule {
     readonly id: string;
     readonly version: number;
     /** Matched against a normalized, forward-slash path. */
     readonly pattern: RegExp;
+    /** Defaults to `every-call`; the repo-local tier cannot set it. */
+    readonly enforcement?: RuleEnforcement;
 }
 /**
  * Paths whose contents are credentials. Reading any of them through a tool is
@@ -120,4 +133,29 @@ export declare const LOCAL_TOOLS: ReadonlySet<string>;
  * @returns `true` when the tool is not a known local-only tool.
  */
 export declare function isEgressCapable(toolName: string, extraEgressTools?: ReadonlySet<string>): boolean;
+/**
+ * Tools that can only look: they query the filesystem, the language server,
+ * the session store or a running job, and have no operation that changes
+ * anything.
+ *
+ * A `writes-only` rule is lifted for these names and for no others. Every
+ * shell, `run_code`, every editor, every `mcp__*` tool and any tool this build
+ * has never heard of stays on the deny side, so a new tool is denied until it
+ * is classified — the same default as {@link LOCAL_TOOLS}, in the same
+ * direction.
+ */
+export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
+/**
+ * Whether a tool is known to be incapable of changing anything.
+ * @param toolName - the executing tool's registered name.
+ * @returns `true` only for a name in {@link READ_ONLY_TOOLS}.
+ */
+export declare function isReadOnlyTool(toolName: string): boolean;
+/**
+ * The credential-path rules one tool is judged against.
+ * @param toolName - the executing tool's registered name.
+ * @param rules - the effective rule table.
+ * @returns every rule, minus the `writes-only` ones for a read-only tool.
+ */
+export declare function rulesForTool(toolName: string, rules: readonly CredentialPathRule[]): readonly CredentialPathRule[];
 //# sourceMappingURL=paths.d.ts.map

package/lib/types/policy.d.ts

@@ -108,15 +108,6 @@ export type RepoPolicyLoad =
  * @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.

package/lib/types/results.d.ts

@@ -10,7 +10,7 @@
  * 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 { JsonSchemaNode, 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. */
@@ -18,6 +18,13 @@ export interface ResultRedaction {
     readonly decision: PostToolDecision;
     readonly spans: readonly RedactedSpan[];
     readonly truncatedScan: boolean;
+    /**
+     * Runs of each invisible-character class the result carried, by rule id.
+     * The `strip` classes also appear in `spans`; the `report` classes appear
+     * only here, because rewriting them would corrupt legitimate emoji and
+     * right-to-left text.
+     */
+    readonly indicators: Readonly<Record<string, number>>;
 }
 /**
  * Redact whatever the downstream decision settled on.
@@ -36,10 +43,11 @@ export interface ResultRedaction {
  *   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.
+ * Replacing the value is re-validated by the registry against the tool's
+ * `output.schema`, and a schema that pins the redacted string rejects it. That
+ * surfaces as a `ToolOutputError` naming a validation failure, which tells the
+ * model nothing it can act on, so the schema is checked here first and the
+ * result is withheld with this plugin's own explanation instead.
  *
  * A downstream `accept{content}` over a dirty value is overruled by the value
  * arm, which discards that listener's presentation choice. Keeping it would
@@ -49,9 +57,10 @@ export interface ResultRedaction {
  * @param result - the dispatch outcome the waterfall was called with.
  * @param policy - the effective policy.
  * @param hasher - mints each span's keyed hash.
+ * @param outputSchema - the executing tool's declared output schema, when one could be resolved.
  * @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>;
+export declare function redactDecision(decision: PostToolDecision, result: Readonly<ToolExecutionResult>, policy: ResolvedPolicy, hasher: SpanHasher, outputSchema?: JsonSchemaNode): Promise<ResultRedaction>;
 /**
  * Decide whether the breadth tier denies one call before dispatch.
  *

package/lib/types/schema.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Whether a redacted value still satisfies the tool's declared `output.schema`.
+ *
+ * Replacing a canonical value makes the registry re-validate it, so a schema
+ * that pins the redacted string turns a redaction into a `ToolOutputError` the
+ * model cannot act on. Asking the question first lets the listener withhold
+ * the result with its own explanation instead.
+ *
+ * This is a re-implementation of the harness's own check rather than a call
+ * into it: every harness type this package uses is imported with `import
+ * type`, so nothing from `@deepseek-ai/dsh-*` is emitted as a runtime import
+ * and the plugin resolves from a profile directory that has none of them
+ * installed. The enforced subset is small — `type`, `oneOf`, `properties`,
+ * `required`, `additionalProperties`, `items`, `enum`, `const` — and the
+ * caller guards against any disagreement by checking the *original* value
+ * first: a value this module rejects before redaction means the answer cannot
+ * be trusted, and the redaction proceeds as it did before.
+ * @module dsh-dlp/schema
+ */
+import type { JsonSchemaNode } from '@deepseek-ai/dsh-tools';
+/**
+ * Whether one value satisfies one schema node.
+ * @param node - a node of the tool's declared output schema.
+ * @param value - the candidate value.
+ * @returns `true` when the registry's own validation would accept it.
+ */
+export declare function satisfiesJsonSchema(node: JsonSchemaNode, value: unknown): boolean;
+/**
+ * Whether replacing a value with its redacted copy would fail the tool's
+ * output validation.
+ *
+ * A schema this module already rejects for the original value is one it does
+ * not model correctly, so the answer is `false` and the registry decides — the
+ * check can withhold a result, and it must never do so on its own confusion.
+ * @param schema - the tool's declared output schema, when one could be resolved.
+ * @param original - the value the tool produced.
+ * @param redacted - the value the redaction pass produced.
+ * @returns `true` only when the original validates and the redacted one does not.
+ */
+export declare function redactionBreaksSchema(schema: JsonSchemaNode | undefined, original: unknown, redacted: unknown): boolean;
+//# sourceMappingURL=schema.d.ts.map

package/lib/types/sink.d.ts

@@ -54,6 +54,12 @@ export interface AuditRecord {
     readonly spans?: readonly RedactedSpan[];
     /** Set when the scanned input exceeded the byte cap. */
     readonly truncatedScan?: boolean;
+    /**
+     * Runs of each invisible-character class the scanned text carried, by rule
+     * id. Counts only: the characters themselves are content, and a hidden
+     * instruction is exactly the content this file must not repeat.
+     */
+    readonly unicode?: Readonly<Record<string, number>>;
     /** Telemetry record channel, for `telemetry-redaction`. */
     readonly channel?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-dlp",
-  "version": "0.1.0",
+  "version": "0.2.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>",
@@ -27,6 +27,9 @@
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
+  "bin": {
+    "dsh-dlp": "lib/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./lib/types/index.d.ts",