@twinsearth/w2m-dsh-plugin 1.2.3 → 1.2.6

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