@envseal/core 0.1.0

package/dist/redact.js

@@ -0,0 +1,338 @@
+import { unsafeSecretToUtf8 } from './sinks/dotenv.js';
+/**
+ * Values shorter than this are never redacted. Rejecting such a value at entry
+ * is the manifest's job (PLAN §7.4); the floor exists here because a 7-byte
+ * filter removes far more innocent output than real material. Documented in
+ * docs/residual-risks.md §9.1.
+ */
+const MIN_SECRET_LENGTH = 8;
+/**
+ * Detection window. Any contiguous run of at least WINDOW characters of any
+ * variant form is redacted — which subsumes the historical rule "every prefix
+ * of length >= 20 is redacted" and additionally covers suffixes and interior
+ * fragments (W2-F5: a value split across a line break emerges as a prefix and a
+ * suffix; only the prefix used to be caught).
+ */
+const WINDOW = 20;
+/**
+ * The whole index is a chained hash table over WINDOW-length windows of every
+ * variant. Memory is bounded by this many entries (16 bytes each, so ~64 MB at
+ * the cap) no matter how long the stored values are. Past the cap the index
+ * becomes sparse (see `strideFor`) rather than growing — it never allocates an
+ * unbounded pattern, which is what used to abort the process (W2-F9: the old
+ * implementation compiled every prefix into one regex alternation, O(N^2) in
+ * pattern source, and V8's regex compiler aborts rather than throwing).
+ */
+const MAX_INDEX_ENTRIES = 4_000_000;
+/**
+ * Cap on candidate windows examined per text position. Only entries whose full
+ * 32-bit hash equals the probe's count against it, so the cap is reached only
+ * when a value contains 64+ windows with an identical hash — i.e. a highly
+ * repetitive value, whose windows are byte-identical, so the first candidate
+ * already verifies. Bucket collisions between *different* windows are skipped
+ * by a single integer compare and never consume the budget.
+ */
+const MAX_PROBES = 64;
+/**
+ * A label is emitted verbatim into the output stream, so it must be a plain
+ * identifier and nothing else. Manifest keys already match a stricter pattern
+ * (`/^[A-Z][A-Z0-9_]{0,63}$/`); anything outside this one falls back to the
+ * unlabelled token rather than being escaped, because a caller supplying such a
+ * "key name" is not describing a real key.
+ */
+const SAFE_LABEL = /^[A-Za-z_][A-Za-z0-9_]{0,63}$/;
+const GENERIC_TOKEN = '«redacted»';
+const HASH_BASE = 33_554_467;
+const HASH_MIX = 0x9e3779b1 | 0;
+const HASH_TOP = (() => {
+    let acc = 1;
+    for (let i = 1; i < WINDOW; i++)
+        acc = Math.imul(acc, HASH_BASE);
+    return acc >>> 0;
+})();
+function hashWindow(s, at) {
+    let h = 0;
+    for (let i = 0; i < WINDOW; i++)
+        h = (Math.imul(h, HASH_BASE) + s.charCodeAt(at + i)) >>> 0;
+    return h;
+}
+function rollWindow(h, outCode, inCode) {
+    return (Math.imul((h - Math.imul(outCode, HASH_TOP)) >>> 0, HASH_BASE) + inCode) >>> 0;
+}
+/**
+ * The forms a child process is most likely to emit a value in. Deliberately
+ * NOT exhaustive: a process that chooses to can always encode a value in a form
+ * no filter matches (PLAN §2.3 non-goal). See docs/residual-risks.md §9.1.
+ */
+function variantsOf(secret) {
+    const variants = new Set([secret]);
+    const encoded = Buffer.from(secret, 'utf8');
+    const base64 = encoded.toString('base64');
+    variants.add(base64);
+    variants.add(base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, ''));
+    variants.add(encodeURIComponent(secret));
+    const jsonEscaped = JSON.stringify(secret);
+    if (jsonEscaped.length >= 3)
+        variants.add(jsonEscaped.slice(1, -1));
+    const hex = encoded.toString('hex');
+    variants.add(hex);
+    variants.add(hex.toUpperCase());
+    return [...variants];
+}
+/**
+ * Index every `stride`-th window. Offset 0 is always indexed, so a whole
+ * variant and every prefix of it are always detected exactly. With stride > 1
+ * the *interior* detection length degrades from WINDOW to WINDOW + stride - 1;
+ * that only happens for values large enough that a dense index would exceed
+ * MAX_INDEX_ENTRIES (roughly 370 KB of stored value).
+ */
+function strideFor(variants) {
+    let dense = 0;
+    for (const v of variants)
+        dense += v.source.length - WINDOW + 1;
+    if (dense <= MAX_INDEX_ENTRIES)
+        return 1;
+    return Math.ceil(dense / MAX_INDEX_ENTRIES);
+}
+function buildIndex(variants, stride) {
+    let total = 0;
+    for (const v of variants)
+        total += Math.ceil((v.source.length - WINDOW + 1) / stride);
+    let bits = 1;
+    while (1 << bits < total && bits < 24)
+        bits++;
+    const size = 1 << bits;
+    const head = new Int32Array(size);
+    const entryNext = new Int32Array(total);
+    const entryVariant = new Uint32Array(total);
+    const entryOffset = new Uint32Array(total);
+    const entryHash = new Uint32Array(total);
+    const shift = 32 - bits;
+    let entry = 0;
+    for (let vi = 0; vi < variants.length; vi++) {
+        const src = variants[vi].source;
+        const windows = src.length - WINDOW + 1;
+        let h = hashWindow(src, 0);
+        for (let off = 0; off < windows; off++) {
+            if (off % stride === 0) {
+                entryVariant[entry] = vi;
+                entryOffset[entry] = off;
+                entryHash[entry] = h;
+                entry++;
+            }
+            if (off + 1 < windows)
+                h = rollWindow(h, src.charCodeAt(off), src.charCodeAt(off + WINDOW));
+        }
+    }
+    // Chain in descending entry order so each bucket's head is its LOWEST offset.
+    // For a repetitive value every window hashes alike; starting from the lowest
+    // offset gives the match the most room to extend forward, which keeps a long
+    // run one redaction rather than a chain of fragments.
+    for (let i = total - 1; i >= 0; i--) {
+        const bucket = Math.imul(entryHash[i], HASH_MIX) >>> shift;
+        entryNext[i] = head[bucket];
+        head[bucket] = i + 1;
+    }
+    return {
+        sources: variants.map((v) => v.source),
+        tokens: variants.map((v) => v.token),
+        head,
+        entryNext,
+        entryVariant,
+        entryOffset,
+        entryHash,
+        shift,
+    };
+}
+const NO_MATCH = { back: 0, forward: 0, variant: -1 };
+/**
+ * Longest run of any indexed variant anchored at text[p..p+WINDOW). `maxBack`
+ * bounds the backwards extension so a match can never reach into text that has
+ * already been emitted.
+ */
+function findMatch(idx, text, p, h, maxBack) {
+    const bucket = Math.imul(h, HASH_MIX) >>> idx.shift;
+    const textLength = text.length;
+    let best = NO_MATCH;
+    let probes = 0;
+    for (let e = idx.head[bucket]; e !== 0; e = idx.entryNext[e - 1]) {
+        const ei = e - 1;
+        if (idx.entryHash[ei] !== h)
+            continue;
+        if (++probes > MAX_PROBES)
+            break;
+        const vi = idx.entryVariant[ei];
+        const src = idx.sources[vi];
+        const off = idx.entryOffset[ei];
+        let k = 0;
+        while (k < WINDOW && src.charCodeAt(off + k) === text.charCodeAt(p + k))
+            k++;
+        if (k < WINDOW)
+            continue;
+        let forward = WINDOW;
+        while (off + forward < src.length &&
+            p + forward < textLength &&
+            src.charCodeAt(off + forward) === text.charCodeAt(p + forward)) {
+            forward++;
+        }
+        let back = 0;
+        while (back < maxBack &&
+            off - back > 0 &&
+            src.charCodeAt(off - back - 1) === text.charCodeAt(p - back - 1)) {
+            back++;
+        }
+        if (forward + back > best.forward + best.back)
+            best = { back, forward, variant: vi };
+    }
+    return best;
+}
+/**
+ * Greedy left-to-right scan. At each position try an indexed WINDOW match
+ * (extended as far as it verifiably reaches), then the shorter literals.
+ * `maxBack` bounds the backwards extension so a match can never reach into
+ * text that has already been claimed by an earlier span.
+ */
+function scanSpans(idx, literals, text) {
+    const spans = [];
+    const length = text.length;
+    let copied = 0;
+    let p = 0;
+    let h = 0;
+    let hashValid = false;
+    while (p < length) {
+        let start = p;
+        let end = p;
+        let token = '';
+        if (idx !== null && p + WINDOW <= length) {
+            if (!hashValid) {
+                h = hashWindow(text, p);
+                hashValid = true;
+            }
+            const match = findMatch(idx, text, p, h, p - copied);
+            if (match.variant >= 0) {
+                start = p - match.back;
+                end = p + match.forward;
+                token = idx.tokens[match.variant];
+            }
+        }
+        // Only reached when no indexed variant matched: every indexed match is at
+        // least WINDOW long and every literal is shorter than WINDOW.
+        if (end === start) {
+            for (const literal of literals) {
+                if (text.startsWith(literal.source, p)) {
+                    start = p;
+                    end = p + literal.source.length;
+                    token = literal.token;
+                    break;
+                }
+            }
+        }
+        if (end > start) {
+            spans.push({ start, end, token });
+            copied = end;
+            p = end;
+            hashValid = false;
+            continue;
+        }
+        if (hashValid && p + WINDOW < length) {
+            h = rollWindow(h, text.charCodeAt(p), text.charCodeAt(p + WINDOW));
+        }
+        else {
+            hashValid = false;
+        }
+        p++;
+    }
+    return spans;
+}
+/** Merge overlapping spans, keeping the earliest span's token and the union's
+ *  extent. Input spans may come from two different scans of the same text. */
+function mergeSpans(spans) {
+    if (spans.length <= 1)
+        return spans;
+    const sorted = [...spans].sort((a, b) => a.start - b.start || b.end - a.end);
+    const merged = [];
+    let current = sorted[0];
+    for (let i = 1; i < sorted.length; i++) {
+        const next = sorted[i];
+        if (next.start <= current.end) {
+            if (next.end > current.end)
+                current = { ...current, end: next.end };
+        }
+        else {
+            merged.push(current);
+            current = next;
+        }
+    }
+    merged.push(current);
+    return merged;
+}
+const WHITESPACE_RE = /\s/;
+/**
+ * Replace every occurrence of a stored value — and of the encodings in
+ * `variantsOf` — with an opaque token. Cost is O(text) in time and O(value) in
+ * memory, both bounded; nothing here compiles a pattern, so no input length can
+ * abort the process.
+ *
+ * When the text contains whitespace, a second scan runs over a
+ * whitespace-stripped dense copy with a dense→original index map (W2-F5: a
+ * value split across a line break emerges as a short head plus a suffix, and
+ * neither fragment alone may reach the detection window). Matches found dense
+ * are mapped back to original offsets and merged with the first pass's spans,
+ * so the joined fragments redact as one region including the separator.
+ */
+export function redact(text, secrets, labels) {
+    const indexable = [];
+    const literals = [];
+    const seen = new Set();
+    for (const secret of secrets) {
+        if (secret.length < MIN_SECRET_LENGTH)
+            continue;
+        const label = labels?.get(secret);
+        const token = label !== undefined && SAFE_LABEL.test(label) ? `«redacted:${label}»` : GENERIC_TOKEN;
+        for (const source of variantsOf(unsafeSecretToUtf8(secret))) {
+            if (source.length === 0 || seen.has(source))
+                continue;
+            seen.add(source);
+            if (source.length >= WINDOW)
+                indexable.push({ source, token });
+            else
+                literals.push({ source, token });
+        }
+    }
+    if (indexable.length === 0 && literals.length === 0)
+        return { text, count: 0 };
+    literals.sort((a, b) => b.source.length - a.source.length);
+    const idx = indexable.length > 0 ? buildIndex(indexable, strideFor(indexable)) : null;
+    let spans = scanSpans(idx, literals, text);
+    if (WHITESPACE_RE.test(text)) {
+        const map = [];
+        let dense = '';
+        for (let i = 0; i < text.length; i++) {
+            const ch = text[i];
+            if (!WHITESPACE_RE.test(ch)) {
+                map.push(i);
+                dense += ch;
+            }
+        }
+        if (dense.length !== text.length) {
+            for (const s of scanSpans(idx, literals, dense)) {
+                // A dense span [s.start, s.end) maps back to the original positions of
+                // its first and last characters; any whitespace between them is part of
+                // the split value and is swallowed into the redacted region.
+                spans.push({ start: map[s.start], end: map[s.end - 1] + 1, token: s.token });
+            }
+            spans = mergeSpans(spans);
+        }
+    }
+    if (spans.length === 0)
+        return { text, count: 0 };
+    let out = '';
+    let copied = 0;
+    for (const span of spans) {
+        out += text.slice(copied, span.start) + span.token;
+        copied = span.end;
+    }
+    out += text.slice(copied);
+    return { text: out, count: spans.length };
+}
+//# sourceMappingURL=redact.js.map

package/dist/sinks/cli-sink-base.d.ts

@@ -0,0 +1,88 @@
+import { SepError } from '@envseal/protocol';
+import type { SecretValue } from '@envseal/protocol';
+import type { ProjectPaths } from '../paths.js';
+import type { Sink } from './types.js';
+export interface CliExecResult {
+    stdout: string;
+    stderr: string;
+}
+export interface CliExecOptions {
+    /**
+     * Stdin payload. This is the ONLY sanctioned route for secret bytes: argv
+     * is world-readable via ps/process listings, an inherited pipe is not.
+     */
+    input?: string;
+    /**
+     * Complete environment for the child (undefined values drop the variable).
+     * Omit to inherit process.env unchanged. This REPLACES the environment
+     * rather than merging — copy process.env explicitly when adding variables,
+     * the way keychain.ts scrubs PSModulePath.
+     */
+    env?: Record<string, string | undefined>;
+    timeoutMs?: number;
+}
+/**
+ * A provider CLI ran and refused: nonzero exit, spawn failure, or timeout.
+ * The exit code rides on the error because several tools document specific
+ * codes as "item absent" — the adapter, not this base, decides which codes
+ * mean absence for read()/remove() and which are real failures.
+ */
+export declare class CliCommandFailure extends Error {
+    readonly command: string;
+    readonly exitCode: number | undefined;
+    readonly stderr: string;
+    constructor(message: string, command: string, exitCode: number | undefined, stderr: string);
+}
+export declare function exitCodeOf(error: unknown): number | undefined;
+/** Same probe keychain.ts uses; `where`/`which` exit nonzero when absent. */
+export declare function commandExists(command: string): Promise<boolean>;
+export declare function execCli(command: string, args: string[], options?: CliExecOptions): Promise<CliExecResult>;
+export type CliSinkOperation = 'read' | 'write' | 'remove';
+export declare abstract class CliSinkBase implements Sink {
+    abstract readonly id: string;
+    /**
+     * External CLIs this sink shells out to, probed in order. List every binary
+     * an operation spawns, not configuration: VAULT_ADDR-style settings are
+     * validated at operation time, where a bad value can produce a precise
+     * message instead of a vague "not installed".
+     */
+    protected abstract readonly requiredCommands: readonly string[];
+    /**
+     * What is missing, phrased for the user — e.g. "the vault CLI is not
+     * installed or VAULT_ADDR is unset". Feeds both the SEP_SINK_UNAVAILABLE
+     * thrown when a listed command is missing at operation time and the stub
+     * refusals below, until an implementing agent fills the operations in.
+     */
+    protected abstract unavailableReason(): string;
+    available(_paths: ProjectPaths): Promise<boolean>;
+    read(_paths: ProjectPaths, _key: string): Promise<SecretValue | null>;
+    write(_paths: ProjectPaths, _key: string, _value: SecretValue): Promise<void>;
+    remove(_paths: ProjectPaths, _key: string): Promise<boolean>;
+    /**
+     * Probe requiredCommands and turn a miss into SEP_SINK_UNAVAILABLE. Every
+     * real operation starts here: available() may have been consulted long
+     * before, and the CLI can vanish in between.
+     */
+    protected requirePrerequisites(): Promise<void>;
+    /**
+     * Default mapping of a raw CLI failure onto the protocol surface. The
+     * protocol has no read/remove-specific code, so WRITE_FAILED — the generic
+     * "sink operation failed" surface, and retriable, which fits how most of
+     * these failures clear (expired session, unreachable host) — is the default
+     * for every operation. Adapters override this where their tool argues for
+     * something sharper.
+     *
+     * Provider stderr stays in details only: it is diagnostics, and no
+     * user-facing message should repeat output we do not control.
+     */
+    protected sinkFailure(operation: CliSinkOperation, error: unknown, key?: string): SepError;
+    private firstMissingCommand;
+    private unavailableError;
+    /**
+     * Body of every operation until an implementing agent overrides it. The
+     * parenthetical stays even after the other operations land: a forgotten
+     * override must announce itself, not masquerade as a missing CLI.
+     */
+    private stubFailure;
+}
+//# sourceMappingURL=cli-sink-base.d.ts.map

package/dist/sinks/cli-sink-base.js

@@ -0,0 +1,217 @@
+import { spawn } from 'node:child_process';
+import { SepError } from '@envseal/protocol';
+/**
+ * Machinery shared by sinks that store secrets through an external provider
+ * CLI (vault, op, doppler, sops). The base owns what must behave identically
+ * across all four — presence probing, exec with timeout and stderr capture,
+ * exit-code-to-SepError mapping — so each adapter only translates its tool's
+ * verbs and documented exit codes.
+ *
+ * Posture inherited by every subclass:
+ * - values travel through stdin (the `input` option), never argv, where any
+ *   process listing can read them;
+ * - no path here ever logs, wraps, or stringifies a value;
+ * - read() reports absence as null and remove() as false — via each tool's
+ *   documented "not found" exit code, which only the adapter knows — while
+ *   every other failure is a loud SepError; silence is reserved for genuine
+ *   absence;
+ * - a missing provider CLI degrades available() to false and never throws at
+ *   import or construction time.
+ *
+ * No per-platform hook surface ships here on purpose: none of the four CLIs
+ * needs platform-specific invocation today, and when one does, branch on
+ * process.platform inside the adapter exactly as keychain.ts does.
+ */
+/**
+ * A provider CLI that sits silent is usually sitting on an interactive login
+ * or passphrase prompt this non-interactive pipe can never answer. Kill it
+ * rather than holding the broker open forever.
+ */
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * A provider CLI ran and refused: nonzero exit, spawn failure, or timeout.
+ * The exit code rides on the error because several tools document specific
+ * codes as "item absent" — the adapter, not this base, decides which codes
+ * mean absence for read()/remove() and which are real failures.
+ */
+export class CliCommandFailure extends Error {
+    command;
+    exitCode;
+    stderr;
+    constructor(message, command, exitCode, stderr) {
+        super(message);
+        this.command = command;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.name = 'CliCommandFailure';
+    }
+}
+export function exitCodeOf(error) {
+    return error instanceof CliCommandFailure
+        ? error.exitCode
+        : error?.exitCode;
+}
+/** First stderr line, truncated: enough to diagnose, small enough for a dialog. */
+function firstStderrLine(stderr) {
+    const first = stderr.trimStart().split(/\r?\n/, 1)[0];
+    if (first === undefined || first.length === 0)
+        return '';
+    return first.length > 200 ? `${first.slice(0, 197)}...` : first;
+}
+/** Same probe keychain.ts uses; `where`/`which` exit nonzero when absent. */
+export function commandExists(command) {
+    const checker = process.platform === 'win32' ? 'where' : 'which';
+    return new Promise((resolve) => {
+        const proc = spawn(checker, [command], { shell: false, stdio: 'ignore' });
+        proc.on('close', (code) => resolve(code === 0));
+        proc.on('error', () => resolve(false));
+    });
+}
+export function execCli(command, args, options = {}) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let stdout = '';
+        let stderr = '';
+        const proc = spawn(command, args, {
+            shell: false,
+            stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'],
+            ...(options.env ? { env: options.env } : {}),
+        });
+        const beginSettle = () => {
+            if (settled)
+                return false;
+            settled = true;
+            clearTimeout(timer);
+            return true;
+        };
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const timer = setTimeout(() => {
+            // Settle BEFORE killing: the killed child's 'close' must never overwrite
+            // the timeout verdict with a spurious nonzero-exit error.
+            if (beginSettle()) {
+                reject(new CliCommandFailure(`${command} produced no output within ${timeoutMs}ms — it is likely waiting on an interactive prompt this channel cannot answer`, command, undefined, stderr));
+            }
+            proc.kill();
+        }, timeoutMs);
+        if (proc.stdout) {
+            proc.stdout.on('data', (chunk) => {
+                stdout += chunk.toString();
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on('data', (chunk) => {
+                stderr += chunk.toString();
+            });
+        }
+        proc.on('error', (err) => {
+            if (beginSettle())
+                reject(err);
+        });
+        proc.on('close', (code) => {
+            if (!beginSettle())
+                return;
+            if (code === 0) {
+                resolve({ stdout, stderr });
+                return;
+            }
+            // Callers distinguish "item absent" (a documented exit code per tool)
+            // from real failures, so the code rides on the error itself.
+            const line = firstStderrLine(stderr);
+            reject(new CliCommandFailure(line ? `${command} exited with code ${code}: ${line}` : `${command} exited with code ${code}`, command, code ?? undefined, stderr));
+        });
+        if (proc.stdin && options.input !== undefined) {
+            // A child that dies mid-read raises EPIPE on our stdin end; swallow it —
+            // the real verdict arrives via 'close' or 'error'.
+            proc.stdin.on('error', () => { });
+            proc.stdin.write(options.input);
+            proc.stdin.end();
+        }
+    });
+}
+export class CliSinkBase {
+    async available(_paths) {
+        return (await this.firstMissingCommand()) === null;
+    }
+    async read(_paths, _key) {
+        throw this.stubFailure('read');
+    }
+    async write(_paths, _key, _value) {
+        throw this.stubFailure('write');
+    }
+    async remove(_paths, _key) {
+        throw this.stubFailure('remove');
+    }
+    /**
+     * Probe requiredCommands and turn a miss into SEP_SINK_UNAVAILABLE. Every
+     * real operation starts here: available() may have been consulted long
+     * before, and the CLI can vanish in between.
+     */
+    async requirePrerequisites() {
+        if ((await this.firstMissingCommand()) !== null)
+            throw this.unavailableError();
+    }
+    /**
+     * Default mapping of a raw CLI failure onto the protocol surface. The
+     * protocol has no read/remove-specific code, so WRITE_FAILED — the generic
+     * "sink operation failed" surface, and retriable, which fits how most of
+     * these failures clear (expired session, unreachable host) — is the default
+     * for every operation. Adapters override this where their tool argues for
+     * something sharper.
+     *
+     * Provider stderr stays in details only: it is diagnostics, and no
+     * user-facing message should repeat output we do not control.
+     */
+    sinkFailure(operation, error, key) {
+        if (error instanceof SepError)
+            return error;
+        const target = key === undefined ? '' : ` ${key}`;
+        // The binary vanished between the prerequisite probe and the spawn; that
+        // is unavailability, not a failed operation.
+        if (error?.code === 'ENOENT') {
+            return this.unavailableError();
+        }
+        if (error instanceof CliCommandFailure) {
+            return new SepError({
+                code: 'SEP_SINK_WRITE_FAILED',
+                userMessage: `Could not ${operation}${target} via ${this.id}: ${error.command} failed with exit code ${error.exitCode ?? 'unknown'}.`,
+                details: {
+                    sink: this.id,
+                    operation,
+                    command: error.command,
+                    exitCode: error.exitCode ?? null,
+                    stderr: error.stderr.slice(0, 400),
+                },
+            });
+        }
+        return new SepError({
+            code: 'SEP_SINK_WRITE_FAILED',
+            userMessage: `Could not ${operation}${target} via ${this.id}: unexpected error.`,
+            details: { sink: this.id, operation },
+        });
+    }
+    async firstMissingCommand() {
+        for (const command of this.requiredCommands) {
+            if (!(await commandExists(command)))
+                return command;
+        }
+        return null;
+    }
+    unavailableError() {
+        return new SepError({
+            code: 'SEP_SINK_UNAVAILABLE',
+            userMessage: `The ${this.id} sink is not available — ${this.unavailableReason()}.`,
+        });
+    }
+    /**
+     * Body of every operation until an implementing agent overrides it. The
+     * parenthetical stays even after the other operations land: a forgotten
+     * override must announce itself, not masquerade as a missing CLI.
+     */
+    stubFailure(operation) {
+        return new SepError({
+            code: 'SEP_SINK_UNAVAILABLE',
+            userMessage: `The ${this.id} sink is not available — ${this.unavailableReason()} (${operation} not implemented yet).`,
+        });
+    }
+}
+//# sourceMappingURL=cli-sink-base.js.map

package/dist/sinks/doppler.d.ts

@@ -0,0 +1,45 @@
+import type { SecretValue } from '@envseal/protocol';
+import type { ProjectPaths } from '../paths.js';
+import { CliSinkBase } from './cli-sink-base.js';
+import type { CliExecOptions, CliExecResult } from './cli-sink-base.js';
+/**
+ * True when a doppler credential exists: DOPPLER_TOKEN set, or a config file
+ * on disk from a previous `doppler configure` (~/.doppler/.doppler.json, the
+ * documented location). homedir() is resolved per call — os.homedir() honors
+ * HOME/USERPROFILE, which lets tests isolate the file branch. The check also
+ * degrades safely: a wrong guess about the path yields false (with an
+ * unavailable message that names DOPPLER_TOKEN), never a false "ready".
+ */
+export declare function dopplerCredentialConfigured(): boolean;
+export declare class DopplerSink extends CliSinkBase {
+    readonly id = "doppler";
+    protected readonly requiredCommands: string[];
+    protected unavailableReason(): string;
+    /**
+     * Single choke point for every spawn this sink makes. Production resolves
+     * `doppler` off PATH; tests substitute a fake provider here instead of
+     * staging one on PATH, because Windows cannot spawn shebang scripts and
+     * modern Node refuses .cmd shims outright (CVE-2024-27980) — a PATH-only
+     * double would leave the parsing/error-mapping logic unexercised there
+     * (same trade as vault.ts).
+     */
+    protected run(args: readonly string[], options?: CliExecOptions): Promise<CliExecResult>;
+    /**
+     * Doppler on PATH AND a credential to talk to. The base probe deliberately
+     * checks binaries only — credential configuration is validated here and at
+     * operation time, where its absence can produce a precise message.
+     */
+    available(_paths: ProjectPaths): Promise<boolean>;
+    read(paths: ProjectPaths, key: string): Promise<SecretValue | null>;
+    write(paths: ProjectPaths, key: string, value: SecretValue): Promise<void>;
+    remove(paths: ProjectPaths, key: string): Promise<boolean>;
+    /**
+     * Every operation re-probes the CLI — available() may have been consulted
+     * long before, and the binary can vanish in between — then demands a
+     * credential separately, whose absence gets its own precise message instead
+     * of hiding behind the generic reason.
+     */
+    private requireReady;
+}
+export declare const dopplerSink: DopplerSink;
+//# sourceMappingURL=doppler.d.ts.map