fix: configurable query guards — max asc window + ES timeout

Adds two new config fields to ApiConfigs (+ Zod schema):
- query_timeout: ES search timeout (default: '10s')
- max_asc_window_days: max time range for sort=asc (default: 90)

sort=asc now requires:
1. A valid 'after' or 'before' (ISO date or positive block number)
2. If ISO date (contains 'T'), must be within max_asc_window_days

All get_actions queries (v1 + v2) now have a configurable ES timeout.

Includes 17 unit tests for getSortDir validation.

Author: igorls

CHANGELOG.md

@@ -1,3 +1,92 @@
+# Changelog
+
+## 4.0.3 (2026-03-20)
+
+### Security
+
+*   **Configurable Query Guards for `sort=asc`**: Prevents unbounded ascending sort queries on `get_actions` (v1 & v2) that could overload Elasticsearch by forcing full reverse segment scans across all shards.
+
+### New Config Options
+
+Two new optional fields in the `api` section of the chain config:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `query_timeout` | `string` | `"10s"` | Elasticsearch search timeout per query |
+| `max_asc_window_days` | `number` | `90` | Maximum time range (in days) for `sort=asc` requests |
+
+### Behavior Changes
+
+*   `sort=asc` on `get_actions` now **requires** a valid `after` or `before` parameter:
+    *   ISO date strings (must contain `T`, e.g., `2026-03-19T00:00:00Z`)
+    *   Positive integer block numbers (e.g., `425000000`)
+*   ISO date `after` values must be within `max_asc_window_days` of the current time.
+*   All `get_actions` queries (v1 + v2) now include a configurable Elasticsearch `timeout`.
+*   `sort=desc` (default) is **unchanged** — no new restrictions apply.
+
+### Testing
+
+*   Added 17 unit tests for `getSortDir` validation covering bounds checks, max window enforcement, block number acceptance, and garbage input rejection.
+
+---
+
+## 4.0.2 (2026-03-18)
+
+### Testing
+
+*   **E2E High-Fidelity Test Framework**: 8-phase Docker-based test pipeline with port-isolated infrastructure, contract deployment, manifest-based load generation, and integrity checking.
+*   **CI Workflow**: Target main branch, integrate unit tests into CI pipeline.
+
+### Maintenance
+
+*   Updated all dependencies and fixed security vulnerabilities.
+
+---
+
+## 4.0.1 (2026-03-08)
+
+### Fixes
+
+*   **Dynamic `global-agent` Loading**: Load `global-agent` dynamically via `createRequire` to resolve ESM import errors.
+
+### Maintenance
+
+*   Upgraded all dependencies.
+*   Added unit test suite (Bun-based) for API helpers, common functions, and config validation.
+
+---
+
+## 4.0.0-beta.5 (2025-11-04)
+
+### Fixes
+
+*   **IndexerController**: Guard against missing chain config in `connect()` — reject and clear `connectionPromise` when config is not found.
+*   **getFirstIndexedBlock**: Handle empty `cat.indices` results, add try/catch with error logging.
+
+### Maintenance
+
+*   Dependency updates: `@elastic/elasticsearch` → 9.2.0, `commander` → 14.0.2, `ioredis` → 5.8.2, `typescript` → 5.9.3, `uWebSockets.js` → v20.55.0, `zod` → 4.1.12.
+
+---
+
+## 4.0.0-beta.4 (2025-09-30)
+
+### Features
+
+*   **RabbitMQ Install Script**: Added `rabbit.sh` for automated RabbitMQ installation on Ubuntu.
+*   **Explorer Oracle Metadata**: Explorer metadata route now includes oracle configuration.
+
+### Fixes
+
+*   MongoDB client typing workaround for type compatibility.
+*   Plugin loading cleanup — removed noisy error logs, improved type definitions.
+
+### Maintenance
+
+*   Dependency updates: `@elastic/elasticsearch` → 9.1.1, `fastify` → 5.6.1, `mongodb` → 6.20.0, `typescript` → 5.9.2, `zod` → 4.1.11.
+
+---
+
 # Changelog - Hyperion History API 4.0.0-beta.3 (pre-release)
 
 This changelog summarizes the significant changes leading up to the `4.0.0-beta.3` release, based on Pull Request #157.

bun.lock

@@ -1,6 +1,6 @@
 {
   "name": "hyperion-history",
-  "version": "4.0.2",
+  "version": "4.0.3",
   "description": "Scalable Full History API Solution for Antelope based blockchains",
   "main": "./build/indexer/launcher.js",
   "scripts": {

package.json

@@ -195,8 +195,27 @@ async function getActions(fastify: FastifyInstance, request: FastifyRequest) {
         }
     }
 
+    const maxAscWindowDays = fastify.manager.config.api.max_asc_window_days || 90;
+
     if (reqBody.sort) {
         if (reqBody.sort === 'asc' || reqBody.sort === '1') {
+            // sort=asc requires a valid, recent time range to prevent full-index reverse scans
+            const after = reqBody.after;
+            const before = reqBody.before;
+            const isValidBound = (v) => v && (!isNaN(new Date(v).getTime()) || (Number.isInteger(Number(v)) && Number(v) > 0));
+            if (!isValidBound(after) && !isValidBound(before)) {
+                return {error: 'sort=asc requires a valid "after" or "before" (ISO date or block number) to bound the search'};
+            }
+            // validate the time window is not too wide (only for ISO date strings, not block numbers)
+            if (typeof after === 'string' && after.includes('T')) {
+                const afterDate = new Date(after);
+                if (!isNaN(afterDate.getTime())) {
+                    const maxAge = Date.now() - (maxAscWindowDays * 86400000);
+                    if (afterDate.getTime() < maxAge) {
+                        return {error: `sort=asc "after" date must be within the last ${maxAscWindowDays} days`};
+                    }
+                }
+            }
             sort_direction = 'asc';
         } else if (reqBody.sort === 'desc' || reqBody.sort === '-1') {
             sort_direction = 'desc'
@@ -260,10 +279,12 @@ async function getActions(fastify: FastifyInstance, request: FastifyRequest) {
 
     const getActionsLimit = fastify.manager.config.api.limits.get_actions ?? 1000;
 
+    const queryTimeout = fastify.manager.config.api.query_timeout || '10s';
     const esOpts = {
         "index": fastify.manager.chain + '-action-*',
         "from": from || 0,
         "size": (size > getActionsLimit ? getActionsLimit : size),
+        "timeout": queryTimeout,
         "query": queryStruct,
         "sort": {
             "global_sequence": sort_direction

src/api/routes/v1-history/get_actions/get_actions.ts

@@ -260,10 +260,27 @@ export function getSkipLimit(query: any, max?: number): { skip: number, limit: n
     return {skip, limit};
 }
 
-export function getSortDir(query) {
+export function getSortDir(query, maxAscWindowDays = 90) {
     let sort_direction = 'desc';
     if (query.sort) {
         if (query.sort === 'asc' || query.sort === '1') {
+            // sort=asc requires a valid, recent time range to prevent full-index reverse scans
+            const after = query.after;
+            const before = query.before;
+            const isValidBound = (v) => v && (!isNaN(new Date(v).getTime()) || (Number.isInteger(Number(v)) && Number(v) > 0));
+            if (!isValidBound(after) && !isValidBound(before)) {
+                throw new Error('sort=asc requires a valid "after" or "before" (ISO date or block number) to bound the search');
+            }
+            // validate the time window is not too wide (only for ISO date strings, not block numbers)
+            if (typeof after === 'string' && after.includes('T')) {
+                const afterDate = new Date(after);
+                if (!isNaN(afterDate.getTime())) {
+                    const maxAge = Date.now() - (maxAscWindowDays * 86400000);
+                    if (afterDate.getTime() < maxAge) {
+                        throw new Error(`sort=asc "after" date must be within the last ${maxAscWindowDays} days`);
+                    }
+                }
+            }
             sort_direction = 'asc';
         } else if (query.sort === 'desc' || query.sort === '-1') {
             sort_direction = 'desc'

src/api/routes/v2-history/get_actions/functions.ts

@@ -23,7 +23,8 @@ async function getActions(fastify: FastifyInstance, request: FastifyRequest) {
 
     const {skip, limit} = getSkipLimit(query, maxActions);
 
-    const sort_direction = getSortDir(query);
+    const maxAscWindowDays = fastify.manager.config.api.max_asc_window_days || 90;
+    const sort_direction = getSortDir(query, maxAscWindowDays);
 
     applyAccountFilters(query, queryStruct);
 
@@ -52,10 +53,12 @@ async function getActions(fastify: FastifyInstance, request: FastifyRequest) {
         indexPattern = fastify.manager.chain + '-action';
     }
 
+    const queryTimeout = fastify.manager.config.api.query_timeout || '10s';
     const esOpts = {
         "index": indexPattern,
         "from": skip || 0,
         "size": (limit > maxActions ? maxActions : limit) || 10,
+        "timeout": queryTimeout,
         ...query_body
     };
 

src/api/routes/v2-history/get_actions/get_actions.ts

@@ -166,6 +166,8 @@ interface ApiConfigs {
     limits: ApiLimits;
     v1_chain_cache?: CachedRouteConfig[];
     explorer?: ExplorerConfigs;
+    query_timeout?: string;           // ES search timeout (e.g., "5s"), default: "10s"
+    max_asc_window_days?: number;     // max range in days for sort=asc queries, default: 90
 }
 
 interface ExplorerConfigs {
@@ -320,6 +322,8 @@ export const HyperionApiConfigSchema = z.object({
     limits: ApiLimitsSchema,
     v1_chain_cache: z.array(CachedRouteConfigSchema).optional(),
     explorer: ExplorerConfigsSchema.optional(),
+    query_timeout: z.string().optional(),
+    max_asc_window_days: z.number().optional(),
 });
 
 // Zod schema for tiered index allocation settings