export declare function stripTrailingSlashes(s: string): string; /** * SSRF guard for every fetchJson() call across all 20 url/origin-accepting * tools. This is the single choke point: every handler in src/handlers goes * through fetchJson() (some via a per-file loadDoc/loadCard wrapper, some * calling it directly), so putting the check here covers all of them rather * than needing it duplicated per file. * * Two layers, not one: * * 1. assertSafeFetchTarget() -- an early, fast-fail check: scheme must be * http(s), and a first DNS snapshot must not land in a blocked range. * Cheap, gives a clear error before any network activity, and is * authoritative for literal-IP targets (nothing to resolve, so nothing * to race). * * 2. makeGuardedLookup() -- the actual enforcement point for hostname * targets, wired into the undici Agent's `connect.lookup`. This is * called at the moment a socket is about to be opened, and the address * it returns IS the address the socket connects to -- not a separate * earlier answer. This is what closes the DNS-rebinding gap: a domain * whose DNS server hands out a public address on an early lookup and a * private one moments later cannot slip through, because there is no * "moments later" here -- the check and the connection use the same * resolution, at the same time. * * Rejects nonpublic address ranges on both the literal host in the URL and * every address it resolves to. This includes unspecified addresses such as * 0.0.0.0, which can connect to a loopback listener on some hosts. */ export declare class UnsafeFetchTargetError extends Error { constructor(message: string); } /** Exported for direct unit testing of the range math, not just indirectly * through assertSafeFetchTarget. */ export declare function isBlockedIpv4(ip: string): boolean; /** ::1 (loopback), fc00::/7 (unique local), fe80::/10 (link-local), and * both IPv4-embedding forms (::ffff:0:0/96 and the deprecated ::/96) -- * an IPv4-mapped or IPv4-compatible address is exactly as blocked as the * IPv4 address it embeds, checked via isBlockedIpv4. Without this, every * range above and every RFC1918/loopback/link-local check in isBlockedIpv4 * was bypassable by writing the same destination as ::ffff:a.b.c.d, since * net.isIP() routes any IPv6-syntax string here and this function had no * idea those forms existed. * Exported for direct unit testing of the range math. */ export declare function isBlockedIpv6(ip: string): boolean; /** A resolver is just "given a hostname, return the addresses it maps to." * The real implementation calls node:dns/promises. Tests inject a fake one * so the guard's *logic* can be proven without needing a real DNS server * that can be made to answer differently on successive queries -- which is * exactly the rebinding scenario this exists to catch. */ export type AddressResolver = (hostname: string) => Promise>; export declare function __allowFetchTargetForTests(hostPort: string): void; export declare function __clearFetchTargetAllowlistForTests(): void; export declare function assertSafeFetchTarget(rawUrl: string, resolve?: AddressResolver): Promise; /** * Builds a Node-style `lookup(hostname, options, callback)` function suitable * for an undici Agent's `connect.lookup`. This is the connect-time half of * the guard: whatever address this returns is the address the socket * connects to, in the same call, so there is no gap between "checked" and * "used" for an attacker's DNS server to exploit. * * Node calls this with `options.all` set for the modern Happy-Eyeballs path; * both the array form and the single-address legacy form are handled. */ export declare function makeGuardedLookup(resolve?: AddressResolver): (hostname: string, options: { all?: boolean; }, callback: (err: Error | null, address: string | Array<{ address: string; family: number; }>, family?: number) => void) => void; /** Fetch JSON with bounded redirects and a hard response-body limit. */ export declare function fetchJson(url: string, timeoutMs?: number, maxBytes?: number): Promise; /** * SHA-256 over canonicalized UTF-8 bytes: * - normalize line endings to LF * - strip a single trailing newline * Matches the rule defined in the AI Evidence Format and Prompt * Provenance specifications. */ export declare function canonicalSha256(content: string): string; export declare function pretty(value: unknown): string; /** * SHA-256 over canonical JSON of a parsed value: sorted object keys, * no whitespace, UTF-8. This is the **structural** hash convention used * across the Kinetic Gain implementation stack (procurement-decision-api, * aeo-validator-service, aeo-graph-explorer-rs, hash-attestation-rs). * * Distinct from `canonicalSha256()` above, which hashes a *text content* * string after line-ending normalization (the AI Evidence / Prompt * Provenance convention). * * Identical JSON values produce identical hashes regardless of how the * input was originally serialised: * { "foo": 1, "bar": 2 } and { "bar": 2, "foo": 1 } -> same hash. */ export declare function canonicalJsonSha256(value: unknown): string; export declare function errorJson(error: string, details?: Record): string;