@crewhaus/tool-notify 0.7.0 → 0.8.0

package/dist/net.js

@@ -8,7 +8,8 @@
  * twice:
  *
  *   1. Empty allow-list ⇒ deny all. There is no "allow everything" value,
- *      for origins, for SMTP hosts, or for email recipients.
+ *      for origins, for SMTP hosts, for email recipients, for SMS numbers or
+ *      for push targets.
  *   2. Scheme must be http or https.
  *   3. Origin (scheme + lowercase host + non-default port) must match an
  *      allow-list entry exactly, after canonicalisation.
@@ -29,10 +30,13 @@
  *      real endpoint. Only the read-only `DeliveryCheck` follows, and then
  *      the allow-list, the SSRF gate and the credential rules run again on
  *      every hop.
- *   7. Credentials are environment variable NAMES, never values. Whatever
- *      header a profile sets is dropped the moment a redirect leaves the
- *      origin it was minted for, and every result — success or failure —
- *      goes through a redactor built from the resolved secret.
+ *   7. Credentials are environment variable NAMES, never values, and only
+ *      names the operator listed (`allowed_secret_envs`, or a provider's own
+ *      `auth.envVar` for that provider): a call chooses among them and can
+ *      never add one. Whatever header a profile sets is dropped the moment a
+ *      redirect leaves the origin it was minted for, and every result —
+ *      success or failure — goes through a redactor built from the resolved
+ *      secret.
  *   8. Every request is deadline-bounded and every response is byte-capped,
  *      with the cap bounding memory rather than applied after buffering.
  *
@@ -40,8 +44,12 @@
  * cookie jar, and no certificate handling beyond the runtime's own.
  */
 import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
 import { lookup as dnsLookup, resolveTxt } from "node:dns/promises";
 import { CrewhausError } from "@crewhaus/errors";
+import { isE164Number, normalizePhoneNumber } from "@crewhaus/tool-permission-matcher";
+import { REDACTED, createSecretRedactor, isEnvName, looksLikePastedSecret, resolveCredentialEnv, secretForms, trimSecretTail, } from "@crewhaus/tool-safety/env";
+import { fetchRaw, readResponseBounded } from "@crewhaus/tool-safety/streams";
 import { joinTxtChunks, normalizeDomain } from "./lib/dns-records";
 /** Refusal by the allow-list, the SSRF gate, or a redirect rule. */
 export class NotifyPermissionError extends CrewhausError {
@@ -61,12 +69,17 @@ export const json = (value) => JSON.stringify(value);
 export function byString(a, b) {
     return a < b ? -1 : a > b ? 1 : 0;
 }
+/** Where an operator allows a credential variable. Every refusal names it. */
+export const SECRET_ENVS_KEY = "tool_config.notify.allowed_secret_envs";
 const EMPTY_CONFIG = {
     allowedOrigins: new Set(),
     allowedRecipients: [],
     allowedSmtpHosts: new Set(),
     allowedSenderDomains: new Set(),
     providers: new Map(),
+    allowedSecretEnvs: [],
+    allowedSmsRecipients: [],
+    allowedPushTargets: [],
 };
 let notifyConfig = EMPTY_CONFIG;
 /** Build a config from a spec-shaped block. Pure; both key spellings accepted. */
@@ -111,8 +124,114 @@ export function buildNotifyConfig(input) {
         allowedSmtpHosts: smtpHosts,
         allowedSenderDomains: senderDomains,
         providers,
+        allowedSecretEnvs: buildSecretEnvs(input.allowedSecretEnvs ?? input.allowed_secret_envs),
+        allowedSmsRecipients: buildDestinations(input.allowedSmsRecipients ?? input.allowed_sms_recipients, "sms"),
+        allowedPushTargets: buildDestinations(input.allowedPushTargets ?? input.allowed_push_targets, "push"),
     };
 }
+const DESTINATION_KEYS = {
+    sms: "allowed_sms_recipients",
+    push: "allowed_push_targets",
+};
+/**
+ * A phone number as the SMS allow-list compares it: the separators people
+ * write (spaces, `-`, `.`, parentheses) removed wherever they are, so
+ * `+1 (555) 000-1111` and `+15550001111` are the same number. It is the
+ * permission matcher's own reading, so a deny rule decides on the number
+ * this tool checks and sends.
+ */
+export const normalizeSmsNumber = normalizePhoneNumber;
+/**
+ * Check a destination allow-list at boot. A malformed entry throws, so a
+ * misconfiguration surfaces when the harness starts. There is no "allow
+ * everything" value: a bare `*` is refused, as an empty allow-list elsewhere
+ * here refuses everyone.
+ */
+function buildDestinations(raw, kind) {
+    const key = `tool_config.notify.${DESTINATION_KEYS[kind]}`;
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw))
+        throw new NotifyPermissionError(`${key} must be a list`);
+    const out = new Set();
+    raw.forEach((entry, index) => {
+        const where = `${key} entry ${index + 1}`;
+        if (typeof entry !== "string")
+            throw new NotifyPermissionError(`${where} is not a string`);
+        if (kind === "sms") {
+            const normalized = normalizeSmsNumber(entry);
+            const digits = normalized.endsWith("*") ? normalized.slice(0, -1) : normalized;
+            if (!isE164Number(digits)) {
+                throw new NotifyPermissionError(`${where} must be a number in E.164 form (a + and up to fifteen digits, such as +15550001111), or a prefix of one ending in * (such as +44*); there is no allow-everything value`);
+            }
+            out.add(normalized);
+            return;
+        }
+        const target = entry.trim();
+        const star = target.indexOf("*");
+        if (target === "" || target === "*" || (star !== -1 && star !== target.length - 1)) {
+            throw new NotifyPermissionError(`${where} must be a device token or topic, or a prefix of one ending in * (such as topic:ops-*); there is no allow-everything value`);
+        }
+        out.add(target);
+    });
+    return [...out].sort(byString);
+}
+/**
+ * A provider send's destination as its list compares it, and as it is sent:
+ * an SMS number normalised (`+1 (555) 000-1111` is `+15550001111`), a push
+ * target trimmed. Sending the call's own spelling would let a gateway read
+ * it as another number than the one the list and a permission rule decided on.
+ */
+export function destinationFor(to, kind) {
+    return kind === "sms" ? normalizeSmsNumber(to) : to.trim();
+}
+/**
+ * Why a provider send's destination is refused, or `null` when the list
+ * admits it. The one matcher for both lists: an entry matches exactly, or,
+ * ending in `*`, as a prefix. An SMS number is compared in normalised E.164
+ * form, so a destination that is not a number in that form matches nothing.
+ */
+export function destinationRefusal(to, kind, cfg) {
+    const key = DESTINATION_KEYS[kind];
+    const patterns = kind === "sms" ? cfg.allowedSmsRecipients : cfg.allowedPushTargets;
+    const value = destinationFor(to, kind);
+    const usable = kind === "push" || isE164Number(value);
+    if (usable &&
+        patterns.some((p) => (p.endsWith("*") ? value.startsWith(p.slice(0, -1)) : value === p))) {
+        return null;
+    }
+    const what = kind === "sms"
+        ? `${JSON.stringify(to)} is not in ${key}${usable ? "" : " (numbers are matched in E.164 form: a + and digits)"}`
+        : `that push target is not in ${key}`;
+    const how = kind === "sms"
+        ? "An operator adds a number in E.164 form, or a prefix such as +44*"
+        : "An operator adds a device token or topic, or a prefix ending in *";
+    return patterns.length === 0
+        ? `${what} (an empty allow-list refuses everyone). ${how}`
+        : `${what}. ${how}`;
+}
+/**
+ * Check `allowed_secret_envs` at boot: a list of variable NAMES. A
+ * malformed entry throws, so a misconfiguration surfaces when the harness
+ * starts, and it is never quoted: an operator who pasted a token here, or
+ * wrote `$SLACK_BOT_TOKEN` (which the bundle resolves to the token itself),
+ * would otherwise see it printed.
+ */
+function buildSecretEnvs(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    if (!Array.isArray(raw)) {
+        throw new NotifyPermissionError(`${SECRET_ENVS_KEY} must be a list of variable names`);
+    }
+    const names = new Set();
+    raw.forEach((name, index) => {
+        if (!isEnvName(name) || looksLikePastedSecret(name)) {
+            throw new NotifyPermissionError(`${SECRET_ENVS_KEY} lists environment variable NAMES (such as SLACK_BOT_TOKEN, written without a $); entry ${index + 1} is not one, and has not been echoed back`);
+        }
+        names.add(name);
+    });
+    return [...names].sort(byString);
+}
 /** Replace the process-global allow-list. Codegen calls this at boot. */
 export function registerNotifyConfig(input) {
     notifyConfig = buildNotifyConfig(input);
@@ -296,7 +415,18 @@ const MAX_TXT_RECORD_CHARS = 8192;
 function withDeadline(work, deadline) {
     return new Promise((resolve, reject) => {
         const signal = deadline.signal;
-        const fail = () => reject(new Error("aborted"));
+        // The signal's own reason, so the caller can tell the deadline's timer
+        // from a runtime cancel by what it caught rather than by the clock.
+        const fail = () => {
+            const reason = signal.reason;
+            if (reason instanceof Error) {
+                reject(reason);
+                return;
+            }
+            const err = new Error("aborted");
+            err.name = "AbortError";
+            reject(err);
+        };
         if (signal.aborted) {
             fail();
             return;
@@ -328,7 +458,10 @@ export async function lookupTxt(name, deadline) {
         raw = await withDeadline(dnsTxtFn(name), deadline);
     }
     catch (err) {
-        if (deadline.expired()) {
+        // An answer that arrived after the deadline's time is still the answer
+        // (an NXDOMAIN is still an NXDOMAIN); only the timer's abort is a
+        // deadline.
+        if (isDeadlineAbort(err, deadline)) {
             return { outcome: "unknown", reason: `the lookup of "${name}" hit the deadline` };
         }
         const code = err.code;
@@ -665,6 +798,19 @@ export function expandIpv6(raw) {
     const groups = parseIpv6(raw);
     return groups === null ? null : [...groups];
 }
+// ---------------------------------------------------------------------------
+// deadlines
+// ---------------------------------------------------------------------------
+/**
+ * The reason a deadline's own timer aborts its signal with. An error is
+ * traced to the deadline by this reason, never by the clock: a transport
+ * failure that merely ARRIVES after the deadline's time (a starved event
+ * loop delivers it before the timer callback runs) is that failure, and a
+ * runtime cancel aborts with the runtime's reason instead.
+ */
+export class DeadlineElapsedError extends Error {
+    name = "TimeoutError";
+}
 /**
  * A deadline that also honours the runtime's own cancellation. Every
  * outbound tool here opens one before its first byte and cancels it in a
@@ -673,7 +819,7 @@ export function expandIpv6(raw) {
 export function startDeadline(ms, outer) {
     const ctrl = new AbortController();
     const startedAt = Date.now();
-    const timer = setTimeout(() => ctrl.abort(new Error(`deadline of ${ms}ms elapsed`)), ms);
+    const timer = setTimeout(() => ctrl.abort(new DeadlineElapsedError(`deadline of ${ms}ms elapsed`)), ms);
     const onOuter = () => ctrl.abort(outer?.reason);
     if (outer !== undefined) {
         if (outer.aborted)
@@ -683,8 +829,9 @@ export function startDeadline(ms, outer) {
     }
     return {
         signal: ctrl.signal,
-        remaining: () => Math.max(0, ms - (Date.now() - startedAt)),
+        remaining: () => (ctrl.signal.aborted ? 0 : Math.max(0, ms - (Date.now() - startedAt))),
         expired: () => Date.now() - startedAt >= ms,
+        timedOut: () => ctrl.signal.aborted && ctrl.signal.reason instanceof DeadlineElapsedError,
         cancel: () => {
             clearTimeout(timer);
             outer?.removeEventListener("abort", onOuter);
@@ -709,60 +856,30 @@ export function sleep(ms, signal) {
         signal?.addEventListener("abort", onAbort, { once: true });
     });
 }
-const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const MAX_ENV_NAME_LENGTH = 64;
-const SECRET_PREFIXES = [
-    "xoxb-",
-    "xoxp-",
-    "xoxa-",
-    "xapp-",
-    "sk_live_",
-    "sk_test_",
-    "ghp_",
-    "github_pat_",
-    "glpat-",
-    "whsec_",
-    "bearer ",
-    "sk-",
-    "ac", // Twilio account sids are `AC` + 32 hex, and are paired with a token
-];
-/** True when a value that arrived as a NAME is really a secret. */
-function looksLikeASecret(value) {
-    const lower = value.toLowerCase();
-    if (lower.startsWith("ac") && /^ac[0-9a-f]{32}$/.test(lower))
-        return true;
-    return SECRET_PREFIXES.filter((p) => p !== "ac").some((prefix) => lower.startsWith(prefix));
-}
 /**
- * Read a secret out of the named environment variable.
+ * Read a secret out of the named environment variable, if and only if
+ * `allowed` lists it.
  *
- * The NAME travels through the tool call; the value never does. A value that
- * is not shaped like an environment variable name, or that carries a known
- * secret prefix, is refused as a pasted credential — and the refusal quotes
- * nothing, because a tool result is a transcript, a trace and usually an
- * eval report.
+ * The NAME travels through the tool call; the value never does. `allowed`
+ * is the operator's `allowed_secret_envs` for a name a call supplies, or a
+ * provider's own `auth.envVar` for that provider's call: a call may choose
+ * among the listed names and never add one, so it cannot send another
+ * process secret (the LLM provider's key, say) to an allowed origin, where
+ * the egress classifier would see only the name. The refusal names the key
+ * to set, reads the same whether or not an unlisted variable is set, and
+ * never quotes a value or a "name" that is really a pasted secret, because a
+ * tool result is a transcript, a trace and usually an eval report.
  */
-export function resolveSecret(envVar, what, env = process.env) {
-    if (envVar === undefined || envVar === "") {
-        return {
-            ok: false,
-            message: `no ${what}: name the environment variable holding it — the secret itself is never accepted as an argument`,
-        };
-    }
-    if (!ENV_NAME.test(envVar) || envVar.length > MAX_ENV_NAME_LENGTH || looksLikeASecret(envVar)) {
-        return {
-            ok: false,
-            message: `${what} must be the NAME of an environment variable (letters, digits and underscores, e.g. SLACK_WEBHOOK_URL), not the secret. The value given is not a usable name and has not been echoed back; if it was the secret itself, treat it as exposed to whoever wrote it and set the variable instead`,
-        };
-    }
-    const value = env[envVar];
-    if (value === undefined || value === "") {
-        return {
-            ok: false,
-            message: `${what} names environment variable "${envVar}", which is unset or empty in this process`,
-        };
-    }
-    return { ok: true, value };
+export function resolveSecret(envVar, what, allowed, env = process.env) {
+    const resolved = resolveCredentialEnv(envVar, {
+        allowed,
+        purpose: what,
+        configKey: SECRET_ENVS_KEY,
+        env,
+    });
+    return resolved.ok
+        ? { ok: true, value: resolved.value }
+        : { ok: false, message: resolved.reason };
 }
 /** Header names that must never be supplied inline, and never survive a hop. */
 export const CREDENTIAL_HEADERS = new Set([
@@ -789,10 +906,10 @@ export function rejectInlineCredentials(headers) {
  * guarded exactly as hard as one that puts it in `Authorization` — and the
  * resolved secret values, which feed the redactor.
  */
-export function applyAuth(headers, auth, env = process.env) {
+export function applyAuth(headers, auth, allowed, env = process.env) {
     if (auth === undefined)
         return { ok: true, secretHeaders: new Set(), secrets: [] };
-    const resolved = resolveSecret(auth.envVar, "auth profile envVar", env);
+    const resolved = resolveSecret(auth.envVar, "the auth profile", allowed, env);
     if (!resolved.ok)
         return { ok: false, message: resolved.message };
     const secret = resolved.value;
@@ -807,9 +924,16 @@ export function applyAuth(headers, auth, env = process.env) {
                 message: 'auth type "basic" needs a username; the password comes from envVar',
             };
         }
-        const encoded = Buffer.from(`${auth.username}:${secret}`, "utf8").toString("base64");
+        const publicPrefix = `${auth.username}:`;
+        const encoded = Buffer.from(`${publicPrefix}${secret}`, "utf8").toString("base64");
         headers["Authorization"] = `Basic ${encoded}`;
-        return { ok: true, secretHeaders: new Set(["authorization"]), secrets: [secret, encoded] };
+        // The pair's `user:` is the account name, not a secret: a reply that
+        // ends with it is left alone, while every spelling of the pair is not.
+        return {
+            ok: true,
+            secretHeaders: new Set(["authorization"]),
+            secrets: [secret, { publicPrefix, secret }],
+        };
     }
     if (auth.headerName === undefined) {
         return { ok: false, message: 'auth type "header" needs a headerName' };
@@ -835,31 +959,42 @@ export function applyAuth(headers, auth, env = process.env) {
  *
  * Secrets shorter than six characters are left alone: replacing every "x" in
  * a result would mangle it without protecting anything real.
+ *
+ * This is tool-safety's redactor: every spelling of a secret, and the part
+ * of one a cut left at a string's end. A cut this package makes itself is
+ * trimmed where it is made ({@link readCapped}, {@link excerptOf}), because a
+ * cut inside a JSON result is not at the end of the text this runs on (net
+ * attacker review: a byte cap through an echoed header returned all but one
+ * character of the credential).
+ *
+ * `identifiers` (an SMTP username) are replaced only whole, as 0.7.0 did:
+ * they are not secrets, so the start of one at a string's end is not cut.
  */
-export function redactorFor(secrets) {
-    const forms = new Set();
-    for (const secret of secrets) {
-        if (secret === undefined || secret.length < 6)
-            continue;
-        forms.add(secret);
-        forms.add(encodeURIComponent(secret));
-        try {
-            forms.add(Buffer.from(secret, "utf8").toString("base64"));
-        }
-        catch {
-            // not encodable — the literal form is still covered
-        }
-    }
-    const ordered = [...forms].filter((f) => f.length >= 6).sort((a, b) => b.length - a.length);
-    if (ordered.length === 0)
-        return (text) => text;
+export function redactorFor(secrets, identifiers = []) {
+    const redactSecrets = createSecretRedactor(secrets);
+    const idForms = [
+        ...new Set(identifiers.flatMap((v) => v === undefined || v.trim().length < 6 ? [] : secretForms(v).filter((f) => f.length >= 6))),
+    ].sort((a, b) => b.length - a.length);
     return (text) => {
-        let out = text;
-        for (const form of ordered)
-            out = out.split(form).join("<redacted>");
+        let out = redactSecrets(text);
+        for (const form of idForms)
+            if (out.includes(form))
+                out = out.split(form).join(REDACTED);
         return out;
     };
 }
+/** The most of a reply an error message quotes. */
+export const EXCERPT_CHARS = 500;
+/**
+ * The first {@link EXCERPT_CHARS} of a reply, for an error message. When
+ * that cuts the reply, whatever part of an echoed credential the cut leaves
+ * at the end is trimmed, since the redactor matches whole spellings.
+ */
+export function excerptOf(text, secrets) {
+    if (text.length <= EXCERPT_CHARS)
+        return text;
+    return trimSecretTail(text.slice(0, EXCERPT_CHARS), secrets);
+}
 /** Response headers as a sorted plain object, credentials removed. */
 const STRIPPED_RESPONSE_HEADERS = new Set([
     "authorization",
@@ -879,13 +1014,19 @@ export function responseHeaders(res) {
 /**
  * Dial the vetted IP while keeping the real hostname for the `Host` header
  * and TLS SNI, so virtual hosting and certificate validation still work.
+ *
+ * Both branches fetch with the body kept RAW (`fetchRaw`, Bun's
+ * `decompress: false`). Without it Bun inflates a gzip, deflate, br or zstd
+ * reply in native code before any reader sees a byte, so a 300 KB gzip reply
+ * cost about 860 MB however small `maxBytes` was (security-5#7).
+ * {@link readCapped} decodes the body itself, under the cap.
  */
 function pinnedFetch(req, pinnedIp) {
     const original = new URL(req.url);
     const host = original.hostname;
     const unbracketed = host.replace(/^\[/, "").replace(/\]$/, "");
     if (unbracketed === pinnedIp || pinnedIp === "")
-        return globalThis.fetch(req);
+        return fetchRaw(req);
     const pinnedUrl = new URL(original.toString());
     pinnedUrl.hostname = pinnedIp.includes(":") ? `[${pinnedIp}]` : pinnedIp;
     const headers = new Headers(req.headers);
@@ -901,7 +1042,7 @@ function pinnedFetch(req, pinnedIp) {
         init.body = req.body;
         init.duplex = "half";
     }
-    return globalThis.fetch(pinnedUrl.toString(), init);
+    return fetchRaw(pinnedUrl.toString(), init);
 }
 let rawFetch = pinnedFetch;
 export function _setRawFetch(fn) {
@@ -921,6 +1062,13 @@ export async function openRequest(o) {
         const lower = name.toLowerCase();
         return CREDENTIAL_HEADERS.has(lower) || o.credentialHeaders?.has(lower) === true;
     };
+    // Ask for the body as it is. The reader decodes gzip, deflate, br and zstd
+    // under the cap anyway, so a provider that compresses regardless still
+    // works; asking for identity just spares the decoding. A caller that set
+    // its own Accept-Encoding keeps it.
+    if (!Object.keys(headers).some((name) => name.toLowerCase() === "accept-encoding")) {
+        headers["accept-encoding"] = "identity";
+    }
     let redirects = 0;
     let credentialsDropped = false;
     let current = o.url;
@@ -993,57 +1141,45 @@ async function discard(res) {
     }
 }
 /**
- * Drain a body with a hard byte cap, cancelling the stream the moment the cap
- * is passed so a hostile endpoint cannot pin memory. The cap bounds what is
- * ever held, not what is kept after buffering.
+ * Drain a body with a hard byte cap on its DECODED size, so a hostile
+ * endpoint cannot pin memory: the body arrives raw (see `pinnedFetch`), a
+ * gzip, deflate, br or zstd body is decoded here in small steps, and the
+ * decoder stops once `maxBytes` exist. The cap bounds what is ever held, not
+ * what is kept after buffering.
+ *
+ * A body this reader cannot decode within the bound (an unknown or stacked
+ * coding, a corrupt stream) is a refusal that quotes nothing the endpoint
+ * sent. An aborted read throws an `AbortError`, so `describeFailure` reports
+ * the deadline or the abort as it does for the request itself.
  */
-export async function readCapped(res, maxBytes) {
-    if (res.body === null)
-        return { text: "", bytes: 0, truncated: false };
-    const reader = res.body.getReader();
-    const chunks = [];
-    let total = 0;
-    let truncated = false;
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done || value === undefined)
-                break;
-            if (total + value.byteLength > maxBytes) {
-                chunks.push(value.subarray(0, maxBytes - total));
-                total = maxBytes;
-                truncated = true;
-                try {
-                    await reader.cancel();
-                }
-                catch {
-                    // already aborting
-                }
-                break;
-            }
-            chunks.push(value);
-            total += value.byteLength;
-        }
+export async function readCapped(res, maxBytes, signal, secrets = []) {
+    const read = await readResponseBounded(res, {
+        maxBytes,
+        ...(signal !== undefined ? { signal } : {}),
+    });
+    if (read.ok) {
+        return {
+            // A cut can fall inside a credential the endpoint echoed; what it
+            // leaves is a prefix no whole spelling matches, so it goes here.
+            text: read.truncated ? trimSecretTail(read.text, secrets) : read.text,
+            bytes: read.bytes.byteLength,
+            truncated: read.truncated,
+        };
     }
-    finally {
-        try {
-            reader.releaseLock();
+    switch (read.code) {
+        case "aborted": {
+            const err = new Error("the read was aborted before the reply ended");
+            err.name = "AbortError";
+            throw err;
         }
-        catch {
-            // already released
-        }
-    }
-    const merged = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        merged.set(chunk, offset);
-        offset += chunk.byteLength;
+        case "unsupported-encoding":
+            throw new NotifyPermissionError("the endpoint sent its reply in a stack of content-encodings this tool cannot decode within its byte cap, so the reply was not read");
+        case "decode-error":
+        case "auto-decompressed":
+            throw new NotifyPermissionError("the endpoint's reply is labelled as compressed but could not be decoded, so it was not read");
+        default:
+            throw new NotifyPermissionError("the endpoint's reply could not be read to the end");
     }
-    return {
-        text: new TextDecoder("utf-8", { fatal: false }).decode(merged),
-        bytes: total,
-        truncated,
-    };
 }
 /** A URL the caller supplied, or a readable refusal that does not echo it. */
 export function parseUrl(raw) {
@@ -1054,6 +1190,42 @@ export function parseUrl(raw) {
         return "that is not an absolute URL — include the scheme, e.g. https://hooks.example.com/services/… (the value has not been echoed back, in case it was a webhook URL, which is itself a credential)";
     }
 }
+/**
+ * True for a value made only of dots. `.` and `..` are the two values
+ * `encodeURIComponent` does NOT neutralise: they encode to themselves, and
+ * the URL parser then RESOLVES them, so a message id of `..` substituted
+ * into `/channels/1/messages/{id}` addresses `/channels/1/` — the channel,
+ * not a message. A dot segment is never an id.
+ */
+export function isDotSegment(value) {
+    return /^\.+$/.test(value);
+}
+/**
+ * `template` with every `placeholder` replaced by `value`, percent-encoded,
+ * as the URL that will be requested — or why not: `invalid` when the
+ * template is not an absolute URL, `reshaped` when the parser would send
+ * the request anywhere but the template's own path with the value written
+ * in.
+ *
+ * The check is made on the URL the parser produced, not on the string it
+ * was built from: the template is also parsed with a sentinel in the
+ * value's place, and the two paths must match once the sentinel is the
+ * value. Whatever normalisation the parser applies (a dot segment today),
+ * a value that changes the shape of the path is refused.
+ */
+export function substituteIntoUrl(template, placeholder, value) {
+    const encoded = encodeURIComponent(value);
+    const parsed = parseUrl(template.split(placeholder).join(encoded));
+    const shape = parseUrl(template.split(placeholder).join(PATH_SENTINEL));
+    if (typeof parsed === "string" || typeof shape === "string")
+        return { ok: false, why: "invalid" };
+    if (parsed.pathname !== shape.pathname.split(PATH_SENTINEL).join(encoded)) {
+        return { ok: false, why: "reshaped" };
+    }
+    return { ok: true, url: parsed };
+}
+/** A path segment no parser rewrites and no real value contains. */
+const PATH_SENTINEL = "crewhaus-substitution-4b1f0c";
 /** Read a dotted path out of a parsed JSON body. `undefined` when absent. */
 export function readPath(value, path) {
     let current = value;
@@ -1081,15 +1253,71 @@ export function readPath(value, path) {
 export function describeFailure(err, deadline) {
     if (err instanceof NotifyPermissionError)
         return err.message;
-    if (deadline?.expired() === true)
+    // The cause decides, not the clock: see DeadlineElapsedError.
+    if (isDeadlineAbort(err, deadline))
         return "deadline elapsed before the send completed";
+    const aborted = "the send was aborted before it completed";
+    if (deadline?.signal.aborted === true && err === deadline.signal.reason)
+        return aborted;
     if (err instanceof Error) {
         if (err.name === "AbortError")
-            return "the send was aborted before it completed";
-        return `${err.name}: ${err.message}`;
+            return aborted;
+        // A real failure that arrived late is still that failure; the clock is
+        // mentioned, because the caller may want a longer deadline as well.
+        const late = deadline?.expired() === true ? " (the deadline had also elapsed)" : "";
+        return `${err.name}: ${err.message}${late}`;
     }
     return String(err);
 }
+/**
+ * Whether `err` is what the deadline's own timer did: its abort reason, or an
+ * abort-shaped error (a body reader's AbortError) raised after that timer
+ * fired. Exported for the few callers that report a deadline themselves.
+ */
+export function isDeadlineAbort(err, deadline) {
+    if (err instanceof DeadlineElapsedError)
+        return true;
+    if (deadline?.timedOut() !== true)
+        return false;
+    if (err === deadline.signal.reason)
+        return true;
+    return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+}
+const DELIVERY_KNOBS = new Set([
+    "idempotencyKey",
+    "idempotencyHeader",
+    "timeoutMs",
+    "maxBytes",
+    "retries",
+    "backoffMs",
+    "justification",
+]);
+/** Object keys sorted, so `{a, b}` and `{b, a}` are one request. */
+function sortedKeys(_key, value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const sorted = Object.create(null);
+    for (const key of Object.keys(value).sort()) {
+        sorted[key] = value[key];
+    }
+    return sorted;
+}
+export function requestFingerprint(args) {
+    const fields = new Map();
+    for (const key of Object.keys(args).sort()) {
+        const value = args[key];
+        if (DELIVERY_KNOBS.has(key) || value === undefined)
+            continue;
+        const canonical = JSON.stringify(value, sortedKeys) ?? "undefined";
+        fields.set(key, createHash("sha256").update(canonical, "utf8").digest("hex"));
+    }
+    return fields;
+}
+/** The fields two fingerprints disagree on, sorted; empty when they match. */
+function differingFields(a, b) {
+    const names = new Set([...a.keys(), ...b.keys()]);
+    return [...names].filter((name) => a.get(name) !== b.get(name)).sort(byString);
+}
 /**
  * The per-process record of what has already been sent under which key.
  *
@@ -1097,8 +1325,14 @@ export function describeFailure(err, deadline) {
  * agent, and "post it again" is the wrong answer when the first post
  * succeeded. Every sending tool takes an `idempotencyKey`; the key is passed
  * to the provider when the provider honours one, AND recorded here, so a
- * second call with the same key returns the first call's result and posts
- * nothing.
+ * second call with the same key and the same request returns the first
+ * call's result and posts nothing.
+ *
+ * A key names ONE request. The same key with a different destination or
+ * body used to be answered from here too, so it returned the first call's
+ * `sent: true` and message id for a message that was never sent. It is now
+ * a `conflict`, which the tool refuses (as a provider that honours
+ * Idempotency-Key would), and nothing goes out.
  *
  * This is deliberate hidden state, and it is the one place in the package
  * where a repeated call does not repeat its effect — which is the entire
@@ -1108,12 +1342,24 @@ export function describeFailure(err, deadline) {
  */
 const LEDGER_LIMIT = 512;
 const ledger = new Map();
-export function ledgerLookup(tool, key) {
+/**
+ * `ignoring` names fields left out of the comparison: EmailSend asks with
+ * `attachmentContent` ignored when an attachment can no longer be read, so
+ * a retry after a temp file was cleaned up finds the message it already
+ * sent instead of reporting it unsent.
+ */
+export function ledgerLookup(tool, key, fingerprint, ignoring = []) {
     if (key === undefined || key === "")
         return undefined;
-    return ledger.get(`${tool}\u0000${key}`);
+    const entry = ledger.get(`${tool}\u0000${key}`);
+    if (entry === undefined)
+        return undefined;
+    const differs = differingFields(entry.fingerprint, fingerprint).filter((name) => !ignoring.includes(name));
+    return differs.length === 0
+        ? { kind: "replay", result: entry.result }
+        : { kind: "conflict", differs };
 }
-export function ledgerRecord(tool, key, result) {
+export function ledgerRecord(tool, key, fingerprint, result) {
     if (key === undefined || key === "")
         return;
     const id = `${tool}\u0000${key}`;
@@ -1123,7 +1369,7 @@ export function ledgerRecord(tool, key, result) {
         if (!oldest.done)
             ledger.delete(oldest.value);
     }
-    ledger.set(id, { tool, result });
+    ledger.set(id, { tool, fingerprint, result });
 }
 /** Test-only — a fresh process's empty ledger. */
 export function _resetIdempotencyLedger() {