@dvmkit/sdk 0.0.0 → 0.1.0-rc.1

package/dist/ssrf-BdHsrrIb.d.ts

@@ -0,0 +1,325 @@
+import { C as Currency } from './job-store-C5n6bhap.js';
+
+/**
+ * Quote-time fx snapshot. Embedded in scribe's `lockedQuote` for within-job
+ * consistency between upfront and mid-job charges (see scribe's
+ * `runTranscribeJob`). Within-call lock = "rate cached at first fetch and
+ * reused across the duration calculation"; across-call lock degrades to
+ * "fxFetcher {@link FX_CACHE_TTL_MS} cache window" — see
+ * `public design rationale`.
+ *
+ * `rates` maps an ISO-4217 lowercase currency code to that currency's
+ * value-per-BTC at `as_of`. The set of currencies present matches the
+ * fetcher's configured set (see `createFxFetcher.currencies`).
+ */
+interface FxRateSnapshot {
+    rates: Record<Currency, number>;
+    as_of: string;
+    /**
+     * Configured currencies whose rate here came from an *earlier* fetch, because
+     * the source's latest body omitted them (internal-review). The rate is the best one
+     * this process holds; `as_of` describes the rest of the snapshot, so a
+     * consumer pricing one of these is degrading and should say so — the mid-job
+     * legs report it as `credit_topup_stale_rate` / `dvm.ask_pin_stale_rate`.
+     * Absent on the normal complete-body path.
+     */
+    carried_forward?: readonly Currency[];
+    /**
+     * Configured currencies absent from `rates` altogether — the source omitted
+     * them and this process has never held one to carry forward. {@link fxRateFor}
+     * raises `fx_rate_unavailable` rather than `unsupported_currency` for these:
+     * the DVM advertises the currency, so this is a rate outage narrowed to one
+     * code, and a caller's agent must read it on the same retryable envelope as
+     * any other (internal-review). Absent on the normal complete-body path.
+     */
+    unavailable?: readonly Currency[];
+}
+/**
+ * Default fiat set the bundled fx fetcher resolves against BTC. Add a currency
+ * here and it flows through `DEFAULT_FX_RATE_SOURCE`, the
+ * `UnsupportedCurrencyError` supported-set string, and every fiat-form
+ * `requestPayment` call site — no shape change at the SDK or caller surface.
+ */
+declare const DEFAULT_FX_CURRENCIES: readonly Currency[];
+/**
+ * Default fx-rate source. Points at CoinGecko's free `simple/price` endpoint.
+ * Used for self-hosted DVMs and as the fallback when `DVMKIT_FX_SOURCE` is
+ * unset. Hosted DVMs hit the platform-served endpoint instead — see
+ * {@link PlatformFxSource} and {@link resolveFxSourceFromEnv}.
+ */
+declare const DEFAULT_FX_RATE_SOURCE: string;
+/**
+ * Platform-served fx source. Hosted DVMs hit `${DVMKIT_PLATFORM_URL}/_internal/fx`
+ * authenticated with their per-DVM bearer token. The endpoint serves the
+ * canonical `fx_rates` snapshot the platform refreshes daily — one upstream
+ * fetch covers every hosted DVM. Self-hosted DVMs (no platform wiring) fall
+ * back to CoinGecko-direct.
+ */
+interface PlatformFxSource {
+    kind: "platform";
+    url: string;
+    token: string;
+}
+/** Agent-relayable copy for an {@link FxRateUnavailableError}. */
+interface FxRateUnavailableCopy {
+    display?: string;
+    hint?: string;
+}
+/**
+ * The platform's *deliberate* known-stale refusal, threaded through the fetch
+ * boundary from the `_internal/fx` 503 body (internal-review/internal-review). Present on an
+ * {@link FxRateUnavailableError} only when the platform decided the snapshot is
+ * too old to price against (`error.code === "fx_rate_unavailable"` with a
+ * `detail.stale_days`) — as opposed to a transient unreachability, which carries
+ * no `knownStale`. `resolveServerBtcUsdRate` fails closed on this rather than
+ * degrading to `lastKnown` (internal-review): the platform already refused to serve the
+ * rate, so pricing off a frozen local copy of it would defeat the refusal.
+ */
+interface FxKnownStale {
+    staleDays: number;
+    staleSource?: string;
+    thresholdDays?: number;
+}
+/**
+ * Thrown when the fx source can't be reached or returns an unparseable rate.
+ * `code`/`display`/`hint` mirror the structured-error envelope the SDK quote
+ * path renders to agents as a 503-style response — operators retry; agents
+ * pass `display` to humans.
+ *
+ * `copy` overrides the quote-flavoured defaults. The payment rails raise the
+ * same code from a different moment in the request (internal-review) — an agent that
+ * can't be quoted and an agent whose payment couldn't be priced retry the same
+ * way, so they share one code, but "nothing was charged" is only true of the
+ * latter and must not be said to the former.
+ *
+ * One code, two envelopes: the quote path renders `{ error: { code, display,
+ * hint } }`, the payment path the flat `{ error: "fx_rate_unavailable", display,
+ * hint }` that every other payment error uses (`buildPaymentErrorResponse`). So
+ * an agent has one retry rule but still two shapes to parse the code out of —
+ * that split is the response envelopes', not this error's, and unifying it is
+ * internal-review.
+ */
+declare class FxRateUnavailableError extends Error {
+    readonly code = "fx_rate_unavailable";
+    readonly display: string;
+    readonly hint: string;
+    /**
+     * Set only when the platform explicitly refused a *known-stale* snapshot
+     * (internal-review). Absent means transient/unreachable — a distinction the payment
+     * rail's amount computation branches on: refuse on `knownStale`, degrade to
+     * the last-known rate without it. See {@link FxKnownStale}.
+     */
+    readonly knownStale?: FxKnownStale;
+    constructor(message?: string, copy?: FxRateUnavailableCopy, knownStale?: FxKnownStale);
+}
+/**
+ * Snapshot fetcher for BTC against one or more fiat currencies. Caches
+ * in-process for {@link FX_CACHE_TTL_MS} so concurrent quotes amortise the
+ * rate-limit budget, and a within-window quote → job pair settles at the same
+ * "locked" snapshot without an explicit cross-call lock. `supportedCurrencies()`
+ * returns the configured set synchronously so callers can preflight an
+ * unsupported currency without forcing a network hit.
+ */
+interface FxFetcher {
+    fetch(): Promise<FxRateSnapshot>;
+    supportedCurrencies(): readonly Currency[];
+    /**
+     * The last snapshot this fetcher successfully retrieved, paired with the Unix
+     * ms it was cached, or `null` if none has landed yet. Ignores the freshness
+     * TTL — the cache is never cleared, so this survives an upstream outage and is
+     * the offline degradation source for the payment rail (internal-review): when
+     * {@link fetch} throws, callers serve this rather than fail a priced request.
+     * Optional so lightweight test fakes need not implement it.
+     */
+    lastKnown?(): {
+        snapshot: FxRateSnapshot;
+        cachedAt: number;
+    } | null;
+}
+/**
+ * Options for `createFxFetcher`. `source` accepts either:
+ * - a URL string targeting a CoinGecko-shaped endpoint
+ *   (`{ bitcoin: { <currency>: number, ... } }`), or
+ * - a {@link PlatformFxSource} object pointing at the dvmkit platform's
+ *   `_internal/fx` endpoint (the canonical `fx_rates` snapshot, served with
+ *   bearer auth).
+ *
+ * `undefined` falls back to {@link DEFAULT_FX_RATE_SOURCE} (CoinGecko-direct).
+ */
+interface CreateFxFetcherOpts {
+    source?: string | PlatformFxSource;
+    /** Currencies the fetcher advertises support for. Defaults to {@link DEFAULT_FX_CURRENCIES}. */
+    currencies?: readonly Currency[];
+    fetchFn?: typeof fetch;
+    now?: () => number;
+    cacheTtlMs?: number;
+    retries?: number;
+    /**
+     * Base backoff between retry attempts, doubling each time. Defaults to
+     * {@link FX_RETRY_BASE_DELAY_MS}; pass `0` in tests so the retry loop stays
+     * instant.
+     */
+    retryDelayMs?: number;
+}
+/** Build the default fx fetcher backed by `DVMKIT_FX_SOURCE` (or CoinGecko). */
+declare function createFxFetcher(opts?: CreateFxFetcherOpts): FxFetcher;
+/**
+ * Look up `currency`'s rate in `snapshot`.
+ *
+ * Two ways it can be missing, and they are not the same failure (internal-review):
+ *
+ * - The snapshot lists it in {@link FxRateSnapshot.unavailable} — the DVM
+ *   advertises the currency, but its rate source omitted it and this process
+ *   holds no earlier one. That is a rate outage narrowed to one code, so it
+ *   raises `fx_rate_unavailable`, retryable, the same envelope every other rate
+ *   failure reaches the caller's agent on (internal-review). Answering
+ *   `unsupported_currency` here would reach the quote path as a `400
+ *   invalid_quote_result` — telling an agent the DVM's own quote is malformed,
+ *   and not to retry, over a transient omission upstream.
+ * - Anything else — a currency neither configured nor fetched, typically an
+ *   operator's `DVMKIT_FX_SOURCE` override that doesn't carry it. Raises
+ *   `UnsupportedCurrencyError` naming the keys actually present, so the message
+ *   stays truthful about what this snapshot can price.
+ */
+declare function fxRateFor(snapshot: FxRateSnapshot, currency: Currency): number;
+/**
+ * Resolve the fx source from a DVM process's env. Used by first-party DVMs to
+ * pick between platform-served and CoinGecko-direct fetchers based on whether
+ * the platform wired this DVM up at deploy-time. Returns `undefined` when no
+ * env override is set — the default CoinGecko URL kicks in inside
+ * {@link createFxFetcher}.
+ *
+ * - `DVMKIT_FX_SOURCE === "platform"` + `DVMKIT_PLATFORM_URL` +
+ *   `DVMKIT_PLATFORM_TOKEN` → {@link PlatformFxSource} pointing at
+ *   `${DVMKIT_PLATFORM_URL}/_internal/fx`. The platform's container deploy
+ *   pipeline injects all three together (see `applyPlatformTokenInjection`).
+ * - `DVMKIT_FX_SOURCE` starts with `http(s)://` → URL passed through verbatim
+ *   (CoinGecko-shaped override, mostly used by tests + self-hosted operators
+ *   pointing at a private mirror).
+ * - Otherwise → `undefined` (CoinGecko-direct default).
+ *
+ * The magic string `"platform"` and the URL fallback are intentionally
+ * non-overlapping shapes — operators who want a CoinGecko-style URL pass a
+ * URL, and platform-injected DVMs get the string flag plus the two address
+ * env vars.
+ */
+declare function resolveFxSourceFromEnv(env: Record<string, string | undefined>): string | PlatformFxSource | undefined;
+
+/**
+ * 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 CreateFxFetcherOpts as C, DEFAULT_FX_CURRENCIES as D, type FxFetcher as F, type PinnedFetch as P, SSRFError as S, DEFAULT_FX_RATE_SOURCE as a, type FxRateSnapshot as b, FxRateUnavailableError as c, type PlatformFxSource as d, type SSRFGuardOpts as e, type SSRFReason as f, type SSRFResolver as g, assertSafeUrl as h, createFxFetcher as i, createPinnedFetch as j, fxRateFor as k, resolveFxSourceFromEnv as r };

package/dist/tempo-charge-store-6GJEMNUU.js

@@ -0,0 +1,130 @@
+import {
+  parseStoreValue,
+  stringifyStoreValue
+} from "./chunk-YG7G4DPZ.js";
+import {
+  withSdkInitLock
+} from "./chunk-S3XAHZQY.js";
+
+// src/sdk/server/tempo-charge-store.ts
+var DEFAULT_TABLE_NAME = "mpp_tempo_charge_replays";
+var DEFAULT_RETENTION_MS = 60 * 60 * 1e3;
+var DEFAULT_GC_SAMPLE_RATE = 0.01;
+var VALID_IDENTIFIER = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var PostgresTempoChargeStore = class {
+  pool;
+  tableName;
+  retentionMs;
+  gcSampleRate;
+  now;
+  constructor(pool, opts) {
+    const tableName = opts?.tableName ?? DEFAULT_TABLE_NAME;
+    if (!VALID_IDENTIFIER.test(tableName)) {
+      throw new Error(
+        `PostgresTempoChargeStore: tableName must match ${VALID_IDENTIFIER.source}, got "${tableName}"`
+      );
+    }
+    this.pool = pool;
+    this.tableName = tableName;
+    this.retentionMs = opts?.retentionMs ?? DEFAULT_RETENTION_MS;
+    this.gcSampleRate = opts?.gcSampleRate ?? DEFAULT_GC_SAMPLE_RATE;
+    this.now = opts?.now ?? (() => Date.now());
+    this.get = this.get.bind(this);
+    this.put = this.put.bind(this);
+    this.delete = this.delete.bind(this);
+    this.update = this.update.bind(this);
+  }
+  /** Run the CREATE TABLE migration. Idempotent — safe to call repeatedly. */
+  async init() {
+    await withSdkInitLock(this.pool, () => this.createTables());
+  }
+  /** Read one stored value, or `null` when absent — mppx's miss sentinel. */
+  async get(key) {
+    const { rows } = await this.pool.query(
+      `SELECT value_json FROM ${this.tableName} WHERE store_key = $1`,
+      [key]
+    );
+    return rows[0] ? parseStoreValue(rows[0].value_json) : null;
+  }
+  /** Replace one stored value. */
+  async put(key, value) {
+    await this.update(key, () => ({ op: "set", value, result: void 0 }));
+  }
+  /** Delete one stored value — mppx's compensating release on a failed broadcast. */
+  async delete(key) {
+    await this.update(key, () => ({ op: "delete", result: void 0 }));
+  }
+  /**
+   * Atomic read-modify-write, linearized across every machine sharing the pool.
+   *
+   * The advisory lock is taken before the row lock because a key's *first*
+   * write is the one that matters here: `FOR UPDATE` locks nothing when no row
+   * exists, so two machines marking one hash for the first time would both read
+   * `null` and both believe they won.
+   *
+   * Replay keys are unique per credential, so they never contend. The contended
+   * key is the fee-sponsor budget — one per `(chain, sponsor)`, read-modified
+   * several times per sponsored charge — and serializing it across machines is
+   * the point of sharing the store at all. The critical section is a SELECT and
+   * an upsert, so a queue of waiters clears in tens of milliseconds; a pooled
+   * connection is held for exactly that long and never across a chain call.
+   */
+  async update(key, fn) {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(`SELECT pg_advisory_xact_lock(hashtextextended($1, 2036))`, [key]);
+      const { rows } = await client.query(
+        `SELECT value_json FROM ${this.tableName} WHERE store_key = $1 FOR UPDATE`,
+        [key]
+      );
+      const current = rows[0] ? parseStoreValue(rows[0].value_json) : null;
+      const change = fn(current);
+      const now = this.now();
+      if (change.op === "set") {
+        await client.query(
+          `INSERT INTO ${this.tableName} (store_key, value_json, expires_at)
+           VALUES ($1, $2, $3)
+           ON CONFLICT (store_key) DO UPDATE
+             SET value_json = EXCLUDED.value_json, expires_at = EXCLUDED.expires_at`,
+          [
+            key,
+            stringifyStoreValue(change.value, "Tempo charge store value"),
+            now + this.retentionMs
+          ]
+        );
+      } else if (change.op === "delete") {
+        await client.query(`DELETE FROM ${this.tableName} WHERE store_key = $1`, [key]);
+      }
+      await client.query("COMMIT");
+      if (change.op !== "noop") this.maybeSweep(now);
+      return change.result;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
+  async createTables() {
+    await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        store_key  TEXT PRIMARY KEY,
+        value_json TEXT NOT NULL,
+        expires_at BIGINT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS ${this.tableName}_expires_at_idx
+        ON ${this.tableName} (expires_at);
+    `);
+  }
+  maybeSweep(now) {
+    if (this.gcSampleRate <= 0 || Math.random() >= this.gcSampleRate) return;
+    this.pool.query(`DELETE FROM ${this.tableName} WHERE expires_at < $1`, [now]).catch((err) => {
+      console.error("PostgresTempoChargeStore GC sweep failed:", err);
+    });
+  }
+};
+export {
+  PostgresTempoChargeStore
+};