firedrill-run 2.2.5 → 3.0.0

package/dist/cli/src/runner-grants.js

@@ -0,0 +1,307 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { withBootstrapProcessLock } from './bootstrap-process-lock.js';
+import { CliError, releaseClosed } from './http.js';
+import { verifyLocalSourceBasis } from './local-source-basis.js';
+import { selectMany, selectOne } from './prompts.js';
+import { signRunnerRequest } from './runner-identity.js';
+import { selectedWorld } from './world-access.js';
+import { identifier } from './world-contracts.js';
+import { localGrantLookupMatches, localGrantsMatch, localGrantOfferMatches } from '../../contracts/local-grant-contracts.js';
+function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object') {
+        const item = value;
+        return '{' + Object.keys(item).sort().map(key => JSON.stringify(key) + ':' + canonical(item[key])).join(',') + '}';
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new CliError('local_grant_invalid', 'The local approval is incomplete.');
+    return encoded;
+}
+const digest = (value) => createHash('sha256').update(canonical(value)).digest('hex');
+const auth = (context, signal) => ({ actor: context.owner, workspace: context.workspace, signal });
+const endpoint = (context, key) => `${context.prefix}/local-grants/${identifier(key)}`;
+export async function savedLocalPermission(context, key, signal) {
+    const value = await api(endpoint(context, key), auth(context, signal));
+    if (!localGrantLookupMatches(value, context.owner, context.workspace, context.world, key))
+        throw new CliError('local_grant_receipt_invalid', 'The original permission did not match this account, world and request. No local work was started.');
+    return value;
+}
+export async function localPermissionPage(context, selected, signal) {
+    const params = new URLSearchParams({ page: String(selected.page ?? 1) });
+    if (selected.device)
+        params.set('device_key', identifier(selected.device));
+    if (selected.grant)
+        params.set('grant_id', identifier(selected.grant));
+    if (selected.purpose)
+        params.set('purpose', selected.purpose);
+    if (selected.available)
+        params.set('available', 'true');
+    if (selected.query)
+        params.set('q', selected.query);
+    const value = await api(`${context.prefix}/local-grants?${params}`, auth(context, signal));
+    if (!localGrantsMatch(value, context.owner, context.workspace, { ...selected, world: context.world }))
+        throw new CliError('local_grant_receipt_invalid', 'The permission history did not match this account, world or selected filters.');
+    return value;
+}
+async function permissionOffer(context, device, signal) {
+    const value = await api(`${context.prefix}/local-runners/${identifier(device)}/grant-offer`, auth(context, signal));
+    if (!localGrantOfferMatches(value, context.owner, context.workspace, context.world, device))
+        throw new CliError('local_grant_offer_invalid', 'The source, runtime and transfer disclosures did not match this selected world and device. Nothing was approved.');
+    return value;
+}
+const pathFor = async (context, key) => join(await privateDirectory(), `local-grant-${identifier(context.owner)}-${identifier(context.workspace)}-${identifier(context.world)}-${identifier(key)}.json`);
+function integer(value, fallback, maximum, name, minimum = 1) {
+    if (value === undefined)
+        return fallback;
+    if (!/^[1-9][0-9]*$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < minimum || Number(value) > maximum) {
+        throw new CliError('local_grant_options_invalid', `Use ${name} between ${minimum} and ${maximum}.`, 2);
+    }
+    return Number(value);
+}
+async function persist(context, value) {
+    const path = await pathFor(context, value.key);
+    const temporary = path + '.' + randomUUID() + '.tmp';
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+}
+async function load(context, key) {
+    const path = await pathFor(context, key);
+    const before = await lstat(path);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 32768 || before.mode & 0o077
+        || process.getuid && before.uid !== process.getuid())
+        throw new CliError('local_grant_journal_unsafe', 'The local permission journal must be private and owned by this OS user.');
+    const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const actual = await file.stat();
+        if (actual.ino !== before.ino || actual.dev !== before.dev || actual.size !== before.size)
+            throw new Error();
+        const value = JSON.parse(await file.readFile('utf8'));
+        if (value.schema !== 'firedrill.local-grant-intent.v1' || value.key !== identifier(key) || value.owner !== context.owner
+            || value.workspace !== context.workspace || value.world !== context.world || value.body?.request_key !== key
+            || value.body.schema !== 'firedrill.local-execution-grant.v1' || value.body.world_id !== context.world
+            || !['request_dispatched', 'retained', 'revoked'].includes(value.stage))
+            throw new Error();
+        identifier(value.body.device_key);
+        identifier(value.body.native_session_id);
+        return value;
+    }
+    catch {
+        throw new CliError('local_grant_journal_invalid', 'The local permission journal changed. It was not replayed or replaced.');
+    }
+    finally {
+        await file.close();
+    }
+}
+async function locked(context, key, signal, work) {
+    const directory = join(await privateDirectory(), `local-grant-lock-${context.owner}-${context.workspace}-${context.world}-${identifier(key)}`);
+    return withBootstrapProcessLock(directory, signal, work);
+}
+function describe(value) {
+    if (value.state === 'not_retained')
+        return `Local permission ${value.request_key}: no retained receipt yet. A delayed original request may still arrive. Revoke this exact request to withdraw it.`;
+    return `Local permission ${value.request_key}: ${value.state.replaceAll('_', ' ')}.\nNo simulation was started by this permission command.`;
+}
+async function record(context, journal, value) {
+    if (!localGrantLookupMatches(value, context.owner, context.workspace, context.world, journal.key))
+        throw new CliError('local_grant_receipt_invalid', 'The permission receipt does not match this world.');
+    if (value.state === 'not_retained')
+        return;
+    const frozen = { basis: value.basis, runtime: value.runtime, operations: value.operations, limits: value.limits, consent: value.consent };
+    const approved = { basis: journal.body.basis, runtime: journal.body.runtime, operations: journal.body.operations,
+        limits: journal.body.limits, consent: journal.body.consent };
+    if (value.world_id !== context.world || value.device_key !== journal.body.device_key
+        || value.request_digest !== null && (value.request_digest !== digest(journal.body)
+            || value.native_session_id !== journal.body.native_session_id
+            || canonical(frozen) !== canonical(approved))) {
+        throw new CliError('local_grant_receipt_invalid', 'The permission receipt does not match the approved scope.');
+    }
+    journal.stage = value.state === 'revoked' ? 'revoked' : 'retained';
+    await persist(context, journal);
+}
+export async function executionPermission(context, key, device, purpose, signal) {
+    const journal = await load(context, identifier(key));
+    const receipt = await savedLocalPermission(context, key, signal);
+    if (journal.stage === 'revoked' || receipt.state !== 'active' || receipt.request_digest !== digest(journal.body)
+        || receipt.world_id !== context.world || receipt.device_key !== identifier(device) || !receipt.id
+        || journal.body.device_key !== device || !journal.body.operations.includes(purpose)) {
+        throw new CliError('local_grant_access_removed', 'The saved permission does not authorize this local job. Review its exact source and runtime before continuing.');
+    }
+    identifier(receipt.id);
+    const source = await verifyLocalSourceBasis(context, device, journal.body.native_session_id, journal.body.basis, signal);
+    if (source.project_digest !== journal.body.project_digest) {
+        throw new CliError('local_project_changed', 'Open the exact project directory approved for this local permission.');
+    }
+    return { id: receipt.id, document: journal.body };
+}
+export async function authorizeLocalExecution(context, device, options, output) {
+    const offer = await permissionOffer(context, identifier(device), options.signal);
+    if (offer.schema !== 'firedrill.local-grant-offer.v1' || offer.world_id !== context.world || offer.device_key !== device
+        || !/^[a-f0-9]{64}$/.test(offer.basis?.source_content_digest) || !Array.isArray(offer.runtimes) || offer.runtimes.length !== 1
+        || !Array.isArray(offer.operations) || offer.operations.some(value => !['validation', 'trial', 'world_session'].includes(value))) {
+        throw new CliError('local_grant_offer_unavailable', 'The exact source and pinned local runtime offer is unavailable. No permission was granted.');
+    }
+    if (options.expectedRuntime && canonical(options.expectedRuntime) !== canonical(offer.runtimes[0])) {
+        throw new CliError('local_runtime_changed', 'The selected execution image changed after its isolation check. Review local setup again. No permission was granted.');
+    }
+    const interactive = !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY;
+    const source = await verifyLocalSourceBasis(context, device, offer.native_session_id, offer.basis, options.signal, interactive);
+    let operations;
+    if (options.operations) {
+        operations = options.operations.split(',');
+        if (!operations.length || operations.some(value => !offer.operations.includes(value)) || new Set(operations).size !== operations.length) {
+            throw new CliError('local_grant_operations_required', 'Choose a comma-separated subset of validation,trial,world_session with --operations.', 2);
+        }
+    }
+    else if (interactive)
+        operations = await selectMany('Allow this device to', offer.operations.map(value => ({ value,
+            label: value === 'validation' ? 'Validate this world locally' : value === 'world_session' ? 'Open manual world sessions locally' : 'Run admitted simulation drills locally' })), options.signal);
+    else
+        throw new CliError('local_grant_operations_required', 'Provide --operations with the required subset of validation,trial,world_session.', 2);
+    operations.sort();
+    if (!operations.length)
+        throw new CliError('local_grant_operations_required', 'No operations were selected. No permission was granted.', 2);
+    const limits = { parallelism: integer(options.parallel, 1, 10000, 'parallelism'), cpu_units: integer(options.cpu, 2, operations.includes('world_session') ? 65535 : 65536, 'CPU units'),
+        memory_mb: integer(options.memory, 4096, 16777216, 'memory in MiB', 1024) };
+    const minutes = integer(options.minutes, 60, 1440, 'minutes');
+    const details = offer.disclosures;
+    if (!details || !Array.isArray(details.vault_values) || !Array.isArray(details.local_values) || !Number.isSafeInteger(details.real_connections)
+        || !Number.isSafeInteger(details.target_model_connections) || !Number.isSafeInteger(details.catalog_packages)
+        || details.catalog_packages < 0)
+        throw new CliError('local_grant_offer_invalid', 'Connection disclosures are unavailable.');
+    output('local_permission_review', { world_id: context.world, world_name: offer.world_name, source_id: offer.basis.source_id,
+        file_count: source.file_count, component_count: source.component_count, operations, limits, minutes, disclosures: details }, [`World: ${offer.world_name}`, `Source: ${source.file_count} matching files${source.component_count > 1 ? ` across ${source.component_count} selected folders` : ''}`, `Operations: ${operations.join(', ')}`,
+        `Ceilings: ${limits.parallelism} concurrent, ${limits.cpu_units} CPU units, ${limits.memory_mb} MiB per execution`,
+        `Permission expires after ${minutes} minutes. Actual capacity and run admission are separate.`,
+        `${details.real_connections} real-account connections; ${details.vault_values.length} values mapped to this device.`,
+        ...(details.local_values.length ? [`${details.local_values.length} device-only values remain in this OS credential store.`] : []),
+        ...(details.catalog_packages ? [`${details.catalog_packages} selected tool package bindings may download private service code and baseline data.`] : []),
+        'Cloud coordination and model context processing remain enabled. Local execution is not an offline mode.'].join('\n'));
+    const consent = { policy: 'firedrill.local-execution-consent.v1', cloud_context_processing: true, run_metadata: true,
+        evidence_upload: options.evidence === true, vault_values_to_device: options.vault === true, real_account_access: options.real === true,
+        catalog_packages_to_device: options.catalog === true };
+    if (interactive && !options.approve) {
+        const choices = [
+            { value: 'evidence_upload', label: operations.includes('world_session') ? 'Upload evidence (required for manual sessions)' : 'Upload run evidence', detail: 'Send selected run transcripts, files and captures to your cloud report.' }
+        ];
+        if (details.vault_values.length)
+            choices.push({ value: 'vault_values_to_device', label: 'Use mapped Vault values on this device', detail: 'Only the frozen build/runtime mappings, not your whole Vault.' });
+        if (details.real_connections)
+            choices.push({ value: 'real_account_access', label: 'Use the selected real accounts', detail: 'Real effects cannot be reset or rewound.' });
+        if (details.catalog_packages)
+            choices.push({ value: 'catalog_packages_to_device', label: 'Download the selected tool packages', detail: 'Copies their private service code and baseline data to this device for isolated execution.' });
+        for (const value of await selectMany('Additional permissions', choices, options.signal))
+            consent[value] = true;
+        const approved = await selectOne('Grant this local permission?', [{ value: true, label: 'Grant permission', detail: 'Allows the listed operations, cloud context processing and saved run metadata. Does not start work.' },
+            { value: false, label: 'Cancel' }], options.signal);
+        if (!approved)
+            throw new CliError('canceled', 'No permission was granted.', 130);
+    }
+    else if (!options.approve)
+        throw new CliError('local_grant_consent_required', 'Use --approve-local for explicit local execution, cloud context and run-metadata consent.', 2);
+    if (operations.includes('world_session') && !consent.evidence_upload) {
+        throw new CliError('local_world_session_permission_required', 'Local manual sessions require evidence upload. No permission was submitted.', 2);
+    }
+    if (details.vault_values.length && !consent.vault_values_to_device || details.real_connections && !consent.real_account_access
+        || details.catalog_packages && !consent.catalog_packages_to_device) {
+        throw new CliError('local_grant_consent_required', 'The selected configuration requires the listed value, tool-download or real-account permission. Change the connection choices or explicitly approve them.', 2);
+    }
+    // Refresh the read-only offer after local capture/user review. A changed
+    // basis or runtime requires a new review, never a silent replacement.
+    const current = await permissionOffer(context, device, options.signal);
+    if (digest(current.basis) !== digest(offer.basis) || digest(current.runtimes) !== digest(offer.runtimes)
+        || current.native_session_id !== offer.native_session_id)
+        throw new CliError('local_grant_basis_changed', 'The world or runtime changed during review. No permission was granted.');
+    const issued = Date.parse(current.server_time);
+    if (!Number.isSafeInteger(issued))
+        throw new CliError('local_grant_offer_invalid', 'The approval service time is unavailable.');
+    const key = randomUUID();
+    const body = { schema: 'firedrill.local-execution-grant.v1', request_key: key, world_id: context.world, device_key: device,
+        native_session_id: identifier(current.native_session_id), basis: offer.basis, runtime: offer.runtimes[0], operations, limits, consent,
+        project_digest: source.project_digest, issued_at_ms: issued, expires_at_ms: issued + minutes * 60000 };
+    const signed = await signRunnerRequest(context, device, body, options.signal);
+    const journal = { schema: 'firedrill.local-grant-intent.v1', owner: context.owner, workspace: context.workspace,
+        world: context.world, key, body, stage: 'request_dispatched' };
+    await persist(context, journal);
+    output('local_permission_request', { request_key: key, world_id: context.world }, `Local permission request ${key}. Inspect with firedrill runner grant status ${key} --world ${context.world}.`);
+    return locked(context, key, options.signal, async (active) => {
+        options = { ...options, signal: active };
+        let receipt;
+        try {
+            const accepted = await api(endpoint(context, key), { ...auth(context, options.signal), method: 'PUT', body: signed });
+            if (!localGrantLookupMatches(accepted, context.owner, context.workspace, context.world, key) || accepted.state === 'not_retained')
+                throw new CliError('local_grant_acceptance_uncertain', 'The original local approval response was incomplete.');
+            receipt = await savedLocalPermission(context, key, options.signal);
+            if (receipt.state === 'not_retained' || receipt.id !== accepted.id || receipt.request_digest !== accepted.request_digest)
+                throw new CliError('local_grant_acceptance_uncertain', 'The saved original approval could not be corroborated.');
+        }
+        catch (error) {
+            // A release refusal is definite. Any other failed dispatch may have
+            // committed: read only; never re-sign or replay a broader/new permission
+            // after an uncertain acceptance.
+            if (releaseClosed(error))
+                throw error;
+            receipt = await savedLocalPermission(context, key, options.signal);
+        }
+        await record(context, journal, receipt);
+        output('local_permission_receipt', receipt, describe(receipt));
+        if (receipt.state === 'not_retained')
+            throw new CliError('local_grant_acceptance_uncertain', 'Approval is not confirmed. Inspect or revoke the exact request; it was not repeated.');
+        return receipt;
+    });
+}
+export async function runnerGrantCommand(action, key, options, output) {
+    const context = await selectedWorld({ world: options.world, workspace: options.workspace,
+        interactive: !options.json && !!process.stdin.isTTY && !!process.stderr.isTTY, openBrowser: options.openBrowser, signal: options.signal });
+    if (action === 'authorize') {
+        if (!key)
+            throw new CliError('runner_key_required', 'Choose a runner key from firedrill runner list.', 2);
+        return authorizeLocalExecution(context, identifier(key), options, output);
+    }
+    if (action === 'list') {
+        const page = integer(options.page, 1, 100000000, 'page');
+        const values = await localPermissionPage(context, { page }, options.signal);
+        output('local_permission_list', values, values.results.map(value => `${value.request_key}  ${value.state}  ${(value.operations ?? []).join(', ')}`).join('\n') || 'No local execution permissions for this world.');
+        return;
+    }
+    if (!key)
+        throw new CliError('local_grant_key_required', 'Use the exact local permission request key.', 2);
+    key = identifier(key);
+    return locked(context, key, options.signal, async (active) => {
+        options = { ...options, signal: active };
+        let receipt = await savedLocalPermission(context, key, options.signal);
+        let journal = null;
+        try {
+            journal = await load(context, key);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (action === 'revoke') {
+            const device = receipt.state === 'not_retained' ? journal?.body.device_key : receipt.device_key;
+            if (!device)
+                throw new CliError('local_grant_journal_required', 'No retained device or local request was found. Keep the exact original journal before withdrawing an unobserved approval.');
+            receipt = await api(endpoint(context, key), { ...auth(context, options.signal), method: 'DELETE', body: { device_key: identifier(device) } });
+            if (!localGrantLookupMatches(receipt, context.owner, context.workspace, context.world, key) || receipt.state !== 'revoked'
+                || receipt.device_key !== device)
+                throw new CliError('local_grant_revocation_uncertain', 'Permission revocation was not confirmed. Inspect the exact saved request.');
+        }
+        if (journal)
+            await record(context, journal, receipt);
+        output('local_permission_receipt', receipt, describe(receipt));
+    });
+}