@envseal/core 0.1.2 → 0.1.3

package/dist/display.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared rendering for the human-consent dialogs across every binding.
+ *
+ * This used to live twice — hand-maintained twins in @envseal/mcp-server and
+ * @envseal/sdk — and a third, weaker copy rolled its own in the CLI's `run`
+ * confirmation. One copy here feeds all three: cli, sdk and mcp-server all
+ * already depend on @envseal/core, so this adds no dependency edge.
+ */
+/**
+ * Model-supplied argv, key names and probe metadata land in a dialog the user
+ * is about to trust. Control characters let a crafted argument forge extra
+ * lines — "keys: none", "this command is safe" — inside the very block that
+ * exists to tell the truth about the command; Unicode separators can split
+ * lines invisibly and bidi controls can reorder what a terminal shows.
+ * Render all of them visibly instead.
+ */
+export declare function escapeForDisplay(value: string): string;
+export declare function displayArg(arg: string): string;
+/**
+ * The full `env_use` approval dialog: project, keys, argv one-per-line,
+ * content fingerprints of every named file (see exec.ts target hashing),
+ * the egress warning or the honest heuristics disclaimer, and the answer
+ * format. Every binding renders exactly this.
+ */
+export declare function useConfirmationBody(info: {
+    command: string[];
+    keys: string[];
+    networkEgress: boolean;
+    target?: import('./exec.js').TargetInfo;
+}, projectRoot: string): string;
+//# sourceMappingURL=display.d.ts.map

package/dist/display.js

@@ -0,0 +1,98 @@
+/**
+ * Shared rendering for the human-consent dialogs across every binding.
+ *
+ * This used to live twice — hand-maintained twins in @envseal/mcp-server and
+ * @envseal/sdk — and a third, weaker copy rolled its own in the CLI's `run`
+ * confirmation. One copy here feeds all three: cli, sdk and mcp-server all
+ * already depend on @envseal/core, so this adds no dependency edge.
+ */
+/** Per-argument display cap; longer arguments are shown truncated, and said to be. */
+const MAX_ARG_CHARS = 300;
+/**
+ * Model-supplied argv, key names and probe metadata land in a dialog the user
+ * is about to trust. Control characters let a crafted argument forge extra
+ * lines — "keys: none", "this command is safe" — inside the very block that
+ * exists to tell the truth about the command; Unicode separators can split
+ * lines invisibly and bidi controls can reorder what a terminal shows.
+ * Render all of them visibly instead.
+ */
+export function escapeForDisplay(value) {
+    let out = '';
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        const c1 = code < 0x20 ||
+            (code >= 0x7f && code <= 0x9f) ||
+            code === 0x2028 ||
+            code === 0x2029 ||
+            (code >= 0x200b && code <= 0x200f) ||
+            (code >= 0x202a && code <= 0x202e) ||
+            (code >= 0x2066 && code <= 0x2069) ||
+            code === 0xfeff;
+        out += c1 ? `<U+${code.toString(16).toUpperCase().padStart(4, '0')}>` : ch;
+    }
+    return out;
+}
+export function displayArg(arg) {
+    const escaped = escapeForDisplay(arg);
+    if (escaped.length <= MAX_ARG_CHARS) {
+        return escaped;
+    }
+    const hidden = escaped.length - MAX_ARG_CHARS;
+    return `${escaped.slice(0, MAX_ARG_CHARS)}[... ${hidden} more characters, not shown]`;
+}
+/**
+ * The full `env_use` approval dialog: project, keys, argv one-per-line,
+ * content fingerprints of every named file (see exec.ts target hashing),
+ * the egress warning or the honest heuristics disclaimer, and the answer
+ * format. Every binding renders exactly this.
+ */
+export function useConfirmationBody(info, projectRoot) {
+    const lines = [
+        'EnvSeal is about to run a program with these secrets in its environment.',
+        '',
+        `  project: ${escapeForDisplay(projectRoot)}`,
+        `  keys:    ${info.keys.length > 0 ? info.keys.map(escapeForDisplay).join(', ') : '(none)'}`,
+        '',
+        '  command, one argument per line, exactly as it will be run (no shell):',
+    ];
+    info.command.forEach((arg, index) => {
+        lines.push(`    [${index}] ${displayArg(arg)}`);
+    });
+    lines.push('');
+    if (info.target) {
+        const { resolvedPath, sha256, hashedFiles } = info.target;
+        const targetLabel = sha256 !== null
+            ? escapeForDisplay(resolvedPath)
+            : `${escapeForDisplay(resolvedPath)} (not a readable file)`;
+        lines.push(`  target:  ${targetLabel}`);
+        if (hashedFiles.length > 0) {
+            // The approval binds to these fingerprints, not to the text above:
+            // every named file is re-hashed just before spawn and any mismatch
+            // refuses with SEP_TARGET_CHANGED, so content swapped in after this
+            // dialog closes does not run.
+            for (const file of hashedFiles) {
+                lines.push(`    ${escapeForDisplay(file.argument)}`);
+                lines.push(`      sha256: ${file.sha256}`);
+            }
+            lines.push('  Each listed file is re-checked against its fingerprint immediately', '  before the program runs; one that changed since you read this will', '  not run.');
+        }
+        else {
+            // Honest about the boundary of the control: nothing in the command
+            // named a readable file, so approval stays name-level.
+            lines.push('  No argument named a readable file, so approval covers names only.');
+        }
+        lines.push('');
+    }
+    if (info.networkEgress) {
+        lines.push('  WARNING: this command can reach the network, so it could send these', '           values somewhere. Only continue if you trust it.');
+    }
+    else {
+        // Honest about what the check is worth: NETWORK_TOOLS plus a URL scan is a
+        // heuristic, and claiming more would be the kind of overstatement this
+        // project has already had to walk back once.
+        lines.push('  No network tool or URL was recognised in this command. That is a', '  heuristic, not a guarantee: any program can open a socket.');
+    }
+    lines.push('', 'Type yes to approve, or submit an empty box to deny. Nothing runs unless you approve.');
+    return lines.join('\\n');
+}
+//# sourceMappingURL=display.js.map

package/dist/exec.d.ts

@@ -2,8 +2,45 @@ import type { SecretValue, ExecResult } from '@envseal/protocol';
 /**
  * Residual risk on Linux: A same-uid process can read /proc/<pid>/environ
  * of the child process. This cannot be defended against without sandboxing.
- * Users on shared systems should be aware of this limitation.
+ * Users on shared systems should see this limitation.
  */
+/**
+ * One argument that named a readable file at approval time, bound to its
+ * content. Repo scripts usually ride as arguments (`node ./build/x.mjs`,
+ * `bash scripts/release.sh`), so consent must cover them, not just argv[0].
+ */
+export interface TargetFile {
+    /** The argument exactly as it appeared in the command. */
+    argument: string;
+    /** Absolute path whose content was hashed. */
+    resolvedPath: string;
+    /** SHA-256 of the file content at approval time. */
+    sha256: string;
+}
+/**
+ * What the approver is told about the program they are approving. Consent for
+ * `env_use` binds to this content, not to the displayed argument text: a repo
+ * script named anywhere in argv can be rewritten while the approval dialog is
+ * open, so the dialog shows content fingerprints and every named file is
+ * re-checked immediately before spawn (see the T11 note below).
+ */
+export interface TargetInfo {
+    /** Absolute resolution of argv[0]; often a PATH lookup, not a file. */
+    resolvedPath: string;
+    /**
+     * SHA-256 of argv[0]'s own content when argv[0] names a readable file
+     * (direct script invocation: `./scripts/release.sh`), else null
+     * (PATH-resolved executables: `node`, `python`, ...).
+     */
+    sha256: string | null;
+    /**
+     * Every distinct argument that resolved to a readable file — including
+     * argv[0] itself when it is one. Each entry is re-verified against fresh
+     * disk content just before spawn; any change refuses with
+     * SEP_TARGET_CHANGED.
+     */
+    hashedFiles: TargetFile[];
+}
 export interface ExecOptions {
     cwd?: string;
     timeoutMs?: number;
@@ -11,6 +48,7 @@ export interface ExecOptions {
         command: string[];
         keys: string[];
         networkEgress: boolean;
+        target: TargetInfo;
     }) => Promise<boolean>;
     approvedCommands?: string[];
 }

package/dist/exec.js

@@ -1,4 +1,8 @@
 import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { resolve as resolvePath } from 'node:path';
 import { SepError } from '@envseal/protocol';
 import { redact } from './redact.js';
 import { unsafeSecretToUtf8 } from './sinks/dotenv.js';
@@ -16,6 +20,8 @@ const NETWORK_TOOLS = new Set([
     'telnet',
     'socat',
 ]);
+/** Nothing remotely path-shaped is longer than this on any supported OS. */
+const MAX_PATHISH_CHARS = 4096;
 function detectNetworkEgress(command) {
     if (command.length === 0) {
         return false;
@@ -31,6 +37,100 @@ function detectNetworkEgress(command) {
     }
     return false;
 }
+/**
+ * T11 hardening: hash the files the command names, so approval binds to
+ * content rather than to displayed text. Streaming read — a multi-gigabyte
+ * argument must not be loaded into memory to be fingerprinted. Any read
+ * failure yields null rather than throwing: unreadable targets fail later at
+ * spawn with their own honest error, and refusing here would report a denial
+ * nobody made.
+ */
+async function sha256File(path) {
+    try {
+        const info = await stat(path);
+        if (!info.isFile()) {
+            return null;
+        }
+        const hash = createHash('sha256');
+        await new Promise((resolveStream, rejectStream) => {
+            const stream = createReadStream(path);
+            stream.on('data', (chunk) => hash.update(chunk));
+            stream.on('end', () => resolveStream());
+            stream.on('error', rejectStream);
+        });
+        return hash.digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+async function snapshotNamedFiles(command, cwd) {
+    const base = cwd ?? process.cwd();
+    const files = new Map();
+    const pending = new Set();
+    let argv0Sha = null;
+    let argv0Resolved = '';
+    for (let index = 0; index < command.length; index += 1) {
+        const arg = command[index];
+        if (arg.length === 0 ||
+            arg.length > MAX_PATHISH_CHARS ||
+            // Scheme-shaped (https://..., file://...) — but NOT a Windows drive
+            // path: `C:\repo\script.mjs` matches the naive scheme regex and must
+            // stay hashable.
+            (/^[a-z][a-z0-9+.-]*:/i.test(arg) && !/^[a-zA-Z]:(\\|\/)/.test(arg))) {
+            continue; // empty, impossibly long, or URL-shaped
+        }
+        const abs = resolvePath(base, arg);
+        if (index === 0) {
+            argv0Resolved = abs;
+        }
+        const sha = await sha256File(abs);
+        if (sha !== null) {
+            if (index === 0) {
+                argv0Sha = sha;
+            }
+            files.set(abs, sha);
+        }
+        else if (!files.has(abs)) {
+            pending.add(abs);
+        }
+    }
+    const hashedFiles = [];
+    for (let index = 0; index < command.length; index += 1) {
+        const abs = resolvePath(base, command[index]);
+        const sha = files.get(abs);
+        if (sha !== undefined) {
+            hashedFiles.push({ argument: command[index], resolvedPath: abs, sha256: sha });
+        }
+    }
+    return {
+        info: { resolvedPath: argv0Resolved, sha256: argv0Sha, hashedFiles },
+        snapshot: { files, pending },
+    };
+}
+function assertUnchanged(approved, current, samplePath) {
+    for (const [path, sha] of approved.files) {
+        const now = current.files.get(path);
+        if (now === null || now === undefined || now !== sha) {
+            throw new SepError({
+                code: 'SEP_TARGET_CHANGED',
+                details: { target: path },
+            });
+        }
+    }
+    for (const path of approved.pending) {
+        // Named but absent (or directory) at approval time; a readable file
+        // appearing there before spawn means the command would execute content
+        // nobody could approve.
+        if (current.files.has(path)) {
+            throw new SepError({
+                code: 'SEP_TARGET_CHANGED',
+                details: { target: path },
+            });
+        }
+    }
+    void samplePath;
+}
 export async function runWithSecrets(command, secrets, opts) {
     if (command.length === 0) {
         throw new SepError({
@@ -42,17 +142,28 @@ export async function runWithSecrets(command, secrets, opts) {
     const secretKeys = Array.from(secrets.keys());
     const joinedCommand = command.join(' ');
     const isApproved = opts?.approvedCommands?.some((approved) => approved === joinedCommand);
+    // The named files are fingerprinted twice: before the dialog is drawn (so
+    // the user approves content fingerprints, not just a command line) and
+    // again after consent, immediately before spawn. Content that changed in
+    // between — the injected-content-mutates-a-repo-script window — refuses
+    // with SEP_TARGET_CHANGED and nothing executes. The second read narrows
+    // the race to microseconds; closing it entirely would need an fd handed to
+    // the OS loader, which Node's spawn does not expose.
+    const approvedSnapshot = await snapshotNamedFiles(command, opts?.cwd);
     if (!isApproved && opts?.onConfirm) {
         const confirmed = await opts.onConfirm({
             command,
             keys: secretKeys,
             networkEgress,
+            target: approvedSnapshot.info,
         });
         if (!confirmed) {
             throw new SepError({
                 code: 'SEP_CONFIRMATION_DENIED',
             });
         }
+        const justBeforeSpawn = await snapshotNamedFiles(command, opts?.cwd);
+        assertUnchanged(approvedSnapshot.snapshot, justBeforeSpawn.snapshot, approvedSnapshot.info.resolvedPath);
     }
     else if (!isApproved && !opts?.onConfirm) {
         throw new SepError({
@@ -61,7 +172,7 @@ export async function runWithSecrets(command, secrets, opts) {
     }
     const childEnv = { ...process.env };
     const secretValues = [];
-    // W2-F31: docs/cli-contract.md §"redaction" promises masks read
+    // W2-F31: docs/cli-contract.md promises masks read
     // «redacted:KEY_NAME». Nothing but the key name rides along — redact()
     // rejects a label that is not a plain identifier, so a label can never carry
     // markup or a value fragment into the output stream.

package/dist/index.d.ts

@@ -11,6 +11,7 @@ export type { DotenvLine, ParsedDotenv, WriteDotenvOptions } from './sinks/doten
 export * from './approvals.js';
 export * from './verify.js';
 export * from './exec.js';
+export * from './display.js';
 export * from './sinks/registry.js';
 export { keychainSink } from './sinks/keychain.js';
 export * from './broker.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export { parseDotenv, serializeDotenv, readDotenv, setDotenvValue, removeDotenvK
 export * from './approvals.js';
 export * from './verify.js';
 export * from './exec.js';
+export * from './display.js';
 export * from './sinks/registry.js';
 export { keychainSink } from './sinks/keychain.js';
 export * from './broker.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envseal/core",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -22,10 +22,10 @@
   "dependencies": {
     "jsonc-parser": "^3.3.1",
     "ulid": "^2.3.0",
-    "@envseal/registry": "0.1.2",
-    "@envseal/prompters": "0.1.2",
-    "@envseal/detector": "0.1.2",
-    "@envseal/protocol": "0.1.2"
+    "@envseal/protocol": "0.1.3",
+    "@envseal/registry": "0.1.3",
+    "@envseal/detector": "0.1.3",
+    "@envseal/prompters": "0.1.3"
   },
   "devDependencies": {
     "fast-check": "^3.23.1"