@medialane/sdk 0.108.0 → 0.110.0

package/dist/index.d.cts

@@ -393,18 +393,6 @@ declare function hasCapability(id: string | null | undefined, cap: ServiceCapabi
 
 declare function normalizeAddress(chain: Chain, address: string): string;
 declare const canonicalHashBrand: unique symbol;
-/**
- * A felt hash in exactly one spelling: lowercase, zero-padded to 64 hex digits.
- *
- * Felts have many equal spellings — `0x0ab`, `0xAB` and `0xab` are the same
- * value on chain but three different strings. Anything that uses a hash as an
- * identity or uniqueness key must therefore compare canonical form, or the
- * same on-chain fact can be presented as several distinct records.
- *
- * Only `normalizeHash` can produce this type, so a function that demands a
- * `CanonicalHash` cannot be handed a raw caller-supplied string. It remains
- * assignable to `string`, so existing readers are unaffected.
- */
 type CanonicalHash = string & {
     readonly [canonicalHashBrand]: true;
 };
@@ -423,18 +411,6 @@ declare function u256ToBigInt(low: string, high: string): bigint;
 declare function encodeU256(n: bigint): [string, string];
 
 declare const PUBLIC_RPC_FALLBACKS: readonly string[];
-/**
- * Codes our own proxies emit to *refuse* a call on policy grounds: no API key,
- * insufficient credits, rate limited, wrong origin.
- *
- * These must never be treated as transient. They sit inside the JSON-RPC
- * reserved server-error range and carry messages like "Too many requests", so
- * every generic transient heuristic below would otherwise match them — and a
- * caller with a fallback list would quietly retry the same call against a
- * different upstream. That turns a refusal into a redirect: the harder the
- * meter says no, the faster traffic routes around it. A policy refusal is an
- * answer, not a failure; retrying it elsewhere is always wrong.
- */
 declare const POLICY_REFUSAL_CODES: readonly number[];
 declare function isPolicyRefusal(input: {
     body?: unknown;
@@ -452,18 +428,6 @@ interface FailoverFetchOptions {
     }) => void;
 }
 declare function createFailoverFetch(urls: string[], options?: FailoverFetchOptions): typeof fetch;
-/**
- * Hostnames and env-var names that reach a paid upstream directly.
- *
- * An app must never name one of these. Everything paid goes through the
- * backend, the only place a call can be authenticated, scoped, rate limited
- * and billed. An app that knows a node's address has a route around all four —
- * and since the address ships in the client bundle, so does every visitor.
- *
- * The list lives here, not in each app, because it is the part that drifts:
- * adding an upstream must protect every consumer at once. Each app keeps its
- * own small test that scans its source for these with its own file APIs.
- */
 declare const PAID_UPSTREAM_MARKERS: readonly string[];
 
 interface RpcProxyConfig {
@@ -480,12 +444,6 @@ interface BackendProxyConfig {
     apiKey: string | undefined;
     checkRateLimit: (ip: string) => boolean;
     fetchImpl?: typeof fetch;
-    /**
-     * Forwards a cookie the app already sets (e.g. its own account-session
-     * cookie) as a header, so the backend can attribute cost to the calling
-     * end-user instead of only the app's shared API key. Purely additive —
-     * omitted when the cookie isn't present, never blocks the request.
-     */
     forwardCookie?: {
         name: string;
         header: string;
@@ -497,12 +455,6 @@ declare const ALLOWED_IMAGE_CONTENT_TYPES: Set<string>;
 declare const MAX_IMAGE_REDIRECTS = 5;
 declare const MAX_IMAGE_PROXY_BYTES: number;
 declare function isPrivateHost(hostname: string): boolean;
-/**
- * Validates a URL before it is fetched server-side. `requireHttps` is on by
- * default; callers that legitimately accept plain http (a metadata URI already
- * committed on chain, say) opt out explicitly rather than the guard being
- * lenient for everyone.
- */
 declare function validateUrl(raw: string, options?: {
     requireHttps?: boolean;
 }): {
@@ -511,33 +463,10 @@ declare function validateUrl(raw: string, options?: {
     error: string;
     status: number;
 };
-/** Convenience for callers that only need a yes/no, mirroring the backend's prior helper. */
 declare function isPrivateOrInsecureUrl(raw: string, requireHttps?: boolean): boolean;
 
-/**
- * Proxies a remote image, which means fetching a URL an untrusted caller chose
- * — the classic SSRF shape. Guarded in four places, each of which has to hold:
- *
- *   1. the URL is https, credential-free and not a private host
- *   2. the hostname's *resolved* addresses are re-checked, since a public name
- *      can resolve to a private address
- *   3. redirects are followed manually, re-validating each hop, because a
- *      permitted host can redirect into the private range
- *   4. the response must be an allowed image type and is read under a byte cap
- *
- * This existed as a byte-identical copy in each app, so a fix to one would not
- * have reached the other. DNS resolution is injected rather than imported: it
- * is runtime-specific, and this package stays isomorphic.
- *
- * Note the remaining exposure: between resolving a hostname and fetching it,
- * the name could resolve differently (DNS rebinding). Closing that needs the
- * fetch pinned to the address already checked, which the platform fetch does
- * not expose. The content-type allowlist and byte cap bound what an attacker
- * gets if they win that race.
- */
 interface ImageProxyConfig {
     checkRateLimit: (ip: string) => boolean;
-    /** Returns every address a hostname resolves to. Injected; see above. */
     resolveHostname: (hostname: string) => Promise<string[]>;
     fetchImpl?: typeof fetch;
     userAgent?: string;
@@ -548,7 +477,6 @@ interface CappedBody {
     error?: string;
     status?: number;
 }
-/** Reads a response body, refusing anything past `maxBytes` rather than buffering it. */
 declare function readBodyWithCap(res: Response, maxBytes: number): Promise<CappedBody>;
 declare function createImageProxyHandler(config: ImageProxyConfig): (req: Request) => Promise<Response>;
 
@@ -576,17 +504,6 @@ declare function createRateLimiter(windowMs: number, max: number): (key: string)
 declare const TRUSTED_APP_IP_HEADER = "x-medialane-client-ip";
 declare function requestIp(req: Request): string;
 
-/**
- * Same-origin guard for server routes. A missing `Origin` header is allowed,
- * because same-origin navigations and server-to-server calls do not send one;
- * a present `Origin` must match `Host`.
- *
- * Read that carefully before relying on it: this blocks cross-site *browser*
- * abuse, and nothing else. A non-browser client simply omits `Origin` and
- * passes. It is not a substitute for authentication, and on a route that
- * spends money or credits it must be paired with a rate limit and, where the
- * route touches a paid resource, real auth.
- */
 declare function isSameOrigin(req: Request): boolean;
 
 declare const IDENTITY_TTL_SECONDS = 86400;

package/dist/index.d.ts

@@ -393,18 +393,6 @@ declare function hasCapability(id: string | null | undefined, cap: ServiceCapabi
 
 declare function normalizeAddress(chain: Chain, address: string): string;
 declare const canonicalHashBrand: unique symbol;
-/**
- * A felt hash in exactly one spelling: lowercase, zero-padded to 64 hex digits.
- *
- * Felts have many equal spellings — `0x0ab`, `0xAB` and `0xab` are the same
- * value on chain but three different strings. Anything that uses a hash as an
- * identity or uniqueness key must therefore compare canonical form, or the
- * same on-chain fact can be presented as several distinct records.
- *
- * Only `normalizeHash` can produce this type, so a function that demands a
- * `CanonicalHash` cannot be handed a raw caller-supplied string. It remains
- * assignable to `string`, so existing readers are unaffected.
- */
 type CanonicalHash = string & {
     readonly [canonicalHashBrand]: true;
 };
@@ -423,18 +411,6 @@ declare function u256ToBigInt(low: string, high: string): bigint;
 declare function encodeU256(n: bigint): [string, string];
 
 declare const PUBLIC_RPC_FALLBACKS: readonly string[];
-/**
- * Codes our own proxies emit to *refuse* a call on policy grounds: no API key,
- * insufficient credits, rate limited, wrong origin.
- *
- * These must never be treated as transient. They sit inside the JSON-RPC
- * reserved server-error range and carry messages like "Too many requests", so
- * every generic transient heuristic below would otherwise match them — and a
- * caller with a fallback list would quietly retry the same call against a
- * different upstream. That turns a refusal into a redirect: the harder the
- * meter says no, the faster traffic routes around it. A policy refusal is an
- * answer, not a failure; retrying it elsewhere is always wrong.
- */
 declare const POLICY_REFUSAL_CODES: readonly number[];
 declare function isPolicyRefusal(input: {
     body?: unknown;
@@ -452,18 +428,6 @@ interface FailoverFetchOptions {
     }) => void;
 }
 declare function createFailoverFetch(urls: string[], options?: FailoverFetchOptions): typeof fetch;
-/**
- * Hostnames and env-var names that reach a paid upstream directly.
- *
- * An app must never name one of these. Everything paid goes through the
- * backend, the only place a call can be authenticated, scoped, rate limited
- * and billed. An app that knows a node's address has a route around all four —
- * and since the address ships in the client bundle, so does every visitor.
- *
- * The list lives here, not in each app, because it is the part that drifts:
- * adding an upstream must protect every consumer at once. Each app keeps its
- * own small test that scans its source for these with its own file APIs.
- */
 declare const PAID_UPSTREAM_MARKERS: readonly string[];
 
 interface RpcProxyConfig {
@@ -480,12 +444,6 @@ interface BackendProxyConfig {
     apiKey: string | undefined;
     checkRateLimit: (ip: string) => boolean;
     fetchImpl?: typeof fetch;
-    /**
-     * Forwards a cookie the app already sets (e.g. its own account-session
-     * cookie) as a header, so the backend can attribute cost to the calling
-     * end-user instead of only the app's shared API key. Purely additive —
-     * omitted when the cookie isn't present, never blocks the request.
-     */
     forwardCookie?: {
         name: string;
         header: string;
@@ -497,12 +455,6 @@ declare const ALLOWED_IMAGE_CONTENT_TYPES: Set<string>;
 declare const MAX_IMAGE_REDIRECTS = 5;
 declare const MAX_IMAGE_PROXY_BYTES: number;
 declare function isPrivateHost(hostname: string): boolean;
-/**
- * Validates a URL before it is fetched server-side. `requireHttps` is on by
- * default; callers that legitimately accept plain http (a metadata URI already
- * committed on chain, say) opt out explicitly rather than the guard being
- * lenient for everyone.
- */
 declare function validateUrl(raw: string, options?: {
     requireHttps?: boolean;
 }): {
@@ -511,33 +463,10 @@ declare function validateUrl(raw: string, options?: {
     error: string;
     status: number;
 };
-/** Convenience for callers that only need a yes/no, mirroring the backend's prior helper. */
 declare function isPrivateOrInsecureUrl(raw: string, requireHttps?: boolean): boolean;
 
-/**
- * Proxies a remote image, which means fetching a URL an untrusted caller chose
- * — the classic SSRF shape. Guarded in four places, each of which has to hold:
- *
- *   1. the URL is https, credential-free and not a private host
- *   2. the hostname's *resolved* addresses are re-checked, since a public name
- *      can resolve to a private address
- *   3. redirects are followed manually, re-validating each hop, because a
- *      permitted host can redirect into the private range
- *   4. the response must be an allowed image type and is read under a byte cap
- *
- * This existed as a byte-identical copy in each app, so a fix to one would not
- * have reached the other. DNS resolution is injected rather than imported: it
- * is runtime-specific, and this package stays isomorphic.
- *
- * Note the remaining exposure: between resolving a hostname and fetching it,
- * the name could resolve differently (DNS rebinding). Closing that needs the
- * fetch pinned to the address already checked, which the platform fetch does
- * not expose. The content-type allowlist and byte cap bound what an attacker
- * gets if they win that race.
- */
 interface ImageProxyConfig {
     checkRateLimit: (ip: string) => boolean;
-    /** Returns every address a hostname resolves to. Injected; see above. */
     resolveHostname: (hostname: string) => Promise<string[]>;
     fetchImpl?: typeof fetch;
     userAgent?: string;
@@ -548,7 +477,6 @@ interface CappedBody {
     error?: string;
     status?: number;
 }
-/** Reads a response body, refusing anything past `maxBytes` rather than buffering it. */
 declare function readBodyWithCap(res: Response, maxBytes: number): Promise<CappedBody>;
 declare function createImageProxyHandler(config: ImageProxyConfig): (req: Request) => Promise<Response>;
 
@@ -576,17 +504,6 @@ declare function createRateLimiter(windowMs: number, max: number): (key: string)
 declare const TRUSTED_APP_IP_HEADER = "x-medialane-client-ip";
 declare function requestIp(req: Request): string;
 
-/**
- * Same-origin guard for server routes. A missing `Origin` header is allowed,
- * because same-origin navigations and server-to-server calls do not send one;
- * a present `Origin` must match `Host`.
- *
- * Read that carefully before relying on it: this blocks cross-site *browser*
- * abuse, and nothing else. A non-browser client simply omits `Origin` and
- * passes. It is not a substitute for authentication, and on a route that
- * spends money or credits it must be paired with a rate limit and, where the
- * route touches a paid resource, real auth.
- */
 declare function isSameOrigin(req: Request): boolean;
 
 declare const IDENTITY_TTL_SECONDS = 86400;