dsh-dlp 0.1.0

package/lib/policy.js

@@ -0,0 +1,274 @@
+/**
+ * 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 { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { JSON_SCHEMA, load } from 'js-yaml';
+import z from '@deepseek-ai/schemastery';
+import { SYNC_RULES, severityRank } from "./detectors.js";
+import { CREDENTIAL_PATH_RULES } from "./paths.js";
+export const Config = z.object({
+    auditLog: z.string().required(),
+    redactionKeyFile: z.string().required(),
+    policyFile: z.string(),
+    maxScanBytes: z.number().default(1024 * 1024),
+    breadthTier: z.boolean().default(true),
+    resultRedaction: z.boolean().default(true),
+    telemetryRedaction: z.boolean().default(true),
+    redactTelemetryWorkspacePaths: z.boolean().default(true),
+});
+/** Config toggles a repo-local policy may switch on, and never off. */
+const ENABLEABLE = ['breadthTier', 'resultRedaction', 'telemetryRedaction', 'redactTelemetryWorkspacePaths'];
+/** Keys a repo-local policy file may carry; anything else fails the load. */
+const POLICY_KEYS = ['v', 'addCredentialPaths', 'addEgressTools', 'raiseSeverity', 'enable'];
+/** Payload version this package writes and accepts for repo-local policy files. */
+export const POLICY_VERSION = 1;
+/** Thrown when a policy file is malformed or attempts to loosen the policy. */
+export class PolicyError extends Error {
+    /**
+     * @param message - what the file did and why it is rejected.
+     */
+    constructor(message) {
+        super(`dsh-dlp policy: ${message}`);
+        this.name = 'PolicyError';
+    }
+}
+/** Narrow one parsed YAML node to a plain object. */
+function requireObject(node, what) {
+    if (typeof node !== 'object' || node === null || Array.isArray(node)) {
+        throw new PolicyError(`${what} must be a mapping`);
+    }
+    return node;
+}
+/** Narrow one parsed YAML node to an array of strings. */
+function requireStringArray(node, what) {
+    if (!Array.isArray(node) || node.some(item => typeof item !== 'string')) {
+        throw new PolicyError(`${what} must be a list of strings`);
+    }
+    return node;
+}
+/** Narrow one parsed YAML node to a known severity. */
+function requireSeverity(node, what) {
+    if (typeof node !== 'string' || severityRank(node) < 0) {
+        throw new PolicyError(`${what} must be one of low, medium, high, critical`);
+    }
+    return node;
+}
+/**
+ * Longest repo-authored pattern accepted. A credential path is a short,
+ * anchored expression; length past this buys nothing and grows the search
+ * space a catastrophic pattern can backtrack over.
+ */
+const MAX_PATTERN_LENGTH = 200;
+/**
+ * A quantifier applied to a group that already contains one — `(a+)+`,
+ * `(?:[a-z]*)*`. That shape is what turns a 27-character input into seconds of
+ * backtracking, and the guard runs synchronously on the agent's event loop.
+ *
+ * This is a heuristic, not a decision procedure: no regular-expression syntax
+ * check can prove a pattern runs in linear time, and other shapes
+ * (`(a|a)+`, `a*a*`) still backtrack. It rejects the shape that is both easy
+ * to write and expensive to run; the length cap bounds the rest.
+ */
+const NESTED_QUANTIFIER = /\((?:\?[:=!<]*)?[^()]*[*+?}][^()]*\)\s*[*+{]/;
+/**
+ * Reject a repo-authored pattern that would let a hostile repository stall the
+ * agent through the synchronous guard.
+ * @param pattern - the pattern text from the policy file.
+ * @param where - the field being validated, for the error message.
+ * @throws PolicyError when the pattern is too long or nests quantifiers.
+ */
+function assertSafePattern(pattern, where) {
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        throw new PolicyError(`${where} is ${pattern.length} characters; at most ${MAX_PATTERN_LENGTH} are allowed`);
+    }
+    if (NESTED_QUANTIFIER.test(pattern)) {
+        throw new PolicyError(`${where} nests a quantifier inside a quantified group, which can take exponential time to match;`
+            + ' the guard runs synchronously, so such a pattern is rejected');
+    }
+}
+/** Compile one repo-local credential-path entry, rejecting a pattern that cannot be built. */
+function parseCredentialPathEntry(node, index) {
+    const entry = requireObject(node, `addCredentialPaths[${index}]`);
+    const { id, pattern } = entry;
+    const extra = Object.keys(entry).filter(key => key !== 'id' && key !== 'pattern');
+    if (extra.length > 0) {
+        throw new PolicyError(`addCredentialPaths[${index}] has unknown keys: ${extra.join(', ')}`);
+    }
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new PolicyError(`addCredentialPaths[${index}].id must be a non-empty string`);
+    }
+    if (typeof pattern !== 'string' || pattern.length === 0) {
+        throw new PolicyError(`addCredentialPaths[${index}].pattern must be a non-empty string`);
+    }
+    assertSafePattern(pattern, `addCredentialPaths[${index}].pattern`);
+    try {
+        return { id, version: POLICY_VERSION, pattern: new RegExp(pattern, 'i') };
+    }
+    catch (error) {
+        throw new PolicyError(`addCredentialPaths[${index}].pattern is not a valid regular expression: ${String(error)}`);
+    }
+}
+/**
+ * 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 function parseRepoPolicy(text) {
+    let parsed;
+    try {
+        parsed = load(text, { schema: JSON_SCHEMA });
+    }
+    catch (error) {
+        throw new PolicyError(`file is not safe-schema YAML: ${String(error)}`);
+    }
+    const document = requireObject(parsed, 'file');
+    const unknown = Object.keys(document).filter(key => !POLICY_KEYS.includes(key));
+    if (unknown.length > 0) {
+        throw new PolicyError(`unknown keys: ${unknown.join(', ')}. A repo-local policy may only tighten:`
+            + ` ${POLICY_KEYS.join(', ')}`);
+    }
+    if (document['v'] !== POLICY_VERSION) {
+        throw new PolicyError(`v must be ${POLICY_VERSION}`);
+    }
+    const addCredentialPaths = document['addCredentialPaths'] === undefined
+        ? []
+        : (Array.isArray(document['addCredentialPaths'])
+            ? document['addCredentialPaths'].map(parseCredentialPathEntry)
+            : (() => { throw new PolicyError('addCredentialPaths must be a list'); })());
+    const addEgressTools = document['addEgressTools'] === undefined
+        ? []
+        : requireStringArray(document['addEgressTools'], 'addEgressTools');
+    const raiseSeverity = new Map();
+    if (document['raiseSeverity'] !== undefined) {
+        for (const [ruleId, value] of Object.entries(requireObject(document['raiseSeverity'], 'raiseSeverity'))) {
+            const rule = SYNC_RULES.find(candidate => candidate.id === ruleId);
+            if (rule === undefined)
+                throw new PolicyError(`raiseSeverity names an unknown rule: ${ruleId}`);
+            const severity = requireSeverity(value, `raiseSeverity.${ruleId}`);
+            if (severityRank(severity) < severityRank(rule.severity)) {
+                throw new PolicyError(`raiseSeverity.${ruleId} would lower ${rule.severity} to ${severity};`
+                    + ' a repo-local policy may only tighten');
+            }
+            raiseSeverity.set(ruleId, severity);
+        }
+    }
+    const enable = requireStringArray(document['enable'] ?? [], 'enable');
+    for (const toggle of enable) {
+        if (!ENABLEABLE.includes(toggle)) {
+            throw new PolicyError(`enable names an unknown toggle: ${toggle}. Known toggles: ${ENABLEABLE.join(', ')}`);
+        }
+    }
+    return { addCredentialPaths, addEgressTools, raiseSeverity, enable: enable };
+}
+/**
+ * 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 function loadRepoPolicy(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { kind: 'absent' };
+        return { kind: 'invalid', problem: `cannot read ${path}: ${String(error)}` };
+    }
+    try {
+        return { kind: 'loaded', policy: parseRepoPolicy(text) };
+    }
+    catch (error) {
+        return { kind: 'invalid', problem: String(error) };
+    }
+}
+/** Escape one literal path so it can anchor a regular expression. */
+function escapePattern(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, String.raw `\$&`);
+}
+/**
+ * Deny rules protecting this plugin's own state.
+ *
+ * Every one of these is known at mount: the key file whose bytes make a
+ * placeholder hash keyed rather than a bare digest, the append-only sink that
+ * is the only evidence a decision happened, and the harness home holding the
+ * provider credentials, the session logs and the profiles that decide which
+ * plugins load at all.
+ * @param config - the deployment-controlled configuration.
+ * @param dshHome - the resolved harness home.
+ * @returns rules appended after the built-in table.
+ */
+function selfProtectionRules(config, dshHome) {
+    return [
+        { id: 'dsh-dlp/path-own-redaction-key', version: 1, pattern: new RegExp(`^${escapePattern(resolve(config.redactionKeyFile))}$`, 'i') },
+        { id: 'dsh-dlp/path-own-audit-log', version: 1, pattern: new RegExp(`^${escapePattern(resolve(config.auditLog))}$`, 'i') },
+        { id: 'dsh-dlp/path-dsh-home', version: 1, pattern: new RegExp(`^${escapePattern(resolve(dshHome))}(/|$)`, 'i') },
+    ];
+}
+/**
+ * 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 function resolveDshHome(env = process.env) {
+    const configured = env['DSH_HOME'];
+    return resolve(configured !== undefined && configured.trim().length > 0 ? configured : join(homedir(), '.dsh'));
+}
+/**
+ * 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 function resolvePolicy(config, repo) {
+    const enabled = (toggle) => config[toggle] || (repo?.enable.includes(toggle) ?? false);
+    return {
+        credentialPathRules: [
+            ...CREDENTIAL_PATH_RULES,
+            ...selfProtectionRules(config, resolveDshHome()),
+            ...repo?.addCredentialPaths ?? [],
+        ],
+        extraEgressTools: new Set(repo?.addEgressTools ?? []),
+        syncRules: SYNC_RULES.map((rule) => {
+            const raised = repo?.raiseSeverity.get(rule.id);
+            return raised === undefined ? rule : { ...rule, severity: raised };
+        }),
+        maxScanBytes: config.maxScanBytes,
+        breadthTier: enabled('breadthTier'),
+        resultRedaction: enabled('resultRedaction'),
+        telemetryRedaction: enabled('telemetryRedaction'),
+        redactTelemetryWorkspacePaths: enabled('redactTelemetryWorkspacePaths'),
+    };
+}

package/lib/redaction.js

@@ -0,0 +1,216 @@
+/**
+ * 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 { createHmac } from 'node:crypto';
+import { severityRank } from "./detectors.js";
+/** Number of hex characters kept from the HMAC digest. */
+const HASH_LENGTH = 12;
+/**
+ * Mints the keyed hashes that appear in placeholders and audit records. Holds
+ * the installation key; the key never leaves this object.
+ */
+export class SpanHasher {
+    #key;
+    /**
+     * @param key - installation secret, at least 16 bytes, read from `redactionKeyFile`.
+     */
+    constructor(key) {
+        if (key.length < 16)
+            throw new Error('dsh-dlp: redaction key must be at least 16 bytes');
+        this.#key = Buffer.from(key);
+    }
+    /**
+     * Keyed hash of one replaced region.
+     * @param text - the exact text being replaced.
+     * @returns 12 lowercase hex characters.
+     */
+    hash(text) {
+        return createHmac('sha256', this.#key).update(text, 'utf8').digest('hex').slice(0, HASH_LENGTH);
+    }
+}
+/**
+ * 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 function shortRuleId(ruleId) {
+    return ruleId
+        .replace('@secretlint/secretlint-rule-', '')
+        .replace('dsh-dlp/', '');
+}
+/**
+ * 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 function placeholderFor(span) {
+    return `[REDACTED:dsh-dlp:${shortRuleId(span.ruleId)}:${span.hash}]`;
+}
+/**
+ * Characters that end a secret. Whitespace alone is not enough: one detection
+ * inside a line of minified JSON would expand to the whole line and destroy
+ * every other field on it, so quotes and the JSON, query-string and
+ * assignment separators bound a span too.
+ */
+const SPAN_DELIMITERS = /[\s"'`=:,;&?<>(){}[\]]/;
+/** Grow one span outward until both edges sit on a delimiter or a string boundary. */
+function expand(text, start, end) {
+    let left = Math.max(0, start);
+    let right = Math.min(text.length, end);
+    while (left > 0 && !SPAN_DELIMITERS.test(text.charAt(left - 1)))
+        left -= 1;
+    while (right < text.length && !SPAN_DELIMITERS.test(text.charAt(right)))
+        right += 1;
+    return { start: left, end: right };
+}
+/** Detections merged into non-overlapping regions, each attributed to its strictest rule. */
+function mergeSpans(text, detections) {
+    const expanded = detections
+        .map(detection => ({ ...detection, ...expand(text, detection.start, detection.end) }))
+        .sort((left, right) => left.start - right.start || left.end - right.end);
+    const merged = [];
+    for (const candidate of expanded) {
+        const previous = merged.at(-1);
+        if (previous === undefined || candidate.start > previous.end) {
+            merged.push(candidate);
+            continue;
+        }
+        const stricter = severityRank(candidate.severity) > severityRank(previous.severity);
+        merged[merged.length - 1] = {
+            ruleId: stricter ? candidate.ruleId : previous.ruleId,
+            ruleVersion: stricter ? candidate.ruleVersion : previous.ruleVersion,
+            severity: stricter ? candidate.severity : previous.severity,
+            start: previous.start,
+            end: Math.max(previous.end, candidate.end),
+        };
+    }
+    return merged;
+}
+/**
+ * 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 function redactText(text, detections, hasher, path) {
+    if (detections.length === 0)
+        return { text, spans: [] };
+    const spans = [];
+    const pieces = [];
+    let cursor = 0;
+    for (const region of mergeSpans(text, detections)) {
+        const span = {
+            ...region,
+            hash: hasher.hash(text.slice(region.start, region.end)),
+            ...path === undefined ? {} : { path },
+        };
+        pieces.push(text.slice(cursor, span.start), placeholderFor(span));
+        spans.push(span);
+        cursor = span.end;
+    }
+    pieces.push(text.slice(cursor));
+    return { text: pieces.join(''), spans };
+}
+/**
+ * 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 function nestedStrings(value) {
+    const found = [];
+    const walk = (node) => {
+        if (typeof node === 'string') {
+            found.push(node);
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (typeof node === 'object' && node !== null) {
+            for (const item of Object.values(node))
+                walk(item);
+        }
+    };
+    walk(value);
+    return found;
+}
+/** Escape one JSON pointer segment per RFC 6901. */
+function pointerSegment(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * 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 function redactJson(value, scan, hasher) {
+    const spans = [];
+    let changed = false;
+    const walk = (node, path) => {
+        if (typeof node === 'string') {
+            const redacted = redactText(node, scan(node), hasher, path);
+            if (redacted.spans.length === 0)
+                return node;
+            changed = true;
+            spans.push(...redacted.spans);
+            return redacted.text;
+        }
+        if (Array.isArray(node)) {
+            return node.map((item, index) => walk(item, `${path}/${index}`));
+        }
+        if (typeof node === 'object' && node !== null) {
+            return Object.fromEntries(Object.entries(node).map(([key, item]) => [key, walk(item, `${path}/${pointerSegment(key)}`)]));
+        }
+        return node;
+    };
+    const result = walk(value, '');
+    return { value: result, spans, changed };
+}
+/**
+ * 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 function redactContent(blocks, scan, hasher) {
+    const spans = [];
+    let changed = false;
+    const content = blocks.map((block, index) => {
+        if (block.type !== 'text')
+            return block;
+        const redacted = redactText(block.text, scan(block.text), hasher, `/${index}/text`);
+        if (redacted.spans.length === 0)
+            return block;
+        changed = true;
+        spans.push(...redacted.spans);
+        return { ...block, text: redacted.text };
+    });
+    return { content, spans, changed };
+}