@crewhaus/tool-chainread 0.7.0

package/dist/lib/endpoint.js

@@ -0,0 +1,320 @@
+/**
+ * Which endpoints this package is willing to dial.
+ *
+ * Every other networked package here — `tool-registry`, `tool-containers` —
+ * builds its URLs from constants, so a model never picks a host. This one
+ * cannot: reading a chain the caller names means the caller names the RPC URL,
+ * and an unguarded `fetch(input.rpcUrl)` is a server-side request forgery
+ * primitive with a model holding the steering wheel. `http://169.254.169.254/`
+ * is the cloud metadata service; `http://127.0.0.1:6379/` is somebody's Redis.
+ *
+ * So the host is vetted before the socket opens, the vetted IP is what gets
+ * dialled (resolving here and letting `fetch` re-resolve at connect time is a
+ * DNS-rebinding TOCTOU), and the loopback/private ranges are refused unless an
+ * OPERATOR opened them — `setRpcEndpointPolicy` is bound at boot by the
+ * runtime, exactly like `setEvmAdapterResolver` in `tool-evm`. It is
+ * deliberately not a field in any tool's input schema: a gate a model can open
+ * for itself is not a gate.
+ *
+ * This is a narrower guard than `@crewhaus/tool-fetch`'s `assertNotSsrf`, which
+ * is the repo's canonical one and is not a dependency of this package. What is
+ * here covers the same ground for this package's one shape of request — a
+ * single origin, no redirects followed, no credentials attached — and the
+ * README says so rather than implying parity.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+export class RpcEndpointError extends CrewhausError {
+    name = "RpcEndpointError";
+    constructor(message) {
+        super("tool", message);
+    }
+}
+let policy = {};
+/** Bind the endpoint policy at boot. Generated daemons call this before registering the tools. */
+export function setRpcEndpointPolicy(next) {
+    policy = next;
+}
+/** Read the policy back — for `EvmRpcHealth`, which reports the posture it is operating under. */
+export function getRpcEndpointPolicy() {
+    return policy;
+}
+/**
+ * Resolution seam. Production uses `node:dns/promises`; every test in this
+ * package replaces it, so the suite never sends a DNS query and never opens a
+ * socket — which is the point, because CI has no egress.
+ */
+const defaultDnsLookup = async (host) => {
+    const dns = await import("node:dns/promises");
+    return dns.lookup(host, { verbatim: false });
+};
+let dnsLookupFn = defaultDnsLookup;
+export function _setDnsLookup(fn) {
+    dnsLookupFn = fn ?? defaultDnsLookup;
+}
+// ---------------------------------------------------------------------------
+// BEGIN SYNCHRONISED BLOCK — private-address classifier
+//
+// This block is BYTE-IDENTICAL across every package that guards an outbound
+// request. Do not edit one copy: `apps/cli/src/tool-registry.test.ts` hashes
+// them all and fails if any differs, and it asserts how many it found, because
+// a copy-scanning guard that matches nothing reports green.
+//
+// It exists in copies rather than a shared package because these files are
+// otherwise independent per-package networking layers; a guard proving the
+// copies are identical is cheaper and safer than the import graph a shared
+// package would need across `crawler`, `computer-use-driver` and ten tools.
+//
+// WHY IT PARSES INSTEAD OF MATCHING TEXT. Six copies were confirmed
+// exploitable on 2026-09-18 because they compared address STRINGS. The WHATWG
+// URL parser rewrites `[::ffff:169.254.169.254]` to `[::ffff:a9fe:a9fe]`, so a
+// text check never sees the spelling it was written for; and `64:ff9b::a9fe:a9fe`
+// IS 169.254.169.254 on any network running DNS64/NAT64. Parsing numerically and
+// recursing into the embedded IPv4 is the only form that holds.
+//
+// WHAT IT CANNOT DO. RFC 6052 lets an operator choose any Network-Specific
+// Prefix for NAT64, so an embedded IPv4 behind an arbitrary NSP is undecidable
+// from the address alone. That case is configuration, and the callers that need
+// it resolve the host and re-check the ANSWER before dialling.
+// ---------------------------------------------------------------------------
+/**
+ * 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 function normalizeIpv4(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === "" || /[^0-9a-fA-FxX.]/.test(trimmed))
+        return null;
+    const parts = trimmed.split(".");
+    if (parts.length === 0 || parts.length > 4)
+        return null;
+    const values = [];
+    for (const part of parts) {
+        if (part === "")
+            return null;
+        let value;
+        if (/^0[xX][0-9a-fA-F]+$/.test(part))
+            value = Number.parseInt(part.slice(2), 16);
+        else if (/^0[0-7]+$/.test(part))
+            value = Number.parseInt(part.slice(1), 8);
+        else if (/^\d+$/.test(part))
+            value = Number.parseInt(part, 10);
+        else
+            return null;
+        if (!Number.isFinite(value) || value < 0)
+            return null;
+        values.push(value);
+    }
+    // The short forms pack the remaining octets into the last part: `127.1` is
+    // 127.0.0.1, not 127.1.0.0. Getting this backwards is how a bypass survives.
+    const last = values[values.length - 1];
+    const leading = values.slice(0, -1);
+    if (leading.some((v) => v > 255))
+        return null;
+    const remaining = 4 - leading.length;
+    if (last >= 2 ** (8 * remaining))
+        return null;
+    const octets = [...leading];
+    for (let i = remaining - 1; i >= 0; i--)
+        octets.push((last >>> (8 * i)) & 0xff);
+    return octets.join(".");
+}
+/**
+ * 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 function parseIpv6(raw) {
+    let text = raw.trim().toLowerCase();
+    if (text.startsWith("["))
+        text = text.slice(1);
+    if (text.endsWith("]"))
+        text = text.slice(0, -1);
+    const zone = text.indexOf("%"); // fe80::1%eth0
+    if (zone !== -1)
+        text = text.slice(0, zone);
+    if (!text.includes(":"))
+        return null;
+    // A trailing dotted quad is the last two groups written in IPv4. Require all
+    // three dots: without that, `::1` parses as a one-part inet_aton address and
+    // takes a path that has nothing to do with what was written.
+    const dotted = /^(.*:)(\d+(?:\.\d+){3})$/.exec(text);
+    if (dotted !== null) {
+        const quad = normalizeIpv4(dotted[2]);
+        if (quad === null)
+            return null;
+        const o = quad.split(".").map((n) => Number.parseInt(n, 10));
+        const hi = (o[0] << 8) | o[1];
+        const lo = (o[2] << 8) | o[3];
+        text = `${dotted[1]}${hi.toString(16)}:${lo.toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const pieces = (part) => (part === "" ? [] : part.split(":"));
+    const head = pieces(halves[0]);
+    const tail = halves.length === 2 ? pieces(halves[1]) : [];
+    if (halves.length === 1 && head.length !== 8)
+        return null;
+    if (head.length + tail.length > 8)
+        return null;
+    const groups = [];
+    for (const piece of head) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    for (let i = head.length + tail.length; i < 8; i++)
+        groups.push(0);
+    for (const piece of tail) {
+        if (!/^[0-9a-f]{1,4}$/.test(piece))
+            return null;
+        groups.push(Number.parseInt(piece, 16));
+    }
+    return groups.length === 8 ? groups : null;
+}
+/**
+ * The IPv4 address an IPv6 address carries, when it carries one.
+ *
+ * Every transition mechanism embeds a v4 address somewhere, and every one of
+ * them is a way to reach a v4 destination while wearing a v6 spelling that no
+ * v4 range check looks at. The NAT64 well-known prefix is the sharpest: a
+ * DNS64 resolver answers an IPv4-only name with `64:ff9b::<the v4>`, so
+ * `64:ff9b::a9fe:a9fe` IS the metadata service on any network that runs one.
+ */
+function embeddedIpv4(g) {
+    const quad = (hi, lo) => `${(hi >>> 8) & 0xff}.${hi & 0xff}.${(lo >>> 8) & 0xff}.${lo & 0xff}`;
+    const zeros = (from, to) => g.slice(from, to).every((x) => x === 0);
+    const last = quad(g[6], g[7]);
+    if (zeros(0, 5) && g[5] === 0xffff)
+        return last; // ::ffff:0:0/96, IPv4-mapped
+    if (zeros(0, 4) && g[4] === 0xffff && g[5] === 0)
+        return last; // ::ffff:0:0:0/96, translated
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return last; // 64:ff9b::/96 and 64:ff9b:1::/48, NAT64
+    if (g[0] === 0x2002)
+        return quad(g[1], g[2]); // 2002::/16, 6to4
+    // ::a.b.c.d, IPv4-compatible: deprecated, still routed by some stacks, and
+    // not to be confused with `::` or `::1`, which are handled before this.
+    if (zeros(0, 6))
+        return last;
+    return null;
+}
+/** Ranges that are never a public RPC endpoint. */
+export function isPrivateIp(address) {
+    const v4 = normalizeIpv4(address);
+    if (v4 !== null) {
+        const [a = 0, b = 0, c = 0, d = 0] = v4.split(".").map((n) => Number.parseInt(n, 10));
+        if (a === 0 || a === 10 || a === 127)
+            return true;
+        if (a === 169 && b === 254)
+            return true; // link-local, and the metadata service
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 192 && b === 0 && c === 0)
+            return true;
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // carrier-grade NAT
+        if (a === 198 && (b === 18 || b === 19))
+            return true; // benchmarking
+        if (a >= 224)
+            return true; // multicast, reserved, broadcast
+        return a === 255 && b === 255 && c === 255 && d === 255;
+    }
+    const groups = parseIpv6(address);
+    if (groups === null)
+        return false;
+    if (groups.every((g) => g === 0))
+        return true; // ::, the unspecified address
+    if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1)
+        return true; // ::1
+    const carried = embeddedIpv4(groups);
+    if (carried !== null)
+        return isPrivateIp(carried);
+    const head = groups[0];
+    if ((head & 0xfe00) === 0xfc00)
+        return true; // fc00::/7, unique-local
+    if ((head & 0xffc0) === 0xfe80)
+        return true; // fe80::/10, link-local
+    return (head & 0xff00) === 0xff00; // ff00::/8, multicast
+}
+/**
+ * Validate an RPC URL and resolve the address to pin the connection to.
+ *
+ * Throws `RpcEndpointError` for everything a caller could have got wrong, with
+ * the reason in the message, because every one of these is a refusal a model
+ * should read and act on rather than retry.
+ */
+export async function vetEndpoint(rawUrl) {
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        throw new RpcEndpointError(`"${rawUrl}" is not a URL`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new RpcEndpointError(`refusing scheme "${url.protocol.replace(":", "")}" — an RPC endpoint is http(s); a websocket is a different transport this package does not speak`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        // A provider key belongs in the path (Alchemy, Infura) or a header, not in
+        // userinfo, which lands in logs and in any error message quoting the URL.
+        throw new RpcEndpointError("refusing a URL with credentials in it — strip the user:password@ and put the provider key in the path");
+    }
+    const allowed = policy.allowedOrigins;
+    if (allowed !== undefined && !allowed.includes(url.origin)) {
+        throw new RpcEndpointError(`refusing "${url.origin}" — the operator's rpc allow-list is ${allowed.length === 0 ? "empty" : allowed.join(", ")}`);
+    }
+    const host = url.hostname.toLowerCase();
+    const allowPrivate = policy.allowPrivateHosts === true;
+    if (!allowPrivate && (host === "localhost" || host.endsWith(".localhost"))) {
+        throw new RpcEndpointError(deniedPrivate(url.hostname, "loopback"));
+    }
+    if (!allowPrivate && host.endsWith(".local")) {
+        throw new RpcEndpointError(deniedPrivate(url.hostname, "an mDNS name"));
+    }
+    const unbracketed = host.replace(/^\[/, "").replace(/\]$/, "");
+    // Parsed, not sniffed for a colon: an address this cannot expand is not an
+    // address it can classify either, and treating it as a literal would skip the
+    // resolution that is the only other thing standing between a name and a
+    // private range.
+    const literal = normalizeIpv4(unbracketed) ?? (parseIpv6(unbracketed) === null ? null : unbracketed);
+    if (literal !== null) {
+        if (!allowPrivate && isPrivateIp(literal)) {
+            throw new RpcEndpointError(deniedPrivate(url.hostname, `the private address ${literal}`));
+        }
+        return { url, pinnedIp: literal };
+    }
+    if (allowPrivate) {
+        // The operator opened the private ranges, so a resolution has nothing left
+        // to decide — and resolving anyway would break the offline devnet case the
+        // flag exists for.
+        return { url, pinnedIp: "" };
+    }
+    let resolved;
+    try {
+        resolved = await dnsLookupFn(host);
+    }
+    catch (err) {
+        throw new RpcEndpointError(`cannot resolve "${url.hostname}": ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (isPrivateIp(resolved.address)) {
+        throw new RpcEndpointError(deniedPrivate(url.hostname, `the private address ${resolved.address}`));
+    }
+    return { url, pinnedIp: resolved.address };
+}
+function deniedPrivate(host, what) {
+    return `refusing to dial "${host}" — it is ${what}, and reaching one from a model-supplied URL is how an agent ends up reading a metadata service or an unauthenticated local port. An operator can permit it with setRpcEndpointPolicy({ allowPrivateHosts: true }) for a local devnet.`;
+}

package/dist/lib/history.d.ts

@@ -0,0 +1,196 @@
+/**
+ * One address's onchain history, in the row shape a reconciler already
+ * consumes.
+ *
+ * The row shape is NOT this package's. `@crewhaus/tool-money` owns
+ * `Transaction` — the shape `StatementParse` produces and
+ * `@crewhaus/tool-ledger`'s `LedgerReconcile` consumes — and it is imported
+ * here rather than re-declared, because a second declaration of it is a shape
+ * that drifts the first time a field is added, and an onchain history that
+ * cannot be reconciled against a bank statement is the whole point of the tool
+ * gone.
+ *
+ * What that costs, and what is done about it: `amountMinor` is a JS `number`,
+ * and a uint256 is not. Nothing here rounds to fit. An amount that does not
+ * survive the conversion exactly — dust below the ledger's smallest unit, or a
+ * magnitude past `Number.MAX_SAFE_INTEGER`, which 0.01 ETH in wei already is —
+ * is PARKED with the exact raw value and a named reason rather than emitted as
+ * a row that reconciles to the wrong number. An empty history and an
+ * unrepresentable one are different answers.
+ *
+ * Three sources, and only three, because a public endpoint has no index by
+ * address:
+ *
+ *   1. **Logged token transfers**, from `eth_getLogs` filtered on the Transfer
+ *      topic with the address in the from or the to position. Paged by
+ *      `scanLogs` — the same code `EvmEventScan` uses, so the silent-truncation
+ *      proof, the reorg check and the refusal-rather-than-a-prefix behaviour
+ *      are the tested ones rather than a second implementation of them.
+ *   2. **Native value and gas**, from hydrating each block in the range and
+ *      picking out the transactions this address sent or received. One request
+ *      per block, so the range is bounded and a range past the bound is a
+ *      refusal, not a quiet token-only answer.
+ *   3. Nothing else. Internal native transfers need a trace, ERC-1155 puts its
+ *      parties in different topic positions and its batch amounts in data where
+ *      no filter reaches, and an explorer's address index is not a public RPC.
+ *      All three are reported as excluded in the output, not only here.
+ */
+import type { Transaction } from "@crewhaus/tool-money";
+import { type RpcClient } from "./rpc";
+/**
+ * What a caller knows about one asset's units.
+ *
+ * `decimals` is never read off the chain. Resolving it costs an `eth_call` per
+ * token and a token contract is free to report whatever it likes — an airdrop
+ * whose `decimals()` returns 2 turns a dust transfer into a five-figure row.
+ * So it arrives from the caller or it stays `null`, and `null` means the raw
+ * base units are used as the minor units, which is exact.
+ */
+export type AssetUnits = {
+    readonly decimals: number | null;
+    /** The ledger's minor unit for this asset. Defaults to `decimals`, i.e. base units. */
+    readonly minorUnitDecimals: number | null;
+    readonly symbol: string | null;
+};
+export declare const UNKNOWN_UNITS: AssetUnits;
+export type HistoryOptions = {
+    /** Exactly one address: a statement is one account's, and the row shape has no account column. */
+    readonly address: string;
+    readonly from: bigint;
+    readonly to: bigint;
+    readonly includeTokens: boolean;
+    readonly includeNative: boolean;
+    readonly includeFees: boolean;
+    /** Lowercased token address → units. Also the scan's address filter when `onlyKnownTokens`. */
+    readonly tokenUnits: ReadonlyMap<string, AssetUnits>;
+    readonly onlyKnownTokens: boolean;
+    readonly nativeUnits: AssetUnits;
+    /** Blocks per `eth_getLogs` request to start from; narrowed by `scanLogs` as the endpoint pushes back. */
+    readonly span: bigint;
+    readonly suspectAt: number;
+    readonly maxRows: number;
+    readonly maxHydratedBlocks: number;
+    readonly maxCalls: number;
+};
+/**
+ * Everything about a row that the `Transaction` shape has nowhere to put.
+ *
+ * Keyed by the row's `id`, so the exact uint256 is one lookup away and is never
+ * the thing that got rounded. A reconciler reads `rows`; an auditor reads this.
+ */
+export type RowDetail = {
+    readonly id: string;
+    readonly kind: "token" | "native" | "fee";
+    readonly standard: "erc20" | "erc721" | "native" | "fee";
+    readonly asset: string;
+    readonly symbol: string | null;
+    readonly assetDecimals: number | null;
+    readonly minorUnitDecimals: number | null;
+    /** The chain's own number, in base units, as a decimal string. Never a double. */
+    readonly rawAmount: string;
+    readonly tokenId: string | null;
+    readonly counterparty: string | null;
+    readonly txHash: string;
+    readonly blockNumber: string;
+    readonly blockHash: string;
+    readonly timestamp: string;
+    readonly timestampIso: string | null;
+    /**
+     * The transaction's own status, in the three values a receipt actually has.
+     * `unknown` is a pre-Byzantium receipt, which carries a state root instead
+     * and does not record whether the call reverted — collapsing that onto
+     * `false` would assert a success the chain never claimed.
+     */
+    readonly status: "success" | "reverted" | "unknown";
+    readonly feeModel?: string;
+};
+/** A movement that exists on the chain and cannot be written as a row. Never dropped, never rounded. */
+export type ParkedRow = {
+    readonly id: string;
+    readonly reason: "belowMinorUnit" | "exceedsSafeInteger" | "timestampOutOfRange" | "undecodable";
+    readonly why: string;
+    readonly asset: string;
+    readonly rawAmount: string | null;
+    readonly txHash: string;
+    readonly blockNumber: string;
+};
+/**
+ * Whether the blocks the endpoint served held every transaction this address
+ * SENT over the range — and, when that could not be established, why not.
+ *
+ * A hydrated block is one response that cannot be split, so the split-and-
+ * compare proof the log scan uses has nothing to work with here. The account's
+ * own nonce is the oracle instead: it goes up once per transaction sent, so its
+ * rise across the range is the number of transactions that must be in those
+ * blocks. Fewer is a refusal — every one missed is a fee row and possibly a
+ * payment. The count is never reported as proved when the nonce could not be
+ * read: a pruned endpoint answers a historical `eth_getTransactionCount` with
+ * an error, and "could not check" is not "checked".
+ */
+export type SentProof = {
+    readonly outcome: "proved";
+    readonly sent: number;
+} | {
+    readonly outcome: "moreThanTheNonce";
+    readonly sent: number;
+    readonly nonceAccountsFor: number;
+    readonly why: string;
+} | {
+    readonly outcome: "unproved";
+    readonly sent: number;
+    readonly why: string;
+};
+export type HistoryReport = {
+    readonly rows: ReadonlyArray<Transaction>;
+    readonly detail: ReadonlyArray<RowDetail>;
+    readonly unrepresentable: ReadonlyArray<ParkedRow>;
+    readonly logChunks: number;
+    readonly logCalls: number;
+    readonly silentTruncations: number;
+    readonly verifications: number;
+    readonly hydratedBlocks: number;
+    readonly receiptsRead: number;
+    /** Transfers where this address is both parties: they move nothing, so they are not rows. */
+    readonly selfTransfers: number;
+    /** Absent when no block was hydrated, because then nothing claims to have read what it sent. */
+    readonly sentProof?: SentProof;
+};
+/**
+ * Collect the history, or refuse.
+ *
+ * The range must already be resolved to numbers and pinned by the caller. A
+ * sync whose upper bound is still the string `latest` cannot hand back a cursor
+ * anybody can resume from, because the block it stopped at is not a block it
+ * can name.
+ */
+export declare function collectHistory(client: RpcClient, options: HistoryOptions): Promise<HistoryReport>;
+type Scaled = {
+    readonly ok: true;
+    readonly value: number;
+} | {
+    readonly ok: false;
+    readonly reason: "belowMinorUnit" | "exceedsSafeInteger";
+    readonly why: string;
+};
+/**
+ * A base-unit amount as the ledger's minor units, exactly or not at all.
+ *
+ * Both failures are real and neither is rounding's business. Wei is eighteen
+ * decimals and `Number.MAX_SAFE_INTEGER` is about nine thousandths of one ETH,
+ * so a plain ETH payment does not fit in this field at all until the caller
+ * says what unit the ledger keeps ETH in — and 0.5 USDC does not fit a
+ * cent-denominated ledger however it is asked.
+ */
+export declare function toMinorUnits(raw: bigint, units: AssetUnits): Scaled;
+/**
+ * The `YYYY-MM-DD` the row shape wants, or `null` when the instant cannot be
+ * written that way.
+ *
+ * `Date.prototype.toISOString` switches to the EXPANDED year format outside
+ * 0000–9999 — a block stamped in the year 33658 serialises as
+ * `+033658-…`, and slicing ten characters off that gives `+033658-0`, which is
+ * not a date and which `LedgerReconcile`'s schema rejects at the far end of the
+ * pipeline rather than here. So the slice is validated, not assumed.
+ */
+export declare function calendarDate(iso: string | null): string | null;
+export {};