firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/runner-campaign-controls.js

@@ -0,0 +1,262 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { api } from './auth.js';
+import { privateDirectory } from './credentials.js';
+import { CliError } from './http.js';
+import { signRunnerRequest } from './runner-identity.js';
+import { readLocalClaim } from './runner-claim-reads.js';
+import { identifier } from './world-contracts.js';
+const CAPACITY = { schema: 'firedrill.campaign-world-control-error.v1', code: 'campaign_world_control_capacity' };
+const HASH = /^[a-f0-9]{64}$/, MAX_PACKET = 600 * 1024;
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const sameKeys = (value, fields) => Object.keys(value).sort().join(',') === [...fields].sort().join(',');
+const sha = (value) => createHash('sha256').update(value).digest('hex');
+const date = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+const invalid = () => new CliError('local_campaign_control_unconfirmed', 'World control delivery paused. The original drill was not restarted and no command was repeated.');
+function control(value, owner, execution) {
+    if (value === null)
+        return;
+    if (!record(value) || !sameKeys(value, ['id', 'command_sha256', 'request_key', 'action', 'sequence', 'expected_sequence', 'previous_revision',
+        'expected_watermark', 'next_scenario_id', 'not_after', 'state', 'publication_started_at', 'result', 'workspace_id',
+        'campaign_id', 'execution_id', 'actor_id', 'created_at', 'finished_at', 'provenance', 'problem'])
+        || ['id', 'request_key', 'workspace_id', 'campaign_id', 'execution_id', 'actor_id'].some(key => typeof value[key] !== 'string'
+            || identifier(value[key]) !== value[key])
+        || value.workspace_id !== owner.workspace || value.execution_id !== execution
+        || value.provenance !== 'customer_device'
+        || typeof value.command_sha256 !== 'string' || !HASH.test(value.command_sha256)
+        || typeof value.previous_revision !== 'string' || !HASH.test(value.previous_revision)
+        || typeof value.expected_watermark !== 'string' || !/^(0|[1-9][0-9]{0,5})$/.test(value.expected_watermark)
+        || !Number.isSafeInteger(value.sequence) || Number(value.sequence) < 1 || Number(value.sequence) > 100000
+        || value.expected_sequence !== Number(value.sequence) - 1
+        || typeof value.action !== 'string' || !['pause', 'resume', 'cancel_future', 'revise_future'].includes(value.action)
+        || typeof value.state !== 'string' || !['queued', 'publishing', 'observed', 'rejected', 'unknown', 'ended'].includes(value.state)
+        || !date(value.not_after) || !date(value.created_at)
+        || value.publication_started_at !== null && !date(value.publication_started_at)
+        || value.finished_at !== null && !date(value.finished_at)
+        || value.next_scenario_id !== null && (typeof value.next_scenario_id !== 'string' || identifier(value.next_scenario_id) !== value.next_scenario_id)
+        || value.result !== null && !record(value.result))
+        throw invalid();
+    if (value.problem !== null && (typeof value.problem !== 'string' || value.problem.length > 1000))
+        throw invalid();
+}
+export function campaignControlReadback(value, expected) {
+    if (!record(value) || !sameKeys(value, ['schema', 'command_sha256', 'publication', 'receipt'])
+        || value.schema !== 'firedrill.campaign-world-control-readback.v1' || value.command_sha256 !== expected
+        || typeof value.publication !== 'string' || !['absent', 'queued', 'accepted', 'finished'].includes(value.publication)
+        || (value.receipt !== null) !== (value.publication === 'finished') || value.receipt !== null && !record(value.receipt))
+        throw invalid();
+    return value;
+}
+async function privateFolder(owner) {
+    const path = join(await privateDirectory(), `campaign-controls-${identifier(owner.owner)}-${identifier(owner.workspace)}-${identifier(owner.lease)}`);
+    await mkdir(path, { mode: 0o700 }).catch(error => { if (error.code !== 'EEXIST')
+        throw error; });
+    const row = await lstat(path);
+    if (!row.isDirectory() || row.isSymbolicLink() || row.mode & 0o077 || process.getuid && row.uid !== process.getuid())
+        throw invalid();
+    return path;
+}
+async function saved(directory, expected) {
+    const path = join(directory, identifier(expected.command_id) + '.json');
+    const before = await lstat(path).catch(error => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    if (!before)
+        return expected;
+    if (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1 || before.mode & 0o077 || before.size > 8192
+        || process.getuid && before.uid !== process.getuid())
+        throw invalid();
+    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 invalid();
+        const raw = await file.readFile(), after = await file.stat();
+        if (after.mtimeMs !== actual.mtimeMs || after.ctimeMs !== actual.ctimeMs || after.size !== actual.size)
+            throw invalid();
+        const value = JSON.parse(raw.toString('utf8'));
+        if (!record(value) || !sameKeys(value, Object.keys(expected))
+            || Object.entries(expected).some(([key, child]) => key !== 'stage' && value[key] !== child)
+            || typeof value.stage !== 'string' || !['planned', 'cloud_requested', 'cloud_authorized', 'native_requested', 'readback_only', 'finished'].includes(value.stage))
+            throw invalid();
+        return value;
+    }
+    finally {
+        await file.close();
+    }
+}
+async function persist(directory, journal) {
+    const path = join(directory, identifier(journal.command_id) + '.json'), temporary = path + '.' + randomUUID() + '.tmp';
+    const file = await open(temporary, 'wx', 0o600);
+    try {
+        await file.writeFile(JSON.stringify(journal));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+    const folder = await open(directory, constants.O_RDONLY | (constants.O_DIRECTORY ?? 0));
+    try {
+        await folder.sync();
+    }
+    finally {
+        await folder.close();
+    }
+}
+/** One bounded pump on the original container and claim. It never starts a
+ * target, installs a runner, extends consent or repeats an uncertain write. */
+export function startCampaignWorldControls(owner, configuration, native, signal, output) {
+    const stopping = new AbortController(), active = AbortSignal.any([signal, stopping.signal]);
+    const input = configuration.control;
+    if (owner.purpose !== 'trial' || input.schema !== 'firedrill.trial.v1' || !owner.evidenceUpload
+        || input.world_continuity !== 'continuous'
+        || input.operation_id !== owner.lease || input.job_id !== owner.job || !HASH.test(configuration.manifest_sha256)
+        || typeof input.execution_id !== 'string' || typeof input.execution_inputs_sha256 !== 'string' || !HASH.test(input.execution_inputs_sha256))
+        throw invalid();
+    const execution = identifier(input.execution_id), inputsSha256 = input.execution_inputs_sha256;
+    const prefix = `/api/workspaces/${identifier(owner.workspace)}/local-runners/${identifier(owner.device)}/jobs/${identifier(owner.job)}/claims/${identifier(owner.request)}/campaign-world-controls`;
+    const request = async (action, selected, readback) => {
+        const bounded = AbortSignal.any([active, AbortSignal.timeout(15000)]);
+        const claim = await readLocalClaim(owner, owner.device, owner.job, owner.request, bounded);
+        if (claim.claim?.id !== owner.lease || claim.claim.attempt_id !== owner.attempt || claim.claim.state !== 'claimed'
+            || claim.native_session_id !== owner.nativeSession || claim.payload_digest !== owner.payloadDigest || !date(claim.server_time))
+            throw invalid();
+        const payload = { schema: 'firedrill.local-campaign-control-read.v1', job_id: owner.job, attempt_id: owner.attempt,
+            lease_id: owner.lease, request_key: owner.request, device_key: owner.device, native_session_id: owner.nativeSession,
+            manifest_sha256: configuration.manifest_sha256, execution_id: execution, execution_inputs_sha256: inputsSha256,
+            action, read_key: randomUUID(), sent_at_ms: Date.parse(claim.server_time),
+            ...(selected ? { command_id: selected.id, command_sha256: selected.command_sha256 } : {}),
+            ...(action === 'publish' ? { publication_key: selected.id } : {}), ...(action === 'readback' ? { readback } : {}) };
+        const proof = await signRunnerRequest(owner, owner.device, payload, bounded);
+        const value = await api(prefix, { actor: owner.owner, workspace: owner.workspace, signal: bounded, method: 'POST', body: proof });
+        const extra = action === 'packet' ? ['packet_base64'] : action === 'publish' ? ['should_publish'] : [];
+        if (!record(value) || !sameKeys(value, ['actor_id', 'workspace_id', 'device_key', 'request_key', 'job_id', 'attempt_id', 'lease_id',
+            'manifest_sha256', 'schema', 'execution_id', 'execution_inputs_sha256', 'action', 'command', 'server_time', 'provenance', ...extra])
+            || value.schema !== 'firedrill.local-campaign-control-delivery.v1' || value.action !== action || value.actor_id !== owner.owner
+            || value.workspace_id !== owner.workspace || value.device_key !== owner.device || value.request_key !== owner.request
+            || value.job_id !== owner.job || value.attempt_id !== owner.attempt || value.lease_id !== owner.lease
+            || value.manifest_sha256 !== configuration.manifest_sha256 || value.execution_id !== execution
+            || value.execution_inputs_sha256 !== inputsSha256 || value.provenance !== 'customer_device' || !date(value.server_time))
+            throw invalid();
+        control(value.command, owner, execution);
+        if (selected && (!value.command || ['id', 'command_sha256', 'sequence', 'action', 'not_after'].some(key => value.command[key] !== selected[key])))
+            throw invalid();
+        if (action === 'publish' && typeof value.should_publish !== 'boolean')
+            throw invalid();
+        return value;
+    };
+    const work = (async () => {
+        const directory = await privateFolder(owner);
+        while (!active.aborted) {
+            const next = await request('next'), selected = next.command;
+            if (selected) {
+                const intent = await saved(directory, { schema: 'firedrill.local-campaign-control-journal.v1', job_id: owner.job,
+                    attempt_id: owner.attempt, lease_id: owner.lease, manifest_sha256: configuration.manifest_sha256,
+                    execution_id: execution, execution_inputs_sha256: inputsSha256, command_id: selected.id,
+                    command_sha256: selected.command_sha256, sequence: selected.sequence, stage: 'planned' });
+                if (intent.stage === 'finished')
+                    throw invalid();
+                if (intent.stage === 'planned' && selected.publication_started_at === null && selected.state === 'queued') {
+                    await persist(directory, intent);
+                    const delivered = await request('packet', selected);
+                    if (typeof delivered.packet_base64 !== 'string' || delivered.packet_base64.length > 4 * Math.ceil(MAX_PACKET / 3))
+                        throw invalid();
+                    const packet = Buffer.from(delivered.packet_base64, 'base64');
+                    try {
+                        if (!packet.length || packet.length > MAX_PACKET || packet.toString('base64') !== delivered.packet_base64 || sha(packet) !== selected.command_sha256)
+                            throw invalid();
+                        const value = JSON.parse(packet.toString('utf8'));
+                        if (!record(value) || value.schema !== 'firedrill.campaign-world-control.v1' || value.operation_id !== owner.lease
+                            || value.job_id !== owner.job || value.execution_id !== execution || value.command_id !== selected.id
+                            || value.execution_inputs_sha256 !== inputsSha256 || value.sequence !== selected.sequence
+                            || value.action !== selected.action || value.previous_revision !== selected.previous_revision
+                            || value.expected_watermark !== Number(selected.expected_watermark) || !date(value.not_after)
+                            || Date.parse(value.not_after) !== Date.parse(selected.not_after)
+                            || value.scenario_revision_id !== selected.next_scenario_id || !date(input.job_deadline_at)
+                            || Date.parse(selected.not_after) > Date.parse(input.job_deadline_at))
+                            throw invalid();
+                        try {
+                            await native.stage(selected.id, packet, selected.command_sha256, active);
+                            const check = campaignControlReadback(await native.read(selected.id, 'check', active), selected.command_sha256);
+                            if (check.publication !== 'absent')
+                                throw invalid();
+                        }
+                        catch (error) {
+                            if (!(error instanceof CliError) || error.code !== 'campaign_world_control_capacity')
+                                throw error;
+                            const refused = await request('readback', selected, CAPACITY);
+                            if (refused.command?.state !== 'ended' || !refused.command.problem)
+                                throw invalid();
+                            intent.stage = 'finished';
+                            await persist(directory, intent);
+                            output?.('local_world_control_capacity', { command_id: selected.id, execution_id: execution,
+                                state: 'ended', provenance: 'customer_device', native_publication_observed: false }, refused.command.problem);
+                            await sleep(5000, undefined, { signal: active });
+                            continue;
+                        }
+                        intent.stage = 'cloud_requested';
+                        await persist(directory, intent);
+                        let admitted = null;
+                        try {
+                            admitted = await request('publish', selected);
+                        }
+                        catch (error) {
+                            intent.stage = 'readback_only';
+                            await persist(directory, intent);
+                            if (!(error instanceof CliError) || !['connection_uncertain', 'response_unavailable'].includes(error.code))
+                                throw error;
+                        }
+                        if (admitted?.should_publish === true) {
+                            intent.stage = 'cloud_authorized';
+                            await persist(directory, intent);
+                            // Persist the irreversible send boundary BEFORE the only native
+                            // publication. A lost result can only use mode=result thereafter.
+                            intent.stage = 'native_requested';
+                            await persist(directory, intent);
+                            try {
+                                await native.read(selected.id, 'publish', active);
+                            }
+                            catch { /* Result-only readback below; never republish. */ }
+                        }
+                        else {
+                            intent.stage = 'readback_only';
+                            await persist(directory, intent);
+                        }
+                    }
+                    finally {
+                        packet.fill(0);
+                    }
+                }
+                const observed = campaignControlReadback(await native.read(selected.id, 'result', active), selected.command_sha256);
+                let retained;
+                try {
+                    retained = await request('readback', selected, observed);
+                }
+                catch (error) {
+                    if (!(error instanceof CliError) || error.code !== 'campaign_world_control_pending')
+                        throw error;
+                    // Ordered live evidence can arrive after the native result. Keep the
+                    // original command in readback-only state; this never sends it again.
+                    intent.stage = 'readback_only';
+                    await persist(directory, intent);
+                    await sleep(2000, undefined, { signal: active });
+                    continue;
+                }
+                intent.stage = retained.command && ['observed', 'rejected', 'ended'].includes(retained.command.state) ? 'finished' : 'readback_only';
+                await persist(directory, intent);
+                if (intent.stage === 'finished')
+                    output?.('local_world_control', { command_id: selected.id, execution_id: execution,
+                        state: retained.command.state, action: selected.action, provenance: 'customer_device' }, `World control ${retained.command.state}: ${selected.action.replaceAll('_', ' ')}.`);
+            }
+            await sleep(selected ? 2000 : 5000, undefined, { signal: active });
+        }
+    })().catch(() => {
+        if (!active.aborted)
+            output?.('local_world_controls_paused', { job_id: owner.job, execution_id: execution,
+                provenance: 'customer_device', commands_replayed: false }, 'Live world controls paused. Inspect the original command in the portal; the drill was not restarted.');
+    });
+    return { stop: async () => { stopping.abort(); await work; } };
+}

package/dist/cli/src/runner-claim-reads.js

@@ -0,0 +1,36 @@
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { identifier } from './world-contracts.js';
+import { localAssignmentMatches, localClaimLookupMatches, localAssignmentsMatch } from '../../contracts/local-claim-contracts.js';
+const prefix = (scope, device) => `/api/workspaces/${identifier(scope.workspace)}/local-runners/${identifier(device)}/jobs`;
+const original = (scope, device, job, request) => `${prefix(scope, device)}/${identifier(job)}/claims/${identifier(request)}`;
+const selected = (scope, device, job, request) => ({ actor: scope.owner, workspace: scope.workspace, world: scope.world, device, job, request });
+const auth = (scope, signal) => ({ actor: scope.owner, workspace: scope.workspace, signal });
+const invalid = () => new CliError('local_claim_response_invalid', 'The saved local assignment did not match this account, device, job or original claim. No replacement was sent.');
+export async function localAssignmentsPage(scope, device, filters, signal) {
+    const query = new URLSearchParams({ page: String(filters.page ?? 1) });
+    if (filters.world)
+        query.set('world_id', identifier(filters.world));
+    if (filters.campaign)
+        query.set('campaign_id', identifier(filters.campaign));
+    if (filters.query)
+        query.set('q', filters.query);
+    if (filters.available)
+        query.set('available', 'true');
+    const value = await api(`${prefix(scope, device)}?${query}`, auth(scope, signal));
+    if (!localAssignmentsMatch(value, selected(scope, device), filters))
+        throw invalid();
+    return value;
+}
+export async function readLocalClaim(scope, device, job, request, signal) {
+    const value = await api(original(scope, device, job, request), auth(scope, signal));
+    if (!localClaimLookupMatches(value, { ...selected(scope, device, job, request), request }))
+        throw invalid();
+    return value;
+}
+export async function changeLocalClaim(scope, device, job, request, action, body, signal) {
+    const value = await api(original(scope, device, job, request) + (action === 'presence' ? '/presence' : ''), { ...auth(scope, signal), method: action === 'claim' ? 'PUT' : action === 'withdraw' ? 'DELETE' : 'POST', body });
+    if (!localAssignmentMatches(value, selected(scope, device, job, request)) || !value.claim)
+        throw invalid();
+    return value;
+}

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

@@ -0,0 +1,65 @@
+import { createHash } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { api } from './auth.js';
+import { CliError } from './http.js';
+import { historicalRunnerSigner } from './runner-identity.js';
+import { localContainerCompletion } from './runner-container.js';
+import { identifier } from './world-contracts.js';
+import { localClosingReceiptMatches } from '../../contracts/local-evidence-contracts.js';
+const fail = () => new CliError('local_completion_unconfirmed', 'The closing receipt is not confirmed. The saved operation was not restarted.');
+const canonical = (value) => {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonical(value[key])).join(',') + '}';
+    const body = JSON.stringify(value);
+    if (body === undefined)
+        throw fail();
+    return body;
+};
+/** Historical receipt only. Never claims, renews, executes or reruns a target. */
+export async function syncLocalCompletion(scope, operation, signal, options = {}) {
+    return syncClosingReceipt(scope, await localContainerCompletion(scope, operation), signal, options);
+}
+/** Shared fixed closing proof. Each purpose constructs its own exact document. */
+export async function syncClosingReceipt(scope, saved, signal, options = {}) {
+    const document = canonical(saved.document);
+    const digest = createHash('sha256').update(document).digest('hex');
+    const path = `/api/workspaces/${identifier(scope.workspace)}/local-runners/${identifier(saved.device)}/jobs/${identifier(saved.job)}/claims/${identifier(saved.request)}/completion`;
+    const auth = { actor: scope.owner, workspace: scope.workspace, signal };
+    const matching = (receipt) => {
+        if (!localClosingReceiptMatches(receipt, { ...scope, ...saved })
+            || receipt.schema !== 'firedrill.local-completion-receipt.v1' || receipt.job_id !== saved.job || receipt.attempt_id !== saved.attempt
+            || receipt.lease_id !== saved.lease || receipt.request_key !== saved.request || receipt.manifest_sha256 !== saved.manifestSha256
+            || receipt.provenance !== 'customer_device' || receipt.independently_attested !== false || typeof receipt.received !== 'boolean'
+            || typeof receipt.settled !== 'boolean' || !Number.isSafeInteger(Date.parse(receipt.server_time))
+            || receipt.received && (receipt.digest !== digest || canonical(receipt.document) !== document || receipt.cleanup_recorded !== true)
+            || !receipt.received && (receipt.digest !== null || receipt.document !== null || receipt.cleanup_recorded || receipt.settled)
+            || receipt.settled && !['completed', 'failed', 'canceled'].includes(receipt.job_state))
+            throw fail();
+    };
+    let receipt = await api(path, auth);
+    matching(receipt);
+    if (!receipt.received) {
+        const signer = await historicalRunnerSigner(scope, saved.device, signal);
+        const proof = await signer.sign({ schema: 'firedrill.local-completion.v1', job_id: saved.job, attempt_id: saved.attempt,
+            lease_id: saved.lease, request_key: saved.request, device_key: saved.device, native_session_id: signer.nativeSession,
+            manifest_sha256: saved.manifestSha256, sent_at_ms: Date.parse(receipt.server_time), document: saved.document });
+        try {
+            receipt = await api(path, { ...auth, method: 'POST', body: proof });
+        }
+        catch {
+            receipt = await api(path, auth);
+        } // Reconcile the exact intent, never an automatic write replay.
+        matching(receipt);
+        if (!receipt.received)
+            throw fail();
+    }
+    const until = performance.now() + 180000;
+    while (options.wait && !receipt.settled && performance.now() < until) {
+        await sleep(1000, undefined, { signal });
+        receipt = await api(path, auth);
+        matching(receipt);
+    }
+    return receipt;
+}