@cyanheads/mcp-ts-core 0.1.0-beta.12

package/dist/utils/network/fetchWithTimeout.js

@@ -0,0 +1,305 @@
+/**
+ * @fileoverview Provides a utility function to make fetch requests with a specified timeout
+ * and optional SSRF protection including DNS resolution validation and redirect following.
+ * @module src/utils/network/fetchWithTimeout
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+import { runtimeCaps } from '../../utils/internal/runtime.js';
+/**
+ * IPv4 patterns for private/reserved ranges that should be blocked when
+ * `rejectPrivateIPs` is enabled. Covers RFC 1918, loopback, link-local,
+ * and cloud metadata endpoints.
+ */
+const PRIVATE_IP_PATTERNS = [
+    /^127\./, // Loopback
+    /^10\./, // RFC 1918 Class A
+    /^172\.(1[6-9]|2\d|3[01])\./, // RFC 1918 Class B
+    /^192\.168\./, // RFC 1918 Class C
+    /^169\.254\./, // Link-local / cloud metadata
+    /^0\./, // Current network
+    /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, // RFC 6598 (CGNAT)
+];
+/** IPv6 prefixes for private/reserved ranges (checked against DNS-resolved addresses). */
+const PRIVATE_IPV6_PREFIXES = [
+    'fe80:', // Link-local
+    'fc', // Unique local (fc00::/7)
+    'fd', // Unique local (fc00::/7)
+    '::1', // Loopback
+    '::ffff:127.', // IPv4-mapped loopback
+    '::ffff:10.', // IPv4-mapped RFC 1918
+    '::ffff:192.168.', // IPv4-mapped RFC 1918
+    '::ffff:172.16.', // IPv4-mapped RFC 1918 (partial)
+    '::ffff:169.254.', // IPv4-mapped link-local
+];
+const PRIVATE_HOSTNAMES = new Set(['localhost', 'metadata.google.internal', 'metadata.internal']);
+/** Maximum number of redirects to follow when rejectPrivateIPs is enabled. */
+const MAX_SSRF_REDIRECTS = 5;
+/**
+ * Checks whether a resolved IP address (v4 or v6) falls within a private or
+ * reserved range as defined by {@link PRIVATE_IP_PATTERNS} and
+ * {@link PRIVATE_IPV6_PREFIXES}.
+ *
+ * @param ip - The IP address string to check (bare, no brackets).
+ * @returns `true` if the address is private or reserved, `false` otherwise.
+ */
+function isPrivateIP(ip) {
+    if (PRIVATE_IP_PATTERNS.some((pattern) => pattern.test(ip)))
+        return true;
+    const lower = ip.toLowerCase();
+    if (PRIVATE_IPV6_PREFIXES.some((prefix) => lower.startsWith(prefix)))
+        return true;
+    return false;
+}
+/**
+ * Validates that a URL string does not target private or reserved IP space.
+ *
+ * Performs three checks in order:
+ * 1. Known private hostnames (`localhost`, `metadata.google.internal`, etc.)
+ * 2. Literal IPv4/IPv6 addresses in the URL hostname
+ * 3. DNS resolution (Node.js only) — resolves A and AAAA records and validates each
+ *
+ * DNS resolution failures (ENOTFOUND, etc.) are swallowed and left for the native
+ * `fetch` to handle; only confirmed private IPs cause rejection.
+ *
+ * @param urlString - The fully-qualified URL string to validate.
+ * @throws {McpError} `ValidationError` if the URL is malformed, the hostname is a known
+ *   internal name, the literal IP is private, or DNS resolves to a private address.
+ */
+async function assertNotPrivateUrl(urlString) {
+    let parsed;
+    try {
+        parsed = new URL(urlString);
+    }
+    catch {
+        throw new McpError(JsonRpcErrorCode.ValidationError, `Invalid URL: ${urlString}`);
+    }
+    const hostname = parsed.hostname.replace(/^\[|\]$/g, ''); // Strip IPv6 brackets
+    // Check known private hostnames
+    if (PRIVATE_HOSTNAMES.has(hostname.toLowerCase())) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, `Request to private/internal hostname blocked: ${hostname}`);
+    }
+    // Check IPv6 loopback
+    if (hostname === '::1' || hostname === '0:0:0:0:0:0:0:1') {
+        throw new McpError(JsonRpcErrorCode.ValidationError, `Request to loopback address blocked: ${hostname}`);
+    }
+    // Check IPv4 private ranges (hostname as literal IP)
+    if (PRIVATE_IP_PATTERNS.some((pattern) => pattern.test(hostname))) {
+        throw new McpError(JsonRpcErrorCode.ValidationError, `Request to private/reserved IP blocked: ${hostname}`);
+    }
+    // DNS resolution check (Node.js only — Workers have no DNS API)
+    if (runtimeCaps.isNode) {
+        await assertDnsNotPrivate(hostname);
+    }
+}
+/**
+ * Resolves DNS for a hostname (A and AAAA records in parallel) and confirms
+ * that none of the resolved IP addresses fall within private or reserved ranges.
+ *
+ * DNS resolution errors (e.g., `ENOTFOUND`) are silently swallowed — they are
+ * not an SSRF signal and are better handled by the native `fetch` call.
+ *
+ * @param hostname - The bare hostname to resolve (no brackets, no port).
+ * @throws {McpError} `ValidationError` if any resolved address is private.
+ */
+async function assertDnsNotPrivate(hostname) {
+    try {
+        const dns = await import('node:dns/promises');
+        const [ipv4Results, ipv6Results] = await Promise.allSettled([
+            dns.resolve4(hostname),
+            dns.resolve6(hostname),
+        ]);
+        const resolvedIPs = [
+            ...(ipv4Results.status === 'fulfilled' ? ipv4Results.value : []),
+            ...(ipv6Results.status === 'fulfilled' ? ipv6Results.value : []),
+        ];
+        for (const ip of resolvedIPs) {
+            if (isPrivateIP(ip)) {
+                throw new McpError(JsonRpcErrorCode.ValidationError, `DNS resolved ${hostname} to private IP ${ip} — SSRF blocked`);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof McpError)
+            throw error;
+        // DNS resolution failures (ENOTFOUND, etc.) are not SSRF — let fetch handle them
+    }
+}
+/**
+ * Fetches a resource with a configurable timeout and optional SSRF protection.
+ *
+ * Internally manages an `AbortController` that fires after `timeoutMs`. An optional
+ * external `signal` (e.g., `ctx.signal`) can be passed via `options` to support
+ * early cancellation by the caller. The two signals are composed — whichever fires
+ * first wins.
+ *
+ * When `options.rejectPrivateIPs` is `true`, the target URL is validated before the
+ * request is sent, and all redirects are followed manually with per-hop SSRF checks
+ * (up to 5 hops). This mode forces `redirect: 'manual'` on the underlying fetch.
+ *
+ * Non-2xx responses are treated as errors: the response body is read, logged, and
+ * wrapped in a `McpError` with code `ServiceUnavailable`.
+ *
+ * @param url - The URL to fetch (string or `URL` instance).
+ * @param timeoutMs - Maximum duration in milliseconds before the request is aborted.
+ * @param context - Request context used for structured logging (requestId, operation, etc.).
+ * @param options - Optional fetch configuration extending `RequestInit`.
+ *   - `rejectPrivateIPs`: Block requests to private/internal IP space (SSRF protection).
+ *   - `signal`: External `AbortSignal` to cancel the request independently of the timeout.
+ *   - All other standard `RequestInit` fields (method, headers, body, etc.) are forwarded.
+ * @returns A promise resolving to the `Response` object on HTTP 2xx.
+ * @throws {McpError} `ValidationError` if the URL targets a private/reserved address
+ *   and `rejectPrivateIPs` is enabled.
+ * @throws {McpError} `Timeout` if the request exceeds `timeoutMs`.
+ * @throws {McpError} `InternalError` if the request is cancelled via the external signal.
+ * @throws {McpError} `ServiceUnavailable` if the server returns a non-2xx status or a
+ *   network-level error occurs.
+ * @example
+ * ```ts
+ * // Basic GET with a 5-second timeout
+ * const response = await fetchWithTimeout(
+ *   'https://api.example.com/data',
+ *   5000,
+ *   ctx,
+ * );
+ * const data = await response.json();
+ *
+ * // POST with SSRF protection and caller-cancellable signal
+ * const response = await fetchWithTimeout(
+ *   userProvidedUrl,
+ *   10_000,
+ *   ctx,
+ *   {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify(payload),
+ *     rejectPrivateIPs: true,
+ *     signal: ctx.signal,
+ *   },
+ * );
+ * ```
+ */
+export async function fetchWithTimeout(url, timeoutMs, context, options) {
+    const urlString = url.toString();
+    // SSRF protection: reject private/internal targets when enabled
+    if (options?.rejectPrivateIPs) {
+        await assertNotPrivateUrl(urlString);
+    }
+    const operationDescription = `fetch ${options?.method || 'GET'} ${urlString}`;
+    logger.debug(`Attempting ${operationDescription} with ${timeoutMs}ms timeout.`, context);
+    // Strip custom options before passing to native fetch
+    const { rejectPrivateIPs: rejectPrivate, signal: externalSignal, ...fetchInit } = options ?? {};
+    // When SSRF protection is active, handle redirects manually to validate each hop
+    if (rejectPrivate) {
+        fetchInit.redirect = 'manual';
+    }
+    // Use AbortController instead of AbortSignal.timeout() for cross-runtime compatibility
+    // (AbortSignal.timeout() can fail in Bun's stdio transport due to realm mismatch)
+    const controller = new AbortController();
+    const timeoutSentinel = 'FETCH_TIMEOUT';
+    const timeoutId = setTimeout(() => controller.abort(timeoutSentinel), timeoutMs);
+    // If an external signal is provided (e.g., client disconnect), forward its abort
+    if (externalSignal) {
+        if (externalSignal.aborted) {
+            controller.abort(externalSignal.reason);
+        }
+        else {
+            externalSignal.addEventListener('abort', () => controller.abort(externalSignal.reason), {
+                once: true,
+                signal: controller.signal,
+            });
+        }
+    }
+    try {
+        let currentUrl = url;
+        let redirectCount = 0;
+        for (;;) {
+            const response = await fetch(currentUrl, {
+                ...fetchInit,
+                signal: controller.signal,
+            });
+            // Handle redirects manually when SSRF protection is active
+            if (rejectPrivate && response.status >= 300 && response.status < 400) {
+                const location = response.headers.get('location');
+                if (!location) {
+                    throw new McpError(JsonRpcErrorCode.ServiceUnavailable, `Redirect response missing Location header from ${String(currentUrl)}`);
+                }
+                redirectCount++;
+                if (redirectCount > MAX_SSRF_REDIRECTS) {
+                    throw new McpError(JsonRpcErrorCode.ValidationError, `Too many redirects (${MAX_SSRF_REDIRECTS}) — possible SSRF redirect loop`);
+                }
+                // Resolve relative redirect URLs against the current URL
+                const redirectUrl = new URL(location, currentUrl.toString()).toString();
+                // Validate the redirect target against SSRF rules
+                await assertNotPrivateUrl(redirectUrl);
+                logger.debug(`Following validated redirect ${redirectCount}: ${redirectUrl}`, context);
+                currentUrl = redirectUrl;
+                continue;
+            }
+            if (!response.ok) {
+                const errorBody = await response.text().catch(() => 'Could not read response body');
+                logger.error(`Fetch failed for ${String(currentUrl)} with status ${response.status}.`, {
+                    ...context,
+                    statusCode: response.status,
+                    statusText: response.statusText,
+                    responseBody: errorBody,
+                    errorSource: 'FetchHttpError',
+                });
+                throw new McpError(JsonRpcErrorCode.ServiceUnavailable, `Fetch failed for ${String(currentUrl)}. Status: ${response.status}`, {
+                    requestId: context.requestId,
+                    operation: context.operation,
+                    statusCode: response.status,
+                    statusText: response.statusText,
+                    responseBody: errorBody,
+                });
+            }
+            logger.debug(`Successfully fetched ${String(currentUrl)}. Status: ${response.status}`, context);
+            return response;
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')) {
+            const isTimeout = error.name === 'TimeoutError' || controller.signal.reason === timeoutSentinel;
+            if (isTimeout) {
+                logger.error(`${operationDescription} timed out after ${timeoutMs}ms.`, {
+                    ...context,
+                    errorSource: 'FetchTimeout',
+                });
+                throw new McpError(JsonRpcErrorCode.Timeout, `${operationDescription} timed out.`, {
+                    requestId: context.requestId,
+                    operation: context.operation,
+                    errorSource: 'FetchTimeout',
+                });
+            }
+            // External signal abort (e.g., client disconnect) — not a timeout
+            logger.info(`${operationDescription} aborted by caller.`, {
+                ...context,
+                errorSource: 'FetchAborted',
+            });
+            throw new McpError(JsonRpcErrorCode.InternalError, `${operationDescription} was aborted.`, {
+                requestId: context.requestId,
+                operation: context.operation,
+                errorSource: 'FetchAborted',
+            });
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        logger.error(`Network error during ${operationDescription}: ${errorMessage}`, {
+            ...context,
+            originalErrorName: error instanceof Error ? error.name : 'UnknownError',
+            errorSource: 'FetchNetworkError',
+        });
+        if (error instanceof McpError) {
+            throw error;
+        }
+        throw new McpError(JsonRpcErrorCode.ServiceUnavailable, `Network error during ${operationDescription}: ${errorMessage}`, {
+            requestId: context.requestId,
+            operation: context.operation,
+            originalErrorName: error instanceof Error ? error.name : 'UnknownError',
+            errorSource: 'FetchNetworkErrorWrapper',
+        });
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+//# sourceMappingURL=fetchWithTimeout.js.map

package/dist/utils/network/fetchWithTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchWithTimeout.js","sourceRoot":"","sources":["../../../src/utils/network/fetchWithTimeout.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAqC1D;;;;GAIG;AACH,MAAM,mBAAmB,GAAG;IAC1B,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,mBAAmB;IAC5B,4BAA4B,EAAE,mBAAmB;IACjD,aAAa,EAAE,mBAAmB;IAClC,aAAa,EAAE,8BAA8B;IAC7C,MAAM,EAAE,kBAAkB;IAC1B,0CAA0C,EAAE,mBAAmB;CAChE,CAAC;AAEF,0FAA0F;AAC1F,MAAM,qBAAqB,GAAG;IAC5B,OAAO,EAAE,aAAa;IACtB,IAAI,EAAE,0BAA0B;IAChC,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,WAAW;IAClB,aAAa,EAAE,uBAAuB;IACtC,YAAY,EAAE,uBAAuB;IACrC,iBAAiB,EAAE,uBAAuB;IAC1C,gBAAgB,EAAE,iCAAiC;IACnD,iBAAiB,EAAE,yBAAyB;CAC7C,CAAC;AAEF,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,0BAA0B,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAElG,8EAA8E;AAC9E,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,EAAU;IAC7B,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACzE,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAC/B,IAAI,qBAAqB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAClF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,KAAK,UAAU,mBAAmB,CAAC,SAAiB;IAClD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,eAAe,EAAE,gBAAgB,SAAS,EAAE,CAAC,CAAC;IACpF,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC,sBAAsB;IAEhF,gCAAgC;IAChC,IAAI,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,iDAAiD,QAAQ,EAAE,CAC5D,CAAC;IACJ,CAAC;IAED,sBAAsB;IACtB,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,KAAK,iBAAiB,EAAE,CAAC;QACzD,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,wCAAwC,QAAQ,EAAE,CACnD,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,IAAI,mBAAmB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,2CAA2C,QAAQ,EAAE,CACtD,CAAC;IACJ,CAAC;IAED,gEAAgE;IAChE,IAAI,WAAW,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACjD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAE9C,MAAM,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;YAC1D,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACtB,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;SACvB,CAAC,CAAC;QAEH,MAAM,WAAW,GAAa;YAC5B,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,WAAW,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;SACjE,CAAC;QAEF,KAAK,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;YAC7B,IAAI,WAAW,CAAC,EAAE,CAAC,EAAE,CAAC;gBACpB,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,gBAAgB,QAAQ,kBAAkB,EAAE,iBAAiB,CAC9D,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ;YAAE,MAAM,KAAK,CAAC;QAC3C,iFAAiF;IACnF,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAiB,EACjB,SAAiB,EACjB,OAAuB,EACvB,OAAiC;IAEjC,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;IAEjC,gEAAgE;IAChE,IAAI,OAAO,EAAE,gBAAgB,EAAE,CAAC;QAC9B,MAAM,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,oBAAoB,GAAG,SAAS,OAAO,EAAE,MAAM,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;IAE9E,MAAM,CAAC,KAAK,CAAC,cAAc,oBAAoB,SAAS,SAAS,aAAa,EAAE,OAAO,CAAC,CAAC;IAEzF,sDAAsD;IACtD,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,SAAS,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;IAEhG,iFAAiF;IACjF,IAAI,aAAa,EAAE,CAAC;QAClB,SAAS,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAChC,CAAC;IAED,uFAAuF;IACvF,kFAAkF;IAClF,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,eAAe,GAAG,eAAe,CAAC;IACxC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,CAAC;IAEjF,iFAAiF;IACjF,IAAI,cAAc,EAAE,CAAC;QACnB,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;YAC3B,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;aAAM,CAAC;YACN,cAAc,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE;gBACtF,IAAI,EAAE,IAAI;gBACV,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,IAAI,UAAU,GAAiB,GAAG,CAAC;QACnC,IAAI,aAAa,GAAG,CAAC,CAAC;QAEtB,SAAS,CAAC;YACR,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE;gBACvC,GAAG,SAAS;gBACZ,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YAEH,2DAA2D;YAC3D,IAAI,aAAa,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACrE,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;gBAClD,IAAI,CAAC,QAAQ,EAAE,CAAC;oBACd,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,kDAAkD,MAAM,CAAC,UAAU,CAAC,EAAE,CACvE,CAAC;gBACJ,CAAC;gBAED,aAAa,EAAE,CAAC;gBAChB,IAAI,aAAa,GAAG,kBAAkB,EAAE,CAAC;oBACvC,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,eAAe,EAChC,uBAAuB,kBAAkB,iCAAiC,CAC3E,CAAC;gBACJ,CAAC;gBAED,yDAAyD;gBACzD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAExE,kDAAkD;gBAClD,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;gBAEvC,MAAM,CAAC,KAAK,CAAC,gCAAgC,aAAa,KAAK,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;gBACvF,UAAU,GAAG,WAAW,CAAC;gBACzB,SAAS;YACX,CAAC;YAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,8BAA8B,CAAC,CAAC;gBACpF,MAAM,CAAC,KAAK,CAAC,oBAAoB,MAAM,CAAC,UAAU,CAAC,gBAAgB,QAAQ,CAAC,MAAM,GAAG,EAAE;oBACrF,GAAG,OAAO;oBACV,UAAU,EAAE,QAAQ,CAAC,MAAM;oBAC3B,UAAU,EAAE,QAAQ,CAAC,UAAU;oBAC/B,YAAY,EAAE,SAAS;oBACvB,WAAW,EAAE,gBAAgB;iBAC9B,CAAC,CAAC;gBACH,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,oBAAoB,MAAM,CAAC,UAAU,CAAC,aAAa,QAAQ,CAAC,MAAM,EAAE,EACpE;oBACE,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,SAAS,EAAE,OAAO,CAAC,SAA+B;oBAClD,UAAU,EAAE,QAAQ,CAAC,MAAM;oBAC3B,UAAU,EAAE,QAAQ,CAAC,UAAU;oBAC/B,YAAY,EAAE,SAAS;iBACxB,CACF,CAAC;YACJ,CAAC;YAED,MAAM,CAAC,KAAK,CACV,wBAAwB,MAAM,CAAC,UAAU,CAAC,aAAa,QAAQ,CAAC,MAAM,EAAE,EACxE,OAAO,CACR,CAAC;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;IACH,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,IAAI,KAAK,YAAY,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,EAAE,CAAC;YAC7F,MAAM,SAAS,GACb,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,eAAe,CAAC;YAChF,IAAI,SAAS,EAAE,CAAC;gBACd,MAAM,CAAC,KAAK,CAAC,GAAG,oBAAoB,oBAAoB,SAAS,KAAK,EAAE;oBACtE,GAAG,OAAO;oBACV,WAAW,EAAE,cAAc;iBAC5B,CAAC,CAAC;gBACH,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,oBAAoB,aAAa,EAAE;oBACjF,SAAS,EAAE,OAAO,CAAC,SAAS;oBAC5B,SAAS,EAAE,OAAO,CAAC,SAA+B;oBAClD,WAAW,EAAE,cAAc;iBAC5B,CAAC,CAAC;YACL,CAAC;YACD,kEAAkE;YAClE,MAAM,CAAC,IAAI,CAAC,GAAG,oBAAoB,qBAAqB,EAAE;gBACxD,GAAG,OAAO;gBACV,WAAW,EAAE,cAAc;aAC5B,CAAC,CAAC;YACH,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,GAAG,oBAAoB,eAAe,EAAE;gBACzF,SAAS,EAAE,OAAO,CAAC,SAAS;gBAC5B,SAAS,EAAE,OAAO,CAAC,SAA+B;gBAClD,WAAW,EAAE,cAAc;aAC5B,CAAC,CAAC;QACL,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,MAAM,CAAC,KAAK,CAAC,wBAAwB,oBAAoB,KAAK,YAAY,EAAE,EAAE;YAC5E,GAAG,OAAO;YACV,iBAAiB,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;YACvE,WAAW,EAAE,mBAAmB;SACjC,CAAC,CAAC;QAEH,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;YAC9B,MAAM,KAAK,CAAC;QACd,CAAC;QAED,MAAM,IAAI,QAAQ,CAChB,gBAAgB,CAAC,kBAAkB,EACnC,wBAAwB,oBAAoB,KAAK,YAAY,EAAE,EAC/D;YACE,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,SAAS,EAAE,OAAO,CAAC,SAA+B;YAClD,iBAAiB,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,cAAc;YACvE,WAAW,EAAE,0BAA0B;SACxC,CACF,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/utils/pagination/pagination.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Pagination utilities for MCP list operations.
+ * Implements cursor-based pagination per MCP specification 2025-06-18.
+ *
+ * MCP Pagination Model:
+ * - Opaque cursor-based approach (not numbered pages)
+ * - Cursor is an opaque string token representing a position in the result set
+ * - Page size is determined by server (clients MUST NOT assume fixed page size)
+ * - Invalid cursors should result in error code -32602 (Invalid params)
+ *
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/utils/pagination | MCP Pagination Spec}
+ * @module src/utils/pagination/pagination
+ */
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/**
+ * Generic pagination state that can be encoded into a cursor.
+ * Implementations can extend this with additional fields as needed.
+ * This is the data structure serialized into the opaque cursor token.
+ */
+export interface PaginationState {
+    /** Maximum number of items per page; must be a positive integer */
+    limit: number;
+    /** Zero-based index of the first item in the current page */
+    offset: number;
+    /** Optional additional state preserved across pages (implementation-specific) */
+    [key: string]: unknown;
+}
+/**
+ * Result of a paginated operation.
+ * Returned by {@link paginateArray} and should be the shape returned by MCP list handlers.
+ * Per MCP spec, `nextCursor` must be omitted (not set to `null` or `""`) when no further pages exist.
+ */
+export interface PaginatedResult<T> {
+    /** Items for the current page */
+    items: T[];
+    /**
+     * Opaque cursor token for the next page.
+     * Omitted entirely when this is the last page — do not set to `null` or `""`.
+     */
+    nextCursor?: string;
+    /**
+     * Total item count across all pages, if cheaply available.
+     * Optional — some backends cannot compute this efficiently.
+     */
+    totalCount?: number;
+}
+/**
+ * Encodes pagination state into an opaque base64url cursor string.
+ * Serializes `state` to JSON, then encodes as base64url (URL-safe, no padding).
+ * The format is an implementation detail — callers must treat the returned string as opaque.
+ *
+ * @param state - Pagination state to encode; must have `offset >= 0` and `limit > 0`
+ * @returns Base64url-encoded cursor string (no `+`, `/`, or `=` characters)
+ * @throws {McpError} With code `InternalError` (-32603) if JSON serialization fails
+ * @example
+ * const cursor = encodeCursor({ offset: 50, limit: 25 });
+ * // cursor is an opaque string like "eyJvZmZzZXQiOjUwLCJsaW1pdCI6MjV9"
+ */
+export declare function encodeCursor(state: PaginationState): string;
+/**
+ * Decodes an opaque cursor string back into pagination state.
+ * Reverses base64url encoding, parses the JSON, and validates the required fields:
+ * `offset` must be a non-negative number and `limit` must be a positive number.
+ * Logs a warning and throws `InvalidParams` on any failure, per MCP spec.
+ *
+ * @param cursor - Opaque cursor string previously returned by {@link encodeCursor}
+ * @param context - Request context used to correlate warning log entries
+ * @returns Validated `PaginationState` decoded from the cursor
+ * @throws {McpError} With code `InvalidParams` (-32602) if the cursor is malformed,
+ *   base64-invalid, not valid JSON, or has an invalid `offset`/`limit` structure
+ * @example
+ * const state = decodeCursor(req.params.cursor, ctx);
+ * // state.offset and state.limit are safe to use directly
+ */
+export declare function decodeCursor(cursor: string, context: RequestContext): PaginationState;
+/**
+ * Extracts the cursor parameter from an MCP request's params object.
+ * Checks `params.cursor` first, then falls back to `params._meta.cursor`,
+ * matching both locations where MCP clients may supply the cursor token.
+ *
+ * @param params - Optional request params object; may contain `cursor` at the top
+ *   level or nested under `_meta`
+ * @returns The cursor string if found in either location, `undefined` otherwise
+ * @example
+ * // Top-level cursor
+ * extractCursor({ cursor: 'abc123' }); // => 'abc123'
+ *
+ * // Nested under _meta
+ * extractCursor({ _meta: { cursor: 'abc123' } }); // => 'abc123'
+ *
+ * // No cursor present
+ * extractCursor({}); // => undefined
+ * extractCursor(undefined); // => undefined
+ */
+export declare function extractCursor(params?: {
+    cursor?: string;
+    _meta?: {
+        cursor?: string;
+    };
+}): string | undefined;
+/**
+ * Paginates an in-memory array using opaque cursor-based pagination.
+ * Decodes the cursor (if provided) to determine offset and limit, slices the array,
+ * and returns a {@link PaginatedResult} with `nextCursor` set only when more items follow.
+ * When `cursorStr` is `undefined`, pagination starts from the beginning using `defaultPageSize`.
+ * When the decoded cursor's offset is beyond the array length, returns an empty items array.
+ * The cursor's `limit` is clamped to `maxPageSize` even if the encoded value is larger.
+ *
+ * @param items - Complete array of items to paginate; not mutated
+ * @param cursorStr - Opaque cursor token from the client, or `undefined` for the first page
+ * @param defaultPageSize - Page size to use when no cursor is present; must be a positive integer
+ * @param maxPageSize - Upper bound on items per page; cursor limit values are clamped to this
+ * @param context - Request context used for logging when cursor decoding fails
+ * @returns `PaginatedResult<T>` with the current page's items, `totalCount` set to `items.length`,
+ *   and `nextCursor` included only if additional pages remain
+ * @throws {McpError} With code `InvalidParams` (-32602) if `cursorStr` is present but invalid,
+ *   propagated from {@link decodeCursor}
+ * @example
+ * const allItems = ['a', 'b', 'c', 'd', 'e'];
+ *
+ * // First page (no cursor)
+ * const page1 = paginateArray(allItems, undefined, 2, 100, ctx);
+ * // => { items: ['a', 'b'], nextCursor: '<opaque>', totalCount: 5 }
+ *
+ * // Second page (using cursor from page1)
+ * const page2 = paginateArray(allItems, page1.nextCursor, 2, 100, ctx);
+ * // => { items: ['c', 'd'], nextCursor: '<opaque>', totalCount: 5 }
+ *
+ * // Last page
+ * const page3 = paginateArray(allItems, page2.nextCursor, 2, 100, ctx);
+ * // => { items: ['e'], totalCount: 5 }  (no nextCursor)
+ */
+export declare function paginateArray<T>(items: T[], cursorStr: string | undefined, defaultPageSize: number, maxPageSize: number, context: RequestContext): PaginatedResult<T>;
+/**
+ * Default pagination configuration values used by {@link paginateArray} callers.
+ * These serve as sensible defaults; individual call sites may pass different values
+ * or defer to environment-variable-driven config parsed in the config module.
+ *
+ * @example
+ * import { DEFAULT_PAGINATION_CONFIG, paginateArray } from '../../utils/pagination/pagination.js';
+ * const result = paginateArray(
+ *   items,
+ *   cursorStr,
+ *   DEFAULT_PAGINATION_CONFIG.DEFAULT_PAGE_SIZE,
+ *   DEFAULT_PAGINATION_CONFIG.MAX_PAGE_SIZE,
+ *   ctx,
+ * );
+ */
+export declare const DEFAULT_PAGINATION_CONFIG: {
+    /** Default number of items per page */
+    readonly DEFAULT_PAGE_SIZE: 50;
+    /** Maximum allowed items per page */
+    readonly MAX_PAGE_SIZE: 1000;
+    /** Minimum allowed items per page */
+    readonly MIN_PAGE_SIZE: 1;
+};
+//# sourceMappingURL=pagination.d.ts.map

package/dist/utils/pagination/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../../src/utils/pagination/pagination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iCAAiC;IACjC,KAAK,EAAE,CAAC,EAAE,CAAC;IACX;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAc3D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA8BrF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7B,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,eAAe,EAAE,MAAM,EACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,cAAc,GACtB,eAAe,CAAC,CAAC,CAAC,CAmCpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB;IACpC,uCAAuC;;IAEvC,qCAAqC;;IAErC,qCAAqC;;CAE7B,CAAC"}

package/dist/utils/pagination/pagination.js

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview Pagination utilities for MCP list operations.
+ * Implements cursor-based pagination per MCP specification 2025-06-18.
+ *
+ * MCP Pagination Model:
+ * - Opaque cursor-based approach (not numbered pages)
+ * - Cursor is an opaque string token representing a position in the result set
+ * - Page size is determined by server (clients MUST NOT assume fixed page size)
+ * - Invalid cursors should result in error code -32602 (Invalid params)
+ *
+ * @see {@link https://modelcontextprotocol.io/specification/2025-06-18/utils/pagination | MCP Pagination Spec}
+ * @module src/utils/pagination/pagination
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { base64ToString, stringToBase64 } from '../../utils/internal/encoding.js';
+import { logger } from '../../utils/internal/logger.js';
+/**
+ * Encodes pagination state into an opaque base64url cursor string.
+ * Serializes `state` to JSON, then encodes as base64url (URL-safe, no padding).
+ * The format is an implementation detail — callers must treat the returned string as opaque.
+ *
+ * @param state - Pagination state to encode; must have `offset >= 0` and `limit > 0`
+ * @returns Base64url-encoded cursor string (no `+`, `/`, or `=` characters)
+ * @throws {McpError} With code `InternalError` (-32603) if JSON serialization fails
+ * @example
+ * const cursor = encodeCursor({ offset: 50, limit: 25 });
+ * // cursor is an opaque string like "eyJvZmZzZXQiOjUwLCJsaW1pdCI6MjV9"
+ */
+export function encodeCursor(state) {
+    try {
+        const jsonString = JSON.stringify(state);
+        // Use cross-platform encoding, then convert standard base64 to base64url
+        const base64 = stringToBase64(jsonString)
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/, '');
+        return base64;
+    }
+    catch (error) {
+        throw new McpError(JsonRpcErrorCode.InternalError, 'Failed to encode pagination cursor', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Decodes an opaque cursor string back into pagination state.
+ * Reverses base64url encoding, parses the JSON, and validates the required fields:
+ * `offset` must be a non-negative number and `limit` must be a positive number.
+ * Logs a warning and throws `InvalidParams` on any failure, per MCP spec.
+ *
+ * @param cursor - Opaque cursor string previously returned by {@link encodeCursor}
+ * @param context - Request context used to correlate warning log entries
+ * @returns Validated `PaginationState` decoded from the cursor
+ * @throws {McpError} With code `InvalidParams` (-32602) if the cursor is malformed,
+ *   base64-invalid, not valid JSON, or has an invalid `offset`/`limit` structure
+ * @example
+ * const state = decodeCursor(req.params.cursor, ctx);
+ * // state.offset and state.limit are safe to use directly
+ */
+export function decodeCursor(cursor, context) {
+    try {
+        // Convert base64url back to standard base64, then decode cross-platform
+        const standardBase64 = cursor.replace(/-/g, '+').replace(/_/g, '/');
+        const jsonString = base64ToString(standardBase64);
+        const state = JSON.parse(jsonString);
+        // Validate required fields
+        if (typeof state.offset !== 'number' ||
+            typeof state.limit !== 'number' ||
+            state.offset < 0 ||
+            state.limit <= 0) {
+            throw new Error('Invalid pagination state structure');
+        }
+        return state;
+    }
+    catch (error) {
+        logger.warning('Failed to decode pagination cursor', {
+            ...context,
+            cursor,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        throw new McpError(JsonRpcErrorCode.InvalidParams, 'Invalid pagination cursor. The cursor may be expired, corrupted, or from a different request.', { cursor });
+    }
+}
+/**
+ * Extracts the cursor parameter from an MCP request's params object.
+ * Checks `params.cursor` first, then falls back to `params._meta.cursor`,
+ * matching both locations where MCP clients may supply the cursor token.
+ *
+ * @param params - Optional request params object; may contain `cursor` at the top
+ *   level or nested under `_meta`
+ * @returns The cursor string if found in either location, `undefined` otherwise
+ * @example
+ * // Top-level cursor
+ * extractCursor({ cursor: 'abc123' }); // => 'abc123'
+ *
+ * // Nested under _meta
+ * extractCursor({ _meta: { cursor: 'abc123' } }); // => 'abc123'
+ *
+ * // No cursor present
+ * extractCursor({}); // => undefined
+ * extractCursor(undefined); // => undefined
+ */
+export function extractCursor(params) {
+    return params?.cursor ?? params?._meta?.cursor;
+}
+/**
+ * Paginates an in-memory array using opaque cursor-based pagination.
+ * Decodes the cursor (if provided) to determine offset and limit, slices the array,
+ * and returns a {@link PaginatedResult} with `nextCursor` set only when more items follow.
+ * When `cursorStr` is `undefined`, pagination starts from the beginning using `defaultPageSize`.
+ * When the decoded cursor's offset is beyond the array length, returns an empty items array.
+ * The cursor's `limit` is clamped to `maxPageSize` even if the encoded value is larger.
+ *
+ * @param items - Complete array of items to paginate; not mutated
+ * @param cursorStr - Opaque cursor token from the client, or `undefined` for the first page
+ * @param defaultPageSize - Page size to use when no cursor is present; must be a positive integer
+ * @param maxPageSize - Upper bound on items per page; cursor limit values are clamped to this
+ * @param context - Request context used for logging when cursor decoding fails
+ * @returns `PaginatedResult<T>` with the current page's items, `totalCount` set to `items.length`,
+ *   and `nextCursor` included only if additional pages remain
+ * @throws {McpError} With code `InvalidParams` (-32602) if `cursorStr` is present but invalid,
+ *   propagated from {@link decodeCursor}
+ * @example
+ * const allItems = ['a', 'b', 'c', 'd', 'e'];
+ *
+ * // First page (no cursor)
+ * const page1 = paginateArray(allItems, undefined, 2, 100, ctx);
+ * // => { items: ['a', 'b'], nextCursor: '<opaque>', totalCount: 5 }
+ *
+ * // Second page (using cursor from page1)
+ * const page2 = paginateArray(allItems, page1.nextCursor, 2, 100, ctx);
+ * // => { items: ['c', 'd'], nextCursor: '<opaque>', totalCount: 5 }
+ *
+ * // Last page
+ * const page3 = paginateArray(allItems, page2.nextCursor, 2, 100, ctx);
+ * // => { items: ['e'], totalCount: 5 }  (no nextCursor)
+ */
+export function paginateArray(items, cursorStr, defaultPageSize, maxPageSize, context) {
+    let offset = 0;
+    let limit = defaultPageSize;
+    // Decode cursor if provided
+    if (cursorStr) {
+        const state = decodeCursor(cursorStr, context);
+        offset = state.offset;
+        limit = Math.min(state.limit, maxPageSize); // Enforce max page size
+    }
+    // Validate bounds
+    if (offset >= items.length) {
+        return {
+            items: [],
+            totalCount: items.length,
+        };
+    }
+    // Extract page
+    const pageItems = items.slice(offset, offset + limit);
+    const hasMore = offset + limit < items.length;
+    // Build result, conditionally adding nextCursor only if it exists
+    const result = {
+        items: pageItems,
+        totalCount: items.length,
+    };
+    // Only add nextCursor if more results exist
+    if (hasMore) {
+        result.nextCursor = encodeCursor({ offset: offset + limit, limit });
+    }
+    return result;
+}
+/**
+ * Default pagination configuration values used by {@link paginateArray} callers.
+ * These serve as sensible defaults; individual call sites may pass different values
+ * or defer to environment-variable-driven config parsed in the config module.
+ *
+ * @example
+ * import { DEFAULT_PAGINATION_CONFIG, paginateArray } from '../../utils/pagination/pagination.js';
+ * const result = paginateArray(
+ *   items,
+ *   cursorStr,
+ *   DEFAULT_PAGINATION_CONFIG.DEFAULT_PAGE_SIZE,
+ *   DEFAULT_PAGINATION_CONFIG.MAX_PAGE_SIZE,
+ *   ctx,
+ * );
+ */
+export const DEFAULT_PAGINATION_CONFIG = {
+    /** Default number of items per page */
+    DEFAULT_PAGE_SIZE: 50,
+    /** Maximum allowed items per page */
+    MAX_PAGE_SIZE: 1000,
+    /** Minimum allowed items per page */
+    MIN_PAGE_SIZE: 1,
+};
+//# sourceMappingURL=pagination.js.map