@heightproof/shared 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jayces
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @heightproof/shared
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Internal building blocks shared by the [Heightproof](https://github.com/macjayz/heightproof)
+SDKs and services: the `HeightproofEvent` schema (Zod), JSON-RPC result normalization and
+hashing, redaction helpers, and the content-aware RPC reliability detectors.
+
+You normally do not install this directly; it is a dependency of
+[`@heightproof/web3`](https://www.npmjs.com/package/@heightproof/web3) and
+[`@heightproof/sdk-node`](https://www.npmjs.com/package/@heightproof/sdk-node). Its API follows
+those packages and may change between minor versions while Heightproof is pre-1.0.
+
+## License
+
+MIT

package/dist/airnode.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Airnode attestations.
+ *
+ * An Airnode signs every response it serves: an EIP-191 signature over
+ * keccak256(requestHash ‖ uint256 timestamp ‖ body bytes). A verification observation that
+ * carries one is no longer just "a third provider said so" — anyone holding the signed body
+ * can check, offline and without trusting Heightproof, which address answered which request
+ * at which time.
+ *
+ * What a signature does not prove is that the answer is correct. It is attribution, not
+ * truth: an attested reference can be stale like any other endpoint, and detectors treat it
+ * as one more comparable peer, never as an oracle.
+ *
+ * Spec: https://airnodehub-docs.api3.org/airnode/attestation
+ */
+export type AirnodeAttestation = {
+    /** The address the response claims to be signed by (X-Airnode-Address). */
+    signer: string;
+    requestHash: string;
+    /** Unix seconds at which the response was signed. */
+    timestamp: string;
+    signature: string;
+};
+export type AirnodeAttestationCheck = {
+    /** The signature recovers to `signer` over exactly this body, request and time. */
+    signatureValid: boolean;
+    /** The request hash is the one this exact request derives, so the answer is ours. */
+    requestBound: boolean;
+};
+/** Reads the four attestation headers. Undefined unless all four are present and well formed. */
+export declare function readAirnodeAttestation(headers: Pick<Headers, "get">): AirnodeAttestation | undefined;
+/**
+ * The request hash an Airnode derives for a passthrough request.
+ *
+ * keccak256(utf8(JSON.stringify(["passthrough", METHOD, path, queryEntries, headerEntries, body])))
+ * where `path` excludes the `/api` prefix and query entries keep their sent order with every
+ * `x-airnode-*` parameter removed.
+ */
+export declare function airnodePassthroughRequestHash(input: {
+    method: string;
+    /** Full request URL, including the `/api` prefix and the query. */
+    url: string;
+    body: string;
+    headerEntries?: [string, string][];
+}): string | undefined;
+/** Recovers the address that signed `body` under this attestation, or undefined if malformed. */
+export declare function recoverAirnodeSigner(attestation: AirnodeAttestation, body: string): string | undefined;
+/**
+ * Checks an attestation against the body that arrived and, when known, the request that
+ * was sent. Never throws: a malformed attestation is simply not valid.
+ *
+ * `body` must be the response text exactly as received. Parsing and re-serializing it
+ * changes the bytes and every signature then fails.
+ */
+export declare function checkAirnodeAttestation(attestation: AirnodeAttestation, body: string, expectedRequestHash?: string): AirnodeAttestationCheck;
+/**
+ * Re-checks an attestation that arrived on an ingested event, without trusting the SDK.
+ *
+ * `signatureValid` survives only when the kept body still carries the signature *and*
+ * holds the very result whose hash was compared — otherwise a valid signature over some
+ * other answer could vouch for this one. Without a kept body there is nothing to check, so
+ * it is false. `requestBound` is the SDK's: re-deriving it needs the exact request bytes
+ * and endpoint URL, which are deliberately never transmitted.
+ */
+export declare function reverifyAttestation<T extends AirnodeAttestation & {
+    signatureValid: boolean;
+    signedBody?: string;
+}>(attestation: T, method: string, resultHash: string | undefined, hashResult: (result: unknown, method: string) => string): T;
+//# sourceMappingURL=airnode.d.ts.map

package/dist/airnode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"airnode.d.ts","sourceRoot":"","sources":["../src/airnode.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,mFAAmF;IACnF,cAAc,EAAE,OAAO,CAAC;IACxB,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAC;CACvB,CAAC;AAMF,iGAAiG;AACjG,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,GAC5B,kBAAkB,GAAG,SAAS,CAYhC;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;CACpC,GAAG,MAAM,GAAG,SAAS,CA6BrB;AAED,iGAAiG;AACjG,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,kBAAkB,EAC/B,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAyBpB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,kBAAkB,EAC/B,IAAI,EAAE,MAAM,EACZ,mBAAmB,CAAC,EAAE,MAAM,GAC3B,uBAAuB,CAUzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,SAAS,kBAAkB,GAAG;IAAE,cAAc,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAE/E,WAAW,EAAE,CAAC,EACd,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,GACtD,CAAC,CAkBH"}

package/dist/airnode.js

@@ -0,0 +1,117 @@
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from "@noble/hashes/utils";
+const HEX_32 = /^0x[0-9a-fA-F]{64}$/;
+const HEX_ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const HEX_SIGNATURE = /^0x[0-9a-fA-F]{130}$/;
+/** Reads the four attestation headers. Undefined unless all four are present and well formed. */
+export function readAirnodeAttestation(headers) {
+    const signer = headers.get("x-airnode-address");
+    const requestHash = headers.get("x-airnode-request-hash");
+    const timestamp = headers.get("x-airnode-timestamp");
+    const signature = headers.get("x-airnode-signature");
+    if (!signer || !HEX_ADDRESS.test(signer))
+        return undefined;
+    if (!requestHash || !HEX_32.test(requestHash))
+        return undefined;
+    if (!timestamp || !/^\d+$/.test(timestamp))
+        return undefined;
+    if (!signature || !HEX_SIGNATURE.test(signature))
+        return undefined;
+    return { signer, requestHash, timestamp, signature };
+}
+/**
+ * The request hash an Airnode derives for a passthrough request.
+ *
+ * keccak256(utf8(JSON.stringify(["passthrough", METHOD, path, queryEntries, headerEntries, body])))
+ * where `path` excludes the `/api` prefix and query entries keep their sent order with every
+ * `x-airnode-*` parameter removed.
+ */
+export function airnodePassthroughRequestHash(input) {
+    let parsed;
+    try {
+        parsed = new URL(input.url);
+    }
+    catch {
+        return undefined;
+    }
+    const apiIndex = parsed.pathname.indexOf("/api/");
+    if (apiIndex === -1)
+        return undefined;
+    const path = parsed.pathname.slice(apiIndex + "/api".length);
+    const queryEntries = [...parsed.searchParams.entries()].filter(([name]) => !name.startsWith("x-airnode-"));
+    const headerEntries = [...(input.headerEntries ?? [])].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+    const serialized = JSON.stringify([
+        "passthrough",
+        input.method.toUpperCase(),
+        path,
+        queryEntries,
+        headerEntries,
+        input.body
+    ]);
+    return toHex(keccak_256(utf8ToBytes(serialized)));
+}
+/** Recovers the address that signed `body` under this attestation, or undefined if malformed. */
+export function recoverAirnodeSigner(attestation, body) {
+    try {
+        const timestamp = BigInt(attestation.timestamp);
+        const digest = keccak_256(concatBytes(hexToBytes(attestation.requestHash.slice(2)), hexToBytes(timestamp.toString(16).padStart(64, "0")), utf8ToBytes(body)));
+        const prefixed = keccak_256(concatBytes(utf8ToBytes("\x19Ethereum Signed Message:\n32"), digest));
+        const signature = hexToBytes(attestation.signature.slice(2));
+        const recovery = signature[64] >= 27 ? signature[64] - 27 : signature[64];
+        const publicKey = secp256k1.Signature.fromCompact(signature.slice(0, 64))
+            .addRecoveryBit(recovery)
+            .recoverPublicKey(prefixed)
+            .toRawBytes(false);
+        return toHex(keccak_256(publicKey.slice(1)).slice(-20));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Checks an attestation against the body that arrived and, when known, the request that
+ * was sent. Never throws: a malformed attestation is simply not valid.
+ *
+ * `body` must be the response text exactly as received. Parsing and re-serializing it
+ * changes the bytes and every signature then fails.
+ */
+export function checkAirnodeAttestation(attestation, body, expectedRequestHash) {
+    const recovered = recoverAirnodeSigner(attestation, body);
+    return {
+        signatureValid: recovered !== undefined && recovered.toLowerCase() === attestation.signer.toLowerCase(),
+        requestBound: expectedRequestHash !== undefined &&
+            expectedRequestHash.toLowerCase() === attestation.requestHash.toLowerCase()
+    };
+}
+/**
+ * Re-checks an attestation that arrived on an ingested event, without trusting the SDK.
+ *
+ * `signatureValid` survives only when the kept body still carries the signature *and*
+ * holds the very result whose hash was compared — otherwise a valid signature over some
+ * other answer could vouch for this one. Without a kept body there is nothing to check, so
+ * it is false. `requestBound` is the SDK's: re-deriving it needs the exact request bytes
+ * and endpoint URL, which are deliberately never transmitted.
+ */
+export function reverifyAttestation(attestation, method, resultHash, hashResult) {
+    if (!attestation.signedBody)
+        return { ...attestation, signatureValid: false };
+    const { signatureValid } = checkAirnodeAttestation(attestation, attestation.signedBody);
+    if (!signatureValid)
+        return { ...attestation, signatureValid: false };
+    let coversResult = resultHash === undefined;
+    if (resultHash !== undefined) {
+        try {
+            const parsed = JSON.parse(attestation.signedBody);
+            coversResult =
+                parsed.result !== undefined && hashResult(parsed.result, method) === resultHash;
+        }
+        catch {
+            coversResult = false;
+        }
+    }
+    return { ...attestation, signatureValid: coversResult };
+}
+function toHex(bytes) {
+    return `0x${bytesToHex(bytes)}`;
+}

package/dist/demoEvents.d.ts

@@ -0,0 +1,6 @@
+import { HeightproofEvent } from "./index.js";
+export declare function buildDemoEvents(options: {
+    projectId: string;
+    serviceName: string;
+}): HeightproofEvent[];
+//# sourceMappingURL=demoEvents.d.ts.map

package/dist/demoEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demoEvents.d.ts","sourceRoot":"","sources":["../src/demoEvents.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,gBAAgB,EAAE,CA0EvG"}

package/dist/demoEvents.js

@@ -0,0 +1,126 @@
+import { randomUUID } from "node:crypto";
+export function buildDemoEvents(options) {
+    const { projectId, serviceName } = options;
+    const now = Date.now();
+    return [
+        ...range(60).map((index) => httpEvent({
+            projectId,
+            serviceName,
+            now,
+            index,
+            method: "GET",
+            path: `/api/users/${1000 + index}`,
+            route: "/api/users/:id",
+            statusCode: 200,
+            latencyMs: 35 + (index % 40),
+            ip: `198.51.100.${10 + (index % 8)}`
+        })),
+        ...range(35).map((index) => httpEvent({
+            projectId,
+            serviceName,
+            now,
+            index: index + 60,
+            method: "POST",
+            path: "/api/login",
+            route: "/api/login",
+            statusCode: index % 3 === 0 ? 401 : 403,
+            latencyMs: 70 + (index % 20),
+            ip: "203.0.113.14",
+            authFailed: true
+        })),
+        ...range(25).map((index) => httpEvent({
+            projectId,
+            serviceName,
+            now,
+            index: index + 95,
+            method: "POST",
+            path: "/graphql",
+            route: "/graphql",
+            statusCode: index % 10 === 0 ? 500 : 200,
+            latencyMs: 110 + (index % 90),
+            ip: `192.0.2.${20 + (index % 6)}`,
+            kind: "graphql",
+            graphQL: { operationName: index % 2 === 0 ? "GetAccount" : "UpdateProfile", operationType: "query" }
+        })),
+        ...range(18).map((index) => httpEvent({
+            projectId,
+            serviceName,
+            now,
+            index: index + 120,
+            method: "POST",
+            path: "/rpc",
+            route: "/rpc",
+            statusCode: index % 4 === 0 ? 401 : 200,
+            latencyMs: 55 + (index % 50),
+            ip: "198.51.100.22",
+            authFailed: index % 4 === 0,
+            kind: "evm_rpc",
+            evmRpc: {
+                method: index % 4 === 0 ? "eth_sendRawTransaction" : "eth_call",
+                chainId: "1",
+                provider: index % 2 === 0 ? "alchemy" : "infura",
+                walletAddress: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
+                contractAddress: "0x0000000000000000000000000000000000000002"
+            }
+        }))
+    ];
+}
+function httpEvent(input) {
+    return {
+        id: randomUUID(),
+        traceId: randomBytesHex(16),
+        projectId: input.projectId,
+        serviceName: input.serviceName,
+        environment: "demo",
+        timestamp: new Date(input.now - input.index * 1200).toISOString(),
+        kind: input.kind ?? "rest",
+        request: {
+            method: input.method,
+            path: input.path,
+            route: input.route,
+            ip: input.ip,
+            userAgent: input.index % 5 === 0 ? "curl/8.0" : "Mozilla/5.0",
+            headers: {
+                "content-type": "application/json",
+                authorization: "[REDACTED]"
+            },
+            query: {},
+            body: requestBody(input),
+            auth: {
+                present: true,
+                scheme: "Bearer",
+                failed: input.authFailed ?? false
+            }
+        },
+        response: {
+            statusCode: input.statusCode,
+            latencyMs: input.latencyMs,
+            bodyBytes: 512 + input.index
+        },
+        graphQL: input.graphQL,
+        evmRpc: input.evmRpc
+    };
+}
+function requestBody(input) {
+    if (input.kind === "graphql") {
+        return {
+            operationName: input.graphQL?.operationName,
+            query: "query GetAccount { account { id email } }"
+        };
+    }
+    if (input.kind === "evm_rpc") {
+        return {
+            jsonrpc: "2.0",
+            id: 1,
+            method: input.evmRpc?.method,
+            params: []
+        };
+    }
+    return { sample: true };
+}
+function range(count) {
+    return Array.from({ length: count }, (_, index) => index);
+}
+function randomBytesHex(length) {
+    return randomUUID().replace(/-/g, "").slice(0, length * 2);
+}

package/dist/detectors.d.ts

@@ -0,0 +1,154 @@
+import type { HeightproofEvent, ThreatSignal } from "./index.js";
+/**
+ * Content-aware RPC detectors D1, D3 and D6 (see docs/detectors.md).
+ *
+ * These are pure functions over an event plus context the worker gathers from storage, so
+ * every firing condition is testable without a database. They deliberately do not fire on
+ * absence alone: an empty result, a null receipt and a slow head are all frequently
+ * correct. Each rule below fires on a *change* or a *comparison*, never on emptiness.
+ */
+export type DetectorThresholds = {
+    /** How many block times a head may stand still before it is considered stalled. */
+    staleHeadBlockTimeMultiplier: number;
+    /** How far behind the fastest endpoint a head may fall before it is considered lagging. */
+    maxHeadLagBlocks: number;
+    /** Minimum head observations before D1 will judge an endpoint at all. */
+    minHeadObservations: number;
+    /** How often a result count must recur at the same ceiling to read as a page limit. */
+    pageLimitMinHits: number;
+    /** Reorg depth at or above which a reorg is worth raising rather than just recording. */
+    reorgAlertMinDepth: number;
+    /** How long an endpoint may keep serving a superseded block before it counts as lag. */
+    reorgConvergenceLagMs: number;
+    /** Share of recent requests carrying a throttle signature before it is worth reporting. */
+    throttleRateThreshold: number;
+    /** Minimum requests behind a rate before D5 will judge an endpoint. */
+    minThrottleSample: number;
+    /** Latency multiplier over baseline that counts as a cliff. */
+    softThrottleLatencyMultiplier: number;
+    /** How much worse recent result quality must be than baseline to count as degradation. */
+    softThrottleDegradationMultiplier: number;
+};
+export declare const DEFAULT_DETECTOR_THRESHOLDS: DetectorThresholds;
+export type StaleHeadContext = {
+    /** Highest head this endpoint reported in the window. */
+    endpointHeadBlockNumber?: number;
+    /** Milliseconds since this endpoint's head last advanced. */
+    endpointHeadStalledMs?: number;
+    /** Head observations from this endpoint in the window. */
+    endpointHeadObservations?: number;
+    /** Highest head reported by any endpoint on this chain in the window. */
+    chainHeadBlockNumber?: number;
+    /** Median block time measured from observations, for chains not in the static table. */
+    measuredBlockTimeMs?: number;
+};
+export type SilentFailureContext = {
+    /** This endpoint previously returned a non-null result for the same target (e.g. tx hash). */
+    priorNonNullForSameTarget?: boolean;
+    /** This endpoint previously returned data for identical params at an earlier block. */
+    priorDataForSameCall?: boolean;
+    /** Largest result count seen from this endpoint for this method. */
+    endpointMaxResultCount?: number;
+    /** How many times that maximum recurred — a repeated hard ceiling reads as a page limit. */
+    endpointMaxResultCountHits?: number;
+};
+export type CostWasteContext = {
+    /** Identical (method, params, block) already recorded for this project in the same block. */
+    duplicateCallCount?: number;
+    /** Cost units already spent on those duplicates. */
+    duplicateCostUnits?: number;
+};
+/**
+ * D1 — stale head.
+ *
+ * Two independent conditions: a head that has stopped advancing while the endpoint is
+ * still answering, and a head that trails the fastest endpoint on the same chain.
+ */
+export declare function detectStaleHead(event: HeightproofEvent, context?: StaleHeadContext, thresholds?: DetectorThresholds): ThreatSignal[];
+/**
+ * D3 — silent failure.
+ *
+ * Responses that arrive as successes but carry no usable answer. Every rule except the
+ * explicit in-body error is comparative, because emptiness on its own is usually correct.
+ */
+export declare function detectSilentFailure(event: HeightproofEvent, context?: SilentFailureContext, thresholds?: DetectorThresholds): ThreatSignal[];
+/**
+ * D6 — cost and waste.
+ *
+ * Waste is a billing problem, not a threat, so these signals carry zero weight: they are
+ * recorded against the event and aggregated for reporting without inflating a threat score
+ * or manufacturing an incident.
+ */
+export declare function detectCostWaste(event: HeightproofEvent, context?: CostWasteContext): ThreatSignal[];
+export type PeerResult = {
+    endpointHash?: string;
+    provider?: string;
+    resultHash: string;
+    /** Signer of a verified Airnode attestation over this peer's answer, if it carried one. */
+    attestedBy?: string;
+};
+export type DisagreementContext = {
+    /**
+     * Result hashes other endpoints returned for the same call at the same pinned height.
+     * Only ever populated from block-pinned verification calls: comparing two `latest`
+     * responses measures head skew, not disagreement.
+     */
+    peerResults?: PeerResult[];
+    /** Peers that could not serve the pinned height at all. */
+    peersMissingBlock?: number;
+};
+export type ReorgContext = {
+    /** A different block hash previously recorded at this height, from any endpoint. */
+    priorBlockHashAtHeight?: string;
+    /** Distinct heights in the recent window that have shown more than one hash. */
+    reorgDepth?: number;
+    /** Another endpoint already reports a different hash at this height. */
+    supersededByPeer?: boolean;
+    /** How long ago a peer first reported the newer hash. */
+    peerConvergenceLagMs?: number;
+};
+/**
+ * D2 — cross-provider disagreement.
+ *
+ * At equal block height a mismatch is either a provider bug or an unpropagated reorg.
+ * Both are worth raising, and neither is visible to anything that only watches status
+ * codes and latency.
+ *
+ * The caller is responsible for only ever supplying peer results from block-pinned calls.
+ * A peer that cannot serve the pinned height is not a disagreement — that is a stale head,
+ * and D1 is what reports it.
+ */
+export declare function detectDisagreement(event: HeightproofEvent, context?: DisagreementContext): ThreatSignal[];
+/**
+ * D4 — reorg lag.
+ *
+ * A hash changing at a height that was already observed is a reorg. Single-block reorgs
+ * are ordinary on mainnet and are recorded rather than alerted; what matters is depth, and
+ * whether this endpoint is still serving a chain its peers have already abandoned.
+ */
+export declare function detectReorgLag(event: HeightproofEvent, context?: ReorgContext, thresholds?: DetectorThresholds): ThreatSignal[];
+export type ThrottlingContext = {
+    /** Share of recent requests to this endpoint that carried a throttle signature. */
+    recentThrottleRate?: number;
+    /** Requests behind that rate, so a single throttled call cannot read as 100%. */
+    recentRequestCount?: number;
+    /** Share of recent results that came back empty or errored rather than as values. */
+    recentDegradedResultRate?: number;
+    /** The same share over the preceding window, for comparison. */
+    baselineDegradedResultRate?: number;
+    recentP95LatencyMs?: number;
+    baselineP95LatencyMs?: number;
+};
+/**
+ * D5 — throttling as success.
+ *
+ * The clean case is a 429. The case that matters is a provider quietly degrading under
+ * load: latency steps up and results start coming back empty, with every response still
+ * reporting success.
+ *
+ * The soft rule deliberately requires **both** latency degradation and result degradation.
+ * A latency cliff on its own is already reported by `provider_degradation`, and firing here
+ * as well would just restate it under a second name.
+ */
+export declare function detectThrottling(event: HeightproofEvent, context?: ThrottlingContext, thresholds?: DetectorThresholds): ThreatSignal[];
+//# sourceMappingURL=detectors.d.ts.map

package/dist/detectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detectors.d.ts","sourceRoot":"","sources":["../src/detectors.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE;;;;;;;GAOG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,mFAAmF;IACnF,4BAA4B,EAAE,MAAM,CAAC;IACrC,2FAA2F;IAC3F,gBAAgB,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,gBAAgB,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,kBAAkB,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2FAA2F;IAC3F,qBAAqB,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,6BAA6B,EAAE,MAAM,CAAC;IACtC,0FAA0F;IAC1F,iCAAiC,EAAE,MAAM,CAAC;CAC3C,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,kBAWzC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,yDAAyD;IACzD,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,6DAA6D;IAC7D,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,0DAA0D;IAC1D,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,yEAAyE;IACzE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,8FAA8F;IAC9F,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,oEAAoE;IACpE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,4FAA4F;IAC5F,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,6FAA6F;IAC7F,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oDAAoD;IACpD,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AASF;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,gBAAqB,EAC9B,UAAU,GAAE,kBAAgD,GAC3D,YAAY,EAAE,CAkDhB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,oBAAyB,EAClC,UAAU,GAAE,kBAAgD,GAC3D,YAAY,EAAE,CAkDhB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,gBAAqB,GAAG,YAAY,EAAE,CAqBvG;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;IAC3B,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,oFAAoF;IACpF,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yDAAyD;IACzD,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAKF;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,mBAAwB,GAChC,YAAY,EAAE,CAkChB;AAiBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,YAAiB,EAC1B,UAAU,GAAE,kBAAgD,GAC3D,YAAY,EAAE,CAsChB;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,mFAAmF;IACnF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qFAAqF;IACrF,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,iBAAsB,EAC/B,UAAU,GAAE,kBAAgD,GAC3D,YAAY,EAAE,CA4ChB"}