@twinsearth/w2m-dsh-plugin 1.2.5 → 1.2.6

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 };
+}