@envseal/mcp-server 0.1.0

package/dist/confirm.js

@@ -0,0 +1,247 @@
+import { randomBytes } from 'node:crypto';
+import { SepError, zero } from '@envseal/protocol';
+import { makeDisplayNonce } from '@envseal/prompters';
+/**
+ * The interactive consent surface for the two operations that move a live
+ * value: `env_use` (inject into a child process) and `env_verify` against a
+ * host the registry does not allowlist.
+ *
+ * Before this existed, three of the four bindings constructed the Broker with
+ * no `onConfirm`, and exec.ts turned that absence into
+ * SEP_CONFIRMATION_DENIED — "The user denied the confirmation" — when no user
+ * had been asked and no user had denied. `env_use` was advertised in
+ * tools/list and in the OpenAPI document and could never succeed.
+ *
+ * There is deliberately no environment-variable bypass here. `envseal run`
+ * honours ENVSEAL_ASSUME_YES because a human typed that command; in these
+ * bindings the argv comes from a *model*, and this prompt is the only thing
+ * between a prompt-injected model and arbitrary code holding live
+ * credentials. In CI these operations are simply unavailable, and say so.
+ *
+ * DUPLICATION: this file is a hand-maintained twin of
+ * packages/sdk/src/confirm.ts. Its natural home is a `confirm()` method
+ * on the `Prompter` interface — every surface already knows how to draw a
+ * dialog — but @envseal/mcp-server does not depend on @envseal/sdk, and
+ * @envseal/prompters was outside the scope of the change that added this. Both
+ * packages test the behaviour independently, so drift shows up as a red test
+ * rather than as a binding that quietly stops asking.
+ */
+/** Value-entry key name carrying the `env_use` confirmation. */
+export const CONFIRM_KEY_USE = 'APPROVE';
+/** Value-entry key name carrying the `env_verify` probe-consent question. */
+export const CONFIRM_KEY_PROBE = 'APPROVE_PROBE';
+const DEFAULT_TIMEOUT_MS = 120_000;
+/** Per-argument display cap; longer arguments are shown truncated, and said to be. */
+const MAX_ARG_CHARS = 300;
+/** Whole-dialog cap. Past this we refuse rather than ask about something unreadable. */
+const MAX_BODY_CHARS = 16 * 1024;
+const INSTRUCTION = 'Type yes to approve, or submit an empty box to deny.';
+/**
+ * Only one confirmation may be open per process. Without this a model can call
+ * `env_use` in a loop and stack up dialogs until one gets clicked through.
+ */
+let confirmationOpen = false;
+/**
+ * Model-supplied argv, key names and probe metadata land in a dialog the user
+ * is about to trust. A raw newline lets a crafted argument forge extra lines —
+ * "keys: none", "this command is safe" — inside the very block that exists to
+ * tell the truth about the command. Render control characters visibly instead.
+ */
+function escapeForDisplay(value) {
+    let out = '';
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code < 0x20 || (code >= 0x7f && code <= 0x9f)) {
+            out += `<0x${code.toString(16).padStart(2, '0')}>`;
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+function displayArg(arg) {
+    const escaped = escapeForDisplay(arg);
+    if (escaped.length <= MAX_ARG_CHARS) {
+        return escaped;
+    }
+    const hidden = escaped.length - MAX_ARG_CHARS;
+    return `${escaped.slice(0, MAX_ARG_CHARS)}[... ${hidden} more characters, not shown]`;
+}
+export function useConfirmationBody(info, projectRoot) {
+    const lines = [
+        'EnvSeal is about to run a program with these secrets in its environment.',
+        '',
+        `  project: ${escapeForDisplay(projectRoot)}`,
+        `  keys:    ${info.keys.length > 0 ? info.keys.map(escapeForDisplay).join(', ') : '(none)'}`,
+        '',
+        '  command, one argument per line, exactly as it will be run (no shell):',
+    ];
+    info.command.forEach((arg, index) => {
+        lines.push(`    [${index}] ${displayArg(arg)}`);
+    });
+    lines.push('');
+    if (info.networkEgress) {
+        lines.push('  WARNING: this command can reach the network, so it could send these', '           values somewhere. Only continue if you trust it.');
+    }
+    else {
+        // Honest about what the check is worth: NETWORK_TOOLS plus a URL scan is a
+        // heuristic, and claiming more would be the kind of overstatement this
+        // project has already had to walk back once.
+        lines.push('  No network tool or URL was recognised in this command. That is a', '  heuristic, not a guarantee: any program can open a socket.');
+    }
+    lines.push('', `${INSTRUCTION} Nothing runs unless you approve.`);
+    return lines.join('\n');
+}
+export function probeConfirmationBody(entry) {
+    const probe = entry.verify;
+    if (!probe) {
+        return null;
+    }
+    const lines = [
+        `EnvSeal is about to send the stored value of ${escapeForDisplay(entry.key)} to a host`,
+        'that is not on its bundled allowlist. Nothing has been sent yet.',
+        '',
+        `  key:     ${escapeForDisplay(entry.key)}`,
+        `  method:  ${escapeForDisplay(probe.method)}`,
+        `  url:     ${displayArg(probe.url)}`,
+        '  headers:',
+    ];
+    for (const [header, template] of Object.entries(probe.headerTemplate)) {
+        lines.push(`    ${escapeForDisplay(header)}: ${displayArg(template)}`);
+    }
+    lines.push('', '  {{value}} is replaced with the real secret when the request is sent.', '', 'Type yes to approve exactly this probe. The answer is recorded in', '.envseal/approvals.json and replayed without asking again until the', 'method, URL or headers change. Submit an empty box to deny.');
+    return lines.join('\n');
+}
+async function ask(surface, keyName, headline, body) {
+    if (body === null || body.length > MAX_BODY_CHARS) {
+        return 'too-large';
+    }
+    const prompter = await surface.prompter();
+    if (prompter.id === 'none') {
+        return 'no-surface';
+    }
+    if (confirmationOpen) {
+        return 'busy';
+    }
+    confirmationOpen = true;
+    try {
+        const response = await prompter.prompt({
+            ticket: `confirm-${randomBytes(8).toString('hex')}`,
+            nonce: makeDisplayNonce(),
+            projectRoot: surface.projectRoot,
+            reason: headline,
+            keys: [{ key: keyName, description: body, formatHint: INSTRUCTION }],
+            timeoutMs: surface.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        });
+        const result = response.results.find((r) => r.key === keyName);
+        // A timeout is kept apart from a denial: nobody answered at all, and
+        // reporting that as "the user denied" blames a user who never spoke — the
+        // defect class the CLI fixed for the missing-surface case.
+        if (result !== undefined && result.outcome === 'timeout') {
+            return 'timed-out';
+        }
+        // skipped / cancelled / a surface that answered about some other key: we
+        // did not get a yes, and none of them names anyone, so they land on the
+        // honest-but-blunt denial.
+        if (result === undefined || result.outcome !== 'entered') {
+            return 'denied';
+        }
+        const typed = result.value.toString('utf8');
+        zero(result.value);
+        return /^y(es)?$/i.test(typed.trim()) ? 'approved' : 'denied';
+    }
+    finally {
+        confirmationOpen = false;
+    }
+}
+/**
+ * `onConfirm` for the Broker: gates `env_use`.
+ *
+ * Throws rather than returning false when no human could be asked or when the
+ * ask expired with nobody answering it, because exec.ts maps a `false` to
+ * SEP_CONFIRMATION_DENIED and that would blame the user for a missing surface
+ * or for a silence — the defect this project already fixed once in the CLI.
+ */
+export function createUseConfirm(surface) {
+    return async (info) => {
+        const outcome = await ask(surface, CONFIRM_KEY_USE, 'Approve running a command with secrets in its environment? Nothing has run yet.', useConfirmationBody(info, surface.projectRoot));
+        switch (outcome) {
+            case 'approved':
+                return true;
+            case 'denied':
+                return false;
+            case 'timed-out':
+                // SEP_TICKET_EXPIRED, not SEP_CONFIRMATION_DENIED: the repo already
+                // treats an unanswered prompt as an expired ticket (exit-codes.ts maps
+                // outcome `timeout` and this code to the same exit), and a model that
+                // can tell "nobody answered" from "the user said no" retries instead
+                // of reporting a refusal that never happened.
+                throw new SepError({
+                    code: 'SEP_TICKET_EXPIRED',
+                    userMessage: 'The env_use confirmation closed after its timeout with nobody answering it. Nothing was ' +
+                        'run and no value was read. This is not a denial: ask the user to approve it, then call ' +
+                        'env_use again.',
+                });
+            case 'no-surface':
+                throw new SepError({
+                    code: 'SEP_NO_INTERACTIVE_SURFACE',
+                    userMessage: 'env_use needs the user to confirm before secrets are injected into a child process, ' +
+                        'but there is no interactive surface here to ask on (this is what CI looks like to envseal). ' +
+                        'Nothing was run and no value was read. ' +
+                        'There is no flag or environment variable that skips this prompt in this binding: the command ' +
+                        'came from a model, and the confirmation is the only control on it. ' +
+                        'Run the command yourself with `envseal run -- <command>` in a session that has a browser or a terminal.',
+                });
+            case 'busy':
+                throw new SepError({
+                    code: 'SEP_RATE_LIMITED',
+                    userMessage: 'Another envseal confirmation is already open. Answer that one first, then call env_use again.',
+                });
+            case 'too-large':
+                throw new SepError({
+                    code: 'SEP_FORMAT_INVALID',
+                    userMessage: 'This command is too large to display in a confirmation dialog, and envseal will not ask ' +
+                        'anyone to approve something it cannot show them. Run it with fewer or shorter arguments.',
+                });
+        }
+    };
+}
+/**
+ * `onApprovalNeeded` for the Broker: PLAN.md §6.4 probe consent for
+ * `env_verify` against a host that is not registry-allowlisted.
+ *
+ * Never throws. verifyKey() calls this per key inside a loop that builds
+ * per-key results; throwing would abort the whole `env_verify` call, so a
+ * missing surface would take down the verification of keys whose probes are
+ * allowlisted and fine. Every non-approval returns false, which keeps the
+ * existing fail-closed `probe_not_approved` outcome for that one key.
+ */
+export function createProbeApproval(surface) {
+    return async (entry) => {
+        const outcome = await ask(surface, CONFIRM_KEY_PROBE, `Approve sending ${entry.key} to a host that is not on envseal's allowlist? Nothing has been sent yet.`, probeConfirmationBody(entry));
+        return outcome === 'approved';
+    };
+}
+/**
+ * `probe_not_approved` on its own tells the caller nothing it can act on.
+ * verify.ts (core) names the host; this adds what to do about it, in the one
+ * place a binding can add it without reaching into core.
+ */
+export function annotateVerifyResults(results) {
+    return results.map((result) => {
+        if (result.result !== 'probe_not_approved') {
+            return result;
+        }
+        return {
+            ...result,
+            message: `${result.message}. This host is not on envseal's bundled allowlist and no approval for this ` +
+                `exact probe is recorded, so the credential was NOT sent. Run \`envseal verify ${result.key}\` ` +
+                'in an interactive terminal on a machine with access to this ' +
+                'project to review the method, URL and header template and decide. The decision is recorded in ' +
+                '.envseal/approvals.json and replayed without asking again, until the key, method, URL or header ' +
+                'template changes.',
+        };
+    });
+}
+//# sourceMappingURL=confirm.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createServer } from './server.js';
+export * as describe from './tools/describe.js';
+export * as declare from './tools/declare.js';
+export * as request from './tools/request.js';
+export * as await_ from './tools/await.js';
+export * as verify from './tools/verify.js';
+export * as use from './tools/use.js';
+export * as revoke from './tools/revoke.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+export { createServer } from './server.js';
+export * as describe from './tools/describe.js';
+export * as declare from './tools/declare.js';
+export * as request from './tools/request.js';
+export * as await_ from './tools/await.js';
+export * as verify from './tools/verify.js';
+export * as use from './tools/use.js';
+export * as revoke from './tools/revoke.js';
+//# sourceMappingURL=index.js.map

package/dist/respond.d.ts

@@ -0,0 +1,22 @@
+export interface TextContent {
+    type: 'text';
+    text: string;
+}
+export interface ToolResult {
+    content: TextContent[];
+    isError?: true;
+    [key: string]: unknown;
+}
+/**
+ * THE SINGLE EGRESS POINT. Every tool handler returns exclusively through
+ * `respond` or `respondError`; nothing in `src/tools/` may construct a
+ * response object itself. Every string that leaves the server toward the
+ * model passes through the core redactor here. The secret set is empty at
+ * this layer by construction: the broker never hands a secret value to a
+ * tool handler, so there is nothing to redact-against-and-reveal here. Any
+ * string that touched a live value (e.g. `env_use` child output) is already
+ * redacted by the broker before it reaches this point.
+ */
+export declare function respond(payload: unknown): ToolResult;
+export declare function respondError(error: unknown): ToolResult;
+//# sourceMappingURL=respond.d.ts.map

package/dist/respond.js

@@ -0,0 +1,44 @@
+import { isSepError } from '@envseal/protocol';
+import { redact } from '@envseal/core';
+/**
+ * THE SINGLE EGRESS POINT. Every tool handler returns exclusively through
+ * `respond` or `respondError`; nothing in `src/tools/` may construct a
+ * response object itself. Every string that leaves the server toward the
+ * model passes through the core redactor here. The secret set is empty at
+ * this layer by construction: the broker never hands a secret value to a
+ * tool handler, so there is nothing to redact-against-and-reveal here. Any
+ * string that touched a live value (e.g. `env_use` child output) is already
+ * redacted by the broker before it reaches this point.
+ */
+export function respond(payload) {
+    return { content: asContent(JSON.stringify(payload)) };
+}
+export function respondError(error) {
+    if (isSepError(error)) {
+        // SepError messages are curated, user-facing strings from the protocol —
+        // never raw internals, stack traces, or provider responses.
+        return {
+            content: asContent(JSON.stringify({
+                code: error.code,
+                userMessage: error.userMessage,
+                retriable: error.retriable,
+            })),
+            isError: true,
+        };
+    }
+    // Unknown error: NEVER surface the raw message or stack trace — it may
+    // embed a credential or a partial value. Send a fixed safe message instead.
+    return {
+        content: asContent(JSON.stringify({
+            code: 'SEP_INTERNAL',
+            userMessage: 'An internal error occurred. Details were suppressed because they may contain sensitive information.',
+            retriable: false,
+        })),
+        isError: true,
+    };
+}
+function asContent(text) {
+    const filtered = redact(text, []);
+    return [{ type: 'text', text: filtered.text }];
+}
+//# sourceMappingURL=respond.js.map

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Broker } from '@envseal/core';
+import * as describe from './tools/describe.js';
+import * as declare from './tools/declare.js';
+import * as request from './tools/request.js';
+import * as await_ from './tools/await.js';
+import * as verify from './tools/verify.js';
+import * as use from './tools/use.js';
+import * as revoke from './tools/revoke.js';
+export declare function createServer(broker: Broker): Server;
+export { describe, declare, request, await_, verify, use, revoke };
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,43 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { SepError } from '@envseal/protocol';
+import * as describe from './tools/describe.js';
+import * as declare from './tools/declare.js';
+import * as request from './tools/request.js';
+import * as await_ from './tools/await.js';
+import * as verify from './tools/verify.js';
+import * as use from './tools/use.js';
+import * as revoke from './tools/revoke.js';
+import { respondError } from './respond.js';
+const toolModules = [describe, declare, request, await_, verify, use, revoke];
+export function createServer(broker) {
+    // Capabilities must be declared up front or a client will never issue
+    // tools/list, and the handlers below would be dead code.
+    const server = new Server({ name: 'envseal-mcp', version: '0.1.0' }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: toolModules.map((mod) => ({
+            name: mod.name,
+            description: mod.description,
+            inputSchema: zodToJsonSchema(mod.inputSchema),
+        })),
+    }));
+    // The SDK's result type is a union that also covers long-running "task"
+    // responses; annotating pins it to the plain content form these tools return.
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const toolName = req.params.name;
+        const toolModule = toolModules.find((mod) => mod.name === toolName);
+        if (toolModule === undefined) {
+            // Routed through the single egress helper like every other result, so
+            // there is exactly one place where an outbound string is built.
+            return respondError(new SepError({
+                code: 'SEP_UNKNOWN_KEY',
+                userMessage: `Unknown tool: ${toolName}`,
+            }));
+        }
+        return await toolModule.handler(req.params.arguments, broker);
+    });
+    return server;
+}
+export { describe, declare, request, await_, verify, use, revoke };
+//# sourceMappingURL=server.js.map

package/dist/test-prompter.d.ts

@@ -0,0 +1,40 @@
+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.
+ *
+ * Since confirmations are asked on the selected prompter too (see confirm.ts),
+ * this stub also answers them: `ENVSEAL_TEST_PROMPTER_VALUE=yes` approves every
+ * env_use and every non-allowlisted verify probe, and any other value denies
+ * them. That widens the same double-gated hole rather than opening a second
+ * one, and it is what lets the env_use tests drive a real approval and a real
+ * denial against the shipped binary.
+ *
+ * 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.
+ *
+ * Confirmations are asked on this prompter too, which until now made every
+ * non-stored outcome undrivable against the real binary — `timeout` could not
+ * be produced at all, so the honest-timeout mapping in confirm.ts was asserted
+ * by nothing end to end. Same mechanism as the CLI's refusing prompter, and
+ * gated the same way (`ENVSEAL_TEST_MODE=1` plus a second variable).
+ *
+ * Strictly the safer of the two stubs: it can only ever make envseal report
+ * that nobody answered or declined. 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,68 @@
+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.
+ *
+ * Since confirmations are asked on the selected prompter too (see confirm.ts),
+ * this stub also answers them: `ENVSEAL_TEST_PROMPTER_VALUE=yes` approves every
+ * env_use and every non-allowlisted verify probe, and any other value denies
+ * them. That widens the same double-gated hole rather than opening a second
+ * one, and it is what lets the env_use tests drive a real approval and a real
+ * denial against the shipped binary.
+ *
+ * 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.
+ *
+ * Confirmations are asked on this prompter too, which until now made every
+ * non-stored outcome undrivable against the real binary — `timeout` could not
+ * be produced at all, so the honest-timeout mapping in confirm.ts was asserted
+ * by nothing end to end. Same mechanism as the CLI's refusing prompter, and
+ * gated the same way (`ENVSEAL_TEST_MODE=1` plus a second variable).
+ *
+ * Strictly the safer of the two stubs: it can only ever make envseal report
+ * that nobody answered or declined. 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/dist/tools/await.d.ts

@@ -0,0 +1,15 @@
+import type { Broker } from '@envseal/core';
+export declare const name = "env_await";
+export declare const description: string;
+export declare const inputSchema: import("zod").ZodObject<{
+    ticket: import("zod").ZodString;
+    timeoutMs: import("zod").ZodDefault<import("zod").ZodNumber>;
+}, "strict", import("zod").ZodTypeAny, {
+    ticket: string;
+    timeoutMs: number;
+}, {
+    ticket: string;
+    timeoutMs?: number | undefined;
+}>;
+export declare function handler(args: unknown, broker: Broker): Promise<import("../respond.js").ToolResult>;
+//# sourceMappingURL=await.d.ts.map

package/dist/tools/await.js

@@ -0,0 +1,20 @@
+import { INPUT_SCHEMAS } from '@envseal/protocol';
+import { respond, respondError } from '../respond.js';
+export const name = 'env_await';
+export const description = 'Blocks up to timeoutMs (default 90000, max 120000) for a pending env_request ticket to resolve, then ' +
+    'returns per-key outcomes: stored, skipped, cancelled, invalid_format, verify_failed, or timeout. ' +
+    'If the outcome is timeout, the prompt is still open — call env_await again with the same ticket. ' +
+    'It will NOT return the value the user typed, only outcomes. ' +
+    'To retry a failed request, call env_request again.';
+export const inputSchema = INPUT_SCHEMAS.env_await;
+export async function handler(args, broker) {
+    try {
+        const input = INPUT_SCHEMAS.env_await.parse(args ?? {});
+        const result = await broker.await(input);
+        return respond(result);
+    }
+    catch (error) {
+        return respondError(error);
+    }
+}
+//# sourceMappingURL=await.js.map