@envseal/core 0.1.2 → 0.1.4

package/dist/broker.d.ts

@@ -6,6 +6,7 @@ export interface BrokerOptions {
     root: string;
     prompter?: Prompter;
     onConfirm?: ExecOptions['onConfirm'];
+    onRevokeConfirm?: (keys: string[]) => Promise<boolean>;
     onApprovalNeeded?: VerifyOptions['onApprovalNeeded'];
 }
 export declare class Broker {
@@ -14,6 +15,7 @@ export declare class Broker {
     private prompterPromise;
     private readonly ticketStore;
     private readonly onConfirm;
+    private readonly onRevokeConfirm;
     private readonly onApprovalNeeded;
     private readonly salt;
     constructor(opts: BrokerOptions);

package/dist/broker.js

@@ -1,5 +1,6 @@
 import { createHmac } from 'node:crypto';
 import { SepError, isSepError, zero } from '@envseal/protocol';
+import { compileSafePattern } from './pattern.js';
 import { getProvider, findKey } from '@envseal/registry';
 import { selectPrompter } from '@envseal/prompters';
 import { projectPaths, loadOrCreateSalt } from './paths.js';
@@ -39,12 +40,14 @@ export class Broker {
     prompterPromise;
     ticketStore;
     onConfirm;
+    onRevokeConfirm;
     onApprovalNeeded;
     salt;
     constructor(opts) {
         this.paths = projectPaths(opts.root);
         this.ticketStore = new TicketStore();
         this.onConfirm = opts.onConfirm;
+        this.onRevokeConfirm = opts.onRevokeConfirm;
         this.onApprovalNeeded = opts.onApprovalNeeded;
         this.salt = loadOrCreateSalt(this.paths);
         this.prompter = opts.prompter ?? null;
@@ -90,7 +93,7 @@ export class Broker {
                 if (formatValid === null) {
                     const trusted = findKey(entry.key)?.key.format?.pattern;
                     if (trusted !== undefined) {
-                        formatValid = new RegExp(trusted).test(value.toString('utf8'));
+                        formatValid = compileSafePattern(trusted).test(value.toString('utf8'));
                     }
                 }
             }
@@ -269,7 +272,7 @@ export class Broker {
                 }
                 if (result.outcome === 'entered') {
                     if (entry.format?.pattern) {
-                        const pattern = new RegExp(entry.format.pattern);
+                        const pattern = compileSafePattern(entry.format.pattern);
                         const valueStr = result.value.toString('utf8');
                         if (!pattern.test(valueStr)) {
                             this.ticketStore.setOutcome(ticketId, result.key, 'invalid_format');
@@ -385,16 +388,30 @@ export class Broker {
     }
     async use(input) {
         const manifest = loadManifest(this.paths) ?? emptyManifest();
+        const declaredKeys = new Set(manifest.entries.map((e) => e.key));
+        for (const keyName of input.keys) {
+            if (!declaredKeys.has(keyName)) {
+                throw new SepError({ code: 'SEP_NOT_DECLARED' });
+            }
+        }
         const secrets = new Map();
+        const missing = [];
         for (const keyName of input.keys) {
             const entry = manifest.entries.find((e) => e.key === keyName);
-            if (!entry)
-                continue;
             const sink = getSink(entry.sink ?? 'dotenv');
             const value = await sink.read(this.paths, keyName);
             if (value) {
                 secrets.set(keyName, value);
             }
+            else {
+                missing.push(keyName);
+            }
+        }
+        if (missing.length > 0) {
+            throw new SepError({
+                code: 'SEP_KEYS_MISSING',
+                userMessage: `Missing stored values for: ${missing.join(', ')}. Declare and store them before use.`,
+            });
         }
         const result = await runWithSecrets(input.command, secrets, {
             onConfirm: this.onConfirm,
@@ -405,6 +422,13 @@ export class Broker {
         return result;
     }
     async revoke(input) {
+        if (!this.onRevokeConfirm) {
+            throw new SepError({ code: 'SEP_CONFIRMATION_DENIED' });
+        }
+        const confirmed = await this.onRevokeConfirm(input.keys);
+        if (!confirmed) {
+            throw new SepError({ code: 'SEP_CONFIRMATION_DENIED' });
+        }
         const manifest = loadManifest(this.paths) ?? emptyManifest();
         const results = [];
         for (const keyName of input.keys) {

package/dist/display.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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;
+/**
+ * The full `env_revoke` approval dialog: project and key names only — never
+ * values. Every binding renders exactly this.
+ */
+export declare function revokeConfirmationBody(keys: string[], projectRoot: string): string;
+//# sourceMappingURL=display.d.ts.map

package/dist/display.js

@@ -0,0 +1,113 @@
+/**
+ * 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');
+}
+/**
+ * The full `env_revoke` approval dialog: project and key names only — never
+ * values. Every binding renders exactly this.
+ */
+export function revokeConfirmationBody(keys, projectRoot) {
+    const lines = [
+        'EnvSeal is about to remove these stored credentials.',
+        '',
+        `  project: ${escapeForDisplay(projectRoot)}`,
+        `  keys:    ${keys.length > 0 ? keys.map(escapeForDisplay).join(', ') : '(none)'}`,
+        '',
+        'Type yes to approve, or submit an empty box to deny. Nothing is removed 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/guard.d.ts

@@ -61,6 +61,7 @@ export declare function scanText(path: string, text: string, tier: GuardTier): S
  * not scanned.
  */
 export declare function scanManifestEntry(entry: ManifestEntry, basePath: string): SecretFinding | null;
+export declare function secretInManifestFileError(finding: SecretFinding): SepError;
 export declare function secretInDeclarationError(finding: SecretFinding): SepError;
 export declare function secretInRequestError(finding: SecretFinding): SepError;
 //# sourceMappingURL=guard.d.ts.map

package/dist/guard.js

@@ -133,6 +133,14 @@ export function scanManifestEntry(entry, basePath) {
     }
     return findings.find((finding) => finding !== null) ?? null;
 }
+export function secretInManifestFileError(finding) {
+    return new SepError({
+        code: 'SEP_VALUE_IN_REQUEST',
+        userMessage: `Refusing to load manifest: ${finding.path} contains secret-shaped text (${finding.label}). ` +
+            'Remove any credential from comments or other non-schema text before continuing.',
+        details: { field: finding.path, detected: finding.label, confidence: finding.confidence },
+    });
+}
 export function secretInDeclarationError(finding) {
     return new SepError({
         code: 'SEP_VALUE_IN_REQUEST',

package/dist/index.d.ts

@@ -6,11 +6,14 @@ export * from './redact.js';
 export * from './tickets.js';
 export * from './audit.js';
 export * from './sinks/types.js';
-export { parseDotenv, serializeDotenv, readDotenv, setDotenvValue, removeDotenvKey, DotenvSink, } from './sinks/dotenv.js';
-export type { DotenvLine, ParsedDotenv, WriteDotenvOptions } from './sinks/dotenv.js';
+export { parseDotenv, serializeDotenv, readDotenv, setDotenvValue, removeDotenvKey, DotenvSink, inspectDotenvGitSafety, } from './sinks/dotenv.js';
+export type { DotenvLine, ParsedDotenv, WriteDotenvOptions, DotenvGitSafety } from './sinks/dotenv.js';
+export { compileSafePattern } from './pattern.js';
+export { buildDarwinWriteArgs } from './sinks/keychain.js';
 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

@@ -6,10 +6,13 @@ export * from './redact.js';
 export * from './tickets.js';
 export * from './audit.js';
 export * from './sinks/types.js';
-export { parseDotenv, serializeDotenv, readDotenv, setDotenvValue, removeDotenvKey, DotenvSink, } from './sinks/dotenv.js';
+export { parseDotenv, serializeDotenv, readDotenv, setDotenvValue, removeDotenvKey, DotenvSink, inspectDotenvGitSafety, } from './sinks/dotenv.js';
+export { compileSafePattern } from './pattern.js';
+export { buildDarwinWriteArgs } from './sinks/keychain.js';
 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/manifest.js

@@ -3,7 +3,7 @@ import { isDeepStrictEqual } from 'node:util';
 import * as jsonc from 'jsonc-parser';
 import { DeclareResult, Manifest, ManifestEntry, SepError } from '@envseal/protocol';
 import { appendAudit } from './audit.js';
-import { scanManifestEntry, secretInDeclarationError } from './guard.js';
+import { scanText, scanManifestEntry, secretInDeclarationError, secretInManifestFileError } from './guard.js';
 export function emptyManifest() {
     return { version: 1, entries: [] };
 }
@@ -39,6 +39,15 @@ export function loadManifest(paths) {
     const text = readFileIfPresent(paths.manifest);
     if (text === null)
         return null;
+    const rawFinding = scanText('manifest', text, 'strict');
+    if (rawFinding !== null) {
+        appendAudit(paths, {
+            type: 'blocked',
+            reason: 'secret_in_declaration',
+            detail: `${rawFinding.path}: ${rawFinding.label}`,
+        });
+        throw secretInManifestFileError(rawFinding);
+    }
     const errors = [];
     const value = jsonc.parse(text, errors, {
         disallowComments: false,

package/dist/pattern.d.ts

@@ -0,0 +1,3 @@
+/** Compile a manifest format.pattern after the protocol's linearish safety check. */
+export declare function compileSafePattern(pattern: string): RegExp;
+//# sourceMappingURL=pattern.d.ts.map

package/dist/pattern.js

@@ -0,0 +1,14 @@
+import { isLinearishRegex, SepError } from '@envseal/protocol';
+/** Compile a manifest format.pattern after the protocol's linearish safety check. */
+export function compileSafePattern(pattern) {
+    if (!isLinearishRegex(pattern)) {
+        throw new SepError({ code: 'SEP_PATTERN_UNSAFE' });
+    }
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        throw new SepError({ code: 'SEP_PATTERN_UNSAFE' });
+    }
+}
+//# sourceMappingURL=pattern.js.map

package/dist/sinks/dotenv.d.ts

@@ -36,6 +36,12 @@ export interface ParsedDotenv {
 export declare function unsafeSecretToUtf8(value: SecretValue): string;
 export declare function parseDotenv(text: string): ParsedDotenv;
 export declare function serializeDotenv(parsed: ParsedDotenv): string;
+export interface DotenvGitSafety {
+    insideGit: boolean;
+    tracked: boolean;
+    ignored: boolean;
+}
+export declare function inspectDotenvGitSafety(paths: ProjectPaths): DotenvGitSafety;
 export interface WriteDotenvOptions {
     allowUnsafe?: boolean;
     description?: string;

package/dist/sinks/dotenv.js

@@ -239,6 +239,9 @@ function atomicWrite(paths, target, content) {
 function renameOverwrite(tmp, target) {
     try {
         withTransientRetry(() => renameSync(tmp, target));
+        if (isPosix) {
+            chmodSync(target, 0o600);
+        }
     }
     catch (error) {
         try {
@@ -279,18 +282,60 @@ function runGit(cwd, args) {
         return typeof status === 'number' ? status : 1;
     }
 }
+function readGitignoreLines(root) {
+    try {
+        return readFileSync(join(root, '.gitignore'), 'utf8').split(/\r\n|\n|\r/);
+    }
+    catch {
+        return [];
+    }
+}
+/** Whether a single .gitignore line would ignore the project `.env` file. */
+function gitignoreLineCoversDotenv(line) {
+    let trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('!')) {
+        return false;
+    }
+    trimmed = trimmed.replace(/\/+$/, '');
+    if (trimmed === '.env' || trimmed === '.env*' || trimmed.startsWith('.env*')) {
+        return true;
+    }
+    if (trimmed === '**/.env' || trimmed.endsWith('/.env')) {
+        return true;
+    }
+    if (trimmed === '**/.env*' || trimmed.endsWith('/.env*')) {
+        return true;
+    }
+    return /(^|\/)\.env(\*|$)/.test(trimmed);
+}
+function dotenvCoveredByGitignore(root) {
+    return readGitignoreLines(root).some(gitignoreLineCoversDotenv);
+}
+export function inspectDotenvGitSafety(paths) {
+    const insideGit = runGit(paths.root, ['rev-parse', '--is-inside-work-tree']) === 0;
+    if (!insideGit) {
+        return {
+            insideGit: false,
+            tracked: false,
+            ignored: dotenvCoveredByGitignore(paths.root),
+        };
+    }
+    const relPath = relative(paths.root, paths.dotenv);
+    const tracked = runGit(paths.root, ['ls-files', '--error-unmatch', '--', relPath]) === 0;
+    const ignored = runGit(paths.root, ['check-ignore', '-q', relPath]) === 0;
+    return { insideGit, tracked, ignored };
+}
 function assertGitSafe(paths, allowUnsafe) {
     if (allowUnsafe)
         return;
-    if (runGit(paths.root, ['rev-parse', '--is-inside-work-tree']) !== 0)
+    const status = inspectDotenvGitSafety(paths);
+    if (status.insideGit) {
+        if (status.tracked || !status.ignored) {
+            throw new SepError({ code: 'SEP_GITIGNORE_UNSAFE' });
+        }
         return;
-    const relPath = relative(paths.root, paths.dotenv);
-    const tracked = runGit(paths.root, ['ls-files', '--error-unmatch', '--', relPath]) === 0;
-    if (tracked) {
-        throw new SepError({ code: 'SEP_GITIGNORE_UNSAFE' });
     }
-    const ignored = runGit(paths.root, ['check-ignore', '-q', relPath]) === 0;
-    if (!ignored) {
+    if (!status.ignored) {
         throw new SepError({ code: 'SEP_GITIGNORE_UNSAFE' });
     }
 }

package/dist/sinks/keychain.d.ts

@@ -1,6 +1,13 @@
 import type { SecretValue } from '@envseal/protocol';
 import type { ProjectPaths } from '../paths.js';
 import type { Sink } from './types.js';
+/**
+ * Args for `security add-generic-password`. `security(1)` has no documented
+ * non-interactive stdin password path: omitting `-w` stores an empty secret
+ * (verified on macos-latest). The password therefore appears on argv for the
+ * lifetime of the spawn — residual-risks.md §2.
+ */
+export declare function buildDarwinWriteArgs(account: string, secret: string): string[];
 declare class KeychainSink implements Sink {
     readonly id = "keychain";
     available(): Promise<boolean>;

package/dist/sinks/keychain.js

@@ -44,6 +44,15 @@ function execCommand(file, args, input, env) {
         }
     });
 }
+/**
+ * Args for `security add-generic-password`. `security(1)` has no documented
+ * non-interactive stdin password path: omitting `-w` stores an empty secret
+ * (verified on macos-latest). The password therefore appears on argv for the
+ * lifetime of the spawn — residual-risks.md §2.
+ */
+export function buildDarwinWriteArgs(account, secret) {
+    return ['add-generic-password', '-U', '-s', 'envseal', '-a', account, '-w', secret];
+}
 function exitCodeOf(error) {
     return error?.exitCode;
 }
@@ -241,16 +250,7 @@ class KeychainSink {
         const account = accountFor(_paths, key);
         const valueStr = unsafeSecretToUtf8(value);
         if (process.platform === 'darwin') {
-            await execCommand('security', [
-                'add-generic-password',
-                '-U',
-                '-s',
-                'envseal',
-                '-a',
-                account,
-                '-w',
-                valueStr,
-            ]);
+            await execCommand('security', buildDarwinWriteArgs(account, valueStr));
         }
         else if (process.platform === 'win32') {
             const dir = windowsCredsDir();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envseal/core",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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.4",
+    "@envseal/registry": "0.1.4",
+    "@envseal/detector": "0.1.4",
+    "@envseal/prompters": "0.1.4"
   },
   "devDependencies": {
     "fast-check": "^3.23.1"