@dvmkit/sdk 0.1.0-rc.2 → 0.1.0-rc.4

package/dist/ssrf-DbFkpDv0.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Why `assertSafeUrl` refused this URL. Carried on `SSRFError` so callers can
+ * branch without string-matching `err.message` — DNS failures (NXDOMAIN, empty
+ * resolution), unparseable URLs, and a non-https scheme each have distinct
+ * recovery paths and shouldn't collapse together.
+ */
+type SSRFReason = "invalid_url" | "insecure_scheme" | "private_address" | "dns_failed";
+/**
+ * Thrown when an input URL points at internal infrastructure we refuse to
+ * fetch from inside the cluster. Carries a `reason` discriminator so the
+ * caller can map cleanly onto its public taxonomy instead of inspecting the
+ * message string.
+ */
+declare class SSRFError extends Error {
+    readonly code: "ssrf_blocked";
+    readonly reason: SSRFReason;
+    constructor(reason: SSRFReason, message: string);
+}
+/** Pluggable DNS resolver. Defaults to `node:dns/promises` `lookup(host, { all: true })`. */
+type SSRFResolver = (host: string) => Promise<{
+    address: string;
+    family: number;
+}[]>;
+/**
+ * Configurable hooks for `assertSafeUrl`. Defaults preserve the dvmkit
+ * baseline denylist; extra entries compose with (never replace) the defaults.
+ */
+interface SSRFGuardOpts {
+    /** Custom DNS resolver — typically a test stub. */
+    resolver?: SSRFResolver;
+    /** Additional exact hostnames to deny on top of the defaults (lowercased on input). */
+    extraHostnamesExact?: Iterable<string>;
+    /**
+     * Additional hostname suffixes to deny on top of the defaults. Each entry
+     * should include the leading dot (e.g. `.example.invalid`) — the same shape
+     * the defaults use.
+     */
+    extraHostnameSuffixes?: Iterable<string>;
+    /** Additional IPv4 predicate. Returns true for an unsafe address. */
+    extraUnsafeIPv4?: (ipv4: string) => boolean;
+    /** Additional IPv6 predicate. Returns true for an unsafe address. */
+    extraUnsafeIPv6?: (ipv6: string) => boolean;
+    /**
+     * Underlying fetch implementation `createPinnedFetch` wraps. Defaults to
+     * `globalThis.fetch`. Pass an instrumented wrapper (e.g. scribe's
+     * `ctx.fetch` from `createInstrumentedFetch`) to keep `dvm.fetch` spans
+     * around outbound HEAD / GET — the dispatcher pin for every safe redirect
+     * hop is preserved because `init.dispatcher` flows through any thin fetch
+     * wrapper unchanged.
+     */
+    baseFetch?: typeof fetch;
+    /**
+     * Called after a redirect response is accepted and before the target is
+     * resolved or connected. Lets an outer transport refuse to replay an
+     * original request once its source has demonstrably responded.
+     */
+    onRedirectFollowed?: () => void;
+}
+/**
+ * Reject URLs whose host points at internal infrastructure — private /
+ * link-local IP ranges, the AWS / GCP metadata IP, Fly's `*.internal`
+ * service-discovery names, and a small denylist of obviously-internal
+ * hostnames. Defence-in-depth — full mitigation belongs at the egress firewall
+ * and at fetch-time IP pinning (`createPinnedFetch`, internal-review).
+ *
+ * Throws `SSRFError` with a `reason` discriminator so callers can branch onto
+ * their own typed error taxonomy.
+ */
+declare function assertSafeUrl(url: string, opts?: SSRFGuardOpts): Promise<void>;
+/**
+ * A `fetch`-compatible function pinned to a single pre-validated IP address.
+ *
+ * Returned by {@link createPinnedFetch}. Closes the DNS-rebinding window in
+ * which `assertSafeUrl` validates an address but the subsequent `fetch()`
+ * re-resolves DNS and lands on a different (private) address.
+ *
+ * Callers MUST `await close()` when done with the pin so undici's connection
+ * pool is released.
+ */
+interface PinnedFetch {
+    /** Fetch whose initial request and every followed redirect are pinned to their pre-validated address sets. */
+    fetch: typeof fetch;
+    /** Primary (first) validated address of the initial URL. */
+    address: string;
+    /** IP family (4 or 6) of {@link address} (the primary). */
+    family: number;
+    /** Release the undici connection pool backing this pinned fetch. */
+    close(): Promise<void>;
+}
+/**
+ * Resolve the URL's host once, validate every answer against the same
+ * denylist `assertSafeUrl` applies, then return a `fetch` whose `connect.lookup`
+ * replays that frozen, pre-validated address set (see {@link buildPinnedLookup}).
+ * Redirects are followed manually: each target URL is independently required
+ * to be HTTPS, resolved once, denylist-checked, and pinned before it can be
+ * requested. That prevents an automatic redirect from reusing the source
+ * host's dispatcher for a different hostname, while keeping a redirect from
+ * opening a DNS-rebinding window.
+ *
+ * Throws `SSRFError` with the same `reason` discriminator as `assertSafeUrl`,
+ * so error-mapping paths (`mapSsrfError` in cast/scribe) work unchanged.
+ *
+ * For IP-literal URLs no dispatcher is needed, but redirects still pass
+ * through the same validation loop.
+ *
+ * Replaying the full validated set (not just `addresses[0]`) preserves Node's
+ * happy-eyeballs fallback across the answers — a host whose first address is an
+ * unroutable family still connects via the others — while keeping the rebind
+ * window closed, since every replayed address was already denylist-checked.
+ *
+ * Pass `opts.baseFetch` to wrap an instrumented fetch (e.g. scribe's
+ * `ctx.fetch` from `createInstrumentedFetch`) — `dvm.fetch` spans flow
+ * through because `init.dispatcher` is forwarded to the underlying
+ * `globalThis.fetch` unchanged.
+ */
+declare function createPinnedFetch(url: string, opts?: SSRFGuardOpts): Promise<PinnedFetch>;
+
+export { type PinnedFetch as P, SSRFError as S, type SSRFGuardOpts as a, type SSRFReason as b, type SSRFResolver as c, assertSafeUrl as d, createPinnedFetch as e };

package/dist/tempo-charge-store-RIFTALZK.js

@@ -0,0 +1,8 @@
+import {
+  PostgresTempoChargeStore
+} from "./chunk-JZWELPFH.js";
+import "./chunk-YG7G4DPZ.js";
+import "./chunk-S3XAHZQY.js";
+export {
+  PostgresTempoChargeStore
+};

package/dist/tempo-session-store-DALMRIWN.js

@@ -0,0 +1,11 @@
+import {
+  PostgresTempoSessionStore,
+  assertMonotonicTransition
+} from "./chunk-RU7SXHLO.js";
+import "./chunk-YG7G4DPZ.js";
+import "./chunk-C3MTFLC6.js";
+import "./chunk-S3XAHZQY.js";
+export {
+  PostgresTempoSessionStore,
+  assertMonotonicTransition
+};

package/dist/testing/index.d.ts

@@ -1,9 +1,10 @@
-import { aX as StreamableJobStore, aY as ReceiptIssuingStore, J as JobRecord, aZ as RequestIdClaim, a_ as RequestIdClaimResult, a9 as JobReceipt, a$ as OutgoingMessage, aa as AppendOutgoingOptions, b0 as PaymentCreditDelta, b1 as VerifyAndCreditResult, b2 as JobCounters, a6 as Message, av as MessageType, K as KVStore, L as Logger, v as ResponseContent, P as PaymentContent, S as SDKJobContext } from '../job-store-6gR4pZRP.js';
+import { c8 as StreamableJobStore, c9 as ReceiptIssuingStore, J as JobRecord, ca as RequestIdClaim, cb as RequestIdClaimResult, _ as JobReceipt, as as OutgoingMessage, cc as AppendOutgoingOptions, cd as PaymentCreditDelta, ce as VerifyAndCreditResult, cf as JobCounters, a2 as Message, a3 as MessageType, K as KVStore, L as Logger, v as ResponseContent, P as PaymentContent, S as SDKJobContext } from '../job-store-DxFqDPYq.js';
 import '@cashu/cashu-ts';
 import 'mppx';
-import 'hono';
 import '@x402/core/server';
 import '@x402/evm/batch-settlement/server';
+import 'hono';
+import 'viem';
 import 'pg';
 import '@x402/core/types';
 import 'zod';

package/dist/testing/index.js

@@ -4,8 +4,9 @@ import {
   MemoryKVStore,
   createInstrumentedFetch,
   createNoopLogger
-} from "../chunk-7IH5SG2A.js";
-import "../chunk-KXWROQGK.js";
+} from "../chunk-TKA6ZP4M.js";
+import "../chunk-66HGCPBU.js";
+import "../chunk-FUJ36YDV.js";
 
 // src/sdk/testing/test-context.ts
 function createTestContext(opts) {

package/dist/usd-Cha_j80I.d.ts

@@ -0,0 +1,97 @@
+import { C as Currency } from './job-store-DxFqDPYq.js';
+
+/**
+ * Thrown by `fiatToSatsCeil` / `satsToFiat` when the supplied `ratePerBtc` is
+ * non-finite or non-positive. Surfaces a misconfigured fx fetcher loudly
+ * instead of silently producing a 0-sats charge or a 0-fiat display string —
+ * a silent 0 lost real money in internal-review slice-04. Callers obtain a valid rate
+ * from the SDK's fx fetcher (which raises `FxRateUnavailableError` on
+ * upstream failure); this error is the defence-in-depth backstop for any
+ * caller that constructs a rate by other means.
+ */
+declare class InvalidFxRateError extends Error {
+    readonly code = "invalid_fx_rate";
+    readonly ratePerBtc: unknown;
+    constructor(ratePerBtc: unknown);
+}
+/**
+ * Convert a fiat amount to integer sats at the supplied fiat-per-BTC rate.
+ * Rounds **up** so the operator never overcharges the caller (caller-friendly
+ * rounding). Negative or non-finite amounts collapse to 0 (a $0 charge is
+ * well-defined). A non-finite or non-positive `ratePerBtc` raises
+ * `InvalidFxRateError` — a silent 0 would mask a misconfigured fetcher into
+ * shipping a free charge. The math is currency-agnostic — `ratePerBtc` is the
+ * number of units of *some* fiat per 1 BTC; the caller looks the right rate
+ * out of an `FxRateSnapshot`.
+ */
+declare function fiatToSatsCeil(amount: number, ratePerBtc: number): number;
+/**
+ * Convert integer sats back to a fiat amount at the supplied fiat-per-BTC
+ * rate. A non-finite or non-positive `ratePerBtc` raises
+ * `InvalidFxRateError` — the silent `0` would land in display strings and
+ * mislead callers about the value at hand.
+ */
+declare function satsToFiat(sats: number, ratePerBtc: number): number;
+/**
+ * Thrown when a builder-declared USD price literal is malformed (internal-review).
+ * Carries the offending value and the config field it came from so
+ * `configureDVM`'s boot check can surface both without re-deriving them.
+ */
+declare class InvalidUsdPriceError extends Error {
+    readonly field: string;
+    readonly value: unknown;
+    readonly code = "invalid_usd_price";
+    constructor(field: string, value: unknown, detail: string);
+}
+/**
+ * Parse a builder-declared USD price literal (`"$0.05"`) into a bare USD
+ * number. The single parser for every price surface — capability `price`,
+ * `credit.min`/`credit.max`, the `/v1/info` pricing ceiling, and the ledger's
+ * fiat denomination — so those surfaces cannot drift on what they accept.
+ *
+ * Strict by construction on both format and precision:
+ *
+ * - The grammar is `$` followed by a decimal number, so `"$1abc"` (which every
+ *   ad-hoc `parseFloat(v.slice(1))` used to accept as 1) is rejected.
+ * - The amount must be expressible at {@link roundUsd}'s four decimal places,
+ *   which is the precision **every** advertisement surface carries — `/v1/info`
+ *   pricing ceilings, `/v1/quote` upfronts, the isolate tier's re-emit. A price
+ *   finer than that advertises as a different number than it charges, and one
+ *   below `$0.0001` advertises as `$0` while still gating the job: advertised
+ *   paid, apparently free, which is the shape internal-review exists to close.
+ *
+ * The floor is deliberately 100× coarser than the credit ledger's micro-unit.
+ * The ledger could denominate `$0.000001`; no surface a caller reads can
+ * express it, so blessing it here would only move the incoherence downstream.
+ */
+declare function parseUsdPrice(value: string, field: string): number;
+/**
+ * Round a USD value to 4 decimal places (matches scribe's stored display
+ * precision). This is the **storage / accounting** precision — preserves
+ * sub-cent amounts so a `$0.0150` per-minute rate doesn't collapse to
+ * `$0.02` before it ever reaches a multiplier. See {@link formatUsd} for the
+ * human-render precision, which deliberately truncates at the cent boundary
+ * for amounts ≥ $0.01.
+ */
+declare function roundUsd(usd: number): number;
+/**
+ * Format a USD amount with adaptive precision so sub-cent amounts don't
+ * render as `$0.00`. The 2dp/4dp boundary at $0.01 is **human-render**
+ * precision and is intentionally coarser than {@link roundUsd}'s storage
+ * precision: a value like `0.015` keeps four decimals through `roundUsd`
+ * (storage / multiplier inputs) but renders as `$0.02` here (human display).
+ * Don't try to unify the two — they serve different surfaces.
+ */
+declare function formatUsd(usd: number): string;
+/**
+ * Format a fiat amount with currency-aware symbol, precision, and ISO code.
+ * Used by the CLI to render payment-request `fiat_amount` envelopes ("$0.05
+ * USD", "€0.05 EUR", "¥5 JPY"). Precision is adaptive: JPY has no sub-yen
+ * denomination so renders as 0 decimals, every other currency uses 2 decimals
+ * at or above 0.01 and 4 below so sub-cent figures don't collapse to 0.00.
+ * Unknown currencies (anything not in {@link FIAT_SYMBOLS}) render with the
+ * uppercased ISO code and no leading symbol.
+ */
+declare function formatFiat(amount: number, currency: Currency): string;
+
+export { InvalidFxRateError as I, formatFiat as a, formatUsd as b, InvalidUsdPriceError as c, fiatToSatsCeil as f, parseUsdPrice as p, roundUsd as r, satsToFiat as s };

package/dist/x402-XXFQQAAD.js

@@ -0,0 +1,81 @@
+import {
+  connectedX402Payer,
+  ensureAddress,
+  generateX402PrivateKey,
+  getX402Balance,
+  loadX402Wallet,
+  removeX402Wallet,
+  repinX402WalletNetwork,
+  resolveX402Asset,
+  saveX402Wallet,
+  tryX402Payment,
+  verifyX402Payment,
+  x402WrongAssetHint
+} from "./chunk-GJD7PVWY.js";
+import "./chunk-2K6UXDAN.js";
+import {
+  X402_DEFAULT_FACILITATOR,
+  X402_DEFAULT_NETWORK,
+  X402_NETWORKS,
+  X402_V1_VERSION,
+  X402_VERSION,
+  assertSupportedX402Network,
+  buildPaymentRequiredV2,
+  buildPaymentRequirements,
+  caip2ToX402Network,
+  chainIdFromCaip2,
+  decodePayment,
+  decodePaymentRequiredHeader,
+  encodePayment,
+  encodePaymentRequiredHeader,
+  encodeSettleResponseHeader,
+  exactEvmAuthorization,
+  paymentRequiredV2FromV1,
+  usdcContractByCaip2,
+  x402NetworkByCaip2,
+  x402NetworkLabel,
+  x402NetworkListForCopy,
+  x402NetworkToCaip2,
+  x402SupportedNetworksHint
+} from "./chunk-AAJNGQMC.js";
+import "./chunk-F2L6KIMD.js";
+import "./chunk-66HGCPBU.js";
+import "./chunk-FUJ36YDV.js";
+import "./chunk-AT6V3SY7.js";
+export {
+  X402_DEFAULT_FACILITATOR,
+  X402_DEFAULT_NETWORK,
+  X402_NETWORKS,
+  X402_V1_VERSION,
+  X402_VERSION,
+  assertSupportedX402Network,
+  buildPaymentRequiredV2,
+  buildPaymentRequirements,
+  caip2ToX402Network,
+  chainIdFromCaip2,
+  connectedX402Payer,
+  decodePayment,
+  decodePaymentRequiredHeader,
+  encodePayment,
+  encodePaymentRequiredHeader,
+  encodeSettleResponseHeader,
+  ensureAddress,
+  exactEvmAuthorization,
+  generateX402PrivateKey,
+  getX402Balance,
+  loadX402Wallet,
+  paymentRequiredV2FromV1,
+  removeX402Wallet,
+  repinX402WalletNetwork,
+  resolveX402Asset,
+  saveX402Wallet,
+  tryX402Payment,
+  usdcContractByCaip2,
+  verifyX402Payment,
+  x402NetworkByCaip2,
+  x402NetworkLabel,
+  x402NetworkListForCopy,
+  x402NetworkToCaip2,
+  x402SupportedNetworksHint,
+  x402WrongAssetHint
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dvmkit/sdk",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.4",
   "description": "SDK for building accountless, pay-per-use Digital Vending Machines",
   "license": "Apache-2.0",
   "repository": {
@@ -27,6 +27,10 @@
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal/index.d.ts",
+      "import": "./dist/internal/index.js"
     }
   },
   "files": [
@@ -37,7 +41,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "build": "tsup --config tsup.config.ts && node scripts/prune-sdk-dist.mjs",
+    "build": "NODE_OPTIONS=--max-old-space-size=6144 tsup --config tsup.config.ts && node scripts/prune-sdk-dist.mjs",
     "check:api": "node scripts/check-api-surface.mjs",
     "check:consumer": "node scripts/consumer-smoke.mjs",
     "check:package": "node scripts/package-smoke.mjs",