@cohortapp/agent-sdk 2.3.0

package/lib/comms/send-gate.mjs

@@ -0,0 +1,554 @@
+/**
+ * lib/comms/send-gate.mjs — the ONE shared outbound send-gate chokepoint.
+ *
+ * Why this exists
+ * ---------------
+ * The pre-send audit hook (scripts/hooks/pre-send-audit.sh) historically gated
+ * exactly one path: the `gmail_create_draft` tool. Every other real send path —
+ * scripts/slack-send.sh, scripts/send-whatsapp.sh, scripts/send-sms.sh,
+ * scripts/send-email.sh, the daemon responder, and BaseAdapter._send — bypassed
+ * it (gaps-product-quality P0-3). This module is the single policy layer those
+ * paths now share, so banned-phrase screening, AI-disclosure rules, information
+ * barriers, and the recipient allowlist are enforced in ONE place instead of
+ * being re-implemented (or skipped) per script.
+ *
+ * Relationship to validate_outbound.py (Layer 0)
+ * ----------------------------------------------
+ * The Python validator (relationship/title/possessive-claim checks) stays as the
+ * Layer-0 call inside each send script. send-gate is the unified POLICY layer
+ * ABOVE it: the two run in series and a block from either stops the send.
+ *
+ * Fail posture (mirrors scripts/validate_outbound semantics)
+ * ----------------------------------------------------------
+ * The house idiom is "fail-open + silence", but for outbound governance that is
+ * the wrong default for EXTERNAL recipients: an unreadable policy file must not
+ * silently open the perimeter to outsiders. So:
+ *   - external recipient + a required policy file is unreadable/malformed →
+ *     fail CLOSED (allow:false, reason explains which file).
+ *   - internal recipient + the same fault → fail OPEN (allow:true) so an
+ *     internal ops message is never blocked by a transient FS fault.
+ * A recipient is classified external unless it provably matches an internal
+ * signal (Slack/Telegram workspace ids, or an email whose domain is on the
+ * configured internal_domains list). Default-deny: unknown ⇒ external.
+ *
+ * Determinism / testability
+ * --------------------------
+ * screenOutbound is pure-ish: it reads only the policy files and never sends.
+ * The filesystem reader is injectable (`opts.fs = { readFileSync, existsSync }`)
+ * so tests drive every branch — including "unreadable policy" — without touching
+ * disk. js-yaml is loaded lazily (the package's only YAML dep), matching
+ * lib/learning/config.mjs and lib/collective/config.mjs.
+ *
+ * CLI form (consumed by the shell send scripts)
+ * ---------------------------------------------
+ *   echo "message text" | node lib/comms/send-gate.mjs \
+ *       --channel slack --recipient C0123 [--agent-root /path]
+ *   exit 0 → allow;  exit 1 → BLOCK (reason on stderr);  prints redactedText (if
+ *   any) on stdout. Any unexpected internal error for an EXTERNAL recipient also
+ *   exits 1 (fail closed); for an internal recipient it exits 0 (fail open).
+ *
+ * @module lib/comms/send-gate
+ */
+
+"use strict";
+
+import {
+  readFileSync as nodeReadFileSync,
+  existsSync as nodeExistsSync,
+} from "node:fs";
+import { join } from "node:path";
+
+/* ─────────────────────────── policy file locations ───────────────────────── */
+
+const POLICY = Object.freeze({
+  style: "policies/communication-style.md",
+  disclosure: "policies/ai-disclosure.yaml",
+  barriers: "policies/information-barriers.yaml",
+});
+
+/* ───────────────────────────── banned phrases ────────────────────────────── */
+// Source of truth: policies/communication-style.md §"Default tone" rule 2.
+// Kept in sync with scripts/hooks/pre-send-audit.sh BANNED_SUBSTRINGS so both
+// gates reject the same set. Matching is case-insensitive, substring-based.
+export const BANNED_SUBSTRINGS = Object.freeze([
+  "I'm here to help",
+  "I am here to help",
+  "Let me know if you need anything else",
+  "I hope this helps",
+  "Feel free to ask if you have any questions",
+  "As an AI",
+  "As a language model",
+  "I should clarify that I am",
+  "Here's a comprehensive overview of",
+  "Here is a comprehensive overview of",
+  "I'd be happy to",
+  "I would be happy to",
+]);
+
+// Opener-only fillers: legitimate mid-sentence, banned as a line/message opener.
+export const BANNED_OPENERS = Object.freeze([
+  "Certainly!",
+  "Absolutely!",
+  "Great question!",
+]);
+
+/* ────────────────────────── recipient classification ─────────────────────── */
+
+/**
+ * Decide whether a recipient is INTERNAL (workspace member / internal domain) or
+ * EXTERNAL (everyone else). Default-deny: anything unrecognised is external, so
+ * the fail-CLOSED branch covers the unknown case.
+ *
+ * @param {string} channel  slack|telegram|whatsapp|sms|email|voice|document
+ * @param {string} recipient
+ * @param {string[]} internalDomains  lower-cased email domains treated internal
+ * @returns {"internal"|"external"}
+ */
+export function classifyRecipient(channel, recipient, internalDomains = []) {
+  const r = String(recipient || "").trim();
+  if (!r) return "external"; // no recipient ⇒ treat conservatively
+
+  switch (channel) {
+    case "slack":
+    case "telegram":
+      // Slack channel/DM ids (C…, D…, G…, U…) and Telegram chat ids live inside
+      // the agent's own workspace → internal by construction. A bare email/phone
+      // passed on these channels is ambiguous, so fall through to the domain test.
+      if (/^[CDGU][A-Z0-9]{6,}$/.test(r)) return "internal"; // Slack id
+      if (/^-?\d{5,}$/.test(r)) return "internal"; // Telegram numeric chat id
+      break;
+    default:
+      break;
+  }
+
+  // Email: internal only if its domain is explicitly allow-listed as internal.
+  const at = r.lastIndexOf("@");
+  if (at > 0 && at < r.length - 1) {
+    const domain = r.slice(at + 1).toLowerCase();
+    for (const d of internalDomains) {
+      const dn = String(d || "").toLowerCase().replace(/^@/, "");
+      if (dn && (domain === dn || domain.endsWith("." + dn))) return "internal";
+    }
+    return "external";
+  }
+
+  // Phone numbers (whatsapp/sms) and everything else: external by default.
+  return "external";
+}
+
+/* ─────────────────────────────── helpers ─────────────────────────────────── */
+
+function makeFs(injected) {
+  return {
+    readFileSync: injected?.readFileSync || nodeReadFileSync,
+    existsSync: injected?.existsSync || nodeExistsSync,
+  };
+}
+
+let _yaml = null;
+async function getYaml() {
+  if (_yaml) return _yaml;
+  const mod = await import("js-yaml");
+  _yaml = mod.default || mod;
+  return _yaml;
+}
+
+/**
+ * Read a policy file. Returns { ok, text } — ok:false means unreadable/missing,
+ * which the caller maps to fail-open (internal) or fail-closed (external).
+ */
+function readPolicy(fs, agentRoot, rel) {
+  const path = join(agentRoot, rel);
+  try {
+    if (!fs.existsSync(path)) return { ok: false, text: "", path };
+    const text = fs.readFileSync(path, "utf-8");
+    return { ok: true, text, path };
+  } catch {
+    return { ok: false, text: "", path };
+  }
+}
+
+function blocked(reason, extra = {}) {
+  return { allow: false, reason, ...extra };
+}
+function allowed(extra = {}) {
+  return { allow: true, reason: "", ...extra };
+}
+
+/* ───────────────────────── individual screen layers ──────────────────────── */
+
+/**
+ * (a) Banned-phrase / AI-tell screen. Pure; no IO. Returns a block reason string
+ * or null. Sourced from policies/communication-style.md (constant above).
+ */
+export function screenBannedPhrases(text) {
+  const lc = String(text || "").toLowerCase();
+  for (const phrase of BANNED_SUBSTRINGS) {
+    if (lc.includes(phrase.toLowerCase())) {
+      return `banned AI-tell phrase "${phrase}" (policies/communication-style.md)`;
+    }
+  }
+  // Opener-only: at message start or at the start of any line.
+  for (const opener of BANNED_OPENERS) {
+    const re = new RegExp(
+      "(^|[\\r\\n])\\s*" + opener.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
+      "i",
+    );
+    if (re.test(String(text || ""))) {
+      return `banned filler opener "${opener}" (policies/communication-style.md)`;
+    }
+  }
+  return null;
+}
+
+/**
+ * (b) AI-disclosure screen. Resolves the active posture for the recipient's
+ * jurisdiction from ai-disclosure.yaml and enforces two things:
+ *   1. The non-overridable truthfulness invariant: an outbound message must
+ *      never DENY being an AI (e.g. "I am not a bot", "I'm a real person").
+ *      This holds under every posture — concealment must never become a lie.
+ *   2. Where the active posture requires proactive disclosure / a machine-
+ *      readable marking, a first-contact message that conceals it is blocked.
+ *
+ * @returns {string|null} block reason, or null if disclosure rules are satisfied
+ */
+export function screenDisclosure(text, { policy, jurisdiction, firstContact }) {
+  const lc = String(text || "").toLowerCase();
+
+  // 1. Truthfulness invariant — locked, applies under every posture. A message
+  //    that explicitly denies AI nature is never allowed to leave.
+  const denials = [
+    "i am not an ai",
+    "i'm not an ai",
+    "i am not a bot",
+    "i'm not a bot",
+    "i am a real person",
+    "i'm a real person",
+    "i am a human",
+    "i'm a human",
+    "no, i'm not a bot",
+    "no i am not a bot",
+    "i am not a robot",
+    "i'm not a robot",
+  ];
+  for (const d of denials) {
+    if (lc.includes(d)) {
+      return `AI-disclosure invariant: message denies AI nature ("${d}") — concealment may never become a lie (policies/ai-disclosure.yaml)`;
+    }
+  }
+
+  if (!policy) return null; // policy already handled upstream (fail posture)
+
+  // 2. Resolve posture for this jurisdiction (fail-safe = default_posture).
+  const postures = policy.posture || {};
+  const jurisdictions = policy.jurisdictions || {};
+  const jKey = jurisdiction && jurisdictions[jurisdiction] ? jurisdiction : "default";
+  let postureName =
+    (jurisdictions[jKey] && jurisdictions[jKey].posture) ||
+    policy.default_posture ||
+    "disclose-always";
+
+  // concealed-where-legal collapses to disclose-always unless governance signed
+  // it off for this jurisdiction (resolution.unsigned_concealed_posture).
+  if (postureName === "concealed-where-legal") {
+    const signoff = policy.governance && policy.governance.sign_off;
+    const signedJur =
+      signoff &&
+      Array.isArray(signoff.jurisdictions) &&
+      signoff.approver &&
+      signoff.jurisdictions.includes(jurisdiction);
+    if (!signedJur) postureName = "disclose-always";
+  }
+
+  const posture = postures[postureName] || {};
+
+  // Only first-contact messages carry the proactive-disclosure duty; a reply in
+  // an ongoing thread does not have to re-disclose every turn.
+  if (posture.proactive_disclosure && firstContact) {
+    const discloses =
+      /\bai\b/i.test(String(text || "")) ||
+      lc.includes("automated") ||
+      lc.includes("assistant working") ||
+      lc.includes("on behalf of");
+    if (!discloses) {
+      return `AI-disclosure required: posture "${postureName}" (${jKey}) mandates proactive disclosure on first contact, message conceals it (policies/ai-disclosure.yaml)`;
+    }
+  }
+  return null;
+}
+
+/**
+ * (c) Information-barrier screen. Reads an OPTIONAL `barriers:` section from
+ * information-barriers.yaml. Each barrier wall is:
+ *   - recipients:        [exact recipient strings]      (optional)
+ *   - recipient_pattern: "regex"                         (optional)
+ *   - recipient_class:   "external"|"internal"           (optional)
+ *   - blocked_topics / deny_keywords: [case-insensitive substrings]  (required)
+ *   - reason:            "human-readable wall name"      (optional)
+ * A message to a matching recipient that contains a blocked topic is denied.
+ * When no `barriers:` section is present the screen is a no-op (no walls ⇒
+ * nothing to block) — the existing taxonomy-only file stays valid.
+ *
+ * @returns {string|null} block reason, or null
+ */
+export function screenBarriers(text, { policy, recipient, recipientClass }) {
+  if (!policy || !Array.isArray(policy.barriers)) return null;
+  const lc = String(text || "").toLowerCase();
+  const r = String(recipient || "");
+
+  for (const wall of policy.barriers) {
+    if (!wall || typeof wall !== "object") continue;
+    const topics = wall.blocked_topics || wall.deny_keywords || [];
+    if (!Array.isArray(topics) || topics.length === 0) continue;
+
+    let appliesToRecipient = false;
+    if (Array.isArray(wall.recipients) && wall.recipients.includes(r)) {
+      appliesToRecipient = true;
+    }
+    if (!appliesToRecipient && wall.recipient_pattern) {
+      try {
+        if (new RegExp(wall.recipient_pattern).test(r)) appliesToRecipient = true;
+      } catch {
+        // A malformed pattern is a policy authoring error; treat the wall as
+        // applying (fail toward blocking) so a broken wall can't silently open.
+        appliesToRecipient = true;
+      }
+    }
+    if (!appliesToRecipient && wall.recipient_class) {
+      if (wall.recipient_class === recipientClass) appliesToRecipient = true;
+    }
+    // A wall with NO recipient predicate at all applies to everyone.
+    if (
+      !appliesToRecipient &&
+      !Array.isArray(wall.recipients) &&
+      !wall.recipient_pattern &&
+      !wall.recipient_class
+    ) {
+      appliesToRecipient = true;
+    }
+    if (!appliesToRecipient) continue;
+
+    for (const topic of topics) {
+      const t = String(topic || "").toLowerCase().trim();
+      if (t && lc.includes(t)) {
+        const name = wall.reason || wall.name || "information barrier";
+        return `information barrier "${name}": topic "${topic}" walled from recipient (policies/information-barriers.yaml)`;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * (d) Recipient allowlist. Only enforced when `allowlist` is a non-empty array.
+ * An empty / undefined allowlist means "not configured" → no restriction (the
+ * pre-send-audit hook has the same opt-in semantics).
+ *
+ * @returns {string|null} block reason, or null
+ */
+export function screenAllowlist(recipient, allowlist) {
+  if (!Array.isArray(allowlist) || allowlist.length === 0) return null;
+  const r = String(recipient || "").trim();
+  if (!r) return `recipient missing but a send allowlist is configured`;
+  for (const entry of allowlist) {
+    if (String(entry || "").trim() === r) return null;
+  }
+  return `recipient "${r}" is not on the configured send allowlist`;
+}
+
+/* ──────────────────────────── main entry point ───────────────────────────── */
+
+/**
+ * Screen an outbound message at the one shared chokepoint.
+ *
+ * @param {object} args
+ * @param {string} args.channel    slack|telegram|whatsapp|sms|email|voice|document
+ * @param {string} args.recipient  channel id / email / phone / handle
+ * @param {string} args.text       the outbound message body
+ * @param {string} [args.agentRoot=process.cwd()] repo root holding policies/
+ * @param {string} [args.jurisdiction] recipient jurisdiction key (EU, US-CA, …)
+ * @param {boolean} [args.firstContact=true] is this the first message in the convo
+ * @param {string[]} [args.internalDomains] email domains treated as internal
+ * @param {string[]} [args.allowlist] recipient allowlist (opt-in)
+ * @param {object} [args.fs] injected { readFileSync, existsSync } for tests
+ * @returns {Promise<{allow:boolean, reason:string, redactedText?:string}>}
+ */
+export async function screenOutbound({
+  channel,
+  recipient,
+  text,
+  agentRoot = process.cwd(),
+  jurisdiction = undefined,
+  firstContact = true,
+  internalDomains = [],
+  allowlist = undefined,
+  fs: injectedFs = undefined,
+} = {}) {
+  const fs = makeFs(injectedFs);
+  const recipientClass = classifyRecipient(channel, recipient, internalDomains);
+  const isExternal = recipientClass === "external";
+
+  // failPolicy: for a missing/unreadable REQUIRED policy file. External → block,
+  // internal → open (so transient FS faults never wall off internal ops chatter).
+  const failPolicy = (file) =>
+    isExternal
+      ? blocked(
+          `outbound policy "${file}" unreadable — failing closed for external recipient (mirrors validate_outbound)`,
+        )
+      : allowed();
+
+  try {
+    // (a) Banned phrases — pure, sourced from communication-style.md. If that
+    //     file is unreadable we still apply the embedded constant list (the SoT
+    //     is mirrored here), so a missing style file does NOT open the AI-tell
+    //     gate; it only loses the ability to refresh the list.
+    const bannedReason = screenBannedPhrases(text);
+    if (bannedReason) return blocked(bannedReason);
+
+    // (b) AI-disclosure. The truthfulness invariant is enforced from the
+    //     embedded denial list even without the file; posture resolution needs
+    //     the file. Missing file → invariant still runs; posture defaults apply.
+    let disclosurePolicy = null;
+    const disc = readPolicy(fs, agentRoot, POLICY.disclosure);
+    if (disc.ok) {
+      try {
+        const yaml = await getYaml();
+        disclosurePolicy = yaml.load(disc.text) || null;
+      } catch {
+        // Malformed disclosure YAML: required policy → fail per posture.
+        const fp = failPolicy(POLICY.disclosure);
+        if (!fp.allow) return fp;
+      }
+    } else {
+      const fp = failPolicy(POLICY.disclosure);
+      if (!fp.allow) return fp;
+    }
+    const disclosureReason = screenDisclosure(text, {
+      policy: disclosurePolicy,
+      jurisdiction,
+      firstContact,
+    });
+    if (disclosureReason) return blocked(disclosureReason);
+
+    // (c) Information barriers (recipient/topic walls). Optional section.
+    let barriersPolicy = null;
+    const bar = readPolicy(fs, agentRoot, POLICY.barriers);
+    if (bar.ok) {
+      try {
+        const yaml = await getYaml();
+        barriersPolicy = yaml.load(bar.text) || null;
+      } catch {
+        const fp = failPolicy(POLICY.barriers);
+        if (!fp.allow) return fp;
+      }
+    } else {
+      const fp = failPolicy(POLICY.barriers);
+      if (!fp.allow) return fp;
+    }
+    const barrierReason = screenBarriers(text, {
+      policy: barriersPolicy,
+      recipient,
+      recipientClass,
+    });
+    if (barrierReason) return blocked(barrierReason);
+
+    // (d) Recipient allowlist (opt-in).
+    const allowReason = screenAllowlist(recipient, allowlist);
+    if (allowReason) return blocked(allowReason);
+
+    return allowed();
+  } catch (err) {
+    // Unexpected fault: fail closed for external, open for internal.
+    if (isExternal) {
+      return blocked(
+        `send-gate internal error — failing closed for external recipient: ${err && err.message ? err.message : String(err)}`,
+      );
+    }
+    return allowed();
+  }
+}
+
+/* ─────────────────────────────────── CLI ─────────────────────────────────── */
+
+/**
+ * Parse `--flag value` / `--flag=value` argv into a plain object. Repeated flags
+ * (e.g. --internal-domain) accumulate into an array under the camelCase key.
+ */
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) continue;
+    let key = a.slice(2);
+    let val;
+    const eq = key.indexOf("=");
+    if (eq >= 0) {
+      val = key.slice(eq + 1);
+      key = key.slice(0, eq);
+    } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+      val = argv[++i];
+    } else {
+      val = "true";
+    }
+    const camel = key.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+    if (camel in out) {
+      out[camel] = Array.isArray(out[camel]) ? out[camel].concat(val) : [out[camel], val];
+    } else {
+      out[camel] = val;
+    }
+  }
+  return out;
+}
+
+function readStdin() {
+  try {
+    return nodeReadFileSync(0, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+async function main(argv) {
+  const args = parseArgs(argv);
+  const channel = args.channel || "";
+  const recipient = args.recipient || "";
+  if (!channel) {
+    process.stderr.write("BLOCKED: --channel is required\n");
+    process.exit(1);
+  }
+  // text precedence: --text flag, else stdin.
+  const text = args.text != null ? args.text : readStdin();
+  const internalDomains = args.internalDomain
+    ? [].concat(args.internalDomain)
+    : (process.env.MAESTRO_INTERNAL_DOMAINS || "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+  const allowlist = args.allow ? [].concat(args.allow) : undefined;
+  const firstContact = args.firstContact === "false" ? false : true;
+
+  const result = await screenOutbound({
+    channel,
+    recipient,
+    text,
+    agentRoot: args.agentRoot || process.env.AGENT_DIR || process.cwd(),
+    jurisdiction: args.jurisdiction,
+    firstContact,
+    internalDomains,
+    allowlist,
+  });
+
+  if (result.allow) {
+    if (result.redactedText) process.stdout.write(result.redactedText);
+    process.exit(0);
+  }
+  process.stderr.write(`BLOCKED: ${result.reason}\n`);
+  process.exit(1);
+}
+
+// Run as CLI only when invoked directly (not when imported).
+const invokedDirectly =
+  process.argv[1] && process.argv[1].endsWith("send-gate.mjs");
+if (invokedDirectly) {
+  main(process.argv.slice(2));
+}