@cohortapp/agent-sdk 2.3.0

package/lib/security/redact.test.mjs

@@ -0,0 +1,441 @@
+/**
+ * lib/security/redact.test.mjs
+ *
+ * node:test coverage for redact.mjs:
+ *  - user:pass@ userinfo is stripped
+ *  - sensitive query params (token/key/secret/password/apikey/...) are masked
+ *  - benign URLs are untouched
+ *  - malformed URLs do not throw
+ *  - private vs public IP classification, incl. IPv4-mapped-IPv6 bypass
+ *    (::ffff:10.0.0.1) and loopback 127.0.0.1
+ *
+ * Run: cd /Users/wong/maestro && node --test lib/security/redact.test.mjs
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  redactSensitiveUrl,
+  isPrivateOrReservedIp,
+  isSensitiveParamName,
+  REDACTED,
+  maskText,
+  maskTextString,
+  redactObject,
+  REDACTED_LABEL_PREFIX,
+} from "./redact.mjs";
+
+/* ----------------------------- userinfo ---------------------------------- */
+
+test("strips user:pass@ userinfo from a URL", () => {
+  const out = redactSensitiveUrl("https://alice:hunter2@example.com/path?x=1");
+  assert.ok(!out.includes("alice"), `username leaked: ${out}`);
+  assert.ok(!out.includes("hunter2"), `password leaked: ${out}`);
+  assert.ok(!out.includes("@example.com"), `@ host leaked: ${out}`);
+  assert.ok(out.startsWith("https://example.com/"), `host changed: ${out}`);
+  // Non-sensitive param preserved.
+  assert.ok(out.includes("x=1"), `benign param dropped: ${out}`);
+});
+
+test("strips userinfo with username only (no password)", () => {
+  const out = redactSensitiveUrl("https://tokenuser@api.example.com/");
+  assert.ok(!out.includes("tokenuser"), `username leaked: ${out}`);
+  assert.ok(out.startsWith("https://api.example.com/"), out);
+});
+
+/* --------------------------- secret params ------------------------------- */
+
+test("masks sensitive query params, keeps benign ones", () => {
+  const out = redactSensitiveUrl(
+    "https://example.com/api?token=abc123&page=2&api_key=zzz&q=hello"
+  );
+  assert.ok(out.includes(`token=${encodeURIComponent(REDACTED)}`) || out.includes("token=***"), out);
+  assert.ok(!out.includes("abc123"), `token value leaked: ${out}`);
+  assert.ok(!out.includes("zzz"), `api_key value leaked: ${out}`);
+  // Benign params untouched.
+  assert.ok(out.includes("page=2"), out);
+  assert.ok(out.includes("q=hello"), out);
+});
+
+test("masks each sensitive keyword variant", () => {
+  const cases = [
+    "token",
+    "access_token",
+    "refresh_token",
+    "key",
+    "apiKey",
+    "api_key",
+    "secret",
+    "client_secret",
+    "password",
+    "passwd",
+    "pwd",
+    "auth",
+    "signature",
+    "sig",
+  ];
+  for (const k of cases) {
+    const out = redactSensitiveUrl(`https://e.com/?${k}=SUPERSECRETVALUE`);
+    assert.ok(
+      !out.includes("SUPERSECRETVALUE"),
+      `param "${k}" not masked: ${out}`
+    );
+  }
+});
+
+test("masks repeated sensitive params (multiplicity preserved)", () => {
+  const out = redactSensitiveUrl("https://e.com/?key=a&key=b&n=1");
+  assert.ok(!out.includes("=a"), out);
+  assert.ok(!out.includes("=b"), out);
+  // two key= occurrences remain
+  const count = (out.match(/key=/g) || []).length;
+  assert.equal(count, 2, `expected 2 key= occurrences: ${out}`);
+  assert.ok(out.includes("n=1"), out);
+});
+
+/* ----------------------------- benign ------------------------------------ */
+
+test("leaves a benign URL effectively untouched", () => {
+  const url = "https://example.com/docs/page?lang=en&page=2";
+  const out = redactSensitiveUrl(url);
+  assert.ok(out.includes("example.com/docs/page"), out);
+  assert.ok(out.includes("lang=en"), out);
+  assert.ok(out.includes("page=2"), out);
+  assert.ok(!out.includes(REDACTED), `nothing should be masked: ${out}`);
+});
+
+test("benign URL with no query is unchanged", () => {
+  const url = "https://example.com/";
+  assert.equal(redactSensitiveUrl(url), url);
+});
+
+/* ---------------------------- malformed ---------------------------------- */
+
+test("malformed / non-URL inputs do not throw", () => {
+  const inputs = [
+    "",
+    "not a url",
+    "http://",
+    "://missing-scheme",
+    "ht!tp://bad",
+    "https://alice:pw@", // truncated authority
+    "token=secret&password=hunter2", // bare query-ish string
+    "javascript:alert(1)",
+    "   ",
+    "%%%not-encoded%%%",
+  ];
+  for (const inp of inputs) {
+    assert.doesNotThrow(() => redactSensitiveUrl(inp), `threw on: ${JSON.stringify(inp)}`);
+  }
+});
+
+test("non-string inputs are handled without throwing", () => {
+  assert.doesNotThrow(() => redactSensitiveUrl(null));
+  assert.doesNotThrow(() => redactSensitiveUrl(undefined));
+  assert.doesNotThrow(() => redactSensitiveUrl(12345));
+  assert.equal(redactSensitiveUrl(null), "");
+  assert.equal(redactSensitiveUrl(undefined), "");
+});
+
+test("regex fallback masks secrets in unparseable query strings", () => {
+  const out = redactSensitiveUrl("token=abc123&page=2&password=hunter2");
+  assert.ok(!out.includes("abc123"), out);
+  assert.ok(!out.includes("hunter2"), out);
+  assert.ok(out.includes("page=2"), out);
+});
+
+/* ------------------------ isSensitiveParamName --------------------------- */
+
+test("isSensitiveParamName matches case-insensitively", () => {
+  assert.equal(isSensitiveParamName("ApiKey"), true);
+  assert.equal(isSensitiveParamName("X-Auth-Token"), true);
+  assert.equal(isSensitiveParamName("PASSWORD"), true);
+  assert.equal(isSensitiveParamName("page"), false);
+  assert.equal(isSensitiveParamName("q"), false);
+  assert.equal(isSensitiveParamName(""), false);
+  assert.equal(isSensitiveParamName(null), false);
+});
+
+/* --------------------------- IP: private --------------------------------- */
+
+test("classifies private IPv4 ranges as private/reserved", () => {
+  const priv = [
+    "10.0.0.1",
+    "10.255.255.255",
+    "172.16.0.1",
+    "172.31.255.255",
+    "192.168.0.1",
+    "192.168.1.1",
+    "127.0.0.1", // loopback
+    "127.1.2.3",
+    "169.254.0.1", // link-local
+    "0.0.0.0", // unspecified
+    "100.64.0.1", // CGNAT
+    "255.255.255.255", // broadcast / reserved
+    "224.0.0.1", // multicast
+    "198.18.0.1", // benchmarking
+    "192.0.2.5", // TEST-NET-1
+    "203.0.113.9", // TEST-NET-3
+  ];
+  for (const ip of priv) {
+    assert.equal(isPrivateOrReservedIp(ip), true, `${ip} should be private/reserved`);
+  }
+});
+
+test("127.0.0.1 loopback is private/reserved", () => {
+  assert.equal(isPrivateOrReservedIp("127.0.0.1"), true);
+});
+
+/* ---------------------------- IP: public --------------------------------- */
+
+test("classifies public IPv4 as NOT private/reserved", () => {
+  const pub = ["8.8.8.8", "1.1.1.1", "93.184.216.34", "172.15.0.1", "172.32.0.1", "11.0.0.1"];
+  for (const ip of pub) {
+    assert.equal(isPrivateOrReservedIp(ip), false, `${ip} should be public`);
+  }
+});
+
+/* --------------------------- IP: IPv6 ------------------------------------ */
+
+test("IPv4-mapped-IPv6 private addresses are caught (bypass protection)", () => {
+  assert.equal(isPrivateOrReservedIp("::ffff:10.0.0.1"), true);
+  assert.equal(isPrivateOrReservedIp("::ffff:127.0.0.1"), true);
+  assert.equal(isPrivateOrReservedIp("::ffff:192.168.1.1"), true);
+  assert.equal(isPrivateOrReservedIp("[::ffff:10.0.0.1]"), true);
+});
+
+test("IPv4-mapped-IPv6 public address stays public", () => {
+  assert.equal(isPrivateOrReservedIp("::ffff:8.8.8.8"), false);
+});
+
+test("classifies IPv6 loopback / ULA / link-local / multicast as private", () => {
+  assert.equal(isPrivateOrReservedIp("::1"), true); // loopback
+  assert.equal(isPrivateOrReservedIp("[::1]"), true);
+  assert.equal(isPrivateOrReservedIp("::"), true); // unspecified
+  assert.equal(isPrivateOrReservedIp("fc00::1"), true); // ULA
+  assert.equal(isPrivateOrReservedIp("fd12:3456:789a::1"), true); // ULA
+  assert.equal(isPrivateOrReservedIp("fe80::1"), true); // link-local
+  assert.equal(isPrivateOrReservedIp("fe80::1%eth0"), true); // link-local + zone
+  assert.equal(isPrivateOrReservedIp("ff02::1"), true); // multicast
+});
+
+test("classifies public IPv6 as NOT private", () => {
+  assert.equal(isPrivateOrReservedIp("2606:4700:4700::1111"), false); // cloudflare
+  assert.equal(isPrivateOrReservedIp("2001:4860:4860::8888"), false); // google
+});
+
+/* --------------------------- IP: edges ----------------------------------- */
+
+test("non-IP hosts and junk return false (classifies addresses, not names)", () => {
+  assert.equal(isPrivateOrReservedIp("example.com"), false);
+  assert.equal(isPrivateOrReservedIp("localhost"), false);
+  assert.equal(isPrivateOrReservedIp(""), false);
+  assert.equal(isPrivateOrReservedIp("   "), false);
+  assert.equal(isPrivateOrReservedIp("999.999.999.999"), false);
+  assert.equal(isPrivateOrReservedIp("not-an-ip"), false);
+  assert.equal(isPrivateOrReservedIp(null), false);
+  assert.equal(isPrivateOrReservedIp(undefined), false);
+});
+
+test("isPrivateOrReservedIp never throws on hostile input", () => {
+  for (const v of ["", "::::", "[", "]", "1.2.3", "::ffff:", "fe80::%", null, 42, {}]) {
+    assert.doesNotThrow(() => isPrivateOrReservedIp(/** @type {any} */ (v)));
+  }
+});
+
+/* ========================================================================= *
+ * maskText — free-text PII / secret masking
+ * ========================================================================= */
+
+/** Assert a single secret class is fully masked and counted. */
+function assertMasked(input, secret, label) {
+  const { text, count } = maskText(input);
+  assert.ok(!text.includes(secret), `${label} value leaked: ${text}`);
+  assert.ok(count >= 1, `${label} not counted: ${JSON.stringify({ text, count })}`);
+  assert.ok(
+    text.includes(`${REDACTED_LABEL_PREFIX}`),
+    `${label} placeholder missing: ${text}`
+  );
+}
+
+test("maskText redacts Anthropic keys (sk-ant-) without leaking sk- generic", () => {
+  const key = "sk-ant-api03-AbCdEf0123456789_GhIjKlMnOpQrStUvWx";
+  const { text, count } = maskText(`my key is ${key} ok`);
+  assert.ok(!text.includes(key), text);
+  assert.equal(count, 1);
+  assert.ok(text.includes("[REDACTED:ANTHROPIC_KEY]"), text);
+});
+
+test("maskText redacts OpenAI-style sk- and sk-proj- keys", () => {
+  assertMasked("token sk-proj-0123456789ABCDEFabcdef0123 here", "sk-proj-0123456789ABCDEFabcdef0123", "API_KEY");
+  assertMasked("token sk-0123456789ABCDEFabcdef0123 here", "sk-0123456789ABCDEFabcdef0123", "API_KEY");
+});
+
+test("maskText redacts AWS access key ids (AKIA/ASIA)", () => {
+  assertMasked("creds AKIAIOSFODNN7EXAMPLE done", "AKIAIOSFODNN7EXAMPLE", "AWS_KEY");
+  assertMasked("creds ASIAIOSFODNN7EXAMPLE done", "ASIAIOSFODNN7EXAMPLE", "AWS_KEY");
+});
+
+test("maskText redacts GitHub tokens (ghp_ / github_pat_)", () => {
+  assertMasked(
+    "auth ghp_0123456789abcdefABCDEF0123456789abcdef tail",
+    "ghp_0123456789abcdefABCDEF0123456789abcdef",
+    "GITHUB_TOKEN"
+  );
+  assertMasked(
+    "auth github_pat_0123456789abcdefABCD_extra tail",
+    "github_pat_0123456789abcdefABCD_extra",
+    "GITHUB_TOKEN"
+  );
+});
+
+test("maskText redacts bearer tokens", () => {
+  const { text, count } = maskText("Authorization: Bearer abc.DEF-123_xyz=+/ rest");
+  assert.ok(!text.includes("abc.DEF-123_xyz"), text);
+  assert.ok(count >= 1, `count=${count}`);
+  assert.ok(text.includes("[REDACTED:BEARER_TOKEN]"), text);
+});
+
+test("maskText redacts JWTs", () => {
+  const jwt =
+    "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U";
+  const { text, count } = maskText(`session=${jwt};`);
+  assert.ok(!text.includes(jwt), text);
+  assert.ok(count >= 1);
+});
+
+test("maskText redacts PEM private key blocks", () => {
+  const pem =
+    "-----BEGIN RSA PRIVATE KEY-----\nMIIBVAIBADANBgkqh\nkiG9w0BAQEFA\n-----END RSA PRIVATE KEY-----";
+  const { text, count } = maskText(`key:\n${pem}\nend`);
+  assert.ok(!text.includes("MIIBVAIBADAN"), text);
+  assert.ok(count >= 1);
+  assert.ok(text.includes("[REDACTED:PRIVATE_KEY]"), text);
+});
+
+test("maskText redacts email addresses", () => {
+  assertMasked("contact alice.smith+tag@example.co.uk please", "alice.smith+tag@example.co.uk", "EMAIL");
+});
+
+test("maskText redacts phone numbers", () => {
+  const { text, count } = maskText("call me at +1 (415) 555-0132 tomorrow");
+  assert.ok(!text.includes("555-0132"), text);
+  assert.ok(count >= 1);
+  assert.ok(text.includes("[REDACTED:PHONE]"), text);
+});
+
+test("maskText redacts long hex secrets", () => {
+  const hex = "deadbeefcafef00d0123456789abcdef0123456789abcdef"; // 48 hex chars
+  assertMasked(`hash=${hex} ok`, hex, "HEX_SECRET");
+});
+
+test("maskText redacts long base64-shaped secrets", () => {
+  const b64 = "QWxhZGRpbjpvcGVuIHNlc2FtZQ123456789abcDEF_xyz-987654321";
+  const { text, count } = maskText(`blob ${b64} end`);
+  assert.ok(!text.includes(b64), text);
+  assert.ok(count >= 1);
+});
+
+test("maskText leaves benign prose untouched and counts zero", () => {
+  const benign =
+    "The quarterly report is due Friday. Page 2 covers revenue; total was 1234 units across 3 regions.";
+  const { text, count } = maskText(benign);
+  assert.equal(text, benign);
+  assert.equal(count, 0);
+  assert.ok(!text.includes(REDACTED_LABEL_PREFIX), text);
+});
+
+test("maskText counts multiple distinct secrets in one string", () => {
+  const input =
+    "email bob@corp.com key sk-ant-api03-ZZZZZZZZ_aaaaaaaa11112222 and aws AKIAIOSFODNN7EXAMPLE";
+  const { text, count } = maskText(input);
+  assert.ok(!text.includes("bob@corp.com"), text);
+  assert.ok(!text.includes("AKIAIOSFODNN7EXAMPLE"), text);
+  assert.equal(count, 3, `expected 3 redactions, got ${count}: ${text}`);
+});
+
+test("maskText never throws and coerces non-strings", () => {
+  assert.deepEqual(maskText(null), { text: "", count: 0 });
+  assert.deepEqual(maskText(undefined), { text: "", count: 0 });
+  assert.equal(maskText(12345).count, 0);
+  assert.doesNotThrow(() => maskText({}));
+  assert.deepEqual(maskText(""), { text: "", count: 0 });
+});
+
+test("maskText honors a custom placeholder factory", () => {
+  const { text } = maskText("mail me at x@y.com", {
+    placeholder: (label) => `<${label}>`,
+  });
+  assert.ok(text.includes("<EMAIL>"), text);
+  assert.ok(!text.includes("x@y.com"), text);
+});
+
+test("maskTextString returns only the cleaned string (masker-hook shape)", () => {
+  const out = maskTextString("token sk-0123456789ABCDEFabcdef0123 done");
+  assert.equal(typeof out, "string");
+  assert.ok(!out.includes("sk-0123456789ABCDEFabcdef0123"), out);
+});
+
+/* ========================================================================= *
+ * redactObject — deep masking
+ * ========================================================================= */
+
+test("redactObject deep-masks nested string values, preserving structure", () => {
+  const input = {
+    user: "alice@example.com",
+    meta: {
+      note: "all good",
+      creds: ["AKIAIOSFODNN7EXAMPLE", "harmless"],
+      depth: { token: "sk-ant-api03-QQQQQQQQ_bbbbbbbb33334444" },
+    },
+    count: 7,
+    enabled: true,
+    nothing: null,
+  };
+  const { value, count } = redactObject(input);
+
+  assert.ok(!value.user.includes("alice@example.com"), value.user);
+  assert.equal(value.meta.note, "all good"); // benign untouched
+  assert.ok(!value.meta.creds[0].includes("AKIAIOSFODNN7EXAMPLE"), value.meta.creds[0]);
+  assert.equal(value.meta.creds[1], "harmless");
+  assert.ok(!value.meta.depth.token.includes("sk-ant-"), value.meta.depth.token);
+  // Non-strings pass through unchanged.
+  assert.equal(value.count, 7);
+  assert.equal(value.enabled, true);
+  assert.equal(value.nothing, null);
+  // Keys preserved.
+  assert.deepEqual(Object.keys(value).sort(), ["count", "enabled", "meta", "nothing", "user"]);
+  assert.equal(count, 3);
+});
+
+test("redactObject does not mutate the input", () => {
+  const input = { a: "ping me at z@z.com" };
+  const before = input.a;
+  redactObject(input);
+  assert.equal(input.a, before, "input was mutated");
+});
+
+test("redactObject masks keys' values only, not the keys themselves", () => {
+  const input = { "token-field": "sk-0123456789ABCDEFabcdef0123" };
+  const { value } = redactObject(input);
+  assert.ok(Object.prototype.hasOwnProperty.call(value, "token-field"), "key dropped");
+  assert.ok(!value["token-field"].includes("sk-0123456789"), value["token-field"]);
+});
+
+test("redactObject handles cycles and never throws", () => {
+  const a = { name: "leak: secret@host.com" };
+  a.self = a; // cycle
+  let result;
+  assert.doesNotThrow(() => {
+    result = redactObject(a);
+  });
+  assert.ok(!result.value.name.includes("secret@host.com"), result.value.name);
+  assert.equal(result.count, 1);
+});
+
+test("redactObject passes scalars through untouched", () => {
+  assert.deepEqual(redactObject(42), { value: 42, count: 0 });
+  assert.deepEqual(redactObject(true), { value: true, count: 0 });
+  assert.deepEqual(redactObject(null), { value: null, count: 0 });
+});

package/lib/security/secret-equal.mjs

@@ -0,0 +1,73 @@
+/**
+ * secret-equal.mjs — constant-time comparison of secrets (tokens, signatures,
+ * HMACs, shared keys) without leaking length or content through timing.
+ *
+ * A naive `a === b` short-circuits on the first differing byte and on length
+ * mismatch, which gives an attacker a timing oracle. node:crypto's
+ * timingSafeEqual fixes the byte-by-byte leak but THROWS when the two buffers
+ * differ in length — so calling it directly re-introduces an early-return path.
+ *
+ * safeEqualSecret() closes both holes: it always runs the constant-time
+ * compare over equal-length buffers (padded to the longer of the two) and only
+ * afterwards folds in the original length equality, so a length mismatch costs
+ * the same as a content mismatch. Non-string inputs return false instead of
+ * throwing.
+ *
+ * Ported and adapted from OpenClaw (src/security/secret-equal.ts) for the
+ * maestro autonomy model: any place that checks an inbound webhook signature,
+ * relay token, or shared secret should compare it with safeEqualSecret().
+ *
+ * Pure function; the only dependency is node:crypto.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Copy `bytes` into a fresh buffer of exactly `length` bytes, zero-padding the
+ * tail when the input is shorter. Returns the input untouched when it already
+ * matches `length`.
+ * @param {Buffer} bytes
+ * @param {number} length
+ * @returns {Buffer}
+ */
+function padSecretBytes(bytes, length) {
+  if (bytes.length === length) {
+    return bytes;
+  }
+  const padded = Buffer.alloc(length);
+  bytes.copy(padded);
+  return padded;
+}
+
+/**
+ * Timing-safe secret comparison.
+ *
+ * Returns true iff `provided` and `expected` are both strings with identical
+ * UTF-8 bytes. The comparison runs in time independent of where the values
+ * differ and of their lengths, and never throws on length mismatch or
+ * non-string input.
+ *
+ * @param {string|undefined|null} provided
+ * @param {string|undefined|null} expected
+ * @returns {boolean}
+ */
+export function safeEqualSecret(provided, expected) {
+  if (typeof provided !== "string" || typeof expected !== "string") {
+    return false;
+  }
+  const providedBytes = Buffer.from(provided, "utf8");
+  const expectedBytes = Buffer.from(expected, "utf8");
+  const byteLength = Math.max(providedBytes.length, expectedBytes.length);
+  if (byteLength === 0) {
+    // Both strings are empty: equal, and there is nothing to compare.
+    return true;
+  }
+  // Always perform the constant-time compare, then fold in the length check so
+  // a length mismatch is indistinguishable (timing-wise) from a content one.
+  return (
+    timingSafeEqual(
+      padSecretBytes(providedBytes, byteLength),
+      padSecretBytes(expectedBytes, byteLength),
+    ) && providedBytes.length === expectedBytes.length
+  );
+}

package/lib/security/secret-equal.test.mjs

@@ -0,0 +1,55 @@
+/**
+ * secret-equal.test.mjs — node:test coverage for safeEqualSecret().
+ *
+ * Verifies: equal strings, differing strings, length mismatch (no throw),
+ * non-string inputs (no throw), and empty-string handling.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { safeEqualSecret } from "./secret-equal.mjs";
+
+test("equal strings return true", () => {
+  assert.equal(safeEqualSecret("s3cr3t-token", "s3cr3t-token"), true);
+});
+
+test("different strings of same length return false", () => {
+  assert.equal(safeEqualSecret("abcdef", "abcxef"), false);
+});
+
+test("different lengths return false without throwing", () => {
+  assert.doesNotThrow(() => safeEqualSecret("short", "shorter-secret"));
+  assert.equal(safeEqualSecret("short", "shorter-secret"), false);
+  assert.equal(safeEqualSecret("shorter-secret", "short"), false);
+  // A string that is a strict prefix of the other must not compare equal.
+  assert.equal(safeEqualSecret("abc", "abcd"), false);
+});
+
+test("non-string inputs return false without throwing", () => {
+  assert.doesNotThrow(() => safeEqualSecret(undefined, "x"));
+  assert.equal(safeEqualSecret(undefined, "x"), false);
+  assert.equal(safeEqualSecret("x", undefined), false);
+  assert.equal(safeEqualSecret(null, "x"), false);
+  assert.equal(safeEqualSecret("x", null), false);
+  assert.equal(safeEqualSecret(123, "123"), false);
+  assert.equal(safeEqualSecret("123", 123), false);
+  assert.equal(safeEqualSecret(Buffer.from("x"), "x"), false);
+  assert.equal(safeEqualSecret({}, {}), false);
+  assert.equal(safeEqualSecret(undefined, undefined), false);
+  assert.equal(safeEqualSecret(null, null), false);
+});
+
+test("two empty strings are equal", () => {
+  assert.equal(safeEqualSecret("", ""), true);
+});
+
+test("empty string vs non-empty string returns false", () => {
+  assert.equal(safeEqualSecret("", "x"), false);
+  assert.equal(safeEqualSecret("x", ""), false);
+});
+
+test("multibyte/unicode strings compare on UTF-8 bytes", () => {
+  assert.equal(safeEqualSecret("séçret-🔑", "séçret-🔑"), true);
+  assert.equal(safeEqualSecret("séçret-🔑", "secret-key"), false);
+});

package/lib/session-permissions.mjs

@@ -0,0 +1,101 @@
+/**
+ * Maestro — Session permission scoping (audit H1).
+ *
+ * Every autonomous sub-session the daemon spawns (cadence ticks, and — by
+ * extension — reactive dispatcher/responder/classifier paths) historically ran
+ * `claude --print` with `--dangerously-skip-permissions`. That means an
+ * inbound message containing a prompt-injection payload can drive ARBITRARY
+ * tool use with no human in the loop, which on an unattended 24/7 Mac mini is
+ * the single highest-impact realistic compromise path (audit/AUDIT-REPORT.md
+ * finding H1).
+ *
+ * This module centralizes the decision of WHICH permission CLI args a spawned
+ * session gets, so the dangerous default becomes explicit and operators get a
+ * real gate. It is deliberately OPT-IN: with no env flag set, behaviour is
+ * BYTE-FOR-BYTE UNCHANGED (still `--dangerously-skip-permissions`). Operators
+ * who want the scoped behaviour set `MAESTRO_SCOPED_PERMISSIONS=1`.
+ *
+ * Pure function; zero dependencies beyond the cadence registry. Returns ONLY
+ * the permission flags — callers keep appending `daemonClaudeArgs()`
+ * (`--strict-mcp-config` / `--bare`) exactly as before, so `--strict-mcp-config`
+ * is preserved in BOTH modes.
+ *
+ * Caller sites (today): scripts/daemon/cadence-consumer.mjs#realSpawnSession.
+ */
+
+import { getCadenceDef } from "../scripts/daemon/cadence-handlers.mjs";
+
+/**
+ * Conservative fallback allowlist used in scoped mode when a cadence has no
+ * explicit `allowedTools` field in the registry. Deliberately READ-ONLY /
+ * search-only: an unknown or untrusted cadence should never get a write,
+ * shell, send, or control-plane tool by default. Tightening here is safe;
+ * widening should be a per-cadence opt-in via the registry `allowedTools`.
+ *
+ * Frozen so a caller can't accidentally mutate the shared default.
+ * @type {ReadonlyArray<string>}
+ */
+export const CONSERVATIVE_DEFAULT_ALLOWLIST = Object.freeze([
+  "Read",
+  "Grep",
+  "Glob",
+  "LS",
+]);
+
+/**
+ * Resolve the effective allowlist for a cadence in scoped mode. Prefers an
+ * explicit `allowedTools` array on the cadence registry entry; otherwise falls
+ * back to {@link CONSERVATIVE_DEFAULT_ALLOWLIST}. A registry entry whose
+ * `allowedTools` is absent, non-array, or empty also falls back, so a
+ * mis-specified entry fails CLOSED (to the conservative default) rather than
+ * open.
+ *
+ * @param {string} [cadence] cadence name (registry key)
+ * @returns {string[]} non-empty list of allowed tool names
+ */
+function resolveAllowlist(cadence) {
+  const def = cadence ? getCadenceDef(cadence) : null;
+  const allow = def && def.allowedTools;
+  if (Array.isArray(allow) && allow.length > 0) {
+    // Drop any non-string / blank entries defensively.
+    const cleaned = allow.filter((t) => typeof t === "string" && t.trim());
+    if (cleaned.length > 0) return cleaned;
+  }
+  return [...CONSERVATIVE_DEFAULT_ALLOWLIST];
+}
+
+/**
+ * Build the `claude` CLI permission args for a spawned sub-session.
+ *
+ * Behaviour is gated on the `MAESTRO_SCOPED_PERMISSIONS` env var:
+ *
+ *   - UNSET (or any value other than "1") — back-compat / default. Returns
+ *     `["--dangerously-skip-permissions"]`, identical to the pre-H1 hardcoded
+ *     literal. NOTHING changes for operators who have not opted in.
+ *
+ *   - "1" — scoped mode. Returns `["--allowedTools", "<comma-list>"]`, where
+ *     the list is the cadence's registry `allowedTools` field if present, else
+ *     {@link CONSERVATIVE_DEFAULT_ALLOWLIST}. `--strict-mcp-config` is NOT
+ *     added here — it stays single-sourced in `daemonClaudeArgs()` which the
+ *     caller appends.
+ *
+ * The flag is read at call time (not import time) so an operator can flip it
+ * via `.env` and have a long-lived daemon pick it up on the next spawn without
+ * a code change.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.cadence] cadence name; used to look up a per-cadence allowlist in scoped mode.
+ * @param {string} [opts.mode]    cadence mode ("inline"|"guarded"|"escalate"); accepted for forward-compat (future per-mode tightening), currently unused.
+ * @returns {string[]} permission CLI args to splice into the `claude --print` argv.
+ */
+export function sessionPermissionArgs({ cadence, mode } = {}) {
+  // `mode` is reserved for future per-mode tightening; reference it so linters
+  // don't flag it as unused while keeping the signature stable for callers.
+  void mode;
+  if (process.env.MAESTRO_SCOPED_PERMISSIONS !== "1") {
+    // Default / back-compat: UNCHANGED behaviour.
+    return ["--dangerously-skip-permissions"];
+  }
+  const allow = resolveAllowlist(cadence);
+  return ["--allowedTools", allow.join(",")];
+}