@envseal/cli 0.1.5 → 0.1.7

package/dist/bin.js

@@ -11,6 +11,7 @@ import { verify } from './commands/verify.js';
 import { run } from './commands/run.js';
 import { doctor } from './commands/doctor.js';
 import { revoke } from './commands/revoke.js';
+import { audit } from './commands/audit.js';
 import { mcp } from './commands/mcp.js';
 import { init } from './commands/init.js';
 const VERSION = '0.1.5';
@@ -115,6 +116,10 @@ async function main() {
                 await revoke(root, key, json, parsed.flags.yes === true);
                 break;
             }
+            case 'audit': {
+                await audit(root, json, parsed.flags.verify === true);
+                break;
+            }
             case 'mcp': {
                 await mcp(root);
                 break;
@@ -146,6 +151,8 @@ Commands:
   run -- <cmd...>               Execute command with injected secrets
   doctor                        Report project configuration status
   revoke <KEY>                  Revoke a key from the sink
+  audit [--verify]              Print audit events (--json for machine form);
+                                --verify checks the log's tamper-evidence chain
   mcp                           Start the MCP server
 
 Global Options:

package/dist/commands/audit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `envseal audit` — inspect the project's audit log.
+ *
+ * Default: print recorded events (human-readable) or the raw event array
+ * (--json). With --verify: check the hash chain instead; exit 7
+ * (AUDIT_CHAIN_FAILED) when the chain is broken. A missing log verifies as
+ * intact with zero records — there is nothing to attest, and "no log yet"
+ * must not look like tampering.
+ *
+ * When the project's out-of-band mirror (~/.envseal/mirrors/) exists, verify
+ * also compares the log against it: the mirror is a second copy the project's
+ * agent cannot silently shrink, so records the mirror proves existed but the
+ * log lost are tail truncation — exit 7. See docs/residual-risks.md §10.
+ */
+export declare function audit(root: string, json: boolean, verifyMode: boolean): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/commands/audit.js

@@ -0,0 +1,117 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { compareWithMirror, projectPaths, readAudit, readMirrorLines, verifyAuditChain } from '@envseal/core';
+import { EXIT } from '../exit-codes.js';
+import { finish } from '../exit.js';
+/**
+ * `envseal audit` — inspect the project's audit log.
+ *
+ * Default: print recorded events (human-readable) or the raw event array
+ * (--json). With --verify: check the hash chain instead; exit 7
+ * (AUDIT_CHAIN_FAILED) when the chain is broken. A missing log verifies as
+ * intact with zero records — there is nothing to attest, and "no log yet"
+ * must not look like tampering.
+ *
+ * When the project's out-of-band mirror (~/.envseal/mirrors/) exists, verify
+ * also compares the log against it: the mirror is a second copy the project's
+ * agent cannot silently shrink, so records the mirror proves existed but the
+ * log lost are tail truncation — exit 7. See docs/residual-risks.md §10.
+ */
+export async function audit(root, json, verifyMode) {
+    if (!verifyMode) {
+        // No manifest gate here on purpose: the log is written by provisioning and
+        // use flows, and it stays readable even in a half-torn-down project whose
+        // env.schema.jsonc is already gone. An audit surface that refuses to
+        // audit would be its own finding.
+        const events = readAudit(projectPaths(root));
+        if (json) {
+            console.log(JSON.stringify(events, null, 0));
+            finish(EXIT.OK);
+            return;
+        }
+        if (events.length === 0) {
+            console.log('No audit events recorded.');
+            finish(EXIT.OK);
+            return;
+        }
+        for (const e of events) {
+            console.log(formatEvent(e));
+        }
+        finish(EXIT.OK);
+        return;
+    }
+    // --verify mode: chain check over the raw bytes. A missing file is an empty
+    // chain, not an error (see doc comment).
+    let raw = '';
+    try {
+        raw = readFileSync(join(root, '.envseal', 'audit.jsonl'), 'utf8');
+    }
+    catch {
+        raw = '';
+    }
+    const result = verifyAuditChain(raw);
+    const mirror = compareWithMirror(raw, readMirrorLines(root));
+    const ok = result.ok && !mirror.tailTruncated;
+    if (json) {
+        console.log(JSON.stringify(!ok
+            ? {
+                ok: false,
+                brokenAt: result.ok ? null : (result.brokenAt ?? null),
+                count: result.count,
+                mirror: { present: mirror.mirrorPresent, records: mirror.mirrorRecords },
+            }
+            : { ok: true, count: result.count, mirror: { present: mirror.mirrorPresent, records: mirror.mirrorRecords } }, null, 0));
+        finish(ok ? EXIT.OK : EXIT.AUDIT_CHAIN_FAILED);
+        return;
+    }
+    if (!ok) {
+        if (!result.ok) {
+            console.error(`AUDIT CHAIN FAILED: first break at record ${result.brokenAt} of ${result.count}. ` +
+                'Records were edited, deleted, reordered, or spliced after the fact. ' +
+                'Treat every record after the break as untrusted and investigate the host.');
+        }
+        else {
+            console.error(`AUDIT TAIL LOST: the project log holds ${mirror.projectRecords} record(s) but its out-of-band mirror ` +
+                `attests ${mirror.mirrorRecords}. Records after the surviving tail were deleted after being mirrored. ` +
+                'Treat the log as incomplete and investigate the host (docs/residual-risks.md §10).');
+        }
+        finish(EXIT.AUDIT_CHAIN_FAILED);
+        return;
+    }
+    if (mirror.mirrorPresent && mirror.mirrorRecords > mirror.projectRecords) {
+        console.log(`Audit chain intact (${result.count} record${result.count === 1 ? '' : 's'}); mirror holds ` +
+            `${mirror.mirrorRecords} — pre-reset history, not tampering.`);
+    }
+    else {
+        console.log(`Audit chain intact (${result.count} record${result.count === 1 ? '' : 's'}).`);
+    }
+    finish(EXIT.OK);
+}
+function formatEvent(e) {
+    const at = e.at;
+    switch (e.type) {
+        case 'declare':
+            return `${at} declare keys=${JSON.stringify(e.keys)}`;
+        case 'request':
+            return `${at} request ticket=${e.ticket} keys=${JSON.stringify(e.keys)} surface=${e.surface}`;
+        case 'stored':
+            return `${at} stored key=${e.key} sink=${e.sink}`;
+        case 'skipped':
+        case 'cancelled':
+        case 'timeout':
+            return `${at} ${e.type} ticket=${e.ticket} key=${e.key}`;
+        case 'verify':
+            return `${at} verify key=${e.key} result=${e.result}`;
+        case 'revoke':
+            return `${at} revoke key=${e.key} sink=${e.sink}`;
+        case 'blocked':
+            return `${at} blocked reason=${e.reason}`;
+        case 'use':
+            return `${at} use keys=${JSON.stringify(e.keys)} networkEgress=${String(e.networkEgress)} cmd=${e.command}`;
+        case 'use_result':
+            return `${at} use_result exit=${String(e.exitCode)} signal=${String(e.signal)} ${e.durationMs}ms`;
+        default:
+            return `${at} ${e.type}`;
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/commands/doctor.js

@@ -1,7 +1,7 @@
 import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { SepError } from '@envseal/protocol';
-import { inspectDotenvGitSafety, projectPaths } from '@envseal/core';
+import { inspectDotenvGitSafety, loadManifest, projectPaths, readHookDecisions, readHookHeartbeat } from '@envseal/core';
 import { emit, fail } from '../output.js';
 import { EXIT } from '../exit-codes.js';
 import { detectHost } from '../host.js';
@@ -22,6 +22,7 @@ export async function doctor(root, json) {
             }));
             return;
         }
+        const manifest = loadManifest(projectPaths(root));
         const broker = await createBroker(root);
         const status = await broker.describe();
         const gitignorePath = join(root, '.gitignore');
@@ -29,14 +30,26 @@ export async function doctor(root, json) {
         const gitSafety = inspectDotenvGitSafety(projectPaths(root));
         const gitignoreCovers = gitSafety.ignored;
         const hookFailClosed = process.env.ENVSEAL_HOOK_FAIL_CLOSED === '1';
-        // Check .env permissions
-        let envFileOk = false;
+        // Check .env permissions.
+        //
+        // POSIX mode bits are only enforced on POSIX. Windows statSync still
+        // reports a mode (0o666 writable, 0o444 read-only), so the group/other
+        // test would produce 0o066 ≠ 0 and report permissionsOk:false on EVERY
+        // Windows machine regardless of the real ACLs — a permanent false alarm.
+        // Report null ("not measurable here") instead; access on Windows is an
+        // ACL question this check cannot answer.
+        let envFileOk = null;
         if (existsSync(envPath)) {
-            const stats = statSync(envPath);
-            envFileOk = (stats.mode & 0o077) === 0;
+            if (process.platform !== 'win32') {
+                const stats = statSync(envPath);
+                envFileOk = (stats.mode & 0o077) === 0;
+            }
         }
         const host = detectHost(root);
+        const egress = manifest?.policy?.egress;
         const inspection = inspectPrimaryHostWiring(root, host.id, { probe: true });
+        const hookLastRan = readHookHeartbeat(root);
+        const hookDecisions = readHookDecisions(root);
         const output = {
             projectRoot: root,
             manifestPath,
@@ -57,9 +70,15 @@ export async function doctor(root, json) {
                 isTracked: gitSafety.tracked,
                 permissionsOk: envFileOk,
             },
+            egressPolicy: egress ?? { mode: 'warn', allow: [] },
             hookFailClosed,
+            hookLastRan,
+            hookDecisions,
             missingRequiredCount: status.missingRequired.length,
             missingRequired: status.missingRequired,
+            rotationOverdue: status.entries
+                .filter((e) => isOverdue(e.rotationDue))
+                .map((e) => ({ key: e.key, due: e.rotationDue })),
             ...(inspection.mcp === undefined
                 ? {}
                 : {
@@ -68,6 +87,9 @@ export async function doctor(root, json) {
                         status: inspection.mcp.status,
                         message: inspection.mcp.message,
                         commandOk: inspection.mcp.commandOk,
+                        ...(inspection.mcp.otherServers === undefined
+                            ? {}
+                            : { otherServers: inspection.mcp.otherServers }),
                     },
                 }),
         };
@@ -82,13 +104,29 @@ export async function doctor(root, json) {
             }
             console.log(`  ${inspection.message}`);
             console.log(`Gitignore covers .env: ${gitignoreCovers ? 'yes' : 'no'}`);
+            console.log(`Egress policy: ${egress?.mode === 'allowlist' ? `allowlist (${egress.allow.length} allowed host${egress.allow.length === 1 ? '' : 's'})` : 'warn (default)'}`);
             console.log(`Hook on internal error: ${hookFailClosed ? 'fail-closed' : 'fail-open (default)'}`);
+            console.log(`Hook heartbeat: ${describeHeartbeatAge(hookLastRan)}`);
+            if (hookDecisions !== null) {
+                console.log(`Hook decisions (approx): ${hookDecisions.allow} allow, ${hookDecisions.deny} deny`);
+            }
+            const siblings = inspection.mcp?.otherServers ?? [];
+            if (siblings.length > 0) {
+                console.log(`Other MCP servers (outside envseal read protection): ${siblings.join(', ')}`);
+            }
             console.log(`Missing required keys: ${status.missingRequired.length}`);
             if (status.missingRequired.length > 0) {
                 for (const key of status.missingRequired) {
                     console.log(`  - ${key}`);
                 }
             }
+            const overdue = status.entries.filter((e) => e.rotationDue !== null && isOverdue(e.rotationDue));
+            if (overdue.length > 0) {
+                console.log('Rotation overdue (advisory — rotate the credential, then rewrite the value):');
+                for (const e of overdue) {
+                    console.log(`  - ${e.key}: due ${e.rotationDue.slice(0, 10)}`);
+                }
+            }
         }
         else {
             emit(json, '', output);
@@ -102,4 +140,38 @@ export async function doctor(root, json) {
         fail(json, error);
     }
 }
+/** Advisory by design: overdue rotation never fails doctor the way a
+ * missing required key does, because an aged-but-working credential is a
+ * hygiene problem, not an outage. */
+function isOverdue(rotationDue) {
+    if (rotationDue === null)
+        return false;
+    const due = Date.parse(rotationDue);
+    return !Number.isNaN(due) && due <= Date.now();
+}
+/**
+ * Human phrasing for the hook heartbeat. Advisory only — wiring can be
+ * present while the hook has never run (no plugin version, no tool call yet),
+ * and a recent timestamp proves liveness, not correctness.
+ */
+function describeHeartbeatAge(hookLastRan) {
+    if (hookLastRan === null) {
+        return 'none recorded (hook has not run for this project, or pre-heartbeat plugin)';
+    }
+    const then = Date.parse(hookLastRan);
+    if (Number.isNaN(then)) {
+        return 'unreadable timestamp';
+    }
+    const seconds = Math.max(0, Math.round((Date.now() - then) / 1000));
+    if (seconds < 90)
+        return `${seconds}s ago`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 90)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 36)
+        return `${hours}h ago`;
+    const days = Math.round(hours / 24);
+    return `${days}d ago`;
+}
 //# sourceMappingURL=doctor.js.map

package/dist/commands/status.js

@@ -18,7 +18,8 @@ export async function status(root, keys, json) {
             else {
                 for (const entry of entriesToShow) {
                     const status_str = entry.present ? '✓' : '✗';
-                    console.log(`${status_str} ${entry.key}`);
+                    const due = describeRotation(entry.rotationDue);
+                    console.log(`${status_str} ${entry.key}${due}`);
                 }
             }
         }
@@ -33,6 +34,7 @@ export async function status(root, keys, json) {
                     fingerprint: e.fingerprint,
                     lastVerified: e.lastVerified,
                     verifyResult: e.verifyResult,
+                    rotationDue: e.rotationDue,
                 })),
             });
         }
@@ -46,4 +48,21 @@ export async function status(root, keys, json) {
         fail(json, error);
     }
 }
+/**
+ * Overdue rotation is the only state worth a human's glance in the terse
+ * listing; a future due date is noise. Absent policy or unknown age (hand
+ * written .env before first status) reports nothing.
+ */
+function describeRotation(rotationDue) {
+    if (rotationDue === null)
+        return '';
+    const due = Date.parse(rotationDue);
+    if (Number.isNaN(due))
+        return '';
+    if (due > Date.now())
+        return '';
+    const days = Math.floor((Date.now() - due) / (24 * 60 * 60 * 1000));
+    const when = days === 0 ? 'today' : `${days}d ago`;
+    return ` (rotation overdue, due ${rotationDue.slice(0, 10)}, ${when})`;
+}
 //# sourceMappingURL=status.js.map

package/dist/exit-codes.d.ts

@@ -7,6 +7,7 @@ export declare const EXIT: {
     readonly NO_SURFACE: 4;
     readonly SINK_FAILURE: 5;
     readonly VERIFY_FAILED: 6;
+    readonly AUDIT_CHAIN_FAILED: 7;
 };
 export declare function exitCodeForError(e: unknown): number;
 /**

package/dist/exit-codes.js

@@ -7,6 +7,7 @@ export const EXIT = {
     NO_SURFACE: 4,
     SINK_FAILURE: 5,
     VERIFY_FAILED: 6,
+    AUDIT_CHAIN_FAILED: 7,
 };
 export function exitCodeForError(e) {
     if (!isSepError(e)) {
@@ -39,6 +40,11 @@ export function exitCodeForError(e) {
         case 'SEP_CONFIRMATION_DENIED':
         case 'SEP_KEYS_MISSING':
             return EXIT.UNSATISFIED;
+        case 'SEP_EGRESS_DENIED':
+            // The project's standing policy refused the command before anything
+            // ran. Not retriable by re-running: the policy file must change first,
+            // so this maps to USAGE (configuration), not a transient failure.
+            return EXIT.USAGE;
         default: {
             const _exhaustive = code;
             return _exhaustive;

package/dist/host-wiring/copilot.js

@@ -79,11 +79,20 @@ export function inspectCopilotSettings(root, options = {}) {
         };
     }
     const entry = list.find((item) => entryName(item) === ENVSEAL_MCP_SERVER_NAME);
+    // Names only, never entry values: a sibling argv or env block can hold a
+    // real credential, and doctor output must not become a new exfil channel.
+    // List configs can repeat a name; report each server once.
+    const otherServers = [
+        ...new Set(list
+            .map((item) => entryName(item))
+            .filter((name) => name !== undefined && name !== ENVSEAL_MCP_SERVER_NAME)),
+    ].sort();
     if (entry === undefined || isEmptyEnvsealStub(entry) || !looksLikeEnvsealServer(entry)) {
         return {
             wired: false,
             status: entry === undefined ? 'missing' : 'stub',
             commandOk: null,
+            otherServers,
             message: `.vscode/settings.json github.copilot.mcp has no working envseal-mcp. ${hint}`,
         };
     }
@@ -94,6 +103,6 @@ export function inspectCopilotSettings(root, options = {}) {
         message =
             'Copilot MCP is configured, but the launch command did not report a version. Run `envseal init`. [VERIFY]';
     }
-    return { wired: true, status: 'wired', commandOk, message };
+    return { wired: true, status: 'wired', commandOk, otherServers, message };
 }
 //# sourceMappingURL=copilot.js.map

package/dist/host-wiring/mcp.d.ts

@@ -13,7 +13,19 @@ export type McpInspection = {
     message: string;
     /** null when the launch command was not probed (npx is not side-effect free). */
     commandOk: boolean | null;
+    /**
+     * Names of co-registered MCP servers besides envseal-mcp. Names only, never
+     * entry values: a sibling argv or env block can hold a real credential, and
+     * doctor output must not become a new exfil channel. Undefined when the host
+     * config shape carries no enumerable server list.
+     */
+    otherServers?: string[];
 };
+/**
+ * Sorted names of every server in a `mcpServers`-style map except envseal-mcp.
+ * Keys only: callers must never forward the entry values.
+ */
+export declare function siblingServerNames(servers: Record<string, unknown>): string[];
 /**
  * Launch argv a host can spawn without a global `envseal-mcp` on PATH.
  * Project MCP uses the workspace as cwd — never bake `--project` in.

package/dist/host-wiring/mcp.js

@@ -4,6 +4,15 @@ import { spawnSync } from 'node:child_process';
 export const ENVSEAL_MCP_PACKAGE = '@envseal/mcp-server';
 export const ENVSEAL_MCP_SERVER_NAME = 'envseal-mcp';
 export const NPX_ARGS = ['-y', ENVSEAL_MCP_PACKAGE];
+/**
+ * Sorted names of every server in a `mcpServers`-style map except envseal-mcp.
+ * Keys only: callers must never forward the entry values.
+ */
+export function siblingServerNames(servers) {
+    return Object.keys(servers)
+        .filter((name) => name !== ENVSEAL_MCP_SERVER_NAME)
+        .sort();
+}
 /**
  * Launch argv a host can spawn without a global `envseal-mcp` on PATH.
  * Project MCP uses the workspace as cwd — never bake `--project` in.
@@ -203,11 +212,13 @@ export function inspectMcpServersFile(path, label, options = {}) {
     }
     const entry = servers[ENVSEAL_MCP_SERVER_NAME];
     const kind = classifyEntry(entry);
+    const otherServers = siblingServerNames(servers);
     if (kind === 'missing') {
         return {
             wired: false,
             status: 'missing',
             commandOk: null,
+            otherServers,
             message: `${label} has no envseal-mcp. ${hint}`,
         };
     }
@@ -216,6 +227,7 @@ export function inspectMcpServersFile(path, label, options = {}) {
             wired: false,
             status: 'stub',
             commandOk: null,
+            otherServers,
             message: `${label} envseal-mcp is the empty envseal-mcp stub (not on PATH for the host). ${hint}`,
         };
     }
@@ -225,7 +237,7 @@ export function inspectMcpServersFile(path, label, options = {}) {
     if (commandOk === false) {
         message = `MCP is configured in ${label}, but the launch command did not report a version. Run \`envseal init\` if the host cannot connect.`;
     }
-    return { wired: true, status: 'wired', commandOk, message };
+    return { wired: true, status: 'wired', commandOk, otherServers, message };
 }
 /** Map an inspection to the doctor `agentWiring.mcp` field. */
 export function mcpWiringState(inspection) {

package/dist/host-wiring/zed.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { ENVSEAL_MCP_SERVER_NAME, isRecord, mcpLaunch, nextEnvsealEntry, parseJsonObject, writeJson, classifyEntry, probeVersion, } from './mcp.js';
+import { ENVSEAL_MCP_SERVER_NAME, isRecord, mcpLaunch, nextEnvsealEntry, parseJsonObject, writeJson, classifyEntry, probeVersion, siblingServerNames, } from './mcp.js';
 function zedHint(platform) {
     const launch = mcpLaunch(platform);
     return `Run \`envseal init\` to merge { "mcp": { "${ENVSEAL_MCP_SERVER_NAME}": ${JSON.stringify(launch)} } } into .zed/settings.json. [VERIFY]`;
@@ -69,11 +69,13 @@ export function inspectZedSettings(root, options = {}) {
     }
     const entry = mcp[ENVSEAL_MCP_SERVER_NAME];
     const kind = classifyEntry(entry);
+    const otherServers = siblingServerNames(mcp);
     if (kind === 'missing') {
         return {
             wired: false,
             status: 'missing',
             commandOk: null,
+            otherServers,
             message: `.zed/settings.json has no envseal-mcp. ${hint}`,
         };
     }
@@ -82,6 +84,7 @@ export function inspectZedSettings(root, options = {}) {
             wired: false,
             status: 'stub',
             commandOk: null,
+            otherServers,
             message: `.zed/settings.json envseal-mcp is the empty stub. ${hint}`,
         };
     }
@@ -92,6 +95,6 @@ export function inspectZedSettings(root, options = {}) {
         message =
             'Zed MCP is configured, but the launch command did not report a version. Run `envseal init`. [VERIFY]';
     }
-    return { wired: true, status: 'wired', commandOk, message };
+    return { wired: true, status: 'wired', commandOk, otherServers, message };
 }
 //# sourceMappingURL=zed.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envseal/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "type": "module",
   "license": "Apache-2.0",
   "main": "./dist/index.js",
@@ -23,13 +23,13 @@
     "provenance": true
   },
   "dependencies": {
-    "@envseal/protocol": "0.1.5",
-    "@envseal/core": "0.1.5",
-    "@envseal/registry": "0.1.5",
-    "@envseal/detector": "0.1.5",
-    "@envseal/mcp-server": "0.1.5",
-    "@envseal/http-server": "0.1.5",
-    "@envseal/prompters": "0.1.5"
+    "@envseal/core": "0.1.7",
+    "@envseal/prompters": "0.1.7",
+    "@envseal/protocol": "0.1.7",
+    "@envseal/detector": "0.1.7",
+    "@envseal/registry": "0.1.7",
+    "@envseal/http-server": "0.1.7",
+    "@envseal/mcp-server": "0.1.7"
   },
   "repository": {
     "type": "git",