@entrorove/skill 0.1.52 → 0.1.53

package/workflow-observation-remote.mjs

@@ -0,0 +1,84 @@
+import { canonical } from './local-integrity.mjs';
+import { buildInvocation, invokeRemoteResult } from './remote-client.mjs';
+import { requestTransport, parseTransportResponse } from './remote-transport.mjs';
+import { ideClientHeaders } from './ide-presentation.mjs';
+import { acknowledgeAutomaticFeedback, queryAutomaticFeedback, verifyAutomaticFeedback } from './automatic-feedback-client.mjs';
+import { saveObservationState } from './workflow-observation-state.mjs';
+import { observationFail } from './workflow-observation-wire.mjs';
+import { readInvocations } from './local-invocations.mjs';
+
+const unknown = requestId => Object.assign(new Error('Original local observation request outcome is unknown; recover its GET without repeating execution'),
+  { code: 'ENTROROVE_LOCAL_OBSERVATION_UNKNOWN', outcomeUnknown: true, requestId });
+const notSent = requestId => Object.assign(new Error('Original local observation was not transmitted'),
+  { code: 'ENTROROVE_LOCAL_OBSERVATION_NOT_SENT', knownBeforeTransmission: true, requestId });
+async function knownNotSent(pending, home) {
+  try {
+    const records = (await readInvocations(home)).filter(value => value.kind === 'remote'
+      && value.operation === pending.operation && value.requestId === pending.requestId);
+    return !records.length || records.at(-1).event === 'not-sent';
+  } catch (error) { return error?.code === 'ENOENT'; }
+}
+async function recover(pending, dependencies) {
+  const token = await dependencies.readCredential(dependencies.home), origin = dependencies.apiOrigin();
+  let response, result;
+  try {
+    response = await requestTransport(origin, `/api/skill/status/${pending.requestId}`, { headers: {
+      authorization: `Bearer ${token}`, ...ideClientHeaders() } });
+    result = parseTransportResponse(response, 'original local observation status');
+    if (!response.ok || result?.output?.requestId !== pending.requestId
+      || ['pending', 'running'].includes(result.output.status)) throw unknown(pending.requestId);
+    result.feedback ??= await queryAutomaticFeedback(pending.requestId, dependencies);
+    verifyAutomaticFeedback(result.feedback, pending.requestId, pending.requestId);
+    result.feedback = await acknowledgeAutomaticFeedback(result.feedback, origin, token, ideClientHeaders());
+  } catch { throw unknown(pending.requestId); }
+  return { response, result };
+}
+function prerequisite(output) {
+  return output?.status === 'blocked' && output.recoverable === true && (output.observationPrerequisite?.effect === 'none'
+    || ['ENTROROVE_SCOPE_RECEIPT_EXPIRED', 'ENTROROVE_SCOPE_RUNNER_REQUIRED', 'ENTROROVE_SCOPE_SNAPSHOT_REQUIRED',
+      'ENTROROVE_SCOPE_AFTER_WRITE_REQUIRED'].includes(output.code));
+}
+export async function observationRemote(stage, operation, input, state, location, dependencies) {
+  const requestId = buildInvocation(operation, input).requestId;
+  let response, result;
+  if (state.pending) {
+    if (state.pending.stage !== stage || state.pending.operation !== operation || state.pending.requestId !== requestId
+      || canonical(state.pending.input) !== canonical(input)) observationFail('Original observation request must finish before another operation');
+    ({ response, result } = await recover(state.pending, dependencies));
+  } else {
+    state.pending = { stage, operation, input, requestId };
+    try { await saveObservationState(location, state); } catch { throw notSent(requestId); }
+    try { ({ response, result } = await invokeRemoteResult({ operation, input }, dependencies)); }
+    catch {
+      if (await knownNotSent(state.pending, dependencies.home)) {
+        delete state.pending;
+        try { await saveObservationState(location, state); } catch { throw notSent(requestId); }
+        throw notSent(requestId);
+      }
+      throw unknown(requestId);
+    }
+  }
+  if (!response.ok || !['reported', 'succeeded'].includes(result?.output?.status)) {
+    if (operation === 'member-observation-admit' && prerequisite(result?.output)) {
+      delete state.pending; await saveObservationState(location, state);
+      throw Object.assign(new Error(result.output.message ?? 'Original local observation prerequisite is unresolved'),
+        { code: result.output.code, output: result.output });
+    }
+    throw unknown(requestId);
+  }
+  state[stage] = result.output; delete state.pending; await saveObservationState(location, state);
+  return result.output;
+}
+export async function authorizeObservation(admission, dependencies, launching) {
+  const token = await dependencies.readCredential(dependencies.home);
+  const response = await requestTransport(dependencies.apiOrigin(), `/api/skill/flows/${admission.flowId}/status`, {
+    headers: { authorization: `Bearer ${token}`, ...ideClientHeaders() } });
+  const status = parseTransportResponse(response, 'original local observation account');
+  if (!response.ok || status?.schemaVersion !== 'entrorove.flow-status/1.0'
+    || status.flow?.flowId !== admission.flowId || status.flow.ownerId !== admission.ownerId
+    || launching && (status.flow.stepId !== admission.stepId || status.flow.status !== 'running'
+      || status.workflow?.phase !== 'execute' || status.workflow.terminalAt
+      || ['pending', 'declined'].includes(status.workflow.authorization))) {
+    observationFail('Current account cannot confirm its original local observation task and execution step');
+  }
+}

package/workflow-observation-runner.mjs

@@ -0,0 +1,87 @@
+import { promises as fs } from 'node:fs';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { scopeRead, scopeTarget } from './local-scope-files.mjs';
+import { regular } from './local-task-handoff-storage.mjs';
+import { assertBudgetRunnerAllowed, withBudgetReadContext } from './local-budget-reads.mjs';
+import { disciplineRepositoryObservation, disciplineRepositoryDifferences } from './local-discipline-repository.mjs';
+import { runApprovedProcess } from './local-approved-process.mjs';
+import { observationAdmission, observationFail } from './workflow-observation-wire.mjs';
+import { saveObservationState } from './workflow-observation-state.mjs';
+
+async function observeFile(input, expected) {
+  const before = await scopeTarget(input.repositoryRoot, expected.path, false, true);
+  const read = await scopeRead(input.repositoryRoot, expected.path, input);
+  const after = await scopeTarget(input.repositoryRoot, expected.path, false, true);
+  if (read.sha256 !== expected.sha256 || expected.mode !== undefined && expected.mode !== null && (after.stat.mode & 511) !== expected.mode
+    || before.stat.dev !== after.stat.dev || before.stat.ino !== after.stat.ino || before.stat.mode !== after.stat.mode) {
+    observationFail('Local observation source or dependency differs from its admitted bytes and permissions');
+  }
+  return { path: expected.path, sha256: read.sha256, mode: after.stat.mode & 511,
+    realPath: await fs.realpath(after.target), dev: after.stat.dev, ino: after.stat.ino };
+}
+async function files(input, manifest) {
+  const result = [];
+  for (const expected of manifest) result.push(await observeFile(input, expected));
+  return result;
+}
+async function executable(admission) {
+  const { bytes, stat } = await regular(admission.command.executable, 256 * 1024 * 1024);
+  if (sha256(bytes) !== admission.command.executableSha256) observationFail('Local observation executable differs from its frozen command hash');
+  return { mode: stat.mode, dev: stat.dev, ino: stat.ino };
+}
+const same = (before, after) => canonical(before) === canonical(after);
+async function remains(action, expected) { try { return same(expected, await action()); } catch { return false; } }
+function processMetadata(process) {
+  return Object.fromEntries(['status', 'started', 'startedAt', 'finishedAt', 'exitCode', 'signal', 'timedOut',
+    'outputLimitExceeded', 'durationMs', 'stdoutSha256', 'stderrSha256', 'capturedBytes', 'droppedBytes'].map(key => [key, process[key]]));
+}
+async function execute(input, admission, state, location, options) {
+  if (state.run) observationFail('Original local observation already started or has an unknown outcome; a new process is forbidden');
+  observationAdmission(admission, input);
+  await assertBudgetRunnerAllowed(input);
+  const originalSources = await files(input, admission.sourceManifest), originalProtected = await files(input, admission.protectedFiles);
+  const originalExecutable = await executable(admission);
+  const before = (await disciplineRepositoryObservation(input, input.repositoryRoot)).comparison;
+  observationAdmission(admission, input);
+  state.run = { phase: 'running', pid: process.pid, startedAt: new Date().toISOString() };
+  await saveObservationState(location, state);
+  let processResult;
+  try {
+    await assertBudgetRunnerAllowed(input);
+    if (!same(originalSources, await files(input, admission.sourceManifest))
+      || !same(originalProtected, await files(input, admission.protectedFiles))
+      || !same(originalExecutable, await executable(admission))) observationFail('Local observation inputs changed immediately before execution');
+    observationAdmission(admission, input);
+    if (options.authorize) await options.authorize();
+    observationAdmission(admission, input);
+    processResult = await runApprovedProcess({ root: input.repositoryRoot, policy: admission.command,
+      objectPlan: true, startDeadlineAt: admission.expiresAt });
+  } catch (error) {
+    if (!error?.execution?.process) {
+      state.run.phase = 'aborted'; await saveObservationState(location, state);
+      observationFail('Local observation stopped before a completed process; recover the original observation without rerunning');
+    }
+    processResult = error.execution.process;
+  }
+  let after = before, budgetAllowed = true;
+  try { await assertBudgetRunnerAllowed(input); after = (await disciplineRepositoryObservation(input, input.repositoryRoot)).comparison; }
+  catch { budgetAllowed = false; }
+  const checks = { sourceManifestUnchanged: budgetAllowed && await remains(() => files(input, admission.sourceManifest), originalSources),
+    protectedFilesUnchanged: budgetAllowed && await remains(() => files(input, admission.protectedFiles), originalProtected),
+    repositoryUnchanged: budgetAllowed && disciplineRepositoryDifferences(before, after).length === 0
+      && await remains(() => executable(admission), originalExecutable) };
+  state.result = { schemaVersion: 'entrorove.local-observation-result/1.0', observationId: admission.observationId,
+    admissionDigest: sha256(canonical(admission)), status: processResult.status === 'succeeded' && Object.values(checks).every(Boolean) ? 'incomplete' : 'failed',
+    independentValidation: 'pending', runner: 'local', receipt: null,
+    executionIsolation: 'host-permissions', externalEffects: 'unverified', process: processMetadata(processResult),
+    sourceManifestDigest: sha256(canonical(admission.sourceManifest)), checks,
+    beforeRepositoryDigest: sha256(canonical(before)), afterRepositoryDigest: sha256(canonical(after)) };
+  state.resultDigest = sha256(canonical(state.result)); state.run.phase = 'finished';
+  await saveObservationState(location, state);
+  return state.result;
+}
+export async function runWorkflowObservation(input, admission, state, location, options = {}) {
+  observationAdmission(admission, input, { allowExpired: Boolean(state.result) });
+  if (state.result) return state.result;
+  return withBudgetReadContext(input, () => execute(input, admission, state, location, options));
+}

package/workflow-observation-state.mjs

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { mutationRoot14, mutationHome14, mutationStateRoot14, privateMutationDirectory14,
+  readMutationJson14, atomicMutationJson14 } from './local-mutation-files.mjs';
+import { observationExact, observationFail } from './workflow-observation-wire.mjs';
+
+export async function observationLocation(repositoryRoot, input, home, apiOrigin) {
+  const root = await mutationRoot14(repositoryRoot), actualHome = await mutationHome14(home);
+  const relative = path.relative(root, actualHome);
+  if (!relative || relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)) {
+    observationFail('Local observation state must be outside the observed repository');
+  }
+  const identity = { ...input, repositoryRoot: root, home: actualHome, apiOrigin };
+  const stateRoot = await mutationStateRoot14({ home: actualHome });
+  const directory = path.join(stateRoot, 'local-observations', sha256(root).slice(0, 32), input.flowId, sha256(canonical(identity)));
+  await privateMutationDirectory14(directory, { privateFrom: stateRoot });
+  return { root, home: actualHome, identity, stateRoot, file: path.join(directory, 'journal.json') };
+}
+export async function readObservationState(location) {
+  let state;
+  try { state = await readMutationJson14(location.file); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!state) return { schemaVersion: 'entrorove.local-observation-state/1.0', identity: location.identity };
+  if (state.schemaVersion !== 'entrorove.local-observation-state/1.0' || canonical(state.identity) !== canonical(location.identity)) {
+    observationFail('Local observation journal lost its original repository, home, task or settlement');
+  }
+  if (state.result && state.resultDigest !== sha256(canonical(state.result))) observationFail('Local observation stored result integrity changed');
+  if (state.run) {
+    observationExact(state.run, ['phase', 'pid', 'startedAt']);
+    if (!['running', 'finished', 'aborted'].includes(state.run.phase) || !Number.isSafeInteger(state.run.pid)
+      || !Number.isFinite(Date.parse(state.run.startedAt))) observationFail('Local observation running state is invalid');
+  }
+  return state;
+}
+export const saveObservationState = (location, state) => atomicMutationJson14(location.file, state,
+  { privateFrom: location.stateRoot, replace: true });

package/workflow-observation-wire.mjs

@@ -0,0 +1,69 @@
+import { createPublicKey, verify } from 'node:crypto';
+import { canonical, sha256 } from './local-integrity.mjs';
+import { mutationId14, mutationPaths14 } from './local-mutation-files.mjs';
+
+export const observationFail = message => { throw Object.assign(new Error(message), { code: 'ENTROROVE_LOCAL_OBSERVATION' }); };
+export const observationIdentityFields = ['taskId', 'flowId', 'stepId', 'leaseId', 'generation', 'settlementId'];
+export function observationExact(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || canonical(Object.keys(value).sort()) !== canonical([...fields].sort())) observationFail('Local observation fields are invalid');
+}
+export function observationInput(input) {
+  observationExact(input, observationIdentityFields);
+  for (const field of observationIdentityFields.filter(field => field !== 'generation')) mutationId14(input[field], field);
+  if (!Number.isSafeInteger(input.generation) || input.generation < 1) observationFail('Local observation generation is invalid');
+  return input;
+}
+function command(value) {
+  observationExact(value, ['executable', 'executableSha256', 'args', 'environment', 'timeoutMs', 'maxOutputBytes', 'requiredExitCode']);
+  if (typeof value.executable !== 'string' || !value.executable.startsWith('/') || /[\u0000-\u001f\u007f]/.test(value.executable)
+    || !/^[a-f0-9]{64}$/.test(value.executableSha256) || !Array.isArray(value.args) || value.args.length > 128
+    || value.args.some(arg => typeof arg !== 'string' || arg.length > 4096 || arg.includes('\0'))
+    || !value.environment || typeof value.environment !== 'object' || Array.isArray(value.environment)
+    || Object.keys(value.environment).length > 64 || Object.entries(value.environment).some(([key, val]) =>
+      !/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof val !== 'string' || val.length > 16_384 || val.includes('\0'))
+    || !Number.isSafeInteger(value.timeoutMs) || value.timeoutMs < 1 || value.timeoutMs > 300_000
+    || !Number.isSafeInteger(value.maxOutputBytes) || value.maxOutputBytes < 1 || value.maxOutputBytes > 1_048_576
+    || value.requiredExitCode !== 0) observationFail('Local observation command differs from its bounded frozen policy');
+}
+function files(values, modes) {
+  if (!Array.isArray(values) || !values.length || values.length > (modes ? 512 : 2_000)) observationFail('Local observation manifest is invalid');
+  const paths = mutationPaths14(values.map(file => file.path));
+  if (canonical(paths) !== canonical(values.map(file => file.path))) observationFail('Local observation manifest must be sorted and unique');
+  for (const file of values) {
+    observationExact(file, ['path', 'sha256', ...(modes ? ['mode'] : [])]);
+    if (!/^[a-f0-9]{64}$/.test(file.sha256) || modes && file.mode !== null
+      && (!Number.isSafeInteger(file.mode) || file.mode < 0 || file.mode > 511)) observationFail('Local observation file baseline is invalid');
+  }
+}
+function signature(value) {
+  try {
+    const encoded = process.env.ENTROROVE_WORKFLOW_PLAN_PUBLIC_KEY, der = Buffer.from(encoded ?? '', 'base64');
+    const key = createPublicKey({ key: der, type: 'spki', format: 'der' }), receipt = value.authorityReceipt;
+    observationExact(receipt, ['schemaVersion', 'keyId', 'payloadDigest', 'signature']);
+    const { authorityReceipt: _, ...core } = value, bytes = Buffer.from(canonical(core));
+    const signed = Buffer.from(receipt.signature, 'base64url');
+    if (key.asymmetricKeyType !== 'ed25519' || key.export({ type: 'spki', format: 'der' }).toString('base64') !== encoded
+      || receipt.schemaVersion !== 'entrorove.workflow-authority-receipt/1.0' || receipt.keyId !== sha256(der)
+      || receipt.payloadDigest !== sha256(bytes) || bytes.length > 1_048_576
+      || signed.length !== 64 || signed.toString('base64url') !== receipt.signature || !verify(null, bytes, key, signed)) throw new Error();
+  } catch { observationFail('Local observation requires its original pinned public cloud admission signature'); }
+}
+export function observationAdmission(value, input, { allowExpired = false } = {}) {
+  observationExact(value, [...observationIdentityFields, 'schemaVersion', 'purpose', 'observationId', 'ownerId', 'taskDigest',
+    'chainDigest', 'epoch', 'planId', 'planDigest', 'executionPlanSha256', 'repositoryDigest', 'settlementDigest', 'command',
+    'sourceManifest', 'protectedFiles', 'issuedAt', 'expiresAt', 'authorityReceipt']);
+  signature(value);
+  const start = Date.parse(value.issuedAt), end = Date.parse(value.expiresAt);
+  if (value.schemaVersion !== 'entrorove.local-observation-admission/1.0' || value.purpose !== 'observe-approved-command'
+    || value.epoch !== 0 || observationIdentityFields.some(field => value[field] !== input[field])
+    || value.repositoryDigest !== sha256(input.repositoryRoot).slice(0, 32) || !Number.isFinite(start) || !Number.isFinite(end)
+    || start > Date.now() || end <= start || end - start > 600_000 || !allowExpired && end <= Date.now()
+    || !/^[a-f0-9-]{36}$/.test(value.ownerId)
+    || ['taskDigest', 'chainDigest', 'planDigest', 'executionPlanSha256', 'settlementDigest'].some(field => !/^[a-f0-9]{64}$/.test(value[field]))) {
+    observationFail('Local observation admission is expired or lost its original task, repository or settlement');
+  }
+  mutationId14(value.observationId, 'observationId'); mutationId14(value.planId, 'planId');
+  command(value.command); files(value.sourceManifest, true); files(value.protectedFiles, false);
+  return value;
+}