firedrill-run 2.2.5 → 3.0.1

package/dist/cli/src/native/local-secrets.js

@@ -0,0 +1,19 @@
+import { CliError } from '../http.js';
+import { SecretValue } from './contracts.js';
+/** Resolve only names from an already-approved plan, without logging their values. */
+export function localSecretBindings(service, existing = {}) {
+    const entries = [];
+    const secrets = [];
+    const occupied = new Set(Object.keys(existing).map(name => name.toUpperCase()));
+    for (const name of service.local_secret_env ?? []) {
+        if (occupied.has(name.toUpperCase()))
+            throw new CliError('native_local_secret_conflict', 'A local secret conflicts with a drill binding. Change the local plan and approve it again.', 2);
+        const value = process.env[name];
+        if (!value || value.includes('\0') || Buffer.byteLength(value, 'utf8') > 16_384) {
+            throw new CliError('native_local_secret_required', `Set ${name} in the local runner environment before starting. Its value must not be placed in the plan.`, 2);
+        }
+        entries.push([name, value]);
+        secrets.push(new SecretValue(value, 'local-configuration'));
+    }
+    return { env: { ...existing, ...Object.fromEntries(entries) }, secrets };
+}

package/dist/cli/src/native/mcp-config.js

@@ -0,0 +1,123 @@
+/**
+ * Drill-scoped MCP client configuration for simulated MCP dependencies (Plan20
+ * FIR-490).
+ *
+ * For every routed `mcp` dependency this writes one remote server entry into a
+ * generic MCP client JSON file, pointing at the companion's per-drill loopback
+ * proxy (dependency-proxy.ts). It carries no credential: root's token stays in
+ * companion memory, and the URL's path capability is the only secret in the file.
+ *
+ *   { "mcpServers": { "<dependency alias>": { "type": "http", "url": "http://127.0.0.1:<port>/<cap>/<alias>/mcp",
+ *                                             "headers": {} } } }
+ *
+ * The file lives in a fresh private directory (0700) under the run scratch
+ * directory, is created exclusively (0600, O_EXCL, O_NOFOLLOW where the platform
+ * has it) and is removed by the returned cleanup. The target is pointed at it by
+ * the caller adding `env` (one variable, named by the approved plan, holding the
+ * absolute file path) to the target service environment.
+ *
+ * This module never reads, edits or creates any user-level or global agent/client
+ * configuration, never installs anything, and never touches proxy, CA, TLS or DNS
+ * settings. On Windows, POSIX modes are not enforced by the OS; the file still
+ * sits in a fresh per-run directory under the private scratch, and `permissions`
+ * reports `platform-default` so the caller can disclose that limitation.
+ */
+import { constants } from 'node:fs';
+import { lstat, mkdtemp, open, rm, chmod } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+import { CliError } from '../http.js';
+import { nativeError } from './contracts.js';
+import { ENV_NAME, isReservedEnvName } from './bindings.js';
+const MCP_SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+/** Only the companion's own loopback proxy may appear in the file. */
+const PROXY_URL = /^http:\/\/127\.0\.0\.1:\d{1,5}\/[A-Za-z0-9_-]{43}\/[a-z][a-z0-9_-]{0,63}\/mcp$/;
+const MAX_CONFIG_BYTES = 256 * 1024;
+/**
+ * Write the MCP client configuration for one service's routed MCP dependencies.
+ * Returns null when there are none (nothing is created). Server names and URLs
+ * are re-checked here because this is an injection point.
+ */
+export async function writeMcpConfig(entries, scratchDir, options) {
+    const format = options.format ?? 'mcp-servers.http';
+    if (format !== 'mcp-servers.http') {
+        throw new CliError('native_mcp_config_unsupported', 'The MCP client configuration was not written: only the generic remote HTTP format is supported.');
+    }
+    if (!ENV_NAME.test(options.envName) || isReservedEnvName(options.envName)) {
+        throw nativeError('binding_invalid', 'The MCP client configuration was not written: the plan names an invalid or reserved environment variable for it.');
+    }
+    if (entries.length === 0)
+        return null;
+    const servers = {};
+    const secrets = [];
+    for (const entry of entries) {
+        if (!MCP_SERVER_NAME.test(entry.name) || Object.prototype.hasOwnProperty.call(servers, entry.name)) {
+            throw nativeError('binding_invalid', `The MCP client configuration was not written: server "${entry.name}" is malformed or listed twice.`);
+        }
+        // Injection point: the URL (with its path capability) is revealed only into the private file.
+        const url = entry.url.reveal();
+        if (!PROXY_URL.test(url)) {
+            throw nativeError('binding_invalid', `The MCP client configuration was not written: server "${entry.name}" does not point at the companion's loopback proxy.`);
+        }
+        servers[entry.name] = { type: 'http', url, headers: {} };
+        secrets.push(entry.url);
+    }
+    const body = `${JSON.stringify({ mcpServers: servers }, null, 2)}\n`;
+    if (Buffer.byteLength(body, 'utf8') > MAX_CONFIG_BYTES) {
+        throw nativeError('binding_invalid', 'The MCP client configuration was not written: it exceeds the size limit.');
+    }
+    if (!isAbsolute(scratchDir)) {
+        throw new CliError('native_scratch_invalid', 'The MCP client configuration was not written: the run scratch directory is not an absolute path.');
+    }
+    let scratch;
+    try {
+        scratch = await lstat(scratchDir);
+    }
+    catch {
+        throw new CliError('native_scratch_invalid', 'The MCP client configuration was not written: the run scratch directory is unavailable.');
+    }
+    if (scratch.isSymbolicLink() || !scratch.isDirectory()) {
+        throw new CliError('native_scratch_invalid', 'The MCP client configuration was not written: the run scratch path is not a real directory.');
+    }
+    const posix = process.platform !== 'win32';
+    if (posix && typeof process.getuid === 'function' && scratch.uid !== process.getuid()) {
+        throw new CliError('native_scratch_invalid', 'The MCP client configuration was not written: the run scratch directory is not owned by the current user.');
+    }
+    if (posix && (scratch.mode & 0o022) !== 0) {
+        throw new CliError('native_scratch_invalid', 'The MCP client configuration was not written: the run scratch directory is writable by other users.');
+    }
+    // mkdtemp creates the directory with mode 0700 and a random suffix.
+    const directory = await mkdtemp(join(scratchDir, 'mcp-'));
+    let removed = false;
+    const cleanup = async () => {
+        if (removed)
+            return;
+        removed = true;
+        await rm(directory, { recursive: true, force: true });
+    };
+    const path = join(directory, 'mcp.json');
+    try {
+        if (posix)
+            await chmod(directory, 0o700);
+        const noFollow = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+        const handle = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollow, 0o600);
+        try {
+            await handle.writeFile(body, 'utf8');
+            await handle.sync();
+            if (posix)
+                await handle.chmod(0o600);
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        await cleanup().catch(() => undefined);
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError('native_mcp_config_unwritten', 'The MCP client configuration was not written to the private run directory. The drill was not started.');
+    }
+    return {
+        path, directory, env: { [options.envName]: path }, secrets, servers: Object.keys(servers),
+        permissions: posix ? 'posix-0600' : 'platform-default', cleanup,
+    };
+}

package/dist/cli/src/native/metadata-requests.js

@@ -0,0 +1,120 @@
+/**
+ * Original native metadata writes, recovered or withdrawn by their request key.
+ *
+ * Root (`native_metadata_requests.py`, `native_metadata_withdrawal.py` and the
+ * library's own request view), for this person in the current workspace:
+ * - `GET .../native-library/requests/{key}`, `.../native-agents/requests/{key}`
+ *   (the registration receipt), `.../agents/{agent}/native-descriptors/requests/{key}`
+ *   and `.../native-worlds/requests/{key}` return the original committed write.
+ *   404: not committed, and it may still be in flight, so it is never a reason
+ *   to send a replacement under a new key. 410: the original was removed. 409
+ *   `native_metadata_request_withdrawn`: it was withdrawn.
+ * - `DELETE` on the same path with exactly `{withdraw_consent: true}` fences
+ *   the key: `{state: "withdrawn", receipt: null}` when nothing was committed
+ *   (a delayed original can then never land), or `{state: "committed",
+ *   receipt}` when it already was (nothing is deleted).
+ *
+ * A pointer to an uncertain original is cleared only after a confirmed
+ * withdrawal, or replaced by the committed receipt.
+ */
+import { api } from '../auth.js';
+import { CliError } from '../http.js';
+import { isTransient } from './control-plane.js';
+import { libraryRow, worldRow } from './cloud-resources.js';
+import { descriptorRevisionRow, registrationReceiptRow } from './registration.js';
+export const METADATA_KINDS = ['library', 'agent', 'descriptor', 'world'];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const RESPONSE_LIMIT = 4 * 1024 * 1024;
+/** Own time to read an original back after its answer was lost. */
+const RECOVERY_MS = 15_000;
+const NOUN = { library: 'library change', agent: 'agent registration', descriptor: 'descriptor revision', world: 'world change' };
+const unconfirmed = (kind) => new CliError('native_response_unconfirmed', `The original ${NOUN[kind]} could not be confirmed. Nothing else was sent.`, 2);
+const object = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+function pathOf(scope, target) {
+    if (!UUID.test(target.requestKey))
+        throw new CliError('native_request_key_invalid', 'Use the request key printed by the original attempt.', 2);
+    const key = target.requestKey.toLowerCase();
+    if ((target.kind === 'descriptor') !== (target.agentId !== undefined) || (target.agentId !== undefined && !UUID.test(target.agentId)))
+        throw new CliError('arguments_invalid', 'A descriptor revision request needs its agent (--agent <id>); other requests take none.', 2);
+    const base = `/api/workspaces/${scope.workspace}`;
+    switch (target.kind) {
+        case 'library': return `${base}/native-library/requests/${key}`;
+        case 'agent': return `${base}/native-agents/requests/${key}`;
+        case 'world': return `${base}/native-worlds/requests/${key}`;
+        default: return `${base}/agents/${target.agentId.toLowerCase()}/native-descriptors/requests/${key}`;
+    }
+}
+function receiptOf(target, raw) {
+    try {
+        switch (target.kind) {
+            case 'library': return libraryRow(true)(raw);
+            case 'world': return worldRow(true)(raw);
+            case 'agent': return registrationReceiptRow(raw, null);
+            default: {
+                const row = descriptorRevisionRow(raw, null, true);
+                if (row.agent_id !== target.agentId.toLowerCase())
+                    throw new Error();
+                return row;
+            }
+        }
+    }
+    catch {
+        throw unconfirmed(target.kind);
+    }
+}
+/** The original write as root holds it now. Never sends it again. */
+export async function recoverMetadataRequest(scope, target, signal) {
+    const path = pathOf(scope, target);
+    let raw;
+    try {
+        raw = await api(path, { actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        if (error.httpStatus === 404)
+            return { state: 'not_found' };
+        if (error.httpStatus === 410)
+            return { state: 'removed' };
+        if (error.code === 'native_metadata_request_withdrawn')
+            return { state: 'withdrawn' };
+        throw error;
+    }
+    return { state: 'committed', receipt: receiptOf(target, raw) };
+}
+/** Withdraw an original that was never committed, after the human approved it. A committed one is returned, not deleted. */
+export async function withdrawMetadataRequest(scope, target, signal) {
+    const raw = await api(pathOf(scope, target), { method: 'DELETE', body: { withdraw_consent: true },
+        actor: scope.owner, workspace: scope.workspace, signal, maximumResponseBytes: RESPONSE_LIMIT });
+    if (!object(raw) || Object.keys(raw).length !== 2 || !('receipt' in raw))
+        throw unconfirmed(target.kind);
+    if (raw.state === 'withdrawn' && raw.receipt === null)
+        return { state: 'withdrawn' };
+    if (raw.state === 'committed' && raw.receipt !== null)
+        return { state: 'committed', receipt: receiptOf(target, raw.receipt) };
+    throw unconfirmed(target.kind);
+}
+/** Answers that arrived but could not be confirmed as this write's receipt. */
+const UNCONFIRMED = new Set(['native_response_unconfirmed', 'native_registration_unconfirmed']);
+/** True when a write got no definitive answer, so it may or may not have been committed. Local refusals before sending are not. */
+export function answerLost(error) {
+    return isTransient(error) || (error instanceof CliError && UNCONFIRMED.has(error.code));
+}
+/**
+ * After a write whose answer was lost: its committed receipt, read back by its
+ * key on the recovery's own time. Otherwise an error that names the key and the
+ * only safe next steps (replay the same request, or withdraw it); never a
+ * replacement under a new key.
+ */
+export async function recoverLostWrite(scope, target, commands) {
+    const original = await recoverMetadataRequest(scope, target, AbortSignal.timeout(RECOVERY_MS)).catch(() => null);
+    if (original?.state === 'committed')
+        return original.receipt;
+    if (original?.state === 'withdrawn')
+        throw new CliError('native_metadata_request_withdrawn', `This ${NOUN[target.kind]} (request ${target.requestKey}) was withdrawn, so it will not land. Make a new change only if the human still wants it.`, 2);
+    if (original?.state === 'removed')
+        throw new CliError('native_metadata_removed', `This ${NOUN[target.kind]} (request ${target.requestKey}) was saved and has since been removed.`, 2);
+    throw new CliError('native_request_unconfirmed', `The answer was lost, so this ${NOUN[target.kind]} is not confirmed (request ${target.requestKey}). It may still land. `
+        + `Replay the same request with: ${commands.replay}. Or, before making a different change, withdraw it: ${commands.withdraw}. Never send it again under a new key.`, 2);
+}
+export function metadataNoun(kind) { return NOUN[kind]; }