@crewhaus/tool-notify 0.7.0

package/dist/lib/ratelimit.js

@@ -0,0 +1,87 @@
+/**
+ * "Have I already told them about this?" — as a pure function over a state
+ * record the caller keeps.
+ *
+ * A harness that notices the same broken thing on every loop iteration will
+ * notify about it on every loop iteration unless something remembers. That
+ * memory has to live somewhere the harness controls (a KV entry, a file, a
+ * field on its own state) rather than inside a tool, because a tool's
+ * process-local memory dies with the process and the flood comes back after
+ * the first restart. So this takes the state in and hands the next state
+ * back, and the caller persists it wherever its state already lives.
+ *
+ * Fixed windows, not a sliding log. A sliding window needs every timestamp
+ * retained, which grows without bound in exactly the situation the gate
+ * exists for; a fixed window costs two numbers per key and is easy to
+ * reason about out loud ("at most 3 per hour per key").
+ */
+/**
+ * How many expired windows to keep before pruning. A state record that only
+ * ever grows is a slow leak in whatever the harness persists it to, so
+ * entries whose window ended more than `windowMs` ago are dropped — they can
+ * no longer refuse anything, so nothing is lost by forgetting them.
+ */
+function prune(state, nowMs, windowMs, keep) {
+    const kept = {};
+    const pruned = [];
+    for (const name of Object.keys(state).sort()) {
+        const entry = state[name];
+        if (name !== keep && nowMs - entry.windowStart >= windowMs * 2) {
+            pruned.push(name);
+            continue;
+        }
+        kept[name] = entry;
+    }
+    return { kept, pruned };
+}
+/** Decide, and hand back the record to persist. */
+export function rateLimitGate(options) {
+    const limit = Math.max(1, options.limit ?? 1);
+    const windowMs = Math.max(1, options.windowMs);
+    const state = options.state ?? {};
+    const { kept, pruned } = prune(state, options.nowMs, windowMs, options.key);
+    const existing = kept[options.key];
+    const inWindow = existing !== undefined && options.nowMs - existing.windowStart < windowMs;
+    const current = inWindow ? existing : undefined;
+    const count = current?.count ?? 0;
+    if (count >= limit) {
+        const windowStart = current.windowStart;
+        const resetAt = windowStart + windowMs;
+        return {
+            allowed: false,
+            reason: `"${options.key}" has already been notified ${count} time(s) in this window of ${windowMs}ms, which is the limit`,
+            count,
+            limit,
+            retryAfterMs: Math.max(0, resetAt - options.nowMs),
+            retryAt: new Date(resetAt).toISOString(),
+            nextState: kept,
+            pruned,
+        };
+    }
+    if (options.mode === "peek") {
+        return {
+            allowed: true,
+            reason: `"${options.key}" is under the limit; nothing was recorded because mode is "peek"`,
+            count,
+            limit,
+            nextState: kept,
+            pruned,
+        };
+    }
+    const next = { ...kept };
+    next[options.key] = {
+        windowStart: current?.windowStart ?? options.nowMs,
+        count: count + 1,
+        last: options.nowMs,
+    };
+    return {
+        allowed: true,
+        reason: count === 0
+            ? `"${options.key}" has not been notified in this window`
+            : `"${options.key}" is under the limit of ${limit} per ${windowMs}ms`,
+        count: count + 1,
+        limit,
+        nextState: next,
+        pruned,
+    };
+}

package/dist/lib/sign.d.ts

@@ -0,0 +1,8 @@
+export type SignatureScheme = "timestamped" | "body";
+export type SignatureAlgorithm = "sha256" | "sha1";
+/** The string a scheme runs the MAC over. */
+export declare function signedPayload(scheme: SignatureScheme, body: string, timestampSeconds?: number): string;
+/** Lowercase hex HMAC. */
+export declare function hmacHex(secret: string, payload: string, algorithm?: SignatureAlgorithm): string;
+/** The header value a sender transmits for this signature. */
+export declare function formatSignatureHeader(scheme: SignatureScheme, hex: string, algorithm: SignatureAlgorithm, timestampSeconds?: number): string;

package/dist/lib/sign.js

@@ -0,0 +1,39 @@
+/**
+ * Webhook signing, in the two shapes providers actually ship.
+ *
+ *   "timestamped" — Stripe's scheme. The MAC covers `<unix-seconds>.<body>`
+ *     and the header reads `t=<unix-seconds>,v1=<hex>`. The timestamp is
+ *     inside the MAC, so a receiver can enforce a replay window.
+ *
+ *   "body" — GitHub's scheme. The MAC covers the raw body and the header
+ *     reads `sha256=<hex>`. There is no timestamp and therefore no replay
+ *     protection; naming the schemes by what they cover rather than by
+ *     vendor is how that stays visible.
+ *
+ * The MAC must run over the EXACT bytes that are transmitted. The signer
+ * therefore takes the serialised body, and the tool signs the same string it
+ * puts on the wire — re-serialising a parsed object between signing and
+ * sending changes the bytes and every verification downstream fails.
+ *
+ * Nothing here reads the clock: `timestampSeconds` is an argument.
+ */
+import { createHmac } from "node:crypto";
+/** The string a scheme runs the MAC over. */
+export function signedPayload(scheme, body, timestampSeconds) {
+    if (scheme === "body")
+        return body;
+    if (timestampSeconds === undefined) {
+        throw new Error('the "timestamped" scheme needs a timestamp');
+    }
+    return `${timestampSeconds}.${body}`;
+}
+/** Lowercase hex HMAC. */
+export function hmacHex(secret, payload, algorithm = "sha256") {
+    return createHmac(algorithm, secret).update(payload, "utf8").digest("hex");
+}
+/** The header value a sender transmits for this signature. */
+export function formatSignatureHeader(scheme, hex, algorithm, timestampSeconds) {
+    if (scheme === "body")
+        return `${algorithm}=${hex}`;
+    return `t=${timestampSeconds},v1=${hex}`;
+}

package/dist/lib/template.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Message templates, where the operator owns the structure and the model
+ * only ever supplies values.
+ *
+ * `@crewhaus/tool-text`'s `RenderTemplate` fills placeholders in a string.
+ * This is the same idea with one extra rule that matters here and nowhere
+ * else: the values are escaped for the platform the message is going to,
+ * BEFORE they are substituted. A deploy summary containing `<!channel>` or
+ * ```` ``` ```` would otherwise change what the message does, not just what
+ * it says — which is the whole reason a harness should not be assembling
+ * notification strings by hand.
+ *
+ * Missing keys are an error, never an empty string. A notification that
+ * silently reads "deploy of  failed at " is worse than one that did not go
+ * out, because somebody acts on it.
+ */
+import type { Platform } from "./blocks";
+export type RenderResult = {
+    readonly ok: true;
+    readonly text: string;
+    /** Placeholder names that were filled, sorted and de-duplicated. */
+    readonly used: readonly string[];
+    /** Keys present in the data that no placeholder asked for. */
+    readonly unused: readonly string[];
+} | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+};
+/** All the placeholder names a template refers to, in first-seen order. */
+export declare function templatePlaceholders(template: string): string[];
+/**
+ * Fill `template` from `data`, escaping every substituted value for
+ * `platform`.
+ *
+ * The template itself is NOT escaped: it is operator-authored, so its `*`
+ * and `<…|…>` are the formatting the operator intended. Only the values are,
+ * which is exactly the boundary that makes the result safe — a value can
+ * never introduce structure, and the structure can never be introduced by
+ * anything but the template.
+ */
+export declare function renderTemplate(template: string, data: Readonly<Record<string, unknown>>, platform: Platform): RenderResult;

package/dist/lib/template.js

@@ -0,0 +1,85 @@
+import { escapeFor } from "./blocks";
+/** `{{ name }}` or `{{ a.b.c }}`; whitespace inside the braces is ignored. */
+const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_][A-Za-z0-9_.]*)\s*\}\}/g;
+/** Read a dotted path out of the data object. */
+function lookup(data, path) {
+    let current = data;
+    for (const segment of path.split(".")) {
+        if (current === null || typeof current !== "object" || Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * How a value becomes text.
+ *
+ * Numbers and booleans are written out; `null` and `undefined` count as
+ * missing rather than rendering the word "null"; objects and arrays are
+ * JSON-encoded, because a template that interpolates a structure wants to
+ * SHOW it, and `[object Object]` in a production alert helps nobody.
+ */
+function stringify(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? String(value) : null;
+    if (typeof value === "boolean")
+        return String(value);
+    if (typeof value === "bigint")
+        return value.toString();
+    try {
+        return JSON.stringify(value) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** All the placeholder names a template refers to, in first-seen order. */
+export function templatePlaceholders(template) {
+    const out = [];
+    const seen = new Set();
+    for (const match of template.matchAll(PLACEHOLDER)) {
+        const name = match[1];
+        if (!seen.has(name)) {
+            seen.add(name);
+            out.push(name);
+        }
+    }
+    return out;
+}
+/**
+ * Fill `template` from `data`, escaping every substituted value for
+ * `platform`.
+ *
+ * The template itself is NOT escaped: it is operator-authored, so its `*`
+ * and `<…|…>` are the formatting the operator intended. Only the values are,
+ * which is exactly the boundary that makes the result safe — a value can
+ * never introduce structure, and the structure can never be introduced by
+ * anything but the template.
+ */
+export function renderTemplate(template, data, platform) {
+    const missing = [];
+    const used = new Set();
+    const text = template.replace(PLACEHOLDER, (_whole, rawName) => {
+        const name = rawName;
+        const value = stringify(lookup(data, name));
+        if (value === null) {
+            missing.push(name);
+            return "";
+        }
+        used.add(name);
+        return escapeFor(platform, value);
+    });
+    if (missing.length > 0) {
+        return { ok: false, missing: [...new Set(missing)].sort() };
+    }
+    const referenced = new Set(templatePlaceholders(template).map((n) => n.split(".")[0]));
+    const unused = Object.keys(data)
+        .filter((key) => !referenced.has(key))
+        .sort();
+    return { ok: true, text, used: [...used].sort(), unused };
+}

package/dist/net.d.ts

@@ -0,0 +1,391 @@
+import { CrewhausError } from "@crewhaus/errors";
+/** Refusal by the allow-list, the SSRF gate, or a redirect rule. */
+export declare class NotifyPermissionError extends CrewhausError {
+    readonly name = "NotifyPermissionError";
+    constructor(message: string);
+}
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare const MAX_TIMEOUT_MS = 300000;
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const MAX_MAX_BYTES: number;
+export declare const MAX_REDIRECTS = 3;
+/** Compact JSON — every byte returned is a byte in somebody's context window. */
+export declare const json: (value: unknown) => string;
+/** Locale-independent string order. `localeCompare` without a locale is not deterministic. */
+export declare function byString(a: string, b: string): number;
+/**
+ * A REST provider described by the operator rather than hard-coded here.
+ *
+ * `SmsSend`, `PushNotify` and `DeliveryCheck` all speak this shape. Naming a
+ * vendor in the code would mean a new release every time somebody moves from
+ * one gateway to another; naming the endpoint, the auth variable and the
+ * field mapping in the spec means the operator does it in a diff.
+ */
+export type ProviderProfile = {
+    /** Absolute https URL. Its origin must also be in `allowed_origins`. */
+    readonly endpoint: string;
+    /** POST unless the provider insists otherwise. */
+    readonly method?: string;
+    /** "json" (default) or "form" — how the mapped fields are encoded. */
+    readonly encoding?: "json" | "form";
+    readonly auth?: AuthProfile;
+    /**
+     * Canonical field name → the provider's own field name. `to`, `body`,
+     * `from`, `title`, `mediaUrl` and `data` are the names the tools use.
+     */
+    readonly fields?: Readonly<Record<string, string>>;
+    /** Constant fields merged into every request (a sender id, an app id). */
+    readonly staticFields?: Readonly<Record<string, string>>;
+    /** Dotted path in the response holding the provider's message id. */
+    readonly idPath?: string;
+    /** Dotted path in the response holding a delivery status. */
+    readonly statusPath?: string;
+    /** URL template for `DeliveryCheck`; `{id}` is substituted. */
+    readonly statusEndpoint?: string;
+    /** Header carrying an idempotency key, when the provider honours one. */
+    readonly idempotencyHeader?: string;
+};
+export type NotifyConfig = {
+    /** Canonical origins. Empty (the default) denies every request. */
+    readonly allowedOrigins: ReadonlySet<string>;
+    /**
+     * Who email may be addressed to: a full address, or `*@domain`. Empty
+     * denies every recipient, which makes `EmailSend` unusable until an
+     * operator says who the harness is allowed to write to.
+     */
+    readonly allowedRecipients: readonly string[];
+    /** SMTP hosts the client may dial. Empty denies every one. */
+    readonly allowedSmtpHosts: ReadonlySet<string>;
+    /**
+     * Domains this harness may ask public DNS about, canonicalised. Empty
+     * denies every one, which makes `DeliverabilityCheck` unusable until an
+     * operator says which domains are theirs.
+     *
+     * A DNS query is not an HTTP request and so does not pass through the
+     * origin allow-list — but the name queried is still chosen by the caller
+     * and still leaves the machine, which is the shape of an exfiltration
+     * channel. This is the gate for that surface, and it is fail-closed like
+     * every other one here.
+     */
+    readonly allowedSenderDomains: ReadonlySet<string>;
+    /** Named REST providers for SMS, push and delivery lookups. */
+    readonly providers: ReadonlyMap<string, ProviderProfile>;
+};
+export type NotifyConfigInput = {
+    readonly allowed_origins?: readonly string[];
+    readonly allowedOrigins?: readonly string[];
+    readonly allowed_recipients?: readonly string[];
+    readonly allowedRecipients?: readonly string[];
+    readonly allowed_smtp_hosts?: readonly string[];
+    readonly allowedSmtpHosts?: readonly string[];
+    readonly allowed_sender_domains?: readonly string[];
+    readonly allowedSenderDomains?: readonly string[];
+    readonly providers?: Readonly<Record<string, ProviderProfile>>;
+};
+/** Build a config from a spec-shaped block. Pure; both key spellings accepted. */
+export declare function buildNotifyConfig(input: NotifyConfigInput): NotifyConfig;
+/** Replace the process-global allow-list. Codegen calls this at boot. */
+export declare function registerNotifyConfig(input: NotifyConfigInput): void;
+export declare function getNotifyConfig(): NotifyConfig;
+/**
+ * The config ONE call runs under: the serving candidate's
+ * `tool_config.notify` block when it declares one, else the boot
+ * registration. A non-object override is ignored rather than widened — the
+ * allow-list only ever comes from a spec block.
+ */
+export declare function resolveNotifyConfig(override: unknown): NotifyConfig;
+/** Test-only — back to fail-closed empty. */
+export declare function _resetNotifyConfig(): void;
+/**
+ * Canonicalise an origin for exact-match comparison: lowercase scheme and
+ * host, drop path/query/fragment, elide the default port. Throws on a
+ * malformed origin so a misconfiguration surfaces at boot, not at the first
+ * send.
+ */
+export declare function canonicalizeOrigin(raw: string): string;
+/**
+ * The origin of a URL already parsed, without putting the URL back into any
+ * message. `label` is what a refusal may name — never the full URL, because
+ * a Slack or Teams incoming-webhook URL IS the credential, and an error
+ * string is a thing that ends up in a transcript.
+ */
+export declare function canonicalizeUrlOrigin(url: URL, label?: string): string;
+/**
+ * How a webhook URL is allowed to appear in a message: scheme, host and a
+ * path length, with the path itself and the query dropped.
+ *
+ * A Slack incoming webhook (`/services/T…/B…/xxxx`) and a Discord one
+ * (`/api/webhooks/<id>/<token>`) both carry their whole authority in the
+ * path. Printing the path into a refusal would post the credential into the
+ * transcript, so only its shape is printed.
+ */
+export declare function safeUrlLabel(raw: string | URL): string;
+/** Refuse a URL that carries `user:pass@`. */
+export declare function assertNoUserinfo(url: URL): void;
+/** Refuse a URL whose origin is not allow-listed. Empty list ⇒ refuse everything. */
+export declare function assertOriginAllowed(url: URL, cfg: NotifyConfig): void;
+/** Refuse an SMTP host no operator named. Empty list ⇒ refuse everything. */
+export declare function assertSmtpHostAllowed(host: string, cfg: NotifyConfig): void;
+/**
+ * Refuse a domain no operator named. Empty list ⇒ refuse everything.
+ *
+ * `domain` must ALREADY be the canonical form — the caller normalises once
+ * and then uses that one value for the gate, for the names it derives and
+ * for what it reports, so there is no spelling that passes the check and a
+ * different one that reaches the resolver.
+ */
+export declare function assertSenderDomainAllowed(domain: string, cfg: NotifyConfig): void;
+/**
+ * Does `address` match an allow-list entry?
+ *
+ * An entry is either a whole address or `*@domain`. A bare domain is NOT
+ * accepted as a wildcard: `example.com` would read to a human as "anyone at
+ * example.com" and to this function as "the address example.com", and a gate
+ * whose entries mean one thing to the operator and another to the code is
+ * not a gate. Matching is case-insensitive on the whole address, which is
+ * looser than RFC 5321 (local-parts are technically case-sensitive) and the
+ * looseness is in the safe direction only for the domain — so a deliberately
+ * case-varied local part cannot slip a DIFFERENT mailbox past an entry,
+ * because the entry had to name that mailbox's spelling in the first place.
+ */
+export declare function recipientAllowed(address: string, cfg: NotifyConfig): boolean;
+export type DnsLookupFn = (host: string) => Promise<{
+    readonly address: string;
+    readonly family: number;
+}>;
+/** Test-only resolver injection, as in `@crewhaus/tool-http`. */
+export declare function _setDnsLookup(fn: DnsLookupFn | undefined): void;
+/**
+ * Every TXT record at a name, each still split into the character-strings
+ * DNS carried it in. The joining rule belongs to the parser, not here, so
+ * the seam a test injects hands back exactly what a resolver hands back.
+ */
+export type DnsTxtFn = (name: string) => Promise<ReadonlyArray<ReadonlyArray<string>>>;
+/** Test-only resolver injection. No test in this package may reach real DNS. */
+export declare function _setDnsTxtResolver(fn: DnsTxtFn | undefined): void;
+/**
+ * What a TXT lookup found — with "nothing is published" and "the question
+ * could not be answered" kept apart.
+ *
+ * This is the whole reason the type has four arms rather than returning
+ * `string[]`. "No SPF record" is a finding about a domain; "the resolver
+ * returned SERVFAIL" is a finding about the lookup, and reporting the second
+ * as the first tells somebody their DNS is fine when nobody asked it
+ * anything.
+ */
+export type TxtAnswer = {
+    readonly outcome: "records";
+    readonly records: readonly string[];
+}
+/** The name exists and publishes no TXT record. */
+ | {
+    readonly outcome: "none";
+}
+/** The name does not exist at all. */
+ | {
+    readonly outcome: "nxdomain";
+} | {
+    readonly outcome: "unknown";
+    readonly reason: string;
+};
+/**
+ * Ask for the TXT records at `name`.
+ *
+ * The two codes that ARE answers are mapped to answers: c-ares reports
+ * NXDOMAIN as `ENOTFOUND` and "the name exists but has no record of this
+ * type" as `ENODATA`, and both of those genuinely mean nothing is published.
+ * Everything else — SERVFAIL, a refused query, a timeout, a resolver that is
+ * not reachable — is `unknown` WITH the reason, because a lookup that did
+ * not happen must not read as a domain that published nothing.
+ */
+export declare function lookupTxt(name: string, deadline: Deadline): Promise<TxtAnswer>;
+export declare function __setPrivateHostsAllowedForTest(allowed: boolean): void;
+/**
+ * Reject a host that is — or resolves to — loopback, link-local, RFC1918,
+ * CGNAT, or mDNS. Returns the vetted IP so the caller can pin the socket to
+ * it instead of letting the stack re-resolve at connect time.
+ */
+export declare function assertNotSsrf(hostname: string): Promise<string>;
+/**
+ * Canonicalise an IPv4 literal.
+ *
+ * `inet_aton` forms are the classic allow-list bypass: `0177.0.0.1`,
+ * `0x7f.0.0.1`, `2130706433` and `127.1` are all 127.0.0.1, and a check that
+ * only understands dotted-decimal waves every one of them through. Returns
+ * `null` when the string is not an IPv4 literal at all.
+ */
+export declare function normalizeIpv4(raw: string): string | null;
+/**
+ * Expand an IPv6 literal to its eight 16-bit groups, or `null` when the string
+ * is not one.
+ *
+ * Classifying IPv6 by its TEXT is where the bypasses live, because one address
+ * has many spellings and the one a check was written against is rarely the one
+ * that arrives. `http://[::ffff:169.254.169.254]/` never reaches a guard in
+ * that form: the WHATWG URL parser re-serialises the embedded quad as hex
+ * pieces, so what the guard sees is `::ffff:a9fe:a9fe`. Normalising to numbers
+ * first means the prefix tests below are arithmetic, and spelling stops
+ * mattering.
+ */
+export declare function parseIpv6(raw: string): ReadonlyArray<number> | null;
+/** Ranges that are never a public RPC endpoint. */
+export declare function isPrivateIp(address: string): boolean;
+/**
+ * `parseIpv6` under this package's older name, returning a mutable array.
+ *
+ * Deliberately OUTSIDE the synchronised block: `smtp.ts` uses it to decide
+ * whether a host is an IP literal and so has no SNI name, the SSRF gate
+ * re-emits an IPv6 literal in expanded form from it, and `lib.test.ts`
+ * imports it. The block's own text must not change, so the adaptation to
+ * this package's older name and signature lives here instead.
+ */
+export declare function expandIpv6(raw: string): number[] | null;
+export type Deadline = {
+    readonly signal: AbortSignal;
+    /** Milliseconds left; never negative. */
+    remaining(): number;
+    expired(): boolean;
+    /** Clear the timer. Always call it, or the process keeps a handle alive. */
+    cancel(): void;
+};
+/**
+ * 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
+ * `finally` — a tool that can hang forever is a defect.
+ */
+export declare function startDeadline(ms: number, outer?: AbortSignal): Deadline;
+/** Resolve after `ms`, or as soon as `signal` aborts. Never rejects. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * An auth profile names an ENVIRONMENT VARIABLE, never a literal secret. A
+ * model that can put a token in a tool argument is a model that can put it in
+ * a transcript, a trace event and an eval report.
+ */
+export type AuthProfile = {
+    readonly type: "bearer" | "basic" | "header";
+    readonly envVar: string;
+    /** Header name for `type: "header"` (e.g. `X-Api-Key`). */
+    readonly headerName?: string;
+    /** Username for `type: "basic"`; the password comes from `envVar`. */
+    readonly username?: string;
+    /** Literal prefix before the secret for `type: "header"` (e.g. `token `). */
+    readonly prefix?: string;
+};
+export type ResolvedSecret = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Read a secret out of the named environment variable.
+ *
+ * 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.
+ */
+export declare function resolveSecret(envVar: string | undefined, what: string, env?: Record<string, string | undefined>): ResolvedSecret;
+/** Header names that must never be supplied inline, and never survive a hop. */
+export declare const CREDENTIAL_HEADERS: ReadonlySet<string>;
+/**
+ * Refuse caller-supplied credential headers. The `auth` profile is the only
+ * way to attach one, which keeps the secret out of the tool arguments and
+ * therefore out of the transcript.
+ */
+export declare function rejectInlineCredentials(headers: Record<string, string>): string | null;
+export type AppliedAuth = {
+    readonly ok: true;
+    readonly secretHeaders: ReadonlySet<string>;
+    readonly secrets: string[];
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/**
+ * Apply an auth profile to `headers`. Returns the lowercased names of the
+ * headers it set — so a profile that puts the secret in `X-Api-Key` is
+ * guarded exactly as hard as one that puts it in `Authorization` — and the
+ * resolved secret values, which feed the redactor.
+ */
+export declare function applyAuth(headers: Record<string, string>, auth: AuthProfile | undefined, env?: Record<string, string | undefined>): AppliedAuth;
+/**
+ * A function that scrubs secrets out of anything on its way back to the
+ * caller.
+ *
+ * Everything this package returns — results, refusals, the text of a
+ * provider error, an SMTP server's reply — goes through one of these. It is
+ * the backstop rather than the primary defence: a secret is only ever placed
+ * in a header or an SMTP AUTH line, never in a path or a body. But a
+ * provider that echoes a header, a transport error that quotes a request, or
+ * an SMTP server that repeats what it was sent would each put the secret in
+ * a transcript, and that is not a mistake worth leaving one layer deep.
+ *
+ * Secrets shorter than six characters are left alone: replacing every "x" in
+ * a result would mangle it without protecting anything real.
+ */
+export declare function redactorFor(secrets: readonly (string | undefined)[]): (text: string) => string;
+export declare function responseHeaders(res: Response): Record<string, string>;
+export type RawFetch = (req: Request, pinnedIp: string) => Promise<Response>;
+export declare function _setRawFetch(fn: RawFetch | undefined): void;
+export type OpenOptions = {
+    readonly url: URL;
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body?: string | undefined;
+    readonly signal: AbortSignal;
+    readonly cfg: NotifyConfig;
+    /**
+     * `"refuse"` (the default for every send) reports a 3xx as a failure.
+     * `"follow"` is for read-only lookups and re-runs the whole gate per hop.
+     */
+    readonly redirect?: "refuse" | "follow";
+    readonly maxRedirects?: number;
+    /** Lowercased header names to treat as credentials on this call. */
+    readonly credentialHeaders?: ReadonlySet<string>;
+};
+export type OpenResult = {
+    readonly res: Response;
+    readonly redirects: number;
+    /** True when a cross-origin hop dropped the credential headers. */
+    readonly credentialsDropped: boolean;
+};
+/**
+ * Issue a request. Redirects, when followed at all, are followed by hand so
+ * the allow-list, the SSRF gate and the credential rules run on every single
+ * hop. The response body is left unread — the caller decides how to drain it
+ * under which cap.
+ */
+export declare function openRequest(o: OpenOptions): Promise<OpenResult>;
+export type CappedBody = {
+    readonly text: string;
+    readonly bytes: number;
+    /** True when the cap cut the read short; `text` is the prefix that fit. */
+    readonly truncated: boolean;
+};
+/**
+ * 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.
+ */
+export declare function readCapped(res: Response, maxBytes: number): Promise<CappedBody>;
+/** A URL the caller supplied, or a readable refusal that does not echo it. */
+export declare function parseUrl(raw: string): URL | string;
+/** Read a dotted path out of a parsed JSON body. `undefined` when absent. */
+export declare function readPath(value: unknown, path: string): unknown;
+/**
+ * Turn anything thrown on the outbound path into the one-line string a tool
+ * returns. A refusal, a deadline and a transport failure read differently,
+ * because the caller's next move differs.
+ */
+export declare function describeFailure(err: unknown, deadline?: Deadline): string;
+export type LedgerEntry = {
+    readonly tool: string;
+    readonly result: string;
+};
+export declare function ledgerLookup(tool: string, key: string | undefined): LedgerEntry | undefined;
+export declare function ledgerRecord(tool: string, key: string | undefined, result: string): void;
+/** Test-only — a fresh process's empty ledger. */
+export declare function _resetIdempotencyLedger(): void;