@heightproof/shared 0.0.0-stage → 0.1.0

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,278 @@
+import { context, SpanStatusCode, trace } from "@opentelemetry/api";
+import { detectCostWaste, detectDisagreement, detectReorgLag, detectSilentFailure, detectStaleHead, detectThrottling } from "./detectors.js";
+import { z } from "zod";
+export { airnodePassthroughRequestHash, checkAirnodeAttestation, readAirnodeAttestation, recoverAirnodeSigner, reverifyAttestation } from "./airnode.js";
+export { buildDemoEvents } from "./demoEvents.js";
+export { detectCostWaste, detectDisagreement, detectReorgLag, detectSilentFailure, detectStaleHead, detectThrottling, DEFAULT_DETECTOR_THRESHOLDS } from "./detectors.js";
+export { chainBlockTimeMs, classifyResultShape, extractBlockHash, extractBlockNumber, extractBlockTag, extractRpcError, hashEndpoint, hashRpcResult, methodCostUnits, normalizeRpcResult, pinBlockTag, blockTagParamIndex, isThrottleSignature, isVerifiableMethod, resultCount, VERIFIABLE_METHODS, CHAIN_BLOCK_TIME_MS, DEFAULT_METHOD_COST_UNITS } from "./rpc.js";
+/** Largest signed response body kept as attestation evidence. */
+export const AIRNODE_SIGNED_BODY_MAX_CHARS = 65_536;
+export const HttpMethodSchema = z.enum([
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "HEAD"
+]);
+export const TrafficKindSchema = z.enum(["rest", "graphql", "evm_rpc", "websocket", "webhook"]);
+export const HeightproofEventSchema = z.object({
+    id: z.string().min(8),
+    traceId: z.string().regex(/^[0-9a-f]{32}$/i).optional(),
+    parentSpanId: z.string().regex(/^[0-9a-f]{16}$/i).optional(),
+    projectId: z.string().min(1),
+    serviceName: z.string().min(1),
+    environment: z.string().default("development"),
+    timestamp: z.string().datetime(),
+    kind: TrafficKindSchema,
+    request: z.object({
+        method: HttpMethodSchema,
+        path: z.string(),
+        route: z.string().optional(),
+        ip: z.string().optional(),
+        userAgent: z.string().optional(),
+        headers: z.record(z.string()).default({}),
+        query: z.record(z.unknown()).default({}),
+        body: z.unknown().optional(),
+        auth: z
+            .object({
+            present: z.boolean(),
+            scheme: z.string().optional(),
+            failed: z.boolean().default(false)
+        })
+            .default({ present: false, failed: false })
+    }),
+    response: z.object({
+        statusCode: z.number().int().min(100).max(599),
+        latencyMs: z.number().nonnegative(),
+        bodyBytes: z.number().nonnegative().optional()
+    }),
+    graphQL: z
+        .object({
+        operationName: z.string().optional(),
+        operationType: z.string().optional()
+    })
+        .optional(),
+    evmRpc: z
+        .object({
+        method: z.string(),
+        chainId: z.string().optional(),
+        provider: z.string().optional(),
+        walletAddress: z.string().optional(),
+        contractAddress: z.string().optional(),
+        // Result capture. Every field below is optional so events produced by older SDK
+        // versions keep validating; detectors treat a missing field as "not observed"
+        // rather than as a negative observation.
+        blockTag: z.string().optional(),
+        blockNumber: z.string().optional(),
+        blockHash: z.string().optional(),
+        resultHash: z.string().optional(),
+        resultShape: z.enum(["null", "empty_array", "empty_data", "value", "error_in_body"]).optional(),
+        resultCount: z.number().int().nonnegative().optional(),
+        /** Whether the response carried a rate-limiting signature (D5). */
+        throttled: z.boolean().optional(),
+        rpcErrorCode: z.number().int().optional(),
+        rpcErrorMessage: z.string().optional(),
+        // Hash of the endpoint URL. The URL itself must never be stored: it embeds the key.
+        endpointHash: z.string().optional(),
+        costUnits: z.number().nonnegative().optional(),
+        // Links a verification call back to the primary call it shadows (detector D2).
+        shadowOfTraceId: z.string().optional(),
+        // A signed answer from an attesting endpoint (an Airnode). Attribution, not truth:
+        // detectors compare it like any other peer. The worker re-checks the signature
+        // against `signedBody` rather than trusting the SDK's verdict.
+        attestation: z
+            .object({
+            scheme: z.literal("airnode"),
+            signer: z.string().regex(/^0x[0-9a-fA-F]{40}$/),
+            requestHash: z.string().regex(/^0x[0-9a-fA-F]{64}$/),
+            timestamp: z.string().regex(/^\d+$/),
+            signature: z.string().regex(/^0x[0-9a-fA-F]{130}$/),
+            signatureValid: z.boolean(),
+            requestBound: z.boolean(),
+            // The response text exactly as signed, kept so the evidence can be re-verified
+            // later by anyone. Capped: an attestation over a larger body is kept without it.
+            signedBody: z.string().max(AIRNODE_SIGNED_BODY_MAX_CHARS).optional()
+        })
+            .optional()
+    })
+        .optional(),
+    error: z
+        .object({
+        type: z.string(),
+        message: z.string(),
+        stack: z.string().optional()
+    })
+        .optional()
+});
+export const EventBatchSchema = z.object({
+    events: z.array(HeightproofEventSchema).min(1).max(100)
+});
+const defaultSensitiveFields = [
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "password",
+    "passcode",
+    "secret",
+    "token",
+    "accessToken",
+    "refreshToken",
+    "apiKey",
+    "xApiKey",
+    "xHeightproofApiKey",
+    "privateKey",
+    "mnemonic"
+];
+export function classifyTraffic(path, body) {
+    if (path.toLowerCase().includes("graphql"))
+        return "graphql";
+    if (isRecord(body) && typeof body.jsonrpc === "string" && typeof body.method === "string") {
+        return "evm_rpc";
+    }
+    return "rest";
+}
+export function normalizeRoutePath(path) {
+    const cleanPath = path.split("?")[0]?.replace(/\/+$/, "") || "/";
+    return cleanPath
+        .split("/")
+        .map((segment) => {
+        if (!segment)
+            return segment;
+        if (/^\d+$/.test(segment))
+            return ":id";
+        if (/^[0-9a-f]{24}$/i.test(segment))
+            return ":objectId";
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(segment)) {
+            return ":uuid";
+        }
+        if (/^0x[0-9a-f]{40}$/i.test(segment))
+            return ":address";
+        if (/^0x[0-9a-f]{64}$/i.test(segment))
+            return ":hash";
+        return segment;
+    })
+        .join("/");
+}
+export function normalizeErrorMessage(message) {
+    return message
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/gi, ":uuid")
+        .replace(/\b\d+\b/g, "#")
+        .trim();
+}
+export function redactValue(value, config = {}) {
+    const replacement = config.replacement ?? "[REDACTED]";
+    const sensitive = new Set([...defaultSensitiveFields, ...(config.fields ?? [])].map(normalizeKey));
+    function visit(input, key) {
+        if (key && sensitive.has(normalizeKey(key)))
+            return replacement;
+        if (Array.isArray(input))
+            return input.map((entry) => visit(entry));
+        if (!isRecord(input))
+            return input;
+        return Object.fromEntries(Object.entries(input).map(([childKey, childValue]) => [childKey, visit(childValue, childKey)]));
+    }
+    return visit(value);
+}
+export function redactHeaders(headers, config = {}) {
+    const replacement = config.replacement ?? "[REDACTED]";
+    const sensitive = new Set([...defaultSensitiveFields, ...(config.headerFields ?? [])].map(normalizeKey));
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+        key,
+        sensitive.has(normalizeKey(key)) ? replacement : value
+    ]));
+}
+export async function withSpan(name, attributes, operation) {
+    const tracer = trace.getTracer("heightproof");
+    const span = tracer.startSpan(name);
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value !== undefined)
+            span.setAttribute(key, value);
+    }
+    try {
+        const result = await context.with(trace.setSpan(context.active(), span), operation);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+    }
+    catch (error) {
+        span.recordException(error);
+        span.setStatus({
+            code: SpanStatusCode.ERROR,
+            message: error instanceof Error ? error.message : "unknown_error"
+        });
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+export function assessThreat(event, recentIpRequestCount = 0, web3Context = {}) {
+    const signals = [];
+    if (event.response.statusCode >= 500) {
+        signals.push({ name: "server_error", weight: 18, reason: "Request produced a server error" });
+    }
+    if ([401, 403].includes(event.response.statusCode) || event.request.auth.failed) {
+        signals.push({ name: "auth_failure", weight: 24, reason: "Authentication failed or was rejected" });
+    }
+    if (event.response.latencyMs > 1500) {
+        signals.push({ name: "high_latency", weight: 12, reason: "Request latency exceeded 1500ms" });
+    }
+    if (recentIpRequestCount > 120) {
+        signals.push({ name: "rate_anomaly", weight: 30, reason: "IP exceeded normal request volume" });
+    }
+    if (event.kind === "evm_rpc" && event.evmRpc?.method.match(/send|sign|private|unlock/i)) {
+        signals.push({ name: "sensitive_rpc", weight: 26, reason: "EVM RPC method can affect keys or funds" });
+    }
+    if (event.kind === "evm_rpc") {
+        if ((web3Context.recentMethodCallCount ?? 0) > 200) {
+            signals.push({
+                name: "rpc_flooding",
+                weight: 28,
+                reason: `${event.evmRpc?.method ?? "This RPC method"} was called far more often than normal from a single source`
+            });
+        }
+        const isTransactionSubmission = Boolean(event.evmRpc?.method.match(/sendrawtransaction|sendtransaction/i));
+        if (isTransactionSubmission &&
+            (web3Context.walletRecentHourTxCount ?? 0) >= 10 &&
+            (web3Context.walletRecentHourTxCount ?? 0) > (web3Context.walletBaselineHourlyTxCount ?? 0) * 10) {
+            signals.push({
+                name: "tx_burst",
+                weight: 30,
+                reason: "Wallet transaction volume spiked well above its historical baseline"
+            });
+        }
+        const baselineLatency = web3Context.providerBaselineP95LatencyMs ?? 0;
+        const recentLatency = web3Context.providerRecentP95LatencyMs ?? 0;
+        if (baselineLatency > 0 && recentLatency > 500 && recentLatency > baselineLatency * 3) {
+            signals.push({
+                name: "provider_degradation",
+                weight: 20,
+                reason: "EVM RPC provider latency has degraded well beyond its recent baseline"
+            });
+        }
+        if ((web3Context.providerRecentFailureRate ?? 0) > 0.2) {
+            signals.push({
+                name: "provider_failures",
+                weight: 22,
+                reason: "EVM RPC provider is failing an abnormal share of recent requests"
+            });
+        }
+        signals.push(...detectStaleHead(event, web3Context.staleHead), ...detectSilentFailure(event, web3Context.silentFailure), ...detectCostWaste(event, web3Context.costWaste), ...detectDisagreement(event, web3Context.disagreement), ...detectReorgLag(event, web3Context.reorg), ...detectThrottling(event, web3Context.throttling));
+    }
+    if (event.kind === "graphql" && String(event.request.body ?? "").length > 10000) {
+        signals.push({ name: "large_graphql_payload", weight: 14, reason: "GraphQL payload is unusually large" });
+    }
+    const score = Math.min(100, signals.reduce((total, signal) => total + signal.weight, 0));
+    return {
+        score,
+        severity: score >= 75 ? "critical" : score >= 50 ? "high" : score >= 25 ? "medium" : "low",
+        signals
+    };
+}
+function normalizeKey(key) {
+    return key.replace(/[-_]/g, "").toLowerCase();
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/dist/rpc.d.ts

@@ -0,0 +1,111 @@
+/**
+ * RPC result capture primitives.
+ *
+ * Every content-aware detector (see docs/detectors.md) depends on being able to answer
+ * "did these two responses say the same thing?" without storing raw chain state. That
+ * reduces to normalizing a JSON-RPC result into a canonical form and hashing it.
+ *
+ * Normalization has to be exactly as aggressive as JSON-RPC's own ambiguity and no more.
+ * Too little and honest providers look like they disagree over formatting; too much and
+ * genuinely different values collide into the same hash and real disagreement goes unseen.
+ */
+export type ResultShape = "null" | "empty_array" | "empty_data" | "value" | "error_in_body";
+export type BlockTag = string;
+/**
+ * Default compute-unit weights, used for cost accounting (detector D6).
+ *
+ * These are order-of-magnitude defaults modelled on published provider pricing. Providers
+ * change their weights, and they differ between providers, so treat these as a starting
+ * point to be overridden per deployment rather than as authoritative billing figures.
+ */
+export declare const DEFAULT_METHOD_COST_UNITS: Record<string, number>;
+/** Cost weight for a method, or `undefined` when the method is not in the table. */
+export declare function methodCostUnits(method: string, table?: Record<string, number>): number | undefined;
+/**
+ * Nominal block time in milliseconds, used by the stale-head detector (D1) to decide how
+ * long a head may stand still before it is suspicious. Unknown chains fall back to a
+ * measured median at the call site rather than to a global constant.
+ */
+export declare const CHAIN_BLOCK_TIME_MS: Record<string, number>;
+export declare function chainBlockTimeMs(chainId: string | undefined): number | undefined;
+/**
+ * Hash of an RPC endpoint URL.
+ *
+ * Provider URLs embed API keys (`https://eth-mainnet.g.alchemy.com/v2/<KEY>`), so the URL
+ * itself must never be persisted or transmitted. This lets two endpoints be told apart
+ * without Heightproof ever holding the credential.
+ */
+export declare function hashEndpoint(url: string): string;
+/** Canonical hash of a JSON-RPC result, for same-height comparison across providers. */
+export declare function hashRpcResult(result: unknown, method?: string): string;
+/**
+ * Reduce a JSON-RPC result to canonical form:
+ *
+ * - object keys sorted, so key order never affects the hash
+ * - `undefined`-valued keys dropped; explicit `null` preserved (they mean different things)
+ * - hex lowercased everywhere (hex is case-insensitive, so case is never a real difference)
+ * - leading zeros stripped only from values the spec defines as QUANTITY
+ * - provider-order-dependent arrays (logs) sorted into chain order
+ */
+export declare function normalizeRpcResult(result: unknown, method?: string): unknown;
+/**
+ * Classify a response so silent failures (D3) are visible without storing the result.
+ *
+ * `empty_array` and `null` are recorded as facts, not as failures — emptiness is often
+ * correct. D3 only ever fires on a *change* or a disagreement, never on emptiness alone.
+ */
+export declare function classifyResultShape(result: unknown, errorInBody?: boolean): ResultShape;
+/**
+ * Number of entries in an array result, used to spot silently truncated pages (D3).
+ * Non-array results have no count rather than a count of zero.
+ */
+export declare function resultCount(result: unknown): number | undefined;
+/** The block tag a call was made against, as written by the caller. */
+export declare function extractBlockTag(method: string, params: unknown): BlockTag | undefined;
+/**
+ * The concrete height a call resolved against.
+ *
+ * Prefers a height carried by the result itself, since that is what the provider actually
+ * answered from; falls back to a numeric block tag in the request.
+ */
+export declare function extractBlockNumber(method: string, params: unknown, result: unknown): string | undefined;
+/** The block hash a result was served from, when the response carries one (reorg tracking, D4). */
+export declare function extractBlockHash(result: unknown): string | undefined;
+/** A JSON-RPC error object returned inside an HTTP 200 body. */
+export declare function extractRpcError(body: unknown): {
+    code?: number;
+    message?: string;
+} | undefined;
+/**
+ * Methods whose answer at a fixed block height is deterministic, and which are therefore
+ * safe to replay against another endpoint for comparison (detector D2).
+ *
+ * This is an allowlist, never a denylist: shadowing `eth_gasPrice` or `eth_estimateGas`
+ * would compare two legitimately different answers and report every sample as a
+ * disagreement.
+ */
+export declare const VERIFIABLE_METHODS: Set<string>;
+export declare function isVerifiableMethod(method: string): boolean;
+export declare function blockTagParamIndex(method: string): number | undefined;
+/**
+ * Rewrite a call's block tag to a concrete height so two endpoints can be asked exactly
+ * the same question.
+ *
+ * This is the single most important step in cross-provider verification. Comparing a
+ * `latest` response from one endpoint against a `latest` response from another measures
+ * how far apart their heads are, not whether they disagree — and at any real head skew
+ * that produces a false positive on essentially every sample.
+ *
+ * Returns `undefined` when the call cannot be pinned, in which case it must not be
+ * shadowed at all.
+ */
+export declare function pinBlockTag(method: string, params: unknown, blockNumber: string): unknown[] | undefined;
+/**
+ * Whether a response carries a rate-limiting signature (detector D5).
+ *
+ * Covers the clean case (HTTP 429) and the case that actually matters: throttling
+ * delivered as a JSON-RPC error inside an HTTP 200, where nothing watching status codes
+ * will ever see it.
+ */
+export declare function isThrottleSignature(statusCode: number | undefined, rpcErrorCode: number | undefined, rpcErrorMessage: string | undefined): boolean;
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,aAAa,GAAG,YAAY,GAAG,OAAO,GAAG,eAAe,CAAC;AAE5F,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AA2E9B;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAe5D,CAAC;AAEF,oFAAoF;AACpF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAA6B,GACxD,MAAM,GAAG,SAAS,CAEpB;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAOtD,CAAC;AAEF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGhF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAS5E;AAwED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,WAAW,UAAQ,GAAG,WAAW,CASrF;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAMrF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAcvG;AAED,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAWpE;AAED,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAW9F;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,aAS7B,CAAC;AAKH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAErE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,EAAE,GAAG,SAAS,CAuCvG;AAgBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,OAAO,CAIT"}