@envseal/cli 0.1.5 → 0.1.6

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, 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,25 @@ 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 output = {
             projectRoot: root,
             manifestPath,
@@ -57,9 +69,14 @@ export async function doctor(root, json) {
                 isTracked: gitSafety.tracked,
                 permissionsOk: envFileOk,
             },
+            egressPolicy: egress ?? { mode: 'warn', allow: [] },
             hookFailClosed,
+            hookLastRan,
             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
                 ? {}
                 : {
@@ -82,13 +99,22 @@ 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)}`);
             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 +128,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envseal/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "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/protocol": "0.1.6",
+    "@envseal/prompters": "0.1.6",
+    "@envseal/registry": "0.1.6",
+    "@envseal/core": "0.1.6",
+    "@envseal/mcp-server": "0.1.6",
+    "@envseal/http-server": "0.1.6",
+    "@envseal/detector": "0.1.6"
   },
   "repository": {
     "type": "git",