@twinsearth/w2m-dsh-plugin 1.2.5 → 1.2.7

package/src/relay/state.mjs

@@ -11,7 +11,7 @@
  * there is intentionally no snapshot/serialization hook yet.
  */
 
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes , verify as verifyBytes } from 'node:crypto';
 
 // v0.7.7: fleet scoping. Imported rather than inlined so the rule has one home with its own
 // exhaustive tests — three lines inside this object would be untestable without a live relay.
@@ -23,7 +23,8 @@ import { scopeFleetId } from '../chatops/fleet-wiring.mjs';
 // v0.8.1: the account-derived fleet key, so a machine can join with no pairing code.
 import { planJoin } from '../chatops/fleet-join.mjs';
 import { validateTaskDependencies } from './task-deps.mjs';
-import { buildMembers, setMemberRole as applyMemberRole } from './fleet-members.mjs';
+import { buildMembers, isMemberRole, setMemberRole as applyMemberRole } from './fleet-members.mjs';
+import { canonicalSignedPayload, publicKeyFromBase64 } from '../util/envelope-signature.mjs';
 
 export const PROTOCOL_VERSION = 1;
 
@@ -733,6 +734,9 @@ export class RabbitState {
           created_at_ms: Number.isFinite(createdAt) ? createdAt : this.nowMs(),
           command_hash: t.command_hash ?? null,
           attempt: t.attempt ?? 1,
+          // v1.2.7: a revived task keeps its graph edges and assignment, or the scheduler silently becomes a different scheduler.
+          depends_on: Array.isArray(t.depends_on) ? t.depends_on : [],
+          assignee: typeof t.assignee === 'string' && t.assignee !== '' ? t.assignee : null,
           leases: new Map(),
           cancelled: false,
           cancel_reason: null,
@@ -750,6 +754,16 @@ export class RabbitState {
         this.tasks.set(task.task_id, task);
         return true;
       }
+      case 'member.role': {
+        /**
+         * v1.2.6: a role survives a restart. The ledger entry already existed (setMemberRole writes it); replaying it here is
+         * what stops "the relay restarted" from silently demoting every owner to the default worker.
+         */
+        if (typeof entry.machine_id !== 'string' || entry.machine_id === '') return false;
+        if (isMemberRole(entry.role) !== true) return false;
+        this.roles.set(entry.machine_id, entry.role);
+        return false;
+      }
       case 'lease.changed': {
         const task = this.tasks.get(entry.task_id);
         const lease = task?.leases.get(entry.machine_id);
@@ -1906,6 +1920,31 @@ export class RabbitState {
     if (typeof dedupeKeyBase !== 'string' || dedupeKeyBase.length !== 64) {
       throw new ProtocolError('INTERNAL', 'failed to compute dedupe_key');
     }
+    /**
+     * v1.2.7: a dependency that is not settled means this task is NOT dispatched yet. Its leases are recorded as `waiting`,
+     * which the sweeper ignores and redelivery skips, and `_releaseDependents` moves them to offers when the graph allows it.
+     */
+    const dependencyStates = (task.depends_on ?? []).map((depId) => {
+      const dep = this.tasks.get(depId);
+      if (dep === undefined) return 'unknown';
+      if (dep.cancelled === true) return 'cancelled';
+      return this._taskSettled(dep) === true ? 'completed' : 'waiting';
+    });
+    const graphBlocked = dependencyStates.some((state) => state === 'cancelled' || state === 'unknown');
+    const graphReady = graphBlocked !== true && dependencyStates.every((state) => state === 'completed');
+    const waitingOn = graphReady === true ? [] : (task.depends_on ?? []);
+    /**
+     * v1.2.7: an assignee is a restriction, not a label. Only that machine gets a lease; another machine cannot accidentally
+     * take work that was meant for one host. An unknown assignee is refused by name rather than producing a task nobody holds.
+     */
+    if (task.assignee !== null && !this.devices.has(task.assignee)) {
+      throw new ProtocolError('BAD_REQUEST', 'assignee is not a known device on this relay', { assignee: task.assignee });
+    }
+    if (task.assignee !== null) {
+      const narrowed = targets.filter((device) => device.machine_id === task.assignee);
+      targets.length = 0;
+      targets.push(...narrowed);
+    }
     let lastSeq = this.seq;
     targets.forEach((device, i) => {
       const index = mode === 'replicate' ? 0 : i % indexTotal;
@@ -1939,6 +1978,12 @@ export class RabbitState {
         task.leases.set(device.machine_id, lease);
         return;
       }
+      if (graphReady !== true) {
+        lease.state = 'waiting';
+        lease.waiting_on = waitingOn;
+        task.leases.set(device.machine_id, lease);
+        return;
+      }
       const gate = gateMachine(task, device);
       if (gate) {
         lease.state = 'refused';
@@ -1991,6 +2036,9 @@ export class RabbitState {
         attempt: task.attempt,
         deadline_ms: task.deadline_ms,
         // v0.4.0: routing metadata, so a restarted relay re-offers with the same facts.
+            // v1.2.7: the dependency graph and assignment belong to the task record, not to a reader's memory of it.
+            depends_on: Array.isArray(task.depends_on) ? task.depends_on : [],
+            assignee: task.assignee ?? null,
         origin_machine_id: task.origin_machine_id ?? null,
         p2p: task.p2p ?? null,
       },
@@ -2200,6 +2248,47 @@ export class RabbitState {
       .map((t) => this.taskSummary(t));
   }
 
+  /** v1.2.7: a task is settled when no lease can still produce a result. Dependencies wait for that, not for a wording. */
+  _taskSettled(task) {
+    for (const lease of task.leases.values()) if (ACTIVE_LEASE_STATES.includes(lease.state)) return false;
+    return true;
+  }
+
+  /**
+   * v1.2.7: release tasks whose prerequisites are all settled.
+   *
+   * Called after a result is stored: a dependency that finished must actually move its dependents from `waiting` to an offer.
+   * Without this the graph would be validated, stored, and then never scheduled -- the exact "validated but not enforced" gap.
+   */
+  _releaseDependents(completedTaskId = null) {
+    const released = [];
+    for (const candidate of this.tasks.values()) {
+      if (!Array.isArray(candidate.depends_on) || candidate.depends_on.length === 0) continue;
+      if (completedTaskId !== null && !candidate.depends_on.includes(completedTaskId)) continue;
+      const waiting = [...candidate.leases.values()].filter((lease) => lease.state === 'waiting');
+      if (waiting.length === 0) continue;
+      let ready = true;
+      for (const depId of candidate.depends_on) {
+        const dep = this.tasks.get(depId);
+        if (dep === undefined) { ready = false; break; }
+        if (dep.cancelled === true) { ready = false; break; }
+        if (this._taskSettled(dep) !== true) { ready = false; break; }
+      }
+      if (ready !== true) continue;
+      for (const lease of waiting) {
+        lease.state = 'queued';
+        lease.claimed_at_ms = this.nowMs();
+        lease.lease_until_ms = this.nowMs() + this.leaseWindowMs();
+        const device = this.devices.get(lease.machine_id);
+        if (device === undefined) continue;
+        this.emitOffer(candidate, lease);
+      }
+      this.emit('notice', { level: 'info', code: 'TASK_READY', message: candidate.task_id + ' is ready: dependencies settled', task_id: candidate.task_id });
+      released.push(candidate.task_id);
+    }
+    return released;
+  }
+
   taskSummary(task) {
     return {
       task_id: task.task_id,
@@ -2211,9 +2300,32 @@ export class RabbitState {
       degraded: task.degraded,
       leases: [...task.leases.values()].map((l) => l.machine_id),
       lease_states: Object.fromEntries([...task.leases.values()].map((l) => [l.machine_id, l.state])),
+      /**
+       * v1.2.7: the state the scheduler is actually in, derived here rather than by each reader.
+       *
+       * Before this, GET /v1/tasks carried no status at all, so a board classified a waiting task as "ready" (its dependencies
+       * map empty) and a released task as "waiting" forever. The board must read the scheduler's own words or it is decoration.
+       */
+      status: (() => {
+        if (task.cancelled === true) return 'cancelled';
+        const leases = [...task.leases.values()];
+        if (leases.some((lease) => lease.state === 'waiting')) return 'waiting';
+        if (leases.some((lease) => ACTIVE_LEASE_STATES.includes(lease.state))) return 'active';
+        const results = [...this.results.values()].filter((record) => record?.envelope?.task_id === task.task_id);
+        if (results.length > 0 && results.every((record) => ['failed', 'crashed', 'refused', 'timeout'].includes(record?.envelope?.status))) return 'failed';
+        return this._taskSettled(task) === true ? 'done' : 'unknown';
+      })(),
+      depends_on: Array.isArray(task.depends_on) ? task.depends_on : [],
+      assignee: task.assignee ?? null,
+      waiting_on: [...task.leases.values()].some((l) => l.state === 'waiting') ? (Array.isArray(task.depends_on) ? task.depends_on : []) : [],
     };
   }
 
+  /** v1.2.6: the role this machine holds, for the permission matrix. Unknown means worker, never owner. */
+  roleOf(machineId) {
+    return typeof machineId === 'string' ? (this.roles.get(machineId) ?? null) : null;
+  }
+
   /** v1.2.5: the fleet's members, with the role each holds and when it joined. */
   listMembers() {
     return buildMembers({ devices: this.devices, roles: this.roles });
@@ -2434,6 +2546,9 @@ export class RabbitState {
       }
       if (changed) task.degraded = 'partial';
     }
+    // v1.2.7: a lease that expires (or a machine that refuses) is a settlement too -- the dependent graph must move.
+    this._releaseDependents();
+
     return expired;
   }
 
@@ -2631,6 +2746,42 @@ export class RabbitState {
       return { deduped: true, task_id: taskId, dedupe_key: dedupeKey, seq: prior.seq };
     }
 
+    /**
+     * v1.2.6: verify the envelope signature against the key this machine registered WHEN IT PAIRED.
+     *
+     * This is the difference between "the result matches the key it carries" and "the key belongs to this machine". The relay is
+     * the place that can answer the second question, because pairing is the moment the operator (or the account) let the machine
+     * in, and that is the only moment its signing key has a reason to be believed. A signature whose key differs from the
+     * registered one is bad_signature even when it verifies against itself.
+     */
+    let signatureStatus = 'unsigned';
+    const signature = envelope.signature ?? null;
+    if (signature !== null) {
+      signatureStatus = 'bad_signature';
+      if (signature.alg !== 'ed25519') {
+        signatureStatus = 'unsupported_algorithm';
+      } else {
+        const registeredKey = machineId === null ? null : (typeof this.devices.get(machineId)?.public_key === 'string' ? this.devices.get(machineId).public_key : null);
+        if (registeredKey === null) {
+          signatureStatus = 'unbound';
+        } else if (signature.public_key !== registeredKey) {
+          signatureStatus = 'bad_signature';
+        } else {
+          const key = publicKeyFromBase64(registeredKey);
+          const payload = canonicalSignedPayload({
+            task_id: envelope.task_id,
+            argv_hash: envelope.command_hash,
+            machine_id: envelope.machine_id,
+            ts: signature.ts,
+          });
+          try {
+            signatureStatus = key !== null && verifyBytes(null, Buffer.from(payload, 'utf8'), key, Buffer.from(String(signature.value ?? ''), 'base64'))
+              ? 'signed' : 'bad_signature';
+          } catch { signatureStatus = 'bad_signature'; }
+        }
+      }
+    }
+
     const now = this.nowMs();
     let envelopeShaOk = null;
     if (typeof envelope.envelope_sha256 === 'string') {
@@ -2649,6 +2800,7 @@ export class RabbitState {
         missing: [...new Set(missing)],
         problems,
         envelope_sha256_ok: envelopeShaOk,
+        signature_status: signatureStatus,
       },
     };
 
@@ -2685,6 +2837,9 @@ export class RabbitState {
     });
 
     // §7: results go into the ledger so the dedupe index survives a restart.
+    // v1.2.7: a settled task may be the prerequisite that frees its dependents.
+    this._releaseDependents(taskId);
+
     this._ledger({ type: 'result.stored', task_id: taskId, machine_id: machineId, result: record });
     if (machineId) {
       const changed = task.leases.get(machineId);

package/src/util/chat-crypto.mjs

@@ -0,0 +1,98 @@
+/**
+ * The fleet chat's end-to-end encryption.
+ *
+ * ## Why the relay never sees the key
+ *
+ * The group key is HKDF over the fleet key, and the fleet key is derived from the account identity on each machine -- it never
+ * travels to the relay. So the relay stores ciphertext it cannot open, and the honest consequence is written down rather than
+ * discovered later: the relay cannot search message content, and the quota it enforces is measured on ciphertext length.
+ *
+ * ## Why the metadata is next to the ciphertext, not inside it
+ *
+ * `{v, alg, iv, tag}` has to be readable by every client of every version, including one that cannot decrypt. Keeping it in a
+ * plain field means a reader can say "encrypted with aes-256-gcm, version 1" even when it has no key, instead of guessing from
+ * random-looking text.
+ *
+ * ## Backward compatibility, both directions
+ *
+ * A message with no `enc` field is plaintext and stays readable. A reader with no key keeps the ciphertext and marks it
+ * `encrypted: true` rather than throwing: an unreadable message must not break a whole page.
+ */
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto';
+
+export const CHAT_CIPHER = Object.freeze({ version: 1, alg: 'aes-256-gcm' });
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+
+/**
+ * Turn the fleet key into the chat group key. Deterministic: every machine in the fleet derives the same key from the same
+ * fleet key, which is what makes a message encrypted on one machine readable on another.
+ *
+ * @param {string} fleetKey base64 (the usual shape) or a passphrase
+ * @returns {Buffer|null}
+ */
+export function deriveChatKey(fleetKey) {
+  if (typeof fleetKey !== 'string' || fleetKey.trim() === '') return null;
+  try {
+    let material = null;
+    try {
+      const decoded = Buffer.from(fleetKey.trim(), 'base64');
+      material = decoded.length >= 16 ? decoded : Buffer.from(fleetKey.trim(), 'utf8');
+    } catch {
+      material = Buffer.from(fleetKey.trim(), 'utf8');
+    }
+    return Buffer.from(hkdfSync('sha256', material, Buffer.from('w2m-fleet-chat-salt'), Buffer.from('fleet-chat-v1'), KEY_BYTES));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Buffer|null} key
+ * @param {string} text
+ * @returns {{ok: true, text: string, enc: {v: number, alg: string, iv: string, tag: string}} | {ok: false, code: string}}
+ */
+export function encryptChatText(key, text) {
+  if (key === null || !Buffer.isBuffer(key) || key.length !== KEY_BYTES) return { ok: false, code: 'CHAT_NO_KEY' };
+  if (typeof text !== 'string' || text === '') return { ok: false, code: 'CHAT_EMPTY_TEXT' };
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const ciphertext = Buffer.concat([cipher.update(Buffer.from(text, 'utf8')), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return {
+    ok: true,
+    text: ciphertext.toString('base64'),
+    enc: { v: CHAT_CIPHER.version, alg: CHAT_CIPHER.alg, iv: iv.toString('base64'), tag: tag.toString('base64') },
+  };
+}
+
+/**
+ * @param {Buffer|null} key
+ * @param {{text?: string, enc?: object|null}} message
+ * @returns {{ok: true, text: string} | {ok: false, code: string}}
+ */
+export function decryptChatMessage(key, message = {}) {
+  const enc = message?.enc ?? null;
+  if (enc === null || enc === undefined) {
+    // Plaintext: the pre-encryption shape, still readable by everyone.
+    return typeof message?.text === 'string' ? { ok: true, text: message.text } : { ok: false, code: 'CHAT_TEXT_MISSING' };
+  }
+  if (key === null || !Buffer.isBuffer(key) || key.length !== KEY_BYTES) return { ok: false, code: 'CHAT_NO_KEY' };
+  if (enc.alg !== CHAT_CIPHER.alg || enc.v !== CHAT_CIPHER.version) return { ok: false, code: 'CHAT_UNSUPPORTED_CIPHER' };
+  try {
+    const iv = Buffer.from(String(enc.iv ?? ''), 'base64');
+    const tag = Buffer.from(String(enc.tag ?? ''), 'base64');
+    if (iv.length !== IV_BYTES || tag.length !== 16) return { ok: false, code: 'CHAT_BAD_ENCRYPTION' };
+    const decipher = createDecipheriv('aes-256-gcm', key, iv);
+    decipher.setAuthTag(tag);
+    const plain = Buffer.concat([decipher.update(Buffer.from(String(message.text ?? ''), 'base64')), decipher.final()]);
+    return { ok: true, text: plain.toString('utf8') };
+  } catch {
+    return { ok: false, code: 'CHAT_DECRYPT_FAILED' };
+  }
+}
+
+/** True when a message carries the encryption metadata, whatever its text looks like. */
+export function isEncrypted(message) {
+  return message?.enc !== null && message?.enc !== undefined && typeof message.enc === 'object';
+}

package/src/util/dataflow.mjs

@@ -41,7 +41,8 @@ const SHA256 = /^[0-9a-f]{64}$/;
  * A missing or malformed hash is refused by name -- the reduce step must never run on a partial fleet and call the answer
  * complete.
  *
- * @param {{results?: Array<{machine_id?: string, mode?: string, stdout?: string, blob_sha256?: string}>,
+ * @param {{results?: Array<{machine_id?: string, mode?: string, stdout?: string, blob_sha256?: string, index?: number}>,
+ *          expectedIndexTotal?: number|null,
  *          reducerMachineId?: string}} input
  * @returns {{ok: true, reducerMachineId: string, inputs: Array<{machine_id: string, mode: 'inline'|'blob', stdout?: string, sha256?: string}>} |
  *           {ok: false, code: string, detail: object}}
@@ -51,6 +52,15 @@ export function buildReducePlan(input = {}) {
   if (reducer === null) return { ok: false, code: 'REDUCER_MISSING', detail: {} };
   const results = Array.isArray(input.results) ? input.results : null;
   if (results === null || results.length === 0) return { ok: false, code: 'NO_MAP_RESULTS', detail: {} };
+  /**
+   * v1.2.7: what the task SAID would be produced, not just what arrived.
+   *
+   * Without an expected count the plan can only describe the reports it was handed, so a split run where one shard never
+   * reported produced a plan that looked complete. The count comes from the task (index_total); a missing index is refused
+   * by name before the reduce step can run on a partial fleet.
+   */
+  const expectedTotal = Number.isInteger(input.expectedIndexTotal) && input.expectedIndexTotal > 0 ? input.expectedIndexTotal : null;
+  const seenIndexes = new Set();
 
   const seen = new Set();
   const inputs = [];
@@ -59,6 +69,14 @@ export function buildReducePlan(input = {}) {
     if (machineId === null) return { ok: false, code: 'MAP_MACHINE_MISSING', detail: {} };
     if (seen.has(machineId)) return { ok: false, code: 'MAP_MACHINE_DUPLICATE', detail: { machineId } };
     seen.add(machineId);
+    if (expectedTotal !== null) {
+      const index = Number.isInteger(result?.index) ? result.index : null;
+      if (index === null) return { ok: false, code: 'MAP_INDEX_MISSING', detail: { machineId } };
+      if (index < 0 || index >= expectedTotal) {
+        return { ok: false, code: 'MAP_INDEX_OUT_OF_RANGE', detail: { machineId, index, expectedIndexTotal: expectedTotal } };
+      }
+      seenIndexes.add(index);
+    }
     const mode = result?.mode === 'blob' ? 'blob' : 'inline';
     if (mode === 'blob') {
       const sha = typeof result?.blob_sha256 === 'string' ? result.blob_sha256.toLowerCase() : '';
@@ -68,5 +86,10 @@ export function buildReducePlan(input = {}) {
       inputs.push({ machine_id: machineId, mode, stdout: typeof result?.stdout === 'string' ? result.stdout : '' });
     }
   }
+  if (expectedTotal !== null) {
+    const missing = [];
+    for (let index = 0; index < expectedTotal; index += 1) if (!seenIndexes.has(index)) missing.push(index);
+    if (missing.length > 0) return { ok: false, code: 'MISSING_SHARD', detail: { missing, expectedIndexTotal: expectedTotal } };
+  }
   return { ok: true, reducerMachineId: reducer, inputs };
 }

package/src/util/envelope-signature.mjs

@@ -0,0 +1,69 @@
+/**
+ * Envelope signatures: what a machine signed, and how a reader checks it.
+ *
+ * ## Why the payload is exactly four fields
+ *
+ * A signature over "the whole envelope" is impossible to verify reproducibly: the envelope carries hashes, timestamps and
+ * transport facts that change between the signing machine and the reader. So the machine signs the four facts that identify
+ * THE COMMAND: task id, argv hash (the envelope's command_hash), machine id, and when it signed. Everything else in the
+ * envelope is covered indirectly through those, and a reader verifies exactly this tuple.
+ *
+ * ## Why verification returns a status rather than throwing
+ *
+ * "unsigned" is not an error -- a machine running an older build, or one configured without a device key, is a fact to report.
+ * "bad_signature" is the interesting case: the data does not match the signature, which is exactly what tampering looks like.
+ * A caller must see the difference, so both are values.
+ */
+import { createPublicKey, verify } from 'node:crypto';
+
+/** The DER prefix for an Ed25519 SubjectPublicKeyInfo; the 32 raw key bytes follow. */
+const ED25519_SPKI_PREFIX = Buffer.from('302a300506032b6570032100', 'hex');
+
+/**
+ * The canonical bytes a machine signs. Sorted keys, no whitespace, so the same tuple always produces the same bytes.
+ *
+ * @param {{task_id: string, argv_hash: string, machine_id: string, ts: string}} input
+ * @returns {string}
+ */
+export function canonicalSignedPayload({ task_id: taskId, argv_hash: argvHash, machine_id: machineId, ts }) {
+  return JSON.stringify({
+    argv_hash: String(argvHash ?? ''),
+    machine_id: String(machineId ?? ''),
+    task_id: String(taskId ?? ''),
+    ts: String(ts ?? ''),
+  });
+}
+
+/**
+ * @param {string|null} publicKeyBase64
+ * @returns {import('node:crypto').KeyObject|null}
+ */
+export function publicKeyFromBase64(publicKeyBase64) {
+  if (typeof publicKeyBase64 !== 'string' || publicKeyBase64 === '') return null;
+  try {
+    const raw = Buffer.from(publicKeyBase64, 'base64');
+    if (raw.length !== 32) return null;
+    return createPublicKey({ key: Buffer.concat([ED25519_SPKI_PREFIX, raw]), format: 'der', type: 'spki' });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{signature?: object|null, task_id?: string, argv_hash?: string, machine_id?: string, ts?: string}} input
+ * @returns {'signed'|'unsigned'|'bad_signature'|'unsupported_algorithm'}
+ */
+export function verifyEnvelopeSignature({ signature = null, task_id: taskId, argv_hash: argvHash, machine_id: machineId, ts } = {}) {
+  if (signature === null || signature === undefined || typeof signature !== 'object') return 'unsigned';
+  if (signature.alg !== 'ed25519') return 'unsupported_algorithm';
+  if (typeof signature.value !== 'string' || signature.value === '') return 'bad_signature';
+  const key = publicKeyFromBase64(signature.public_key);
+  if (key === null) return 'bad_signature';
+  const payload = canonicalSignedPayload({ task_id: taskId, argv_hash: argvHash, machine_id: machineId, ts: signature.ts ?? ts });
+  try {
+    const ok = verify(null, Buffer.from(payload, 'utf8'), key, Buffer.from(signature.value, 'base64'));
+    return ok ? 'signed' : 'bad_signature';
+  } catch {
+    return 'bad_signature';
+  }
+}

package/src/util/policy-matrix.mjs

@@ -0,0 +1,65 @@
+/**
+ * The permission matrix: which fleet role may perform which action.
+ *
+ * ## Why a table, and why refusals are named
+ *
+ * A role check scattered across call sites drifts: one route checks, another forgets, and the matrix exists only in a document.
+ * This table is the single answer, and a refusal always names the action, the role required and the role held -- an
+ * "access denied" without those three facts is a support ticket, not a diagnostic.
+ *
+ * ## Why the levels are ordinal
+ *
+ * Roles form an order (observer < worker < owner). Stating a minimum level rather than enumerating every allowed role means a
+ * new role slots in between two existing ones without rewriting every action.
+ */
+export const FLEET_ACTIONS = Object.freeze(['read_private', 'vote', 'join', 'dispatch', 'approve', 'manage_members']);
+
+/** Lower number = fewer rights. */
+export const ROLE_LEVEL = Object.freeze({ observer: 0, worker: 1, owner: 2 });
+
+/** The minimum level an action needs. `manage_members` is owner-only; approving is owner-only for the same reason. */
+export const ACTION_MIN_LEVEL = Object.freeze({
+  read_private: 0,
+  vote: 1,
+  join: 1,
+  dispatch: 1,
+  approve: 2,
+  manage_members: 2,
+});
+
+/** The role a level maps back to, for a refusal that says which role would have been enough. */
+export function roleForLevel(level) {
+  const best = Object.entries(ROLE_LEVEL).filter(([, value]) => value === level)[0];
+  return best === undefined ? null : best[0];
+}
+
+/**
+ * @param {{role?: string|null, action: string}} input
+ * @returns {{ok: true, action: string, role: string}} | {ok: false, code: 'FORBIDDEN_ACTION', action: string, required_level: number, current_level: number, required_role: string|null, current_role: string}}
+ */
+export function can({ role = null, action } = {}) {
+  const currentRole = typeof role === 'string' && role in ROLE_LEVEL ? role : 'worker'; // unknown device = worker, never owner
+  if (!FLEET_ACTIONS.includes(action)) {
+    return {
+      ok: false, code: 'FORBIDDEN_ACTION', action, required_level: null, current_level: ROLE_LEVEL[currentRole],
+      required_role: null, current_role: currentRole,
+    };
+  }
+  const requiredLevel = ACTION_MIN_LEVEL[action];
+  const currentLevel = ROLE_LEVEL[currentRole];
+  if (currentLevel >= requiredLevel) return { ok: true, action, role: currentRole };
+  return {
+    ok: false,
+    code: 'FORBIDDEN_ACTION',
+    action,
+    required_level: requiredLevel,
+    current_level: currentLevel,
+    required_role: roleForLevel(requiredLevel),
+    current_role: currentRole,
+  };
+}
+
+/** Every action with its verdict for one role -- the board an operator reads. */
+export function matrixFor(role) {
+  return FLEET_ACTIONS.map((action) => ({ action, ...can({ role, action }) }));
+}

package/src/util/redact.mjs

@@ -0,0 +1,70 @@
+/**
+ * Output redaction: secrets a command prints are replaced before they leave this machine.
+ *
+ * ## Why a replacement, not a deletion
+ *
+ * Deleting the line would keep the secret out of the envelope and also destroy the evidence: line numbers and structure are
+ * what make a failure reproducible. So each match becomes [redacted:class] in place.
+ *
+ * ## Why nothing here touches a hash
+ *
+ * stdout_sha256 and stdout_bytes cover the RAW bytes and are computed by the executor. Redacting the text must not feed back
+ * into them: the envelope's hashes stay evidence, and only the human-readable heads/tails are filtered. The same is true of
+ * blobs -- a blob's name is the hash of its bytes, and rewriting them would make the name a lie.
+ *
+ * ## Why it can be turned off
+ *
+ * An operator debugging a credential problem needs the original. Turning it off is allowed and SAYS SO (unredacted: true in the
+ * envelope), because a redaction that silently does nothing is worse than no redaction at all.
+ */
+
+/** Each rule: a class name and the pattern that finds it. Order matters only for the private-key block. */
+const RULES = Object.freeze([
+  { cls: 'private-key', pattern: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g },
+  { cls: 'api-key', pattern: /\bsk-[A-Za-z0-9_-]{16,}\b/g },
+  { cls: 'api-key', pattern: /\bnpm_[A-Za-z0-9]{20,}\b/g },
+  { cls: 'api-key', pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g },
+  { cls: 'api-key', pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g },
+  { cls: 'api-key', pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { cls: 'aws-key', pattern: /\bAKIA[0-9A-Z]{16}\b/g },
+]);
+
+/**
+ * @param {string} text
+ * @returns {{text: string, replaced: Array<{cls: string, count: number}>}}
+ */
+export function redactText(text) {
+  if (typeof text !== 'string' || text === '') return { text: typeof text === 'string' ? text : '', replaced: [] };
+  let out = text;
+  const counts = new Map();
+  for (const rule of RULES) {
+    let hits = 0;
+    out = out.replace(rule.pattern, () => { hits += 1; return '[redacted:' + rule.cls + ']'; });
+    if (hits > 0) counts.set(rule.cls, (counts.get(rule.cls) ?? 0) + hits);
+  }
+  return { text: out, replaced: [...counts.entries()].map(([cls, count]) => ({ cls, count })) };
+}
+
+/** The envelope fields that carry command output and are therefore filtered. */
+export const REDACTABLE_FIELDS = Object.freeze(['stdout_head', 'stdout_tail', 'stderr_head', 'stderr_tail']);
+
+/**
+ * @param {object} envelope
+ * @param {{enabled?: boolean}} [options]
+ * @returns {{envelope: object, redacted: Array<{field: string, cls: string, count: number}>}}
+ */
+export function redactEnvelope(envelope, { enabled = true } = {}) {
+  if (envelope === null || typeof envelope !== 'object') return { envelope, redacted: [] };
+  if (enabled !== true) return { envelope: { ...envelope, unredacted: true }, redacted: [] };
+  const next = { ...envelope };
+  const redacted = [];
+  for (const field of REDACTABLE_FIELDS) {
+    const value = next[field];
+    if (typeof value !== 'string' || value === '') continue;
+    const result = redactText(value);
+    next[field] = result.text;
+    for (const hit of result.replaced) redacted.push({ field, ...hit });
+  }
+  if (redacted.length > 0) next.redacted = redacted;
+  return { envelope: next, redacted };
+}