Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(search): reject an offset above the pagination cap with 400

Yudhi Armyndharisfc9ffb14dc7b
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index 229b6dfef..414753c9e 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -6270,7 +6270,7 @@ Search messages across sessions (active search provider).
| `dateFrom` | integer (epoch ms) | No | — | Inclusive lower bound on `timestamp`. A non-numeric value is rejected with `400`. |
| `dateTo` | integer (epoch ms) | No | — | Inclusive upper bound on `timestamp`. A non-numeric value is rejected with `400`. |
| `limit` | integer (≥ 1) | No | `50` | Max hits to return. Clamped to `SEARCH_LIMIT_MAX` (default `100`). A non-integer value is rejected with `400`. |
-| `offset` | integer (≥ 0) | No | `0` | Pagination offset. A non-integer value is rejected with `400`. |
+| `offset` | integer (≥ 0) | No | `0` | Pagination offset, at most `100000`. A non-integer or larger value is rejected with `400`. |
**Response** `200` — `SearchResults`
@@ -6305,7 +6305,7 @@ Search messages across sessions (active search provider).
- `score` is optional and provider-specific (rank ordering is stable within a provider; cross-provider
scores are not comparable).
-**Errors:** `400` empty/whitespace `q`, a non-numeric `dateFrom`/`dateTo`/`limit`/`offset`, or a malformed
+**Errors:** `400` empty/whitespace `q`, a non-numeric `dateFrom`/`dateTo`/`limit`/`offset`, an `offset` above `100000`, or a malformed
SQLite FTS5 query (unbalanced quote/paren, bare operator) — Postgres's `websearch_to_tsquery` is
tolerant and has no equivalent · `401` missing/invalid `X-API-Key` · `403` key role below `OPERATOR` ·
`501` no search provider configured (including a non-FTS5 SQLite build, where the provider is absent) ·
diff --git a/openapi.json b/openapi.json
index e15d7aad9..8a2c759e6 100644
--- a/openapi.json
+++ b/openapi.json
@@ -9717,7 +9717,7 @@
"name": "offset",
"required": false,
"in": "query",
- "description": "Pagination offset",
+ "description": "Pagination offset, at most 100000",
"schema": {
"type": "number"
}
diff --git a/src/modules/search/dto/search-query.dto.spec.ts b/src/modules/search/dto/search-query.dto.spec.ts
index 5e41a6148..cef8d3b2e 100644
--- a/src/modules/search/dto/search-query.dto.spec.ts
+++ b/src/modules/search/dto/search-query.dto.spec.ts
@@ -44,6 +44,11 @@ describe('SearchQueryDto', () => {
expect(validateSync(dto).some(e => e.property === 'offset')).toBe(true);
});
+ it('rejects offset above SEARCH_OFFSET_MAX instead of letting the service clamp it to a repeated page', () => {
+ expect(validateSync(fromQuery({ q: 'hello', offset: '100001' })).some(e => e.property === 'offset')).toBe(true);
+ expect(validateSync(fromQuery({ q: 'hello', offset: '100000' }))).toHaveLength(0);
+ });
+
it('rejects an invalid direction (@IsEnum(MessageDirection))', () => {
const dto = fromQuery({ q: 'hello', direction: 'sideways' });
expect(validateSync(dto).some(e => e.property === 'direction')).toBe(true);
diff --git a/src/modules/search/dto/search-query.dto.ts b/src/modules/search/dto/search-query.dto.ts
index 84e7d2ef3..0faae4253 100644
--- a/src/modules/search/dto/search-query.dto.ts
+++ b/src/modules/search/dto/search-query.dto.ts
@@ -1,9 +1,10 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsString, IsNotEmpty, IsOptional, IsEnum, IsInt, IsNumber, Min } from 'class-validator';
+import { IsString, IsNotEmpty, IsOptional, IsEnum, IsInt, IsNumber, Max, Min } from 'class-validator';
import { Type } from 'class-transformer';
import { MessageDirection } from '../../message/entities/message.entity';
import type { MessageType } from '../../../engine/interfaces/whatsapp-engine.interface';
import { ToStrictNumber } from '../../../common/utils/strict-boolean';
+import { SEARCH_OFFSET_MAX } from '../search.constants';
/**
* Request shape for GET /search. Numeric fields are coerced from query-string strings via
@@ -69,11 +70,13 @@ export class SearchQueryDto {
@Min(1)
limit?: number;
- @ApiPropertyOptional({ description: 'Pagination offset', type: Number })
+ @ApiPropertyOptional({ description: `Pagination offset, at most ${SEARCH_OFFSET_MAX}`, type: Number })
@IsOptional()
@ToStrictNumber()
@Type(() => Number)
@IsInt()
@Min(0)
+ // Rejected rather than clamped: a clamped offset silently returns the page at the cap again.
+ @Max(SEARCH_OFFSET_MAX)
offset?: number;
}
diff --git a/src/modules/search/search.controller.ts b/src/modules/search/search.controller.ts
index a89480517..31b2ec236 100644
--- a/src/modules/search/search.controller.ts
+++ b/src/modules/search/search.controller.ts
@@ -5,6 +5,7 @@ import { RequireRole, CurrentApiKey } from '../auth/decorators/auth.decorators';
import { ApiKey, ApiKeyRole } from '../auth/entities/api-key.entity';
import { SearchService } from './search.service';
import { SearchQueryDto } from './dto/search-query.dto';
+import { SEARCH_OFFSET_MAX } from './search.constants';
import type { SearchResults } from './search.types';
@ApiTags('search')
@@ -39,7 +40,12 @@ export class SearchController {
@ApiQuery({ name: 'dateFrom', required: false, description: 'Epoch-ms lower bound (inclusive)' })
@ApiQuery({ name: 'dateTo', required: false, description: 'Epoch-ms upper bound (inclusive)' })
@ApiQuery({ name: 'limit', required: false, type: Number, description: 'Max hits to return' })
- @ApiQuery({ name: 'offset', required: false, type: Number, description: 'Pagination offset' })
+ @ApiQuery({
+ name: 'offset',
+ required: false,
+ type: Number,
+ description: `Pagination offset, at most ${SEARCH_OFFSET_MAX}`,
+ })
async search(@Query() dto: SearchQueryDto, @CurrentApiKey() apiKey?: ApiKey): Promise<SearchResults> {
if (!dto.q || !dto.q.trim()) {
throw new BadRequestException('Query parameter "q" is required and must be non-empty.');