@crewhaus/tool-notify 0.7.0 → 0.8.0

package/dist/net.d.ts

@@ -1,4 +1,5 @@
 import { CrewhausError } from "@crewhaus/errors";
+import { type SecretValue } from "@crewhaus/tool-safety/env";
 /** Refusal by the allow-list, the SSRF gate, or a redirect rule. */
 export declare class NotifyPermissionError extends CrewhausError {
     readonly name = "NotifyPermissionError";
@@ -70,6 +71,23 @@ export type NotifyConfig = {
     readonly allowedSenderDomains: ReadonlySet<string>;
     /** Named REST providers for SMS, push and delivery lookups. */
     readonly providers: ReadonlyMap<string, ProviderProfile>;
+    /**
+     * The environment variables a tool call may name as a credential: a bot
+     * token, a webhook URL, a WebhookPost auth or signing secret, SMTP
+     * credentials. Empty (the default) refuses every such name. A provider's
+     * own `auth.envVar` is operator-written and needs no listing, but it is
+     * read only for that provider, never by a name a call supplies.
+     */
+    readonly allowedSecretEnvs: readonly string[];
+    /**
+     * The numbers `SmsSend` may address, in E.164 form: an exact number, or a
+     * prefix ending in `*` (`+44*`). Empty (the default) refuses every number,
+     * as `allowedRecipients` refuses every address: an SMS costs money, and a
+     * number the model chooses is the premium-rate pumping surface.
+     */
+    readonly allowedSmsRecipients: readonly string[];
+    /** The device tokens or topics `PushNotify` may address: exact, or a `prefix*`. Empty refuses all. */
+    readonly allowedPushTargets: readonly string[];
 };
 export type NotifyConfigInput = {
     readonly allowed_origins?: readonly string[];
@@ -81,9 +99,41 @@ export type NotifyConfigInput = {
     readonly allowed_sender_domains?: readonly string[];
     readonly allowedSenderDomains?: readonly string[];
     readonly providers?: Readonly<Record<string, ProviderProfile>>;
+    readonly allowed_secret_envs?: readonly string[];
+    readonly allowedSecretEnvs?: readonly string[];
+    readonly allowed_sms_recipients?: readonly string[];
+    readonly allowedSmsRecipients?: readonly string[];
+    readonly allowed_push_targets?: readonly string[];
+    readonly allowedPushTargets?: readonly string[];
 };
+/** Where an operator allows a credential variable. Every refusal names it. */
+export declare const SECRET_ENVS_KEY = "tool_config.notify.allowed_secret_envs";
 /** Build a config from a spec-shaped block. Pure; both key spellings accepted. */
 export declare function buildNotifyConfig(input: NotifyConfigInput): NotifyConfig;
+/** Which allow-list a provider send's destination is checked against. */
+export type DestinationKind = "sms" | "push";
+/**
+ * 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 declare const normalizeSmsNumber: (raw: string) => string;
+/**
+ * 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 declare function destinationFor(to: string, kind: DestinationKind): string;
+/**
+ * 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 declare function destinationRefusal(to: string, kind: DestinationKind, cfg: NotifyConfig): string | null;
 /** Replace the process-global allow-list. Codegen calls this at boot. */
 export declare function registerNotifyConfig(input: NotifyConfigInput): void;
 export declare function getNotifyConfig(): NotifyConfig;
@@ -240,11 +290,38 @@ export declare function isPrivateIp(address: string): boolean;
  * this package's older name and signature lives here instead.
  */
 export declare function expandIpv6(raw: string): number[] | null;
+/**
+ * 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 declare class DeadlineElapsedError extends Error {
+    readonly name = "TimeoutError";
+}
 export type Deadline = {
     readonly signal: AbortSignal;
-    /** Milliseconds left; never negative. */
+    /**
+     * Milliseconds left; never negative, and 0 once the signal has aborted —
+     * by the timer, an outer deadline or a cancel — whatever the clock says.
+     * Ask it before starting more work: 0 means start nothing.
+     */
     remaining(): number;
+    /**
+     * The clock says the time is up. The clock can lag the timer and never
+     * sees a cancel, so it decides neither whether to start more work — that
+     * is {@link remaining} — nor why something failed — that is
+     * {@link timedOut}. It only notes, beside a failure of its own, that the
+     * time had run out as well.
+     */
     expired(): boolean;
+    /**
+     * The deadline's timer — or an outer deadline's, forwarded — really
+     * aborted the signal. False for a runtime cancel, and false while the
+     * timer has not run, however late the clock says it is.
+     */
+    timedOut(): boolean;
     /** Clear the timer. Always call it, or the process keeps a handle alive. */
     cancel(): void;
 };
@@ -279,15 +356,20 @@ export type ResolvedSecret = {
     readonly message: string;
 };
 /**
- * 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 declare function resolveSecret(envVar: string | undefined, what: string, env?: Record<string, string | undefined>): ResolvedSecret;
+export declare function resolveSecret(envVar: string | undefined, what: string, allowed: readonly 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>;
 /**
@@ -299,7 +381,7 @@ export declare function rejectInlineCredentials(headers: Record<string, string>)
 export type AppliedAuth = {
     readonly ok: true;
     readonly secretHeaders: ReadonlySet<string>;
-    readonly secrets: string[];
+    readonly secrets: SecretValue[];
 } | {
     readonly ok: false;
     readonly message: string;
@@ -310,7 +392,7 @@ export type AppliedAuth = {
  * 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;
+export declare function applyAuth(headers: Record<string, string>, auth: AuthProfile | undefined, allowed: readonly string[], env?: Record<string, string | undefined>): AppliedAuth;
 /**
  * A function that scrubs secrets out of anything on its way back to the
  * caller.
@@ -325,8 +407,26 @@ export declare function applyAuth(headers: Record<string, string>, auth: AuthPro
  *
  * 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 declare function redactorFor(secrets: readonly (SecretValue | undefined)[], identifiers?: readonly (string | undefined)[]): (text: string) => string;
+/** The most of a reply an error message quotes. */
+export declare 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 declare function redactorFor(secrets: readonly (string | undefined)[]): (text: string) => string;
+export declare function excerptOf(text: string, secrets: readonly (SecretValue | undefined)[]): 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;
@@ -366,13 +466,48 @@ export type CappedBody = {
     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.
+ * 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 declare function readCapped(res: Response, maxBytes: number): Promise<CappedBody>;
+export declare function readCapped(res: Response, maxBytes: number, signal?: AbortSignal, secrets?: readonly (SecretValue | undefined)[]): Promise<CappedBody>;
 /** A URL the caller supplied, or a readable refusal that does not echo it. */
 export declare function parseUrl(raw: string): URL | string;
+/**
+ * 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 declare function isDotSegment(value: string): boolean;
+/**
+ * `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 declare function substituteIntoUrl(template: string, placeholder: string, value: string): {
+    readonly ok: true;
+    readonly url: URL;
+} | {
+    readonly ok: false;
+    readonly why: "invalid" | "reshaped";
+};
 /** Read a dotted path out of a parsed JSON body. `undefined` when absent. */
 export declare function readPath(value: unknown, path: string): unknown;
 /**
@@ -381,11 +516,48 @@ export declare function readPath(value: unknown, path: string): unknown;
  * because the caller's next move differs.
  */
 export declare function describeFailure(err: unknown, deadline?: Deadline): string;
+/**
+ * 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 declare function isDeadlineAbort(err: unknown, deadline?: Deadline): boolean;
+/**
+ * What makes two calls under one key the SAME request: every argument except
+ * the ones that only say how to deliver it (the key itself, deadlines, byte
+ * caps, retry pacing), each reduced to a SHA-256 of its canonical JSON. Kept
+ * per field, so a refusal can say which fields differed without keeping
+ * the message itself in memory. A caller-supplied clock reading that only
+ * stamps the message (EmailSend's `date`, a webhook signature's timestamp)
+ * is left out by the caller: a retry that re-reads its clock is still a
+ * retry.
+ */
+export type RequestFingerprint = ReadonlyMap<string, string>;
+export declare function requestFingerprint(args: Readonly<Record<string, unknown>>): RequestFingerprint;
 export type LedgerEntry = {
     readonly tool: string;
+    readonly fingerprint: RequestFingerprint;
     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;
+/**
+ * `replay` — this key already sent this request; here is what it returned.
+ * `conflict` — this key already sent a DIFFERENT request, which this call
+ * must not be mistaken for: it is refused and sends nothing.
+ */
+export type LedgerAnswer = {
+    readonly kind: "replay";
+    readonly result: string;
+} | {
+    readonly kind: "conflict";
+    readonly differs: readonly string[];
+};
+/**
+ * `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 declare function ledgerLookup(tool: string, key: string | undefined, fingerprint: RequestFingerprint, ignoring?: readonly string[]): LedgerAnswer | undefined;
+export declare function ledgerRecord(tool: string, key: string | undefined, fingerprint: RequestFingerprint, result: string): void;
 /** Test-only — a fresh process's empty ledger. */
 export declare function _resetIdempotencyLedger(): void;