@envseal/core 0.1.5 → 0.1.6

package/dist/audit.d.ts

@@ -30,12 +30,86 @@ export type AuditEvent = {
     type: 'blocked';
     reason: string;
     detail: string;
+}
+/**
+ * One env_use execution attempt. Written after consent succeeds,
+ * immediately before spawn — a crash mid-run still leaves the attempt
+ * recorded; denied consent records nothing. The command is persisted only
+ * after passing through the redaction engine.
+ */
+ | {
+    type: 'use';
+    command: string;
+    keys: string[];
+    networkEgress: boolean;
+    targetHashes?: Record<string, string>;
+}
+/** How the attempt ended; paired with the preceding 'use' record. */
+ | {
+    type: 'use_result';
+    exitCode: number | null;
+    signal: string | null;
+    durationMs: number;
 };
 export type AuditRecord = AuditEvent & {
     at: string;
     v: number;
 };
+/**
+ * Chain fields. `seq` starts at 1; `prev` is the sha256 hex of the previous
+ * RAW line (genesis = 64 zeros), so any edit to a surviving record — or its
+ * deletion, which surfaces as a seq gap — breaks every successor's
+ * attestation and is reported by verifyAuditChain(). The chain proves the
+ * records that survive are intact and ordered; nothing outside the log
+ * records how many records should exist, so tail truncation is NOT
+ * detectable and is documented as an honest boundary rather than hidden.
+ */
+export declare const GENESIS_PREV: string;
 export declare function appendAudit(paths: ProjectPaths, event: AuditEvent): void;
+/** Mirror file for one project root. The key is sha256 of the project's
+ *  canonical path, so the same directory hashes to one mirror file no matter
+ *  how the root was spelled — Windows 8.3 short names, symlinks, differing
+ *  case, or a trailing separator all collapse to the same identity.
+ *  realpathSync.native is the only core API that expands 8.3 short names
+ *  (plain realpath does not); it falls back to realpath then to the resolved
+ *  spelling when the filesystem or a torn-down project refuses it. */
+export declare function auditMirrorPath(root: string): string;
+/** Raw non-empty lines of the project's mirror, or null when there is none. */
+export declare function readMirrorLines(root: string): string[] | null;
+export interface MirrorComparison {
+    mirrorPresent: boolean;
+    mirrorRecords: number;
+    projectRecords: number;
+    /** The mirror holds records the project log no longer does. */
+    tailTruncated: boolean;
+}
+/**
+ * Compare the project log's raw bytes against its mirror.
+ *
+ * Truncation is chain-anchored, not count-based: the mirror's record with
+ * seq = projectMaxSeq + 1 must attest exactly the project's last surviving
+ * line (prev == sha256 of that raw line) for an alarm to fire. That is
+ * cryptographic proof those records existed and were deleted after mirroring.
+ * A legitimate full reset (project log restarted at seq 1) does not false-positive:
+ * its successor in the mirror was written before the reset, so its prev chain
+ * cannot match the new log's lines. An empty project log beside a non-empty
+ * mirror is always loss — records demonstrably existed for this project.
+ */
+export declare function compareWithMirror(projectRaw: string, mirrorLines: string[] | null): MirrorComparison;
+/**
+ * Verify the hash chain over the raw lines of an audit log.
+ *
+ * Blame semantics: a deleted or wrongly-numbered record is reported at its own
+ * expected position; a record whose CONTENT was edited in place keeps a valid
+ * seq, so the break surfaces through its successor's chained hash — it is
+ * blamed on the tampered record itself (brokenAt = k, detected at k+1).
+ * Tail truncation verifies OK by design — see the chain-field comment above.
+ */
+export declare function verifyAuditChain(raw: string): {
+    ok: boolean;
+    brokenAt?: number;
+    count: number;
+};
 export declare function readAudit(paths: ProjectPaths): Array<AuditEvent & {
     at: string;
 }>;

package/dist/audit.js

@@ -1,12 +1,240 @@
-import { appendFileSync, readFileSync, chmodSync } from 'node:fs';
+import { appendFileSync, chmodSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 import { ensureStateDir } from './paths.js';
+/**
+ * Chain fields. `seq` starts at 1; `prev` is the sha256 hex of the previous
+ * RAW line (genesis = 64 zeros), so any edit to a surviving record — or its
+ * deletion, which surfaces as a seq gap — breaks every successor's
+ * attestation and is reported by verifyAuditChain(). The chain proves the
+ * records that survive are intact and ordered; nothing outside the log
+ * records how many records should exist, so tail truncation is NOT
+ * detectable and is documented as an honest boundary rather than hidden.
+ */
+export const GENESIS_PREV = '0'.repeat(64);
 const isPosix = process.platform !== 'win32';
+/** sha256 hex of one raw log line (no trailing newline). */
+function lineHash(line) {
+    return createHash('sha256').update(line, 'utf8').digest('hex');
+}
+/** Last non-empty raw line of the audit file, or null when absent/empty. */
+function lastRawLine(auditPath) {
+    let raw;
+    try {
+        raw = readFileSync(auditPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const lines = raw.split(/\r?\n/).filter((line) => line.length > 0);
+    return lines.length > 0 ? (lines[lines.length - 1] ?? null) : null;
+}
+function lastSeqOf(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed.seq === 'number' && Number.isInteger(parsed.seq) && parsed.seq > 0 ? parsed.seq : 0;
+    }
+    catch {
+        return 0;
+    }
+}
 export function appendAudit(paths, event) {
     ensureStateDir(paths);
-    const record = { ...event, at: new Date().toISOString(), v: 1 };
-    appendFileSync(paths.audit, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    const prevLine = lastRawLine(paths.audit);
+    // A corrupt trailing line reads as seq 0, so the next record restarts at 1.
+    // That is the honest reading of a log whose head of chain is unverifiable.
+    const prev = prevLine === null ? GENESIS_PREV : lineHash(prevLine);
+    const seq = prevLine === null ? 1 : lastSeqOf(prevLine) + 1;
+    const record = { ...event, at: new Date().toISOString(), v: 1, seq, prev };
+    const line = `${JSON.stringify(record)}\n`;
+    appendFileSync(paths.audit, line, { mode: 0o600 });
     if (isPosix)
         chmodSync(paths.audit, 0o600);
+    mirrorAuditLine(paths.root, line);
+}
+// --- Out-of-band mirror -----------------------------------------------------
+//
+// Residual risk §10: the project audit log is agent-writable and tail
+// truncation is undetectable from the log alone. The mirror streams the same
+// records to a second file under the user's own ~/.envseal, outside the
+// project the agent operates in, so `envseal audit --verify` can detect
+// records the project log lost. It raises the bar; it is not immutability —
+// a same-uid attacker can tamper both copies, and the docs say so.
+let mirrorWarned = false;
+/** Directory holding per-project mirrors. ENVSEAL_AUDIT_MIRROR=0 opts out;
+ *  a path value redirects the mirror (e.g. at a synced folder so records also
+ *  leave the machine); unset defaults to ~/.envseal/mirrors. */
+function mirrorsDir() {
+    const setting = process.env.ENVSEAL_AUDIT_MIRROR;
+    if (setting !== undefined && setting !== '0' && setting.trim() !== '') {
+        return setting;
+    }
+    return join(homedir(), '.envseal', 'mirrors');
+}
+/** Mirror file for one project root. The key is sha256 of the project's
+ *  canonical path, so the same directory hashes to one mirror file no matter
+ *  how the root was spelled — Windows 8.3 short names, symlinks, differing
+ *  case, or a trailing separator all collapse to the same identity.
+ *  realpathSync.native is the only core API that expands 8.3 short names
+ *  (plain realpath does not); it falls back to realpath then to the resolved
+ *  spelling when the filesystem or a torn-down project refuses it. */
+export function auditMirrorPath(root) {
+    const resolved = resolve(root);
+    let canonical = resolved;
+    try {
+        canonical = realpathSync.native(resolved);
+    }
+    catch {
+        try {
+            canonical = realpathSync(resolved);
+        }
+        catch {
+            // Nonexistent root: the resolved spelling is the best identity available.
+        }
+    }
+    const key = createHash('sha256').update(resolvePosix(canonical), 'utf8').digest('hex');
+    return join(mirrorsDir(), `${key}.jsonl`);
+}
+function resolvePosix(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Best-effort append of one already-serialized audit line to the project's
+ * mirror. Default ON; ENVSEAL_AUDIT_MIRROR=0 opts out. A mirror failure never
+ * blocks provisioning and never throws: one fixed stderr warning per process,
+ * no path and no error detail (a path or error could carry secret-shaped text).
+ */
+function mirrorAuditLine(root, line) {
+    if (process.env.ENVSEAL_AUDIT_MIRROR === '0') {
+        return;
+    }
+    try {
+        const mirror = auditMirrorPath(root);
+        mkdirSync(dirname(mirror), { recursive: true, mode: 0o700 });
+        appendFileSync(mirror, line, { mode: 0o600 });
+        if (isPosix)
+            chmodSync(mirror, 0o600);
+    }
+    catch {
+        if (!mirrorWarned) {
+            mirrorWarned = true;
+            process.stderr.write('envseal: audit mirror unavailable — continuing without it\n');
+        }
+    }
+}
+/** Raw non-empty lines of the project's mirror, or null when there is none. */
+export function readMirrorLines(root) {
+    try {
+        const raw = readFileSync(auditMirrorPath(root), 'utf8');
+        return raw.split(/\r?\n/).filter((line) => line.length > 0);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        return null;
+    }
+}
+function parseSeqs(lines) {
+    const out = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (typeof parsed.seq === 'number' &&
+                Number.isInteger(parsed.seq) &&
+                parsed.seq > 0 &&
+                typeof parsed.prev === 'string') {
+                out.push({ seq: parsed.seq, line, prev: parsed.prev });
+            }
+        }
+        catch {
+            // Foreign/corrupt mirror lines carry no attestation and are skipped.
+        }
+    }
+    return out;
+}
+/**
+ * Compare the project log's raw bytes against its mirror.
+ *
+ * Truncation is chain-anchored, not count-based: the mirror's record with
+ * seq = projectMaxSeq + 1 must attest exactly the project's last surviving
+ * line (prev == sha256 of that raw line) for an alarm to fire. That is
+ * cryptographic proof those records existed and were deleted after mirroring.
+ * A legitimate full reset (project log restarted at seq 1) does not false-positive:
+ * its successor in the mirror was written before the reset, so its prev chain
+ * cannot match the new log's lines. An empty project log beside a non-empty
+ * mirror is always loss — records demonstrably existed for this project.
+ */
+export function compareWithMirror(projectRaw, mirrorLines) {
+    const projectLines = projectRaw
+        .split(/\r?\n/)
+        .map((line) => line.replace(/\r$/, ''))
+        .filter((line) => line.length > 0);
+    if (mirrorLines === null) {
+        return { mirrorPresent: false, mirrorRecords: 0, projectRecords: projectLines.length, tailTruncated: false };
+    }
+    const project = parseSeqs(projectLines);
+    const mirror = parseSeqs(mirrorLines);
+    let tailTruncated = false;
+    if (project.length === 0) {
+        tailTruncated = mirror.length > 0;
+    }
+    else {
+        const projectMax = project[project.length - 1].seq;
+        const successor = mirror.find((m) => m.seq === projectMax + 1);
+        if (successor !== undefined && successor.prev === lineHash(project[project.length - 1].line)) {
+            tailTruncated = true;
+        }
+    }
+    return {
+        mirrorPresent: true,
+        mirrorRecords: mirror.length,
+        projectRecords: project.length,
+        tailTruncated,
+    };
+}
+/**
+ * Verify the hash chain over the raw lines of an audit log.
+ *
+ * Blame semantics: a deleted or wrongly-numbered record is reported at its own
+ * expected position; a record whose CONTENT was edited in place keeps a valid
+ * seq, so the break surfaces through its successor's chained hash — it is
+ * blamed on the tampered record itself (brokenAt = k, detected at k+1).
+ * Tail truncation verifies OK by design — see the chain-field comment above.
+ */
+export function verifyAuditChain(raw) {
+    const lines = raw
+        .split(/\r?\n/)
+        .map((line) => line.replace(/\r$/, ''))
+        .filter((line) => line.length > 0);
+    let expectedSeq = 1;
+    let prevHash = GENESIS_PREV;
+    for (const line of lines) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            // Unparseable line at this position IS the corruption.
+            return { ok: false, brokenAt: expectedSeq, count: expectedSeq - 1 };
+        }
+        if (parsed.seq !== expectedSeq) {
+            // Missing, duplicated, or renumbered record: blame the position itself.
+            return { ok: false, brokenAt: expectedSeq, count: expectedSeq - 1 };
+        }
+        if (parsed.prev !== prevHash) {
+            // This record's attestation over its predecessor fails, so the
+            // PREDECESSOR's bytes were changed after the fact. First record with a
+            // non-genesis prev means the log head itself was tampered with.
+            const blamed = Math.max(1, expectedSeq - 1);
+            return { ok: false, brokenAt: blamed, count: expectedSeq - 1 };
+        }
+        prevHash = lineHash(line);
+        expectedSeq += 1;
+    }
+    return { ok: true, count: expectedSeq - 1 };
 }
 export function readAudit(paths) {
     let raw;

package/dist/broker.js

@@ -12,6 +12,7 @@ import { verifyKey } from './verify.js';
 import { runWithSecrets } from './exec.js';
 import { getSink } from './sinks/registry.js';
 import { getValidation, recordValidation } from './validation-state.js';
+import { loadRotationState, recordRotation } from './rotation-state.js';
 import { scanText, secretInRequestError } from './guard.js';
 function getLengthBucket(length) {
     if (length < 8)
@@ -71,6 +72,10 @@ export class Broker {
         const presence = await resolvePresence(this.paths, manifest.entries.map((e) => e.key), { sinks: new Map(manifest.entries.map((e) => [e.key, e.sink ?? 'dotenv'])) });
         const entries = [];
         const missingRequired = [];
+        // Age markers for rotation reporting, loaded once and stamped lazily here:
+        // hand-written .env values never cross an envseal write path, so first
+        // sight in describe() is the only hook that sees every stored value.
+        const rotationState = loadRotationState(this.paths);
         for (const entry of manifest.entries) {
             const presenceInfo = presence.get(entry.key);
             const present = presenceInfo?.present ?? false;
@@ -97,6 +102,21 @@ export class Broker {
                     }
                 }
             }
+            // rotationDue = first observation of THESE bytes + the declared
+            // maxAgeDays. Absent policy, absent value, or unknown age all report
+            // null: "no advice" must stay distinguishable from "overdue".
+            let rotationDue = null;
+            if (present && value) {
+                const maxAgeDays = entry.rotation?.maxAgeDays;
+                let ageRecord = rotationState[entry.key];
+                if (!ageRecord || ageRecord.fingerprint !== fingerprint) {
+                    ageRecord = recordRotation(this.paths, entry.key, fingerprint);
+                    rotationState[entry.key] = ageRecord;
+                }
+                if (maxAgeDays !== undefined) {
+                    rotationDue = new Date(Date.parse(ageRecord.at) + maxAgeDays * 24 * 60 * 60 * 1000).toISOString();
+                }
+            }
             const status = {
                 key: entry.key,
                 declared: true,
@@ -108,7 +128,7 @@ export class Broker {
                 lastVerified: null,
                 verifyResult: null,
                 source: 'user-prompt',
-                rotationDue: null,
+                rotationDue,
             };
             entries.push(status);
             if (entry.required && !present) {
@@ -150,7 +170,14 @@ export class Broker {
                 verify: entry.verify ?? key.verify,
             };
         });
-        return declareEntries(this.paths, withDefaults);
+        const result = declareEntries(this.paths, withDefaults);
+        // The declaration itself is audited: a model reshaping the manifest is
+        // exactly the activity the log exists to answer for later.
+        appendAudit(this.paths, {
+            type: 'declare',
+            keys: withDefaults.map((entry) => entry.key),
+        });
+        return result;
     }
     async request(input) {
         // Before the manifest is even read: `reason` is free text that goes
@@ -381,6 +408,9 @@ export class Broker {
             const result = await verifyKey(this.paths, entry, value, {
                 onApprovalNeeded: this.onApprovalNeeded,
             });
+            // Probe outcomes are audited: a verify against an attacker-approved
+            // host is a forensic event even when the probe itself leaks nothing.
+            appendAudit(this.paths, { type: 'verify', key: keyName, result: result.result });
             results.push(result);
             zero(value);
         }
@@ -415,6 +445,12 @@ export class Broker {
         }
         const result = await runWithSecrets(input.command, secrets, {
             onConfirm: this.onConfirm,
+            // The project's standing egress rule: allowlist mode refuses
+            // non-allowlisted network targets before any dialog opens.
+            egressPolicy: manifest.policy?.egress,
+            // Execution auditing (use / use_result) is wired here so the product
+            // path records every attempt in the chained audit log.
+            auditPaths: this.paths,
         });
         for (const value of secrets.values()) {
             zero(value);

package/dist/display.d.ts

@@ -1,11 +1,3 @@
-/**
- * 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
@@ -19,13 +11,22 @@ 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.
+ * the egress warning plus the extracted network targets, 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;
+    /**
+     * Where the command could reach the network, as extracted by
+     * extractEgressHosts (exec.ts computes it either way — this only decides
+     * whether the dialog names the destinations). Optional so older callers
+     * keep rendering; when present alongside networkEgress the user sees
+     * WHERE data could go, not merely THAT it could leave.
+     */
+    egressHosts?: string[];
     target?: import('./exec.js').TargetInfo;
 }, projectRoot: string): string;
 /**

package/dist/display.js

@@ -6,6 +6,7 @@
  * confirmation. One copy here feeds all three: cli, sdk and mcp-server all
  * already depend on @envseal/core, so this adds no dependency edge.
  */
+import { UNKNOWN_HOST } from './egress.js';
 /** Per-argument display cap; longer arguments are shown truncated, and said to be. */
 const MAX_ARG_CHARS = 300;
 /**
@@ -43,8 +44,9 @@ export function displayArg(arg) {
 /**
  * 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.
+ * the egress warning plus the extracted network targets, or the honest
+ * heuristics disclaimer, and the answer format. Every binding renders
+ * exactly this.
  */
 export function useConfirmationBody(info, projectRoot) {
     const lines = [
@@ -85,6 +87,17 @@ export function useConfirmationBody(info, projectRoot) {
     }
     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.');
+        if (info.egressHosts !== undefined && info.egressHosts.length > 0) {
+            // Name the destinations, not just the capability. A host that could
+            // not be determined (bare IP, encoded target — UNKNOWN_HOST from
+            // core/egress.ts) is said so plainly rather than silently dropped:
+            // an undeterminable destination is exactly what exfiltration looks
+            // like, and the dialog must not read as more specific than it is.
+            const shown = info.egressHosts.includes(UNKNOWN_HOST)
+                ? 'undetermined (bare IP or encoded)'
+                : info.egressHosts.map(escapeForDisplay).join(', ');
+            lines.push(`  Network targets: ${shown}`);
+        }
     }
     else {
         // Honest about what the check is worth: NETWORK_TOOLS plus a URL scan is a

package/dist/egress.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Egress target extraction and allowlist matching for env_use.
+ *
+ * Single source of truth for "can this command reach the network, and where".
+ * exec.ts derives its boolean egress heuristic from extraction so the two can
+ * never disagree about whether a command is network-touching.
+ *
+ * The '(unknown)' sentinel marks a network command whose target cannot be
+ * determined (bare IPs, encoded hostnames, no target at all). It never
+ * matches an allowlist entry — under allowlist mode such a command is
+ * refused. That refusal is the feature, not a limitation: an undeterminable
+ * destination is exactly what an exfiltration attempt looks like.
+ */
+export declare const UNKNOWN_HOST = "(unknown)";
+export declare const NETWORK_TOOLS: Set<string>;
+/**
+ * Extract the network destinations a command could reach.
+ *
+ * Returns hostnames in lowercase plus UNKNOWN_HOST markers; an empty result
+ * means the command cannot reach the network at all. Order is unspecified;
+ * callers must treat the set collectively.
+ */
+export declare function extractEgressHosts(command: string[]): string[];
+/**
+ * Anchored allowlist matching. '*.suffix' matches exactly one leading label
+ * plus '.suffix': api.openai.com yes, openai.com no, a.b.openai.com no,
+ * evil.openai.com.attacker.io no. Plain entries are exact (case-insensitive).
+ */
+export declare function hostIsAllowed(host: string, allow: string[]): boolean;
+//# sourceMappingURL=egress.d.ts.map

package/dist/egress.js

@@ -0,0 +1,191 @@
+/**
+ * Egress target extraction and allowlist matching for env_use.
+ *
+ * Single source of truth for "can this command reach the network, and where".
+ * exec.ts derives its boolean egress heuristic from extraction so the two can
+ * never disagree about whether a command is network-touching.
+ *
+ * The '(unknown)' sentinel marks a network command whose target cannot be
+ * determined (bare IPs, encoded hostnames, no target at all). It never
+ * matches an allowlist entry — under allowlist mode such a command is
+ * refused. That refusal is the feature, not a limitation: an undeterminable
+ * destination is exactly what an exfiltration attempt looks like.
+ */
+export const UNKNOWN_HOST = '(unknown)';
+export const NETWORK_TOOLS = new Set([
+    'curl',
+    'wget',
+    'nc',
+    'ncat',
+    'netcat',
+    'ssh',
+    'scp',
+    'rsync',
+    'http',
+    'httpie',
+    'telnet',
+    'socat',
+]);
+/** Flags whose NEXT argument is a value, not the network target. */
+const VALUE_TAKING_FLAGS = new Set([
+    '-o',
+    '--output',
+    '-k',
+    '--config',
+    '--cookie',
+    '-c',
+    '--cookie-jar',
+    '-H',
+    '--header',
+    '--data',
+    '--data-raw',
+    '--data-binary',
+    '--data-urlencode',
+    '-d',
+    '-F',
+    '--form',
+    '-u',
+    '--user',
+    '--proxy',
+    '-x',
+    '--pass',
+    '--key',
+    '--cacert',
+    '--capath',
+]);
+/** Flags whose value IS a network target specification. */
+const TARGET_FLAGS = new Set(['--url', '--connect-to', '--resolve']);
+function basenameOf(head) {
+    return head.split(/[\\/]/).pop()?.toLowerCase() ?? '';
+}
+function looksLikeHostname(arg) {
+    if (!/^[a-z0-9][a-z0-9.-]*$/i.test(arg))
+        return false;
+    // A dotted quad has no letters — bare IPs stay undetermined by design.
+    if (!/[a-z]/i.test(arg) && arg !== 'localhost')
+        return false;
+    return arg.includes('.') || arg === 'localhost';
+}
+/**
+ * Extract the network destinations a command could reach.
+ *
+ * Returns hostnames in lowercase plus UNKNOWN_HOST markers; an empty result
+ * means the command cannot reach the network at all. Order is unspecified;
+ * callers must treat the set collectively.
+ */
+export function extractEgressHosts(command) {
+    if (command.length === 0)
+        return [];
+    const hosts = new Set();
+    const isNetworkTool = NETWORK_TOOLS.has(basenameOf(command[0]));
+    for (let i = 1; i < command.length; i += 1) {
+        const arg = command[i];
+        if (/^https?:\/\//i.test(arg)) {
+            try {
+                const url = new URL(arg);
+                if (url.hostname.length > 0) {
+                    hosts.add(url.hostname.toLowerCase());
+                }
+                else {
+                    hosts.add(UNKNOWN_HOST);
+                }
+            }
+            catch {
+                // Malformed URL literal still proves network intent.
+                hosts.add(UNKNOWN_HOST);
+            }
+            continue;
+        }
+        if (isNetworkTool && TARGET_FLAGS.has(arg)) {
+            const value = command[i + 1];
+            if (value !== undefined) {
+                if (/^https?:\/\//i.test(value)) {
+                    try {
+                        const url = new URL(value);
+                        if (url.hostname.length > 0)
+                            hosts.add(url.hostname.toLowerCase());
+                        else
+                            hosts.add(UNKNOWN_HOST);
+                    }
+                    catch {
+                        hosts.add(UNKNOWN_HOST);
+                    }
+                }
+                else if (looksLikeHostname(value)) {
+                    hosts.add(value.toLowerCase());
+                }
+                else {
+                    hosts.add(UNKNOWN_HOST);
+                }
+            }
+            continue;
+        }
+    }
+    if (isNetworkTool) {
+        // Find the positional target: first operand that is neither a flag nor
+        // the consumed value of a value-taking flag.
+        let skipNext = false;
+        let positional;
+        for (let i = 1; i < command.length; i += 1) {
+            const arg = command[i];
+            if (skipNext) {
+                skipNext = false;
+                continue;
+            }
+            if (arg.startsWith('-')) {
+                if (VALUE_TAKING_FLAGS.has(arg))
+                    skipNext = true;
+                continue;
+            }
+            positional = arg;
+            break;
+        }
+        const hasExplicitTarget = positional !== undefined ||
+            command.some((a) => /^https?:\/\//i.test(a)) ||
+            command.some((a) => TARGET_FLAGS.has(a));
+        if (!hasExplicitTarget) {
+            hosts.add(UNKNOWN_HOST);
+        }
+        else if (positional !== undefined) {
+            // A path (/x/y) or :port suffix does not make the host undeterminable —
+            // only strip them and judge the host component. Genuinely
+            // undeterminable targets (bare IPs, encoded junk) fail the hostname
+            // check and land in UNKNOWN_HOST by design.
+            const candidate = positional.split('/')[0].split(':')[0];
+            if (looksLikeHostname(candidate)) {
+                hosts.add(candidate.toLowerCase());
+            }
+            else {
+                hosts.add(UNKNOWN_HOST);
+            }
+        }
+    }
+    return Array.from(hosts);
+}
+/**
+ * Anchored allowlist matching. '*.suffix' matches exactly one leading label
+ * plus '.suffix': api.openai.com yes, openai.com no, a.b.openai.com no,
+ * evil.openai.com.attacker.io no. Plain entries are exact (case-insensitive).
+ */
+export function hostIsAllowed(host, allow) {
+    const normalized = host.toLowerCase();
+    if (normalized === UNKNOWN_HOST)
+        return false;
+    for (const entry of allow) {
+        const e = entry.toLowerCase();
+        if (e.startsWith('*.')) {
+            const rest = e.slice(1); // ".openai.com"
+            if (normalized.endsWith(rest)) {
+                const prefix = normalized.slice(0, normalized.length - rest.length);
+                // Exactly one label before the suffix: no dots left of it.
+                if (prefix.length > 0 && !prefix.includes('.'))
+                    return true;
+            }
+        }
+        else if (normalized === e) {
+            return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=egress.js.map

package/dist/exec.d.ts

@@ -1,4 +1,5 @@
 import type { SecretValue, ExecResult } from '@envseal/protocol';
+import type { ProjectPaths } from './paths.js';
 /**
  * Residual risk on Linux: A same-uid process can read /proc/<pid>/environ
  * of the child process. This cannot be defended against without sandboxing.
@@ -48,9 +49,27 @@ export interface ExecOptions {
         command: string[];
         keys: string[];
         networkEgress: boolean;
+        /** Extracted network destinations; present whenever networkEgress is true. */
+        egressHosts: string[];
         target: TargetInfo;
     }) => Promise<boolean>;
     approvedCommands?: string[];
+    /**
+     * When provided, every execution is audited: a 'use' record lands after
+     * consent succeeds and immediately before spawn, and a 'use_result' when
+     * the child exits. Denied or refused consent records nothing.
+     */
+    auditPaths?: ProjectPaths;
+    /**
+     * Declarative egress restriction from the manifest (policy.egress).
+     * mode 'allowlist' refuses any network-touching command whose extracted
+     * hosts are not all allowed — BEFORE the consent dialog opens. Absent
+     * policy means 'warn': egress only adds a warning flag to the dialog.
+     */
+    egressPolicy?: {
+        mode: 'warn' | 'allowlist';
+        allow: string[];
+    };
 }
 export declare function runWithSecrets(command: string[], secrets: Map<string, SecretValue>, opts?: ExecOptions): Promise<ExecResult>;
 //# sourceMappingURL=exec.d.ts.map

package/dist/exec.js

@@ -5,38 +5,10 @@ import { stat } from 'node:fs/promises';
 import { resolve as resolvePath } from 'node:path';
 import { SepError } from '@envseal/protocol';
 import { redact } from './redact.js';
+import { appendAudit } from './audit.js';
+import { extractEgressHosts, hostIsAllowed } from './egress.js';
 import { unsafeSecretToUtf8 } from './sinks/dotenv.js';
-const NETWORK_TOOLS = new Set([
-    'curl',
-    'wget',
-    'nc',
-    'ncat',
-    'netcat',
-    'ssh',
-    'scp',
-    'rsync',
-    'http',
-    'httpie',
-    '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;
-    }
-    const basename = command[0].split(/[\\/]/).pop()?.toLowerCase() ?? '';
-    if (NETWORK_TOOLS.has(basename)) {
-        return true;
-    }
-    for (const arg of command) {
-        if (/^https?:\/\//.test(arg)) {
-            return true;
-        }
-    }
-    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
@@ -138,7 +110,21 @@ export async function runWithSecrets(command, secrets, opts) {
             userMessage: 'Command cannot be empty',
         });
     }
-    const networkEgress = detectNetworkEgress(command);
+    const egressHosts = extractEgressHosts(command);
+    const networkEgress = egressHosts.length > 0;
+    // Allowlist enforcement precedes every dialog: a policy refusal is not a
+    // question for the user to answer, it is the project's standing rule. An
+    // undetermined host ('(unknown)') never matches an allow entry, so bare-IP
+    // and encoded-target exfil is refused here by construction.
+    if (opts?.egressPolicy?.mode === 'allowlist') {
+        const denied = egressHosts.filter((host) => !hostIsAllowed(host, opts.egressPolicy.allow));
+        if (denied.length > 0) {
+            throw new SepError({
+                code: 'SEP_EGRESS_DENIED',
+                details: { hosts: denied },
+            });
+        }
+    }
     const secretKeys = Array.from(secrets.keys());
     const joinedCommand = command.join(' ');
     const isApproved = opts?.approvedCommands?.some((approved) => approved === joinedCommand);
@@ -155,6 +141,7 @@ export async function runWithSecrets(command, secrets, opts) {
             command,
             keys: secretKeys,
             networkEgress,
+            egressHosts,
             target: approvedSnapshot.info,
         });
         if (!confirmed) {
@@ -184,6 +171,27 @@ export async function runWithSecrets(command, secrets, opts) {
         redactionLabels.set(value, key);
     }
     const MAX_BUFFER = 1024 * 1024;
+    const startedAt = Date.now();
+    let exitSignal = null;
+    if (opts?.auditPaths) {
+        // What consent actually bound to: the content hashes of every named
+        // file, so the audit record stays meaningful even if the file is later
+        // rewritten or deleted.
+        const targetHashes = {};
+        for (const file of approvedSnapshot.info.hashedFiles) {
+            targetHashes[file.resolvedPath] = file.sha256;
+        }
+        // One filtered exit (PLAN.md principle 4): the persisted command goes
+        // through the same redaction engine as stdout/stderr, so a value the
+        // caller smuggled into argv cannot reach audit.jsonl either.
+        appendAudit(opts.auditPaths, {
+            type: 'use',
+            command: redact(joinedCommand, secretValues, redactionLabels).text,
+            keys: secretKeys,
+            networkEgress,
+            targetHashes,
+        });
+    }
     const proc = spawn(command[0], command.slice(1), {
         cwd: opts?.cwd,
         env: childEnv,
@@ -222,6 +230,14 @@ export async function runWithSecrets(command, secrets, opts) {
             const stderrStr = stderr.toString('utf8');
             const redactStdout = redact(stdoutStr, secretValues, redactionLabels);
             const redactStderr = redact(stderrStr, secretValues, redactionLabels);
+            if (opts?.auditPaths) {
+                appendAudit(opts.auditPaths, {
+                    type: 'use_result',
+                    exitCode: code,
+                    signal: exitSignal,
+                    durationMs: Date.now() - startedAt,
+                });
+            }
             resolve({
                 exitCode,
                 stdout: redactStdout.text,
@@ -230,7 +246,8 @@ export async function runWithSecrets(command, secrets, opts) {
                 redactedCount: redactStdout.count + redactStderr.count,
             });
         };
-        proc.on('exit', (code) => {
+        proc.on('exit', (code, signal) => {
+            exitSignal = signal;
             if (!timedOut) {
                 finish(code);
             }

package/dist/paths.d.ts

@@ -11,4 +11,7 @@ export declare function projectPaths(root: string): ProjectPaths;
 export declare function findProjectRoot(startDir: string): string;
 export declare function ensureStateDir(paths: ProjectPaths): void;
 export declare function loadOrCreateSalt(paths: ProjectPaths): Buffer;
+export declare const HOOK_HEARTBEAT_FILE = "hook-heartbeat";
+/** ISO timestamp of the hook's last observed run for a project, or null. */
+export declare function readHookHeartbeat(root: string): string | null;
 //# sourceMappingURL=paths.d.ts.map

package/dist/paths.js

@@ -84,4 +84,22 @@ export function loadOrCreateSalt(paths) {
         chmodSync(paths.salt, 0o600);
     return salt;
 }
+// --- Hook liveness heartbeat ------------------------------------------------
+//
+// The Claude Code PreToolUse hook refreshes this marker after every decision
+// (at most once per minute), purely so `envseal doctor` can report WHEN the
+// hook last ran instead of only whether its wiring exists. It is
+// observational: never a gate, never an audit record. The marker name lives
+// here so the writer (plugin) and the reader (doctor) cannot drift.
+export const HOOK_HEARTBEAT_FILE = 'hook-heartbeat';
+/** ISO timestamp of the hook's last observed run for a project, or null. */
+export function readHookHeartbeat(root) {
+    try {
+        const raw = readFileSync(join(resolve(root), '.envseal', HOOK_HEARTBEAT_FILE), 'utf8').trim();
+        return raw === '' ? null : raw;
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=paths.js.map

package/dist/rotation-state.d.ts

@@ -0,0 +1,26 @@
+import type { ProjectPaths } from './paths.js';
+/**
+ * Age tracking for stored secret bytes.
+ *
+ * The manifest's `rotation.maxAgeDays` policy is only actionable if we know
+ * when the stored value last changed. Nothing else records that: provisioning
+ * via `env_use` happens once, hand-written .env values never cross any envseal
+ * write path at all, and the audit log answers "who did what", not "how old
+ * are the bytes". So `Broker.describe()` lazily stamps a record the first time
+ * it sees a key, and re-stamps when the value's fingerprint changes.
+ *
+ * This is observational state, deliberately outside the audit chain: the
+ * caller of describe() is often the model itself, and a read that grows the
+ * audit log with model-attributed "rotation" events would manufacture
+ * evidence. The timestamp says the BYTES changed, never who changed them.
+ */
+export interface RotationRecord {
+    /** Fingerprint of the value this age stamp was computed for. */
+    fingerprint: string;
+    /** ISO timestamp of the first observation of this fingerprint. */
+    at: string;
+}
+export declare function loadRotationState(paths: ProjectPaths): Record<string, RotationRecord>;
+/** Stamp (or re-stamp) a key's age marker. Returns the record written. */
+export declare function recordRotation(paths: ProjectPaths, key: string, fingerprint: string, now?: Date): RotationRecord;
+//# sourceMappingURL=rotation-state.d.ts.map

package/dist/rotation-state.js

@@ -0,0 +1,40 @@
+import { readFileSync, writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { ensureStateDir } from './paths.js';
+function statePath(paths) {
+    return join(paths.stateDir, 'rotation.json');
+}
+function load(paths) {
+    try {
+        const parsed = JSON.parse(readFileSync(statePath(paths), 'utf8'));
+        if (parsed !== null && typeof parsed === 'object')
+            return parsed;
+    }
+    catch {
+        // Missing or unreadable: no age known yet, reported as "due now is
+        // unknowable" rather than invented.
+    }
+    return {};
+}
+export function loadRotationState(paths) {
+    return load(paths);
+}
+/** Stamp (or re-stamp) a key's age marker. Returns the record written. */
+export function recordRotation(paths, key, fingerprint, now = new Date()) {
+    ensureStateDir(paths);
+    const all = load(paths);
+    const record = { fingerprint, at: now.toISOString() };
+    all[key] = record;
+    const file = statePath(paths);
+    writeFileSync(file, `${JSON.stringify(all, null, 2)}\n`, 'utf8');
+    if (process.platform !== 'win32') {
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch {
+            // best effort
+        }
+    }
+    return record;
+}
+//# sourceMappingURL=rotation-state.js.map

package/dist/sinks/dotenv.js

@@ -1,4 +1,4 @@
-import { closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, chmodSync, } from 'node:fs';
+import { appendFileSync, closeSync, fsyncSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, chmodSync, } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { dirname, basename, join, relative } from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -223,6 +223,7 @@ function atomicWrite(paths, target, content) {
         writeTempFile(tmp, content);
     }
     catch {
+        ensureSiblingTempIgnored(dirname(target));
         tmp = sibling;
         writeTempFile(tmp, content);
     }
@@ -232,6 +233,7 @@ function atomicWrite(paths, target, content) {
     catch (error) {
         if (error.code !== 'EXDEV')
             throw error;
+        ensureSiblingTempIgnored(dirname(target));
         writeTempFile(sibling, content);
         renameOverwrite(sibling, target);
     }
@@ -253,6 +255,40 @@ function renameOverwrite(tmp, target) {
         throw error;
     }
 }
+const SIBLING_TEMP_IGNORE = '..env.*.tmp';
+let siblingIgnoreWarned = false;
+/**
+ * F-W7-3 residual hardening: a sibling staging temp holds the complete
+ * plaintext next to `.env`, and a `.env` gitignore entry does not match the
+ * name. Best-effort make the project `.gitignore` carry the pattern so a
+ * crash in exactly that window cannot leave the file stageable by an
+ * accidental `git add -A`. Append-once, never throws; a failure warns once
+ * on stderr with no path or error detail (either could carry secret-shaped
+ * text, same discipline as the audit mirror).
+ */
+function ensureSiblingTempIgnored(dir) {
+    try {
+        const gitignorePath = join(dir, '.gitignore');
+        let lines = [];
+        try {
+            lines = readFileSync(gitignorePath, 'utf8').split(/\r\n|\n|\r/);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (lines.some((line) => line.trim() === SIBLING_TEMP_IGNORE)) {
+            return;
+        }
+        appendFileSync(gitignorePath, `\n# envseal: plaintext staging temp for the fallback atomic-write path\n${SIBLING_TEMP_IGNORE}\n`, 'utf8');
+    }
+    catch {
+        if (!siblingIgnoreWarned) {
+            siblingIgnoreWarned = true;
+            process.stderr.write('envseal: staging temp could not be gitignored (gitignore unwritable) — check for ..env.*.tmp files after failures\n');
+        }
+    }
+}
 /**
  * F-W7-4: every filesystem failure used to escape as a bare Node error, so the
  * CLI never mapped it to exit code 5 and the message carried the target's

package/package.json

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