@envseal/cli 0.1.0

package/dist/probe-approval.js

@@ -0,0 +1,94 @@
+import { createInterface } from 'node:readline';
+import { hasInteractiveSurface } from './cli-utils.js';
+/**
+ * A fixed answer for the approval question, for tests only.
+ *
+ * Double-gated exactly like the stub prompter in test-prompter.ts: the caller
+ * must set BOTH `ENVSEAL_TEST_MODE=1` and `ENVSEAL_TEST_APPROVAL` to `yes` or
+ * `no`. Neither is ever set by the shipped CLI. This is a deliberate hole in
+ * "a probe to an unknown host is only ever approved by a human", which is why
+ * it costs two variables — and why the notice is still printed when it fires,
+ * so the display path stays under test rather than being skipped.
+ */
+function forcedAnswer() {
+    if (process.env.ENVSEAL_TEST_MODE !== '1')
+        return null;
+    const answer = process.env.ENVSEAL_TEST_APPROVAL;
+    if (answer === 'yes')
+        return true;
+    if (answer === 'no')
+        return false;
+    return null;
+}
+function describeProbe(key, probe, hostname) {
+    const lines = [
+        '',
+        `envseal needs your approval before verifying ${key}.`,
+        `${hostname} is not on the built-in registry allowlist, so this probe would send`,
+        'the credential to a host envseal cannot vouch for.',
+        '',
+        `  key:     ${key}`,
+        `  host:    ${hostname}`,
+        `  method:  ${probe.method}`,
+        `  url:     ${probe.url}`,
+        '  headers:',
+    ];
+    for (const [name, template] of Object.entries(probe.headerTemplate)) {
+        lines.push(`    ${name}: ${template}`);
+    }
+    lines.push('', '{{value}} is where your credential is substituted at request time. The value', 'itself is never printed here, and never written to the approval record.', '');
+    return lines;
+}
+function noSurfaceNotice(key, approvalsPath) {
+    const reason = process.env.CI !== undefined
+        ? 'CI is set in the environment'
+        : 'stdin is not a terminal';
+    return [
+        `Cannot ask: ${reason}, so there is nobody to answer.`,
+        `The probe was NOT sent and ${key} is reported as probe_not_approved.`,
+        'To approve it, run this once in an interactive terminal on a machine with',
+        `access to this project:  envseal verify ${key}`,
+        `The decision is recorded in ${approvalsPath} and replayed without asking again,`,
+        'until the key, method, URL or header template changes.',
+        '',
+    ];
+}
+/**
+ * Build the `onApprovalNeeded` callback for the broker.
+ *
+ * Fails closed: with no interactive surface it returns false rather than
+ * hanging on a read nobody will answer, and rather than approving silently.
+ * Core turns that false into `probe_not_approved`, so `verify` still exits 6.
+ */
+export function makeProbeApprover(approvalsPath) {
+    return async (entry) => {
+        const probe = entry.verify;
+        if (probe === undefined) {
+            // Core only reaches this callback for entries that declare a probe.
+            // Refusing keeps a broken invariant a refusal rather than a crash.
+            return false;
+        }
+        const hostname = new URL(probe.url).hostname;
+        process.stderr.write(`${describeProbe(entry.key, probe, hostname).join('\n')}\n`);
+        const forced = forcedAnswer();
+        if (forced !== null) {
+            process.stderr.write(`ENVSEAL_TEST_MODE: approval answered '${forced ? 'yes' : 'no'}' from ENVSEAL_TEST_APPROVAL.\n`);
+            return forced;
+        }
+        if (!hasInteractiveSurface()) {
+            process.stderr.write(`${noSurfaceNotice(entry.key, approvalsPath).join('\n')}\n`);
+            return false;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        try {
+            const answer = await new Promise((resolve) => {
+                rl.question(`Send ${entry.key} to ${hostname}? [y/N] `, resolve);
+            });
+            return /^y(es)?$/i.test(answer.trim());
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+//# sourceMappingURL=probe-approval.js.map

package/dist/scan.d.ts

@@ -0,0 +1,9 @@
+export interface DiscoveredKey {
+    key: string;
+    secret: boolean;
+    files: string[];
+}
+export declare function scanForEnvKeys(root: string): DiscoveredKey[];
+/** Build a manifest entry, filling provider metadata from the registry when the name is known. */
+export declare function entryForKey(d: DiscoveredKey): Record<string, unknown>;
+//# sourceMappingURL=scan.d.ts.map

package/dist/scan.js

@@ -0,0 +1,138 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+import { findKey } from '@envseal/registry';
+/**
+ * Discover environment variables a project actually reads.
+ *
+ * Deliberately syntactic rather than semantic: a regex sweep over source text
+ * finds the overwhelming majority of real references at a fraction of the cost
+ * of parsing every dialect a polyglot repo might contain, and a missed variable
+ * is a prompt the user answers once, not a failure.
+ */
+const SOURCE_EXT = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts',
+    '.py', '.rb', '.go', '.rs', '.java', '.kt', '.php', '.cs',
+    '.sh', '.bash', '.zsh', '.yml', '.yaml', '.toml',
+]);
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'out', 'target', 'vendor',
+    '.next', '.nuxt', '.svelte-kit', 'coverage', '.venv', 'venv',
+    '__pycache__', '.envseal', '.turbo', '.cache',
+]);
+/**
+ * Names that are configuration rather than credentials. Declaring these as
+ * secrets would pop a password prompt for `NODE_ENV`, which teaches users to
+ * dismiss the prompt without reading it — the exact habit this tool exists to
+ * break.
+ */
+const NON_SECRET = new Set([
+    'NODE_ENV', 'PORT', 'HOST', 'CI', 'HOME', 'PATH', 'PWD', 'USER', 'SHELL',
+    'LANG', 'TZ', 'TERM', 'TMPDIR', 'LOG_LEVEL', 'DEBUG', 'VERBOSE',
+    'npm_lifecycle_event', 'npm_package_version',
+]);
+/** Prefixes that a bundler inlines into client bundles — public by construction. */
+const PUBLIC_PREFIXES = ['NEXT_PUBLIC_', 'VITE_', 'REACT_APP_', 'PUBLIC_', 'EXPO_PUBLIC_', 'NUXT_PUBLIC_'];
+const PATTERNS = [
+    /process\.env\.([A-Z][A-Z0-9_]*)/g,
+    /process\.env\[['"`]([A-Z][A-Z0-9_]*)['"`]\]/g,
+    /import\.meta\.env\.([A-Z][A-Z0-9_]*)/g,
+    /os\.environ(?:\.get)?[[(]['"]([A-Z][A-Z0-9_]*)['"]/g,
+    /Deno\.env\.get\(['"]([A-Z][A-Z0-9_]*)['"]\)/g,
+    /ENV\[['"]([A-Z][A-Z0-9_]*)['"]\]/g,
+    /os\.Getenv\(['"`]([A-Z][A-Z0-9_]*)['"`]\)/g,
+    /std::env::var\(['"]([A-Z][A-Z0-9_]*)['"]\)/g,
+    /getenv\(['"]([A-Z][A-Z0-9_]*)['"]\)/g,
+    /\$\{?([A-Z][A-Z0-9_]{2,})\}?/g,
+];
+function walk(dir, out, depth = 0) {
+    if (depth > 12)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const full = join(dir, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            walk(full, out, depth + 1);
+        }
+        else if (SOURCE_EXT.has(extname(entry)) && st.size < 2_000_000) {
+            out.push(full);
+        }
+    }
+}
+export function scanForEnvKeys(root) {
+    const files = [];
+    walk(root, files);
+    const found = new Map();
+    for (const file of files) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const source of PATTERNS) {
+            const re = new RegExp(source.source, 'g');
+            let m;
+            while ((m = re.exec(text)) !== null) {
+                const name = m[1];
+                if (name === undefined || name.length < 3)
+                    continue;
+                const rel = file.slice(root.length + 1).replace(/\\/g, '/');
+                const set = found.get(name) ?? new Set();
+                set.add(rel);
+                found.set(name, set);
+            }
+        }
+    }
+    return [...found.entries()]
+        .map(([key, fileSet]) => ({
+        key,
+        secret: !NON_SECRET.has(key) && !PUBLIC_PREFIXES.some((p) => key.startsWith(p)),
+        files: [...fileSet].sort().slice(0, 5),
+    }))
+        .filter((d) => !NON_SECRET.has(d.key) || d.secret)
+        .sort((a, b) => a.key.localeCompare(b.key));
+}
+/** Build a manifest entry, filling provider metadata from the registry when the name is known. */
+export function entryForKey(d) {
+    const where = d.files.length > 0 ? ` Referenced in ${d.files.join(', ')}.` : '';
+    const known = findKey(d.key);
+    const entry = {
+        key: d.key,
+        description: known ? `${known.key.description}${where}` : `Environment variable ${d.key}.${where}`,
+        required: true,
+        secret: d.secret,
+        sink: 'dotenv',
+    };
+    if (known) {
+        if (known.key.format)
+            entry.format = known.key.format;
+        const p = { id: known.provider.id, name: known.provider.name };
+        if (known.key.signupUrl)
+            p.signupUrl = known.key.signupUrl;
+        if (known.key.docsUrl)
+            p.docsUrl = known.key.docsUrl;
+        if (known.key.rotateUrl)
+            p.rotateUrl = known.key.rotateUrl;
+        entry.provider = p;
+        if (known.key.verify)
+            entry.verify = known.key.verify;
+    }
+    return entry;
+}
+//# sourceMappingURL=scan.js.map

package/dist/test-prompter.d.ts

@@ -0,0 +1,33 @@
+import type { Prompter } from '@envseal/prompters';
+/**
+ * A prompter that returns a fixed value without any UI.
+ *
+ * This exists so the zero-leak test can drive the real server, over real stdio,
+ * without a human at a browser. It is a deliberate hole in the "a value only ever
+ * comes from the user" guarantee, so it is gated twice in `bin.ts`: the caller must
+ * set BOTH `ENVSEAL_TEST_MODE=1` and `ENVSEAL_TEST_PROMPTER_VALUE`. Neither is ever
+ * set by the shipped CLI, and nothing in the published package sets them for you.
+ *
+ * If you are reading this because you want to inject a value programmatically in
+ * production: don't. Use a sink the value already lives in (keychain, vault) and let
+ * `presence` resolve it. Injecting through the prompter path would put the value in
+ * an environment variable, which is exactly what threat T6 is about.
+ */
+export declare function createStubPrompter(value: string): Prompter;
+/** Non-`entered` outcomes a stub prompter can be told to report. */
+export type StubOutcome = 'skipped' | 'cancelled' | 'timeout';
+export declare function isStubOutcome(value: string | undefined): value is StubOutcome;
+/**
+ * A prompter that reports a refusal without any UI.
+ *
+ * The documented exit codes for `set` and `ensure` fork on WHY a key was not
+ * stored, and until this existed there was no way to drive `cancelled` or
+ * `timeout` through the real binary — so those rows of docs/cli-contract.md
+ * were asserted by nothing.
+ *
+ * Gated the same way as createStubPrompter (`ENVSEAL_TEST_MODE=1` plus a second
+ * variable), but note it is strictly the safer of the two: it can only ever
+ * make the CLI report that nothing was stored. It cannot introduce a value.
+ */
+export declare function createRefusingPrompter(outcome: StubOutcome): Prompter;
+//# sourceMappingURL=test-prompter.d.ts.map

package/dist/test-prompter.js

@@ -0,0 +1,61 @@
+import { secretFromUtf8 } from '@envseal/protocol';
+/**
+ * A prompter that returns a fixed value without any UI.
+ *
+ * This exists so the zero-leak test can drive the real server, over real stdio,
+ * without a human at a browser. It is a deliberate hole in the "a value only ever
+ * comes from the user" guarantee, so it is gated twice in `bin.ts`: the caller must
+ * set BOTH `ENVSEAL_TEST_MODE=1` and `ENVSEAL_TEST_PROMPTER_VALUE`. Neither is ever
+ * set by the shipped CLI, and nothing in the published package sets them for you.
+ *
+ * If you are reading this because you want to inject a value programmatically in
+ * production: don't. Use a sink the value already lives in (keychain, vault) and let
+ * `presence` resolve it. Injecting through the prompter path would put the value in
+ * an environment variable, which is exactly what threat T6 is about.
+ */
+export function createStubPrompter(value) {
+    return {
+        id: 'ide',
+        available: async () => true,
+        prompt: async (req) => ({
+            ticket: req.ticket,
+            results: req.keys.map((k) => ({
+                key: k.key,
+                outcome: 'entered',
+                value: secretFromUtf8(value),
+            })),
+        }),
+        cancel: async () => {
+            /* nothing to tear down */
+        },
+    };
+}
+export function isStubOutcome(value) {
+    return value === 'skipped' || value === 'cancelled' || value === 'timeout';
+}
+/**
+ * A prompter that reports a refusal without any UI.
+ *
+ * The documented exit codes for `set` and `ensure` fork on WHY a key was not
+ * stored, and until this existed there was no way to drive `cancelled` or
+ * `timeout` through the real binary — so those rows of docs/cli-contract.md
+ * were asserted by nothing.
+ *
+ * Gated the same way as createStubPrompter (`ENVSEAL_TEST_MODE=1` plus a second
+ * variable), but note it is strictly the safer of the two: it can only ever
+ * make the CLI report that nothing was stored. It cannot introduce a value.
+ */
+export function createRefusingPrompter(outcome) {
+    return {
+        id: 'ide',
+        available: async () => true,
+        prompt: async (req) => ({
+            ticket: req.ticket,
+            results: req.keys.map((k) => ({ key: k.key, outcome })),
+        }),
+        cancel: async () => {
+            /* nothing to tear down */
+        },
+    };
+}
+//# sourceMappingURL=test-prompter.js.map

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@envseal/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "envseal": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@envseal/core": "0.1.0",
+    "@envseal/protocol": "0.1.0",
+    "@envseal/registry": "0.1.0",
+    "@envseal/mcp-server": "0.1.0",
+    "@envseal/http-server": "0.1.0",
+    "@envseal/detector": "0.1.0",
+    "@envseal/prompters": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}