@twinsearth/w2m-dsh-plugin 1.3.1 → 1.3.11

package/src/maintenance/operator-key.mjs

@@ -0,0 +1,151 @@
+/**
+ * Operator signing keys: generation, pinning and rotation for the maintenance channel (M1, v1.3.2-beta).
+ *
+ * The operator key is the only thing that can authorise a maintenance action, so it must not be the same credential as
+ * the operator token used to dispatch tasks: a leaked dispatch token should not become a leaked authorisation.
+ *
+ * Target machines pin the operator public key. First contact is trust-on-first-use (the relay hands out the registered
+ * key), and every later change must be signed by the currently pinned key — the rotation chain. That turns a key swap
+ * from a silent event into a refusal unless the previous key authorised it.
+ */
+import { createHash, generateKeyPairSync, sign as signBytes, verify as verifyBytes, createPublicKey, createPrivateKey } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export const OPERATOR_ROTATION_PROTOCOL = 'w2m-operator-rotation/v1';
+
+export class OperatorKeyError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'OperatorKeyError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+export function keyIdOf(publicKeyLike) {
+  const key = publicKeyLike?.type === 'public' ? publicKeyLike : createPublicKey(publicKeyLike);
+  return createHash('sha256').update(key.export({ type: 'spki', format: 'der' })).digest('hex').slice(0, 16);
+}
+
+/** Create a fresh Ed25519 operator key pair. The caller is responsible for storing the private half safely. */
+export function generateOperatorKeyPair() {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  return {
+    keyId: keyIdOf(publicKey),
+    publicKeyPem: publicKey.export({ type: 'spki', format: 'pem' }).toString(),
+    privateKeyPem: privateKey.export({ type: 'pkcs8', format: 'pem' }).toString(),
+  };
+}
+
+export function publicKeyPemOf(privateKeyPem) {
+  return createPublicKey(createPrivateKey(privateKeyPem)).export({ type: 'spki', format: 'pem' }).toString();
+}
+
+/** What the control side sends to the relay so paired machines can pin the key. It is not a secret. */
+export function registrationPayload(keyPair, nowIso = new Date().toISOString()) {
+  return {
+    protocol: 'w2m-operator-key/v1',
+    key_id: keyPair.keyId,
+    public_key_pem: keyPair.publicKeyPem,
+    created_at: nowIso,
+  };
+}
+
+/** The exact bytes signed when rotating to a new key. */
+export function rotationPayload({ oldKeyId, newKeyId, newPublicKeyPem }) {
+  return JSON.stringify({ protocol: OPERATOR_ROTATION_PROTOCOL, old_key_id: oldKeyId, new_key_id: newKeyId, new_public_key_pem: newPublicKeyPem });
+}
+
+/**
+ * A target machine's pin store. One file, atomically replaced; the whole lifecycle (pin, rotate, revoke) is expressed
+ * here so the runner never touches the file format directly.
+ */
+export function createPinStore(filePath, { now = () => Date.now() } = {}) {
+  const empty = () => ({ protocol: 'w2m-operator-pins/v1', pinned: null, revoked: [], history: [] });
+  const load = () => {
+    if (!existsSync(filePath)) return empty();
+    try {
+      const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+      return {
+        protocol: 'w2m-operator-pins/v1',
+        pinned: parsed.pinned ?? null,
+        revoked: Array.isArray(parsed.revoked) ? parsed.revoked : [],
+        history: Array.isArray(parsed.history) ? parsed.history : [],
+      };
+    } catch {
+      // A corrupt pin file must not be silently replaced: refusing is the only safe reading of "I cannot tell which key
+      // is trusted". The runner reports this as a failure rather than continuing with an empty pin.
+      throw new OperatorKeyError('PINS_CORRUPT', 'operator pin store is unreadable; refusing to trust any key');
+    }
+  };
+  const save = (state) => {
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = filePath + '.tmp-' + process.pid;
+    writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+    renameSync(tmp, filePath);
+  };
+  const isRevoked = (keyId) => {
+    const state = load();
+    return state.revoked.some((entry) => entry.key_id === keyId);
+  };
+  return {
+    filePath,
+    load,
+    isRevoked,
+    /**
+     * Pin a key after checking a registration payload. First pin is TOFU; a different pinned key requires rotation.
+     */
+    pinFromRegistration(payload) {
+      if (payload === null || typeof payload !== 'object' || typeof payload.public_key_pem !== 'string') {
+        throw new OperatorKeyError('BAD_REGISTRATION', 'operator registration payload is malformed');
+      }
+      const keyId = keyIdOf(payload.public_key_pem);
+      if (typeof payload.key_id === 'string' && payload.key_id !== keyId) {
+        throw new OperatorKeyError('KEY_ID_MISMATCH', 'registration key_id does not match its public key', { claimed: payload.key_id, computed: keyId });
+      }
+      if (this.isRevoked(keyId)) throw new OperatorKeyError('KEY_REVOKED', 'operator key is revoked', { key_id: keyId });
+      const state = load();
+      if (state.pinned === null) {
+        state.pinned = { key_id: keyId, public_key_pem: payload.public_key_pem, pinned_at: new Date(now()).toISOString(), rotation_of: null };
+        state.history.push({ event: 'pinned', key_id: keyId, at: state.pinned.pinned_at });
+        save(state);
+        return { ok: true, pinned: state.pinned, firstContact: true };
+      }
+      if (state.pinned.key_id === keyId) return { ok: true, pinned: state.pinned, firstContact: false };
+      throw new OperatorKeyError('ROTATION_REQUIRED', 'a different operator key is already pinned; sign a rotation with the pinned key', { pinned: state.pinned.key_id, offered: keyId });
+    },
+    /** Apply a rotation that was signed by the currently pinned key. */
+    rotate({ newPublicKeyPem, signatureBase64 }) {
+      const state = load();
+      if (state.pinned === null) throw new OperatorKeyError('NO_PINNED_KEY', 'nothing is pinned yet; rotation is not possible');
+      const newKeyId = keyIdOf(newPublicKeyPem);
+      if (this.isRevoked(newKeyId)) throw new OperatorKeyError('KEY_REVOKED', 'new operator key is revoked', { key_id: newKeyId });
+      const oldKey = createPublicKey(state.pinned.public_key_pem);
+      const payload = rotationPayload({ oldKeyId: state.pinned.key_id, newKeyId, newPublicKeyPem });
+      const ok = verifyBytes(null, Buffer.from(payload, 'utf8'), oldKey, Buffer.from(String(signatureBase64 ?? ''), 'base64'));
+      if (ok !== true) throw new OperatorKeyError('ROTATION_BAD_SIGNATURE', 'rotation was not signed by the currently pinned key');
+      state.history.push({ event: 'rotated', from: state.pinned.key_id, to: newKeyId, at: new Date(now()).toISOString() });
+      state.pinned = { key_id: newKeyId, public_key_pem: newPublicKeyPem, pinned_at: new Date(now()).toISOString(), rotation_of: state.pinned.key_id };
+      save(state);
+      return { ok: true, pinned: state.pinned };
+    },
+    revoke(keyId, reason) {
+      const state = load();
+      if (!state.revoked.some((entry) => entry.key_id === keyId)) {
+        state.revoked.push({ key_id: keyId, reason: String(reason ?? 'unspecified'), at: new Date(now()).toISOString() });
+        save(state);
+      }
+      return { ok: true, key_id: keyId };
+    },
+  };
+}
+
+/** Sign a rotation payload with the old private key (control-side helper). */
+export function signRotation({ oldPrivateKeyPem, oldKeyId, newPublicKeyPem }) {
+  const oldKey = createPrivateKey(oldPrivateKeyPem);
+  const newKeyId = keyIdOf(newPublicKeyPem);
+  const payload = rotationPayload({ oldKeyId, newKeyId, newPublicKeyPem });
+  const signature = signBytes(null, Buffer.from(payload, 'utf8'), oldKey);
+  return { newKeyId, signatureBase64: signature.toString('base64') };
+}

package/src/maintenance/protocol.mjs

@@ -0,0 +1,204 @@
+/**
+ * The maintenance-request wire protocol (v1.3.2-beta, M1).
+ *
+ * A request is a signed JSON document that authorises exactly one of three fixed actions (update/restart/diag) on one
+ * machine. This module owns the shape, the canonical bytes that are signed, and every refusal the verifier can produce.
+ * It deliberately does not execute anything: the root runner decides, this file only says yes or no.
+ *
+ * Design notes that matter:
+ *   - The signature covers the action and its parameters, the machine id and the time window. A relay (or any transport)
+ *     can therefore reroute a request but cannot reshape it.
+ *   - Timestamps are compared against an injected clock, because tests must be able to sit on both sides of a TTL edge.
+ *   - Every refusal is a named code; "it failed" alone would tell an operator nothing about what to fix.
+ */
+import { createHash, randomBytes, sign as signBytes, verify as verifyBytes, createPrivateKey, createPublicKey } from 'node:crypto';
+
+export const MAINTENANCE_PROTOCOL = 'w2m-maintenance/v1';
+
+/** The complete action vocabulary. Anything else is refused before signature checking can be wasted on it. */
+export const MAINTENANCE_ACTIONS = Object.freeze(['update', 'restart', 'diag']);
+
+/** Request files are small by construction: a large request is either a bug or an attempt to exhaust the queue. */
+export const MAX_REQUEST_BYTES = 64 * 1024;
+
+/** The operator may not authorise an action that stays valid for longer than this, whatever the request says. */
+export const MAX_TTL_MS = 10 * 60 * 1000;
+
+/** Clock disagreement is tolerated, but only in the direction that cannot extend a window. */
+export const CLOCK_SKEW_MS = 60 * 1000;
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const KEY_ID = /^[0-9a-f]{8,32}$/;
+const REQUEST_ID = /^[0-9A-Za-z-]{8,64}$/;
+const NONCE = /^[0-9A-Za-z_-]{8,64}$/;
+
+export class MaintenanceProtocolError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'MaintenanceProtocolError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+/** Deep-sort object keys so two processes sign the same bytes. Arrays keep order: argv and files are ordered data. */
+export function canonicalize(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map((entry) => canonicalize(entry)).join(',') + ']';
+  const keys = Object.keys(value).sort();
+  return '{' + keys.map((key) => JSON.stringify(key) + ':' + canonicalize(value[key])).join(',') + '}';
+}
+
+/** The exact bytes the operator signs. `signature` itself is excluded by construction. */
+export function signingPayload(request) {
+  const { signature: _signature, ...rest } = request;
+  return canonicalize(rest);
+}
+
+export function keyIdOf(publicKeyLike) {
+  const key = publicKeyLike?.type === 'public' ? publicKeyLike : createPublicKey(publicKeyLike);
+  const der = key.export({ type: 'spki', format: 'der' });
+  return createHash('sha256').update(der).digest('hex').slice(0, 16);
+}
+
+export function generateRequestId(nowMs = Date.now()) {
+  return 'mr-' + nowMs.toString(36) + '-' + randomBytes(6).toString('hex');
+}
+
+export function generateNonce() {
+  return randomBytes(16).toString('hex');
+}
+
+/**
+ * Build the unsigned request body. Validation of parameters happens in `validateParams`, not here: a builder that
+ * silently repaired bad input would make the verifier's refusal list incomplete.
+ */
+export function buildRequest({ action, params = {}, machineId, issuedBy = 'operator', ttlMs = 60_000, nowMs = Date.now(), requestId, nonce }) {
+  if (!Number.isInteger(nowMs) || nowMs < 0) throw new MaintenanceProtocolError('MAINTENANCE_BAD_SHAPE', 'nowMs must be a non-negative integer');
+  return {
+    protocol: MAINTENANCE_PROTOCOL,
+    request_id: requestId ?? generateRequestId(nowMs),
+    action,
+    params,
+    machine_id: machineId,
+    nonce: nonce ?? generateNonce(),
+    issued_at: new Date(nowMs).toISOString(),
+    expires_at: new Date(nowMs + ttlMs).toISOString(),
+    issued_by: issuedBy,
+  };
+}
+
+/** Attach an Ed25519 signature. The operator key never leaves the control side. */
+export function signRequest(request, privateKeyPem) {
+  const privateKey = createPrivateKey(privateKeyPem);
+  const publicKey = createPublicKey(privateKey);
+  const signature = signBytes(null, Buffer.from(signingPayload(request), 'utf8'), privateKey);
+  return {
+    ...request,
+    signature: { alg: 'ed25519', key_id: keyIdOf(publicKey), value_base64: signature.toString('base64') },
+  };
+}
+
+export function requestBytes(request) {
+  return Buffer.byteLength(JSON.stringify(request), 'utf8');
+}
+
+function validateParams(action, params) {
+  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
+    return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { action, reason: 'params must be a JSON object' } };
+  }
+  if (action === 'update') {
+    const target = params.target;
+    if (target !== 'plugin' && target !== 'relay') return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'target must be plugin or relay' } };
+    if (typeof params.version !== 'string' || params.version.trim() === '') return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'version is required' } };
+    if (typeof params.artifact_sha256 !== 'string' || !SHA256_HEX.test(params.artifact_sha256)) return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'artifact_sha256 must be 64 lowercase hex' } };
+    const urls = params.artifact_urls;
+    if (!Array.isArray(urls) || urls.length === 0 || urls.length > 3) return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'artifact_urls must be 1..3 entries' } };
+    for (const url of urls) {
+      if (typeof url !== 'string' || !url.startsWith('https://')) return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'artifact_urls entries must be https URLs' } };
+    }
+    if (params.restart_after_update !== undefined && typeof params.restart_after_update !== 'boolean') return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'restart_after_update must be boolean' } };
+    return { ok: true };
+  }
+  if (action === 'restart') {
+    const targets = params.targets;
+    if (targets !== 'rabbit' && targets !== 'agent' && targets !== 'all') return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'targets must be rabbit, agent or all' } };
+    if (params.wait_healthy !== undefined && typeof params.wait_healthy !== 'boolean') return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'wait_healthy must be boolean' } };
+    return { ok: true };
+  }
+  // diag: exactly the fixed, read-only package; an unknown key would be an attempt to widen it.
+  const allowedKeys = new Set(['sections']);
+  for (const key of Object.keys(params)) if (!allowedKeys.has(key)) return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'diag accepts no parameters' } };
+  if (params.sections !== undefined && !Array.isArray(params.sections)) return { ok: false, code: 'MAINTENANCE_BAD_PARAMS', detail: { reason: 'sections must be an array when present' } };
+  return { ok: true };
+}
+
+/**
+ * Verify a request. Every check is ordered cheapest-and-most-fundamental first, and every failure stops before any
+ * execution can be attempted.
+ *
+ * @param {object} request parsed JSON (untrusted)
+ * @param {{ publicKeyPem: string, expectedKeyId?: string, nowMs?: number, expectedMachineId: string,
+ *           usedRequestIds?: Set<string>, usedNonces?: Set<string>, isRevoked?: (keyId: string) => boolean }} context
+ * @returns {{ok: true, request: object} | {ok: false, code: string, detail: object}}
+ */
+export function verifyRequest(request, context) {
+  const nowMs = Number.isInteger(context?.nowMs) ? context.nowMs : Date.now();
+  const fail = (code, message, detail = {}) => ({ ok: false, code, detail: { message, ...detail } });
+
+  if (request === null || typeof request !== 'object' || Array.isArray(request)) return fail('MAINTENANCE_BAD_SHAPE', 'request must be a JSON object');
+  if (requestBytes(request) > MAX_REQUEST_BYTES) return fail('MAINTENANCE_TOO_LARGE', `request exceeds ${MAX_REQUEST_BYTES} bytes`);
+  if (request.protocol !== MAINTENANCE_PROTOCOL) return fail('MAINTENANCE_UNSUPPORTED_VERSION', 'unknown maintenance protocol', { got: String(request.protocol) });
+  if (typeof request.request_id !== 'string' || !REQUEST_ID.test(request.request_id)) return fail('MAINTENANCE_BAD_SHAPE', 'request_id is malformed');
+  if (typeof request.nonce !== 'string' || !NONCE.test(request.nonce)) return fail('MAINTENANCE_BAD_SHAPE', 'nonce is malformed');
+  if (typeof request.machine_id !== 'string' || request.machine_id === '') return fail('MAINTENANCE_BAD_SHAPE', 'machine_id is required');
+  if (!MAINTENANCE_ACTIONS.includes(request.action)) return fail('MAINTENANCE_BAD_ACTION', 'action is not one of update/restart/diag', { got: String(request.action) });
+  const params = validateParams(request.action, request.params);
+  if (params.ok !== true) return fail(params.code, 'action parameters are invalid', params.detail);
+
+  const signature = request.signature;
+  if (signature === null || typeof signature !== 'object' || signature.alg !== 'ed25519' || typeof signature.value_base64 !== 'string' || typeof signature.key_id !== 'string') {
+    return fail('MAINTENANCE_MISSING_SIGNATURE', 'request carries no usable ed25519 signature');
+  }
+  if (!KEY_ID.test(signature.key_id)) return fail('MAINTENANCE_BAD_SHAPE', 'key_id is malformed');
+  if (context?.expectedKeyId !== undefined && signature.key_id !== context.expectedKeyId) {
+    return fail('MAINTENANCE_UNKNOWN_KEY', 'request was signed by a key this machine has not pinned', { key_id: signature.key_id, pinned: context.expectedKeyId });
+  }
+  if (typeof context?.isRevoked === 'function' && context.isRevoked(signature.key_id) === true) {
+    return fail('MAINTENANCE_REVOKED', 'signing key has been revoked', { key_id: signature.key_id });
+  }
+
+  let publicKey;
+  try {
+    publicKey = createPublicKey(context?.publicKeyPem ?? '');
+  } catch {
+    return fail('MAINTENANCE_UNKNOWN_KEY', 'no usable operator public key is configured');
+  }
+  let signatureOk = false;
+  try {
+    signatureOk = verifyBytes(null, Buffer.from(signingPayload(request), 'utf8'), publicKey, Buffer.from(signature.value_base64, 'base64'));
+  } catch {
+    signatureOk = false;
+  }
+  if (signatureOk !== true) return fail('MAINTENANCE_BAD_SIGNATURE', 'signature does not cover this request');
+
+  if (typeof request.machine_id !== 'string' || typeof context?.expectedMachineId !== 'string') return fail('MAINTENANCE_BAD_SHAPE', 'machine binding is missing');
+  if (request.machine_id !== context.expectedMachineId) return fail('MAINTENANCE_WRONG_MACHINE', 'request targets another machine', { request: request.machine_id, local: context.expectedMachineId });
+
+  const issuedAt = Date.parse(String(request.issued_at ?? ''));
+  const expiresAt = Date.parse(String(request.expires_at ?? ''));
+  if (!Number.isFinite(issuedAt) || !Number.isFinite(expiresAt)) return fail('MAINTENANCE_BAD_SHAPE', 'issued_at/expires_at must be RFC3339 timestamps');
+  if (expiresAt <= issuedAt) return fail('MAINTENANCE_BAD_SHAPE', 'expires_at must be after issued_at');
+  if (expiresAt - issuedAt > MAX_TTL_MS) return fail('MAINTENANCE_TTL_TOO_LONG', 'request lives longer than the maximum TTL', { ttl_ms: expiresAt - issuedAt, max_ttl_ms: MAX_TTL_MS });
+  if (issuedAt > nowMs + CLOCK_SKEW_MS) return fail('MAINTENANCE_FUTURE', 'request is not valid yet', { issued_at: request.issued_at });
+  if (nowMs > expiresAt) return fail('MAINTENANCE_EXPIRED', 'request has expired', { expires_at: request.expires_at });
+
+  if (context?.usedRequestIds instanceof Set && context.usedRequestIds.has(request.request_id)) {
+    return fail('MAINTENANCE_REPLAY', 'request_id was already executed', { request_id: request.request_id });
+  }
+  if (context?.usedNonces instanceof Set && context.usedNonces.has(request.nonce)) {
+    return fail('MAINTENANCE_REPLAY', 'nonce was already used', { nonce: request.nonce });
+  }
+
+  return { ok: true, request };
+}

package/src/maintenance/runner.mjs

@@ -0,0 +1,189 @@
+/**
+ * The maintenance runner (v1.3.2-beta, M1).
+ *
+ * This is the only component that may execute a maintenance action. It is installed to run as root/SYSTEM by a path unit
+ * (Linux) or a scheduled task (Windows); it reads request files from a queue directory that the unprivileged agent can
+ * write to, verifies the operator signature, and writes a result file the agent can read back.
+ *
+ * Safety properties this file is responsible for:
+ *   - nothing is executed before the signature, machine binding and time window are verified;
+ *   - a request id is executed at most once (claimed via rename, and a persisted replay set);
+ *   - a result file exists for every request the runner looked at, including refusals, so the agent never waits forever;
+ *   - a corrupt request file fails that request, not the runner.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MaintenanceProtocolError, MAX_REQUEST_BYTES, verifyRequest } from './protocol.mjs';
+import { OperatorKeyError } from './operator-key.mjs';
+
+const STATE_USED_LIMIT = 500;
+
+function loadState(stateFile) {
+  if (!existsSync(stateFile)) return { protocol: 'w2m-maintenance-state/v1', used_request_ids: [], used_nonces: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(stateFile, 'utf8'));
+    return {
+      protocol: 'w2m-maintenance-state/v1',
+      used_request_ids: Array.isArray(parsed.used_request_ids) ? parsed.used_request_ids : [],
+      used_nonces: Array.isArray(parsed.used_nonces) ? parsed.used_nonces : [],
+    };
+  } catch {
+    throw new MaintenanceProtocolError('STATE_CORRUPT', 'maintenance state file is unreadable; refusing to execute anything');
+  }
+}
+
+function saveState(stateFile, state) {
+  mkdirSync(join(stateFile, '..'), { recursive: true });
+  const tmp = stateFile + '.tmp-' + process.pid;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  renameSync(tmp, stateFile);
+}
+
+function writeResult(doneDir, requestId, result) {
+  mkdirSync(doneDir, { recursive: true });
+  const target = join(doneDir, encodeURIComponent(requestId) + '.json');
+  const tmp = target + '.tmp-' + process.pid;
+  writeFileSync(tmp, JSON.stringify(result, null, 2) + '\n', 'utf8');
+  renameSync(tmp, target);
+}
+
+/**
+ * Process every request currently in the queue once. The runner is a one-shot: the path unit starts it again when new
+ * files arrive, so there is no long-lived loop to keep correct.
+ *
+ * @param {object} options
+ * @param {string} options.queueDir directory the agent writes requests to
+ * @param {string} options.doneDir directory results are written to
+ * @param {string} options.stateFile replay state (request ids + nonces already executed)
+ * @param {string} options.claimedDir directory claimed requests are moved to while executing
+ * @param {string} options.machineId this machine's id
+ * @param {() => {pinned: {key_id: string, public_key_pem: string} | null, isRevoked: (keyId: string) => boolean}} options.pinStore
+ * @param {(action: string, params: object, request: object) => Promise<{status: string, code?: string, detail?: object}>} options.executeAction
+ * @param {() => number} options.now
+ * @param {(level: string, message: string, detail?: object) => void} [options.log]
+ */
+export async function runOnce(options) {
+  const {
+    queueDir,
+    doneDir,
+    stateFile,
+    claimedDir,
+    machineId,
+    pinStore,
+    executeAction,
+    now = () => Date.now(),
+    log = () => {},
+  } = options;
+  mkdirSync(claimedDir, { recursive: true });
+  const state = loadState(stateFile);
+  const usedRequestIds = new Set(state.used_request_ids);
+  const usedNonces = new Set(state.used_nonces);
+  const processed = [];
+
+  let entries;
+  try {
+    entries = readdirSync(queueDir).filter((name) => name.endsWith('.json')).sort();
+  } catch {
+    return { ok: true, processed };
+  }
+
+  for (const name of entries) {
+    const source = join(queueDir, name);
+    let request;
+    let raw;
+    try {
+      raw = readFileSync(source);
+    } catch {
+      continue;
+    }
+    const claimPath = join(claimedDir, name);
+    const finish = (result) => {
+      writeResult(doneDir, result.request_id ?? name.replace(/\.json$/, ''), result);
+      try { rmSync(claimPath, { force: true }); } catch { /* claimed file is best effort */ }
+      try { rmSync(source, { force: true }); } catch { /* the request is already claimed */ }
+      processed.push(result);
+    };
+    if (raw.byteLength > MAX_REQUEST_BYTES) {
+      finish({ protocol: 'w2m-maintenance-result/v1', request_id: name, status: 'failed', code: 'MAINTENANCE_TOO_LARGE', machine_id: machineId, ended_at: new Date(now()).toISOString() });
+      continue;
+    }
+    try {
+      request = JSON.parse(raw.toString('utf8'));
+    } catch {
+      finish({ protocol: 'w2m-maintenance-result/v1', request_id: name, status: 'failed', code: 'MAINTENANCE_BAD_SHAPE', detail: { message: 'request is not valid JSON' }, machine_id: machineId, ended_at: new Date(now()).toISOString() });
+      continue;
+    }
+
+    // Claim before any verification side effects: two runners must not both execute the same file.
+    try {
+      renameSync(source, claimPath);
+    } catch {
+      continue;
+    }
+
+    const alreadyDone = typeof request?.request_id === 'string' && existsSync(join(doneDir, encodeURIComponent(request.request_id) + '.json'));
+    if (alreadyDone) {
+      try { rmSync(claimPath, { force: true }); } catch { /* ignore */ }
+      log('info', 'maintenance request already executed; returning the existing result', { request_id: request.request_id });
+      continue;
+    }
+
+    let pins;
+    try {
+      pins = pinStore.load();
+    } catch (error) {
+      finish({ protocol: 'w2m-maintenance-result/v1', request_id: String(request?.request_id ?? name), status: 'failed', code: error instanceof OperatorKeyError ? error.code : 'PINS_CORRUPT', detail: { message: error?.message ?? 'pin store unreadable' }, machine_id: machineId, ended_at: new Date(now()).toISOString() });
+      continue;
+    }
+    if (pins.pinned === null) {
+      finish({ protocol: 'w2m-maintenance-result/v1', request_id: String(request?.request_id ?? name), status: 'failed', code: 'MAINTENANCE_NO_PINNED_KEY', detail: { message: 'no operator key is pinned yet; refusing every maintenance request' }, machine_id: machineId, ended_at: new Date(now()).toISOString() });
+      continue;
+    }
+
+    const verified = verifyRequest(request, {
+      publicKeyPem: pins.pinned.public_key_pem,
+      expectedKeyId: pins.pinned.key_id,
+      expectedMachineId: machineId,
+      nowMs: now(),
+      usedRequestIds,
+      usedNonces,
+      isRevoked: pins.isRevoked,
+    });
+    if (verified.ok !== true) {
+      finish({ protocol: 'w2m-maintenance-result/v1', request_id: String(request?.request_id ?? name), action: request?.action ?? null, status: 'failed', code: verified.code, detail: verified.detail, machine_id: machineId, ended_at: new Date(now()).toISOString() });
+      continue;
+    }
+
+    const startedAt = new Date(now()).toISOString();
+    let outcome;
+    try {
+      outcome = await executeAction(request.action, request.params, request);
+    } catch (error) {
+      outcome = { status: 'failed', code: 'MAINTENANCE_ACTION_FAILED', detail: { message: error?.message ?? String(error) } };
+    }
+    const result = {
+      protocol: 'w2m-maintenance-result/v1',
+      request_id: request.request_id,
+      action: request.action,
+      status: outcome?.status === 'ok' ? 'ok' : 'failed',
+      code: outcome?.status === 'ok' ? null : (outcome?.code ?? 'MAINTENANCE_ACTION_FAILED'),
+      detail: outcome?.detail ?? null,
+      machine_id: machineId,
+      started_at: startedAt,
+      ended_at: new Date(now()).toISOString(),
+    };
+    finish(result);
+    state.used_request_ids.push(request.request_id);
+    state.used_nonces.push(request.nonce);
+    while (state.used_request_ids.length > STATE_USED_LIMIT) state.used_request_ids.shift();
+    while (state.used_nonces.length > STATE_USED_LIMIT) state.used_nonces.shift();
+    usedRequestIds.add(request.request_id);
+    usedNonces.add(request.nonce);
+    try { saveState(stateFile, state); } catch (error) {
+      log('warn', 'maintenance state could not be persisted; a replay would not be detected', { error: error?.message });
+    }
+    log('info', 'maintenance request executed', { request_id: request.request_id, action: request.action, status: result.status });
+  }
+
+  return { ok: true, processed };
+}

package/src/plugin/tools.mjs

@@ -274,7 +274,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.3.1';
+const PLUGIN_VERSION = '1.3.11';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;