dynalitics 0.0.0-stage → 0.1.0

package/dist/read/http.js

@@ -0,0 +1,65 @@
+/** Sent on every response, JSON and HTML alike. */
+export const SECURITY_HEADERS = {
+    'Cache-Control': 'no-store',
+    'X-Content-Type-Options': 'nosniff',
+    'Referrer-Policy': 'no-referrer',
+};
+export const ERROR_STATUS = {
+    forbidden: 403,
+    not_found: 404,
+    method_not_allowed: 405,
+    invalid_parameter: 400,
+    range_too_large: 400,
+    invalid_query: 400,
+    timeout: 504,
+    unavailable: 503,
+    internal: 500,
+};
+/** Fixed, generic sentences. Never SQL, driver text, table names or connection details. */
+const ERROR_MESSAGE = {
+    forbidden: 'Not authorised.',
+    not_found: 'Unknown route.',
+    method_not_allowed: 'Only GET is supported.',
+    invalid_parameter: 'Invalid parameter.',
+    range_too_large: 'The requested time range is too large.',
+    invalid_query: 'Invalid query.',
+    timeout: 'The query took too long. Narrow the time range.',
+    unavailable: 'The analytics database is not available right now.',
+    internal: 'Internal error.',
+};
+export function json(status, body, extra = {}) {
+    return {
+        status,
+        headers: { ...SECURITY_HEADERS, 'Content-Type': 'application/json; charset=utf-8', ...extra },
+        body: JSON.stringify(body),
+    };
+}
+/** Spec 18.4: one fixed sentence per reason. The query text itself is never echoed. */
+export const QUERY_ERROR_MESSAGE = {
+    too_long: 'The query is longer than 512 characters.',
+    too_many_clauses: 'The query has more than 12 parts.',
+    unbalanced_quote: 'A quote is not closed.',
+    empty_value: 'A field or term has no value.',
+    value_too_long: 'A value is longer than 128 characters.',
+    unknown_field: 'Unknown field, or a field that cannot be searched.',
+    bad_value: "The value does not fit the field's type.",
+};
+export function errorResponse(code, param, query) {
+    const message = query !== undefined
+        ? QUERY_ERROR_MESSAGE[query.reason]
+        : param === undefined
+            ? ERROR_MESSAGE[code]
+            : `${ERROR_MESSAGE[code]} (${param})`;
+    return json(ERROR_STATUS[code], {
+        success: false,
+        data: null,
+        unavailable: null,
+        error: {
+            code,
+            message,
+            ...(param === undefined ? {} : { param }),
+            ...(query === undefined ? {} : { reason: query.reason, position: query.position }),
+        },
+    }, code === 'method_not_allowed' ? { Allow: 'GET' } : {});
+}
+//# sourceMappingURL=http.js.map

package/dist/read/index.d.ts

@@ -0,0 +1,5 @@
+export { createHandler } from './handler.js';
+export type { HandlerOptions } from './handler.js';
+export { toFetchHandler, toNodeListener } from './adapters.js';
+export type { AuthResult, Authorize, DynaliticsHandler, DynaliticsRequest, DynaliticsResponse, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/read/index.js

@@ -0,0 +1,3 @@
+export { createHandler } from './handler.js';
+export { toFetchHandler, toNodeListener } from './adapters.js';
+//# sourceMappingURL=index.js.map

package/dist/read/lock/authorize.d.ts

@@ -0,0 +1,22 @@
+import type { Authorize, DynaliticsRequest } from '../types.js';
+/** What authorize() said, read strictly. */
+export interface Auth {
+    readonly allowed: boolean;
+    /** `revealPii === true` on an allowing result. Only one of the three reveal conditions (see gate.ts). */
+    readonly revealPii: boolean;
+    /** The host returned something other than true, false or { allowed: boolean }. Refused and reported. */
+    readonly invalid: boolean;
+}
+/** Strict: only the boolean true or { allowed: true } grants access, only revealPii === true reveals. */
+export declare function normalizeAuth(result: unknown): Auth;
+export type AuthOutcome = {
+    readonly kind: 'decided';
+    readonly auth: Auth;
+}
+/** authorize() threw, rejected or did not settle before the deadline. Always refused with 500, never 200. */
+ | {
+    readonly kind: 'failed';
+};
+/** Always first, even for unknown paths. A hung authorize() must not hold the socket open forever. */
+export declare function authorizeWithDeadline(authorize: Authorize, request: DynaliticsRequest, timeoutMs: number): Promise<AuthOutcome>;
+//# sourceMappingURL=authorize.d.ts.map

package/dist/read/lock/authorize.js

@@ -0,0 +1,32 @@
+/** Strict: only the boolean true or { allowed: true } grants access, only revealPii === true reveals. */
+export function normalizeAuth(result) {
+    if (typeof result === 'boolean')
+        return { allowed: result, revealPii: false, invalid: false };
+    if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+        const r = result;
+        if (typeof r.allowed === 'boolean') {
+            return { allowed: r.allowed, revealPii: r.allowed && r.revealPii === true, invalid: false };
+        }
+    }
+    return { allowed: false, revealPii: false, invalid: true };
+}
+/** Always first, even for unknown paths. A hung authorize() must not hold the socket open forever. */
+export async function authorizeWithDeadline(authorize, request, timeoutMs) {
+    let timer;
+    try {
+        const deadline = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => reject(new Error('authorize timed out')), timeoutMs);
+            timer.unref?.();
+        });
+        const result = await Promise.race([Promise.resolve().then(() => authorize(request)), deadline]);
+        return { kind: 'decided', auth: normalizeAuth(result) };
+    }
+    catch {
+        return { kind: 'failed' };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=authorize.js.map

package/dist/read/lock/base-path.d.ts

@@ -0,0 +1,11 @@
+/** '/' or one or more non-empty segments, optionally with ONE trailing slash. No '//' (a protocol-relative URL). */
+export declare const BASE_PATH_PATTERN: RegExp;
+export declare const isValidBasePath: (p: string) => boolean;
+/** What the client prepends to '/api/...': '' for the root, no trailing slash, so it never builds //api/meta. */
+export declare const normalizeBasePath: (p: string) => string;
+/**
+ * Routes are exact matches on canonical paths only (F-17): no '//', '.', '%', ';', '?' or trailing slash. Letter case
+ * is not decided here: '/API/meta' is canonical but is not a route, so the database side answers not_found.
+ */
+export declare const CANONICAL_PATH: RegExp;
+//# sourceMappingURL=base-path.d.ts.map

package/dist/read/lock/base-path.js

@@ -0,0 +1,12 @@
+// basePath rules (QA F-07, F-17). The lock layer owns them: they decide what the page is told to call.
+/** '/' or one or more non-empty segments, optionally with ONE trailing slash. No '//' (a protocol-relative URL). */
+export const BASE_PATH_PATTERN = /^(\/|(\/[A-Za-z0-9_-]+)+\/?)$/;
+export const isValidBasePath = (p) => BASE_PATH_PATTERN.test(p);
+/** What the client prepends to '/api/...': '' for the root, no trailing slash, so it never builds //api/meta. */
+export const normalizeBasePath = (p) => (p === '/' ? '' : p.replace(/\/$/, ''));
+/**
+ * Routes are exact matches on canonical paths only (F-17): no '//', '.', '%', ';', '?' or trailing slash. Letter case
+ * is not decided here: '/API/meta' is canonical but is not a route, so the database side answers not_found.
+ */
+export const CANONICAL_PATH = /^(\/|(\/[A-Za-z0-9_-]+)+)$/;
+//# sourceMappingURL=base-path.js.map

package/dist/read/lock/gate.d.ts

@@ -0,0 +1,30 @@
+import type { ErrorCode } from '../../protocol.js';
+import type { DynaliticsRequest, Grant } from '../types.js';
+import type { Auth } from './authorize.js';
+export interface GateConfig {
+    /** The `pii.reveal` option. */
+    readonly revealOption: boolean;
+}
+export type Decision = {
+    readonly kind: 'refuse';
+    readonly code: ErrorCode;
+}
+/** GET '/': the dashboard page (the caller answers 404 when no page was supplied). */
+ | {
+    readonly kind: 'page';
+} | {
+    readonly kind: 'run';
+    readonly route: string;
+    readonly grant: Grant;
+};
+/**
+ * The reveal conditions, computed once, here: `pii.reveal` option AND authorize `revealPii === true` AND `?pii=reveal`.
+ * `?pii` is only read for equality; the service still validates it strictly and answers 400 for anything else.
+ */
+export declare function computeGrant(auth: Auth, query: DynaliticsRequest['query'], cfg: GateConfig): Grant;
+/**
+ * Called only for a request authorize() allowed. Order matters and is part of the contract: method, then canonical
+ * path (F-17), then the page, and only then a route is handed to the database side.
+ */
+export declare function gate(request: DynaliticsRequest, auth: Auth, cfg: GateConfig): Decision;
+//# sourceMappingURL=gate.d.ts.map

package/dist/read/lock/gate.js

@@ -0,0 +1,24 @@
+import { CANONICAL_PATH } from './base-path.js';
+/**
+ * The reveal conditions, computed once, here: `pii.reveal` option AND authorize `revealPii === true` AND `?pii=reveal`.
+ * `?pii` is only read for equality; the service still validates it strictly and answers 400 for anything else.
+ */
+export function computeGrant(auth, query, cfg) {
+    const revealable = cfg.revealOption && auth.revealPii;
+    return { revealable, reveal: revealable && query['pii'] === 'reveal' };
+}
+/**
+ * Called only for a request authorize() allowed. Order matters and is part of the contract: method, then canonical
+ * path (F-17), then the page, and only then a route is handed to the database side.
+ */
+export function gate(request, auth, cfg) {
+    if (request.method !== 'GET')
+        return { kind: 'refuse', code: 'method_not_allowed' };
+    // Exact matching on canonical paths only: '//', '..', '%', ';', trailing slashes and the like never route.
+    if (!CANONICAL_PATH.test(request.path))
+        return { kind: 'refuse', code: 'not_found' };
+    if (request.path === '/')
+        return { kind: 'page' };
+    return { kind: 'run', route: request.path, grant: computeGrant(auth, request.query, cfg) };
+}
+//# sourceMappingURL=gate.js.map

package/dist/read/lock/index.d.ts

@@ -0,0 +1,28 @@
+import type { ErrorCode } from '../../protocol.js';
+import type { Authorize, DynaliticsRequest, DynaliticsResponse, Grant, ReadOutcome } from '../types.js';
+/**
+ * The lock layer (docs/SPEC.md 15, 16). It decides whether and how a request may run and never sees SQL. The database
+ * side is reached through one callback, `next(route, grant)`, and ONLY after a strict authorize() success, a GET, and a
+ * canonical path. This module must not import the service, queries, drivers or the database (a test enforces it).
+ */
+export interface LockOptions {
+    /** REQUIRED. Read strictly: only `true` or `{ allowed: true }` grants. */
+    readonly authorize: Authorize;
+    /** '/' or '/segment/...'; validated by the caller (options rule) and normalised here. */
+    readonly basePath: string;
+    readonly dashboardHtml: string | undefined;
+    /** The `pii.reveal` option. */
+    readonly reveal: boolean;
+    /** authorize() has this long to settle, then the request is refused with 500. */
+    readonly authorizeTimeoutMs: number;
+}
+/** Reports a failure of the lock itself. The route is whatever the host's reporter chooses to echo; no request data. */
+export type LockReport = (route: string, code: Extract<ErrorCode, 'internal'> | 'authorize_invalid_result', message: string) => void;
+export type Next = (route: string, grant: Grant) => Promise<ReadOutcome>;
+export interface Lock {
+    /** Normalised: '' for the root, otherwise '/segment/...' without a trailing slash. */
+    readonly basePath: string;
+    handle(request: DynaliticsRequest, next: Next): Promise<DynaliticsResponse>;
+}
+export declare function createLock(options: LockOptions, report: LockReport): Lock;
+//# sourceMappingURL=index.d.ts.map

package/dist/read/lock/index.js

@@ -0,0 +1,46 @@
+import { errorResponse, json } from '../http.js';
+import { authorizeWithDeadline } from './authorize.js';
+import { normalizeBasePath } from './base-path.js';
+import { gate } from './gate.js';
+import { htmlResponse } from './serve-html.js';
+export function createLock(options, report) {
+    const basePath = normalizeBasePath(options.basePath);
+    const cfg = { revealOption: options.reveal };
+    return {
+        basePath,
+        async handle(request, next) {
+            const outcome = await authorizeWithDeadline(options.authorize, request, options.authorizeTimeoutMs);
+            if (outcome.kind === 'failed') {
+                report(request.path, 'internal', 'authorize() threw or timed out; the request was refused');
+                return errorResponse('internal');
+            }
+            const { auth } = outcome;
+            if (auth.invalid) {
+                report(request.path, 'authorize_invalid_result', 'authorize() returned something other than true, false or { allowed: boolean }; the request was refused');
+                return errorResponse('forbidden');
+            }
+            if (!auth.allowed)
+                return errorResponse('forbidden');
+            const decision = gate(request, auth, cfg);
+            if (decision.kind === 'refuse')
+                return errorResponse(decision.code);
+            if (decision.kind === 'page') {
+                return options.dashboardHtml === undefined
+                    ? errorResponse('not_found')
+                    : htmlResponse(options.dashboardHtml, basePath);
+            }
+            try {
+                const result = await next(decision.route, decision.grant);
+                return result.kind === 'ok'
+                    ? json(200, result.body)
+                    : errorResponse(result.code, result.param, result.query);
+            }
+            catch {
+                // The service promises never to throw. If it does anyway, the request fails closed.
+                report(request.path, 'internal', 'unexpected error in the read handler');
+                return errorResponse('internal');
+            }
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/read/lock/options.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Option rules owned by the lock layer. handler.ts spreads them into the one options rule (same key order, same
+ * messages as before the extraction); `pii.reveal` is the lock's, `pii.maskUserId` is the database side's.
+ */
+export declare const lockOptionRules: {
+    authorize: import("../../config/validate.js").Rule & {
+        required: true;
+    };
+    basePath: import("../../config/validate.js").Rule;
+    authorizeTimeoutMs: import("../../config/validate.js").Rule;
+    dashboardHtml: import("../../config/validate.js").Rule;
+};
+//# sourceMappingURL=options.d.ts.map

package/dist/read/lock/options.js

@@ -0,0 +1,18 @@
+import { fn, int, req, str } from '../../config/validate.js';
+import { BASE_PATH_PATTERN } from './base-path.js';
+/**
+ * Option rules owned by the lock layer. handler.ts spreads them into the one options rule (same key order, same
+ * messages as before the extraction); `pii.reveal` is the lock's, `pii.maskUserId` is the database side's.
+ */
+export const lockOptionRules = {
+    authorize: req(fn),
+    basePath: str({
+        min: 1,
+        max: 200,
+        pattern: BASE_PATH_PATTERN,
+        hint: "must be '/' or segments like /admin/analytics (no '//', no '.', no query)",
+    }),
+    authorizeTimeoutMs: int({ min: 100, max: 60_000 }),
+    dashboardHtml: str({ min: 1 }),
+};
+//# sourceMappingURL=options.js.map

package/dist/read/lock/serve-html.d.ts

@@ -0,0 +1,6 @@
+import type { DynaliticsResponse } from '../types.js';
+export declare const newNonce: () => string;
+export declare function csp(nonce: string): string;
+/** Fills the two placeholders of the dashboard page. Nonce is base64url; the base path is pre-validated and normalised. */
+export declare function htmlResponse(html: string, basePath: string, nonce?: string): DynaliticsResponse;
+//# sourceMappingURL=serve-html.d.ts.map

package/dist/read/lock/serve-html.js

@@ -0,0 +1,38 @@
+import { randomBytes } from 'node:crypto';
+import { SECURITY_HEADERS } from '../http.js';
+// Serving the dashboard page: per-request nonce, strict CSP, the two placeholders (docs/SPEC.md 10.8).
+// CORS and CSRF posture, stated here because this layer owns it: the handler emits NO CORS headers, sets NO cookies,
+// accepts only GET and never changes state, so there is nothing for a cross-site request to forge. A cross-origin
+// deployment needs the host's own CORS layer in front. There is no CSRF code on purpose (SECURITY.md non-guarantee).
+export const newNonce = () => randomBytes(16).toString('base64url');
+export function csp(nonce) {
+    return [
+        "default-src 'none'",
+        `script-src 'nonce-${nonce}'`,
+        `style-src 'nonce-${nonce}'`,
+        "connect-src 'self'",
+        "img-src 'self' data:",
+        "base-uri 'none'",
+        "form-action 'none'",
+        "frame-ancestors 'none'",
+    ].join('; ');
+}
+/** Fills the two placeholders of the dashboard page. Nonce is base64url; the base path is pre-validated and normalised. */
+export function htmlResponse(html, basePath, nonce = newNonce()) {
+    const body = html
+        .split('%%DYNALITICS_NONCE%%')
+        .join(nonce)
+        .split('%%DYNALITICS_BASE%%')
+        .join(basePath);
+    return {
+        status: 200,
+        headers: {
+            ...SECURITY_HEADERS,
+            'Content-Type': 'text/html; charset=utf-8',
+            'Content-Security-Policy': csp(nonce),
+            'X-Frame-Options': 'DENY',
+        },
+        body,
+    };
+}
+//# sourceMappingURL=serve-html.js.map

package/dist/read/mask.d.ts

@@ -0,0 +1,12 @@
+/** IPv4 keeps two octets, IPv6 two groups, hashed values 8 hex characters. */
+export declare function maskIp(ip: string | null): string | null;
+/** First character of the local part and the domain: `j***@example.com`. Anything that is not exactly one address: `***`. */
+export declare function maskEmail(email: string | null): string | null;
+export declare function maskUsername(name: string | null): string | null;
+/**
+ * `u_90042` -> `u_***42`: the first two and last two characters of ids of at least 6 characters, `***` for shorter ones
+ * (so at most 4 characters are ever shown). An id that looks like an email address is masked as an email.
+ */
+export declare function maskUserId(id: string | null): string | null;
+export declare const MASKED_CUSTOM = "***";
+//# sourceMappingURL=mask.d.ts.map

package/dist/read/mask.js

@@ -0,0 +1,55 @@
+/**
+ * PII masking (spec 10.6). Every function is TOTAL and FAILS CLOSED: a value that does not match the expected shape
+ * exactly comes out as a fixed "***", never as a partial copy of unparseable input.
+ */
+const first = (s) => [...s][0] ?? '';
+const FIXED = '***';
+const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const HASH = /^[0-9a-f]{64}$/i;
+const IPV6 = /^[0-9a-f]{0,4}(?::[0-9a-f]{0,4}){2,7}$/i;
+const EMAIL = /^[^@\s]+@[^@\s]+$/u;
+const MIN_USER_ID_LENGTH = 6;
+/** IPv4 keeps two octets, IPv6 two groups, hashed values 8 hex characters. */
+export function maskIp(ip) {
+    if (ip === null || ip === '')
+        return null;
+    if (IPV4.test(ip))
+        return `${ip.split('.').slice(0, 2).join('.')}.x.x`;
+    if (HASH.test(ip))
+        return `${ip.slice(0, 8)}…`;
+    if (IPV6.test(ip)) {
+        if (ip.startsWith('::'))
+            return '::x';
+        const [a = '', b = ''] = ip.split(':');
+        return b === '' ? `${a}::x` : `${a}:${b}::x`;
+    }
+    return FIXED; // ports, lists ("1.2.3.4, 5.6.7.8"), zone ids, words: never partially echoed
+}
+/** First character of the local part and the domain: `j***@example.com`. Anything that is not exactly one address: `***`. */
+export function maskEmail(email) {
+    if (email === null)
+        return null;
+    if (!EMAIL.test(email))
+        return FIXED;
+    const at = email.indexOf('@');
+    return `${first(email.slice(0, at))}***${email.slice(at)}`;
+}
+export function maskUsername(name) {
+    return name === null ? null : `${first(name)}***`;
+}
+/**
+ * `u_90042` -> `u_***42`: the first two and last two characters of ids of at least 6 characters, `***` for shorter ones
+ * (so at most 4 characters are ever shown). An id that looks like an email address is masked as an email.
+ */
+export function maskUserId(id) {
+    if (id === null)
+        return null;
+    if (id.includes('@'))
+        return maskEmail(id);
+    const chars = [...id];
+    if (chars.length < MIN_USER_ID_LENGTH)
+        return FIXED;
+    return `${chars.slice(0, 2).join('')}${FIXED}${chars.slice(-2).join('')}`;
+}
+export const MASKED_CUSTOM = FIXED;
+//# sourceMappingURL=mask.js.map

package/dist/read/params.d.ts

@@ -0,0 +1,56 @@
+import type { Interval } from '../protocol.js';
+export type RouteName = 'meta' | 'visits-over-time' | 'top-pages' | 'new-vs-returning' | 'consent-rate' | 'recent-visits' | 'search' | 'search-histogram' | 'search-fields';
+export interface ReadLimits {
+    readonly maxRangeDays: number;
+    readonly maxBuckets: number;
+    readonly topPagesMax: number;
+    readonly recentMax: number;
+    readonly newVsReturningMaxRangeDays: number;
+    /** Explorer routes (spec 18.3): contains-searches only use the timestamp index, so the range is capped lower. */
+    readonly explorerMaxRangeDays: number;
+}
+export interface ParamContext {
+    readonly now: Date;
+    readonly limits: ReadLimits;
+    readonly defaults: {
+        readonly rangeDays: number;
+        readonly interval: Interval;
+        readonly topPagesLimit: number;
+        readonly recentLimit: number;
+    };
+    /** Dimension names offered for `breakdown`. The request can only pick one of these names. */
+    readonly breakdowns: ReadonlySet<string>;
+    /** Explorer facet field names offered for `split`. */
+    readonly splits: ReadonlySet<string>;
+    readonly hasCursor: boolean;
+}
+export interface Cursor {
+    readonly ts: Date;
+    readonly id: string;
+}
+export interface ParsedParams {
+    readonly from: Date;
+    readonly to: Date;
+    readonly interval: Interval;
+    readonly limit: number;
+    readonly breakdown: string | undefined;
+    readonly cursor: Cursor | undefined;
+    readonly pii: boolean;
+    /** Explorer query text, unparsed (the search parser validates it against the allow-list). '' when absent. */
+    readonly q: string;
+    readonly split: string | undefined;
+}
+export type ParseResult = {
+    readonly ok: true;
+    readonly params: ParsedParams;
+} | {
+    readonly ok: false;
+    readonly code: 'invalid_parameter' | 'range_too_large';
+    readonly param?: string;
+};
+export declare function encodeCursor(ts: Date, id: string): string;
+/** Strict: anchored patterns only; the result is typed and later bound as parameters. */
+export declare function decodeCursor(token: string): Cursor | null;
+/** Parses and validates every query parameter of a route. Anything not on the route's allow-list is an error. */
+export declare function parseParams(route: RouteName, query: Readonly<Record<string, string | readonly string[]>>, ctx: ParamContext): ParseResult;
+//# sourceMappingURL=params.d.ts.map

package/dist/read/params.js

@@ -0,0 +1,150 @@
+import { bucketStarts } from './buckets.js';
+const SEARCH_ROUTES = new Set([
+    'search',
+    'search-histogram',
+    'search-fields',
+]);
+const DAY_MS = 86_400_000;
+const MAX_QUERY_CHARS = 2048;
+const INTERVALS = new Set(['hour', 'day', 'week', 'month']);
+const ALLOWED = {
+    meta: new Set(),
+    'visits-over-time': new Set(['from', 'to', 'interval', 'breakdown']),
+    'top-pages': new Set(['from', 'to', 'limit']),
+    'new-vs-returning': new Set(['from', 'to', 'interval']),
+    'consent-rate': new Set(['from', 'to', 'interval']),
+    'recent-visits': new Set(['from', 'to', 'limit', 'cursor', 'pii']),
+    search: new Set(['from', 'to', 'limit', 'cursor', 'pii', 'q']),
+    'search-histogram': new Set(['from', 'to', 'interval', 'q', 'split']),
+    'search-fields': new Set(['from', 'to', 'q']),
+};
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
+const CURSOR_TOKEN = /^[A-Za-z0-9_-]{1,200}$/;
+const CURSOR_BODY = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z)\|(\d{1,19})$/;
+function parseInstant(v) {
+    let iso;
+    if (DATE_ONLY.test(v))
+        iso = `${v}T00:00:00.000Z`;
+    else if (INSTANT.test(v)) {
+        // pad a short fraction to milliseconds: ".5Z" -> ".500Z"; no fraction -> ".000Z"
+        iso = v.includes('.')
+            ? v.replace(/\.(\d{1,3})Z$/, (_m, f) => `.${f.padEnd(3, '0')}Z`)
+            : v.replace('Z', '.000Z');
+    }
+    else
+        return null;
+    const d = new Date(iso);
+    // Reject roll-overs such as 2026-02-30: the round trip must reproduce the input.
+    return Number.isNaN(d.getTime()) || d.toISOString().slice(0, 19) !== iso.slice(0, 19) ? null : d;
+}
+export function encodeCursor(ts, id) {
+    return Buffer.from(`${ts.toISOString()}|${id}`, 'utf8').toString('base64url');
+}
+/** Strict: anchored patterns only; the result is typed and later bound as parameters. */
+export function decodeCursor(token) {
+    if (!CURSOR_TOKEN.test(token))
+        return null;
+    const m = CURSOR_BODY.exec(Buffer.from(token, 'base64url').toString('utf8'));
+    if (m?.[1] === undefined || m[2] === undefined)
+        return null;
+    const ts = parseInstant(m[1]);
+    return ts === null ? null : { ts, id: m[2] };
+}
+const invalid = (param) => param === undefined
+    ? { ok: false, code: 'invalid_parameter' }
+    : { ok: false, code: 'invalid_parameter', param };
+/** Parses and validates every query parameter of a route. Anything not on the route's allow-list is an error. */
+export function parseParams(route, query, ctx) {
+    const allowed = ALLOWED[route];
+    let size = 0;
+    const single = {};
+    for (const key of Object.keys(query)) {
+        if (!allowed.has(key))
+            return invalid(key);
+        const value = query[key];
+        if (typeof value !== 'string')
+            return invalid(key);
+        size += key.length + value.length;
+        single[key] = value;
+    }
+    if (size > MAX_QUERY_CHARS)
+        return invalid();
+    const has = (k) => Object.hasOwn(single, k);
+    let to = ctx.now;
+    if (has('to')) {
+        const t = parseInstant(single['to'] ?? '');
+        if (t === null)
+            return invalid('to');
+        to = t;
+    }
+    let from = new Date(to.getTime() - ctx.defaults.rangeDays * DAY_MS);
+    if (has('from')) {
+        const f = parseInstant(single['from'] ?? '');
+        if (f === null)
+            return invalid('from');
+        from = f;
+    }
+    if (route !== 'meta' && to.getTime() <= from.getTime())
+        return invalid('to');
+    let interval = ctx.defaults.interval;
+    if (has('interval')) {
+        const i = single['interval'] ?? '';
+        if (!INTERVALS.has(i))
+            return invalid('interval');
+        interval = i;
+    }
+    let limit = route === 'top-pages' ? ctx.defaults.topPagesLimit : ctx.defaults.recentLimit;
+    if (has('limit')) {
+        const raw = single['limit'] ?? '';
+        const max = route === 'top-pages' ? ctx.limits.topPagesMax : ctx.limits.recentMax;
+        if (!/^\d{1,4}$/.test(raw) || Number(raw) < 1 || Number(raw) > max)
+            return invalid('limit');
+        limit = Number(raw);
+    }
+    let breakdown;
+    if (has('breakdown')) {
+        const b = single['breakdown'] ?? '';
+        if (!ctx.breakdowns.has(b))
+            return invalid('breakdown');
+        breakdown = b;
+    }
+    let cursor;
+    if (has('cursor')) {
+        const c = decodeCursor(single['cursor'] ?? '');
+        if (c === null || !ctx.hasCursor)
+            return invalid('cursor');
+        cursor = c;
+    }
+    let split;
+    if (has('split')) {
+        const s = single['split'] ?? '';
+        if (!ctx.splits.has(s))
+            return invalid('split');
+        split = s;
+    }
+    const q = single['q'] ?? '';
+    let pii = false;
+    if (has('pii')) {
+        if (single['pii'] !== 'reveal')
+            return invalid('pii');
+        pii = true;
+    }
+    const rangeDays = (to.getTime() - from.getTime()) / DAY_MS;
+    const cap = route === 'new-vs-returning'
+        ? ctx.limits.newVsReturningMaxRangeDays
+        : SEARCH_ROUTES.has(route)
+            ? Math.min(ctx.limits.explorerMaxRangeDays, ctx.limits.maxRangeDays)
+            : ctx.limits.maxRangeDays;
+    if (route !== 'meta' && rangeDays > cap)
+        return { ok: false, code: 'range_too_large' };
+    const bucketed = route === 'visits-over-time' ||
+        route === 'new-vs-returning' ||
+        route === 'consent-rate' ||
+        route === 'search-histogram';
+    if (bucketed && bucketStarts(from, to, interval).length > ctx.limits.maxBuckets) {
+        return { ok: false, code: 'range_too_large' };
+    }
+    return { ok: true, params: { from, to, interval, limit, breakdown, cursor, pii, q, split } };
+}
+//# sourceMappingURL=params.js.map