@alisio/server 0.1.0-alpha.1

package/dist/routes/providers.js

@@ -0,0 +1,230 @@
+/**
+ * Providers, models and credentials (RF-15, §8.2). Credentials are write-only: requests may set
+ * or delete them, but no response carries a value, only `{configured, source, tail?}`. Request
+ * bodies are never logged (the server logs routes and status codes only). Activating a profile
+ * changes the provider of one workspace application, so it is refused while that workspace has
+ * runs (P-01: 409 `runs_active`).
+ */
+import { maskSecret, ProviderSettingsStore } from "@alisio/core";
+import { readJson } from "../http/body.js";
+import { HttpError } from "../http/errors.js";
+import { is, validate } from "../schemas.js";
+import { workspaceApp } from "./management.js";
+/** Credential keys the web may write (RF-15). */
+const CREDENTIAL_KEYS = ["apiKey", "bearerToken"];
+const PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const secretValue = (v) => typeof v === "string" && /^\S{1,4096}$/.test(v);
+function typesOf(opened) {
+    return (opened?.app.providers.list().map((r) => ({
+        id: r.id,
+        name: r.name,
+        ...(r.description ? { description: r.description } : {}),
+        fields: r.fields.map((field) => {
+            // A secret field never carries a default value to the client.
+            const { defaultValue, ...rest } = field;
+            return field.kind === "secret" || defaultValue === undefined
+                ? { ...rest }
+                : { ...rest, defaultValue };
+        }),
+    })) ?? []);
+}
+async function credentialStatus(store, name, values, type) {
+    const stored = await store.credentialStatus(name);
+    const keys = new Set([
+        ...Object.keys(stored),
+        ...(type?.fields.filter((f) => f.kind === "secret").map((f) => f.key) ?? []),
+        ...CREDENTIAL_KEYS.filter((key) => `${key}Env` in values),
+    ]);
+    if (!type && !keys.size)
+        keys.add("apiKey");
+    const out = {};
+    for (const key of keys) {
+        const file = stored[key];
+        const env = values[`${key}Env`];
+        if (file)
+            out[key] = { configured: true, source: "file", ...(file.tail ? { tail: file.tail } : {}) };
+        else if (typeof env === "string" && env && process.env[env])
+            out[key] = { configured: true, source: "env" };
+        else
+            out[key] = { configured: false };
+    }
+    return out;
+}
+/** Non-secret profile values only (a hand-edited file could hold a secret field). */
+function publicValues(values, type) {
+    const secret = new Set([
+        ...CREDENTIAL_KEYS,
+        ...(type?.fields.filter((f) => f.kind === "secret").map((f) => f.key) ?? []),
+    ]);
+    return Object.fromEntries(Object.entries(values).filter(([key]) => !secret.has(key)));
+}
+function validValue(field, value) {
+    switch (field.kind) {
+        case "boolean":
+            return typeof value === "boolean";
+        case "select":
+            return typeof value === "string" && (field.options ?? []).some((o) => o.value === value);
+        case "url": {
+            if (typeof value !== "string" || value.length > 2_000)
+                return false;
+            try {
+                const url = new URL(value);
+                return /^https?:$/.test(url.protocol) && !url.username && !url.password;
+            }
+            catch {
+                return false;
+            }
+        }
+        case "text":
+            return ((typeof value === "string" && value.length <= 2_000) ||
+                (typeof value === "number" && Number.isFinite(value)));
+        default:
+            return false;
+    }
+}
+export function registerProviderRoutes(router, ctx, recycler) {
+    /** Any open app serves the provider types when no workspace is named. */
+    const optionalApp = async (reference) => reference ? workspaceApp(ctx.workspaces, reference) : ctx.workspaces.entries()[0];
+    /** The global profile/credential files (the same ones every workspace app reads). */
+    const store = () => new ProviderSettingsStore();
+    async function profileInfo(name, types) {
+        const settings = await store().load();
+        const profile = settings.profiles[name];
+        if (!profile)
+            return undefined;
+        const type = types.find((t) => t.id === profile.provider);
+        return {
+            name,
+            provider: profile.provider,
+            model: profile.model,
+            values: publicValues(profile.values ?? {}, type),
+            active: settings.active === name,
+            credentials: await credentialStatus(store(), name, profile.values ?? {}, type),
+        };
+    }
+    const profileParam = (value) => {
+        if (!value || !PROFILE_NAME.test(value))
+            throw new HttpError("validation_failed", "Invalid profile name", { fields: ["profile"] });
+        return value;
+    };
+    router.get("/api/providers", async ({ url }) => {
+        const opened = await optionalApp(url.searchParams.get("workspace"));
+        const settings = await store().load();
+        const types = typesOf(opened);
+        const profiles = [];
+        for (const name of Object.keys(settings.profiles).sort()) {
+            const info = await profileInfo(name, types);
+            if (info)
+                profiles.push(info);
+        }
+        const info = opened?.app.providerInfo;
+        const body = {
+            ...(settings.active ? { active: settings.active } : {}),
+            profiles,
+            types,
+            ...(opened && info
+                ? {
+                    current: {
+                        provider: info.id,
+                        model: opened.app.provider.model,
+                        ...(info.profileName ? { profile: info.profileName } : {}),
+                    },
+                }
+                : {}),
+        };
+        return { body };
+    });
+    router.put("/api/providers/:profile", async ({ req, params }) => {
+        const name = profileParam(params.profile);
+        const input = validate(await readJson(req), {
+            workspace: { check: is.nonEmpty(4096), required: true },
+            provider: { check: is.nonEmpty(64), required: true },
+            values: { check: is.object(), required: true },
+            model: { check: is.nonEmpty(300), required: true },
+        });
+        const opened = await workspaceApp(ctx.workspaces, input.workspace);
+        const types = typesOf(opened);
+        const type = types.find((t) => t.id === input.provider);
+        if (!type)
+            throw new HttpError("validation_failed", "Unknown provider type", { fields: ["provider"] });
+        const invalid = [];
+        for (const [key, value] of Object.entries(input.values)) {
+            const field = type.fields.find((f) => f.key === key);
+            // Secrets go through the write-only credentials route, never into providers.json.
+            if (!field || field.kind === "secret" || !validValue(field, value))
+                invalid.push(`values.${key}`);
+        }
+        if (invalid.length)
+            throw new HttpError("validation_failed", "Invalid profile values", { fields: invalid });
+        await store().saveProfile(name, {
+            provider: type.id,
+            values: input.values,
+            model: input.model.trim(),
+        });
+        recycler.announce(opened.id, ["models"]);
+        return { body: await profileInfo(name, types) };
+    });
+    router.put("/api/providers/:profile/credentials", async ({ req, params }) => {
+        const name = profileParam(params.profile);
+        const input = validate(await readJson(req), { apiKey: { check: secretValue }, bearerToken: { check: secretValue } });
+        const secrets = Object.fromEntries(Object.entries(input).filter(([, v]) => typeof v === "string"));
+        if (!Object.keys(secrets).length)
+            throw new HttpError("validation_failed", "Send apiKey or bearerToken", {
+                fields: ["apiKey", "bearerToken"],
+            });
+        if (!(await store().load()).profiles[name])
+            throw new HttpError("not_found", "Provider profile not found");
+        await store().setCredentials(name, secrets);
+        const last = Object.values(secrets).at(-1) ?? "";
+        const tail = maskSecret(last);
+        return { body: { configured: true, ...(tail ? { tail } : {}) } };
+    });
+    router.delete("/api/providers/:profile/credentials", async ({ params }) => {
+        const name = profileParam(params.profile);
+        if (!(await store().deleteCredentials(name)))
+            throw new HttpError("not_found", "No stored credentials for this profile");
+        return { body: { configured: false } };
+    });
+    router.post("/api/providers/:profile/activate", async ({ req, params }) => {
+        const name = profileParam(params.profile);
+        const input = validate(await readJson(req), {
+            workspace: { check: is.nonEmpty(4096), required: true },
+            model: { check: is.nonEmpty(300), required: true },
+        });
+        const opened = await workspaceApp(ctx.workspaces, input.workspace);
+        // P-01: the provider belongs to the workspace app; switching it under a run is refused.
+        if (ctx.scheduler.busyWorkspace(opened.id))
+            throw new HttpError("runs_active", "Runs are active in this workspace; switch the provider when they finish");
+        if (!(await store().load()).profiles[name])
+            throw new HttpError("not_found", "Provider profile not found");
+        let changed;
+        try {
+            changed = await opened.app.activateProviderProfile(name, input.model.trim());
+        }
+        catch (error) {
+            throw new HttpError("provider_unavailable", error instanceof Error ? error.message : "The provider could not be activated");
+        }
+        recycler.announce(opened.id, ["models"]);
+        return { body: { changed } };
+    });
+    router.get("/api/models", async ({ url }) => {
+        const opened = await workspaceApp(ctx.workspaces, url.searchParams.get("workspace"));
+        let catalogs;
+        try {
+            catalogs = await opened.app.configuredProviderCatalogs(AbortSignal.timeout(15_000));
+        }
+        catch {
+            throw new HttpError("provider_unavailable", "Configured providers could not be listed");
+        }
+        return {
+            body: catalogs.map((c) => ({
+                profile: c.profile,
+                provider: c.provider,
+                title: c.title,
+                configuredModel: c.configuredModel,
+                models: c.models,
+                unavailable: c.unavailable,
+            })),
+        };
+    });
+}

package/dist/routes/session-views.d.ts

@@ -0,0 +1,12 @@
+import type { SQLiteStore } from "@alisio/core";
+import type { SessionService } from "../host/sessions.ts";
+import type { Router } from "../http/router.ts";
+/**
+ * Per-session views the web composer and header need: the model catalog of the session's
+ * provider (model + effort selector, RF-09), the context estimate (context ring) and the
+ * session log download (RF-10).
+ */
+export declare function registerSessionViewRoutes(router: Router, ctx: {
+    catalog: SQLiteStore;
+    sessions: SessionService;
+}): void;

package/dist/routes/session-views.js

@@ -0,0 +1,76 @@
+import { storedToRunEvent } from "./sessions.js";
+/**
+ * Per-session views the web composer and header need: the model catalog of the session's
+ * provider (model + effort selector, RF-09), the context estimate (context ring) and the
+ * session log download (RF-10).
+ */
+export function registerSessionViewRoutes(router, ctx) {
+    const { catalog, sessions } = ctx;
+    router.get("/api/sessions/:sid/models", async ({ params }) => {
+        const session = sessions.get(params.sid ?? "");
+        const { app } = await sessions.app(session);
+        let models = [];
+        let unavailable = false;
+        try {
+            models = await app.loadModels(AbortSignal.timeout(10_000));
+        }
+        catch {
+            unavailable = true;
+        }
+        const effort = session.options?.effort;
+        return {
+            body: {
+                provider: session.provider,
+                model: session.model,
+                ...(typeof effort === "string" ? { effort } : {}),
+                models,
+                unavailable,
+            },
+        };
+    });
+    router.get("/api/sessions/:sid/context", async ({ params }) => {
+        const session = sessions.get(params.sid ?? "");
+        const { app } = await sessions.app(session);
+        const estimated = await app.runner.estimateContext(session.id);
+        const budget = app.contextBudget(session.model);
+        return {
+            body: {
+                estimated,
+                ...(budget.total !== undefined ? { total: budget.total } : {}),
+                basis: budget.basis,
+                compactionAt: budget.compactionAt,
+            },
+        };
+    });
+    // Session log: one `RunEvent` line per durable event (events.seq order, `alisio run --json`
+    // format with the global `eventId`), then one `{"type":"message"}` line per stored message.
+    router.get("/api/sessions/:sid/export", ({ params, res }) => {
+        const session = sessions.get(params.sid ?? "");
+        res.writeHead(200, {
+            "Content-Type": "application/x-ndjson; charset=utf-8",
+            "Content-Disposition": `attachment; filename="alisio-${session.id}.jsonl"`,
+        });
+        let after = 0;
+        for (;;) {
+            const page = catalog.eventsPage(session.id, { after, limit: 5000 });
+            for (const event of page.items)
+                res.write(`${JSON.stringify(storedToRunEvent(session.id, event))}\n`);
+            const last = page.items.at(-1);
+            if (!page.hasMore || !last)
+                break;
+            after = Number(last.eventId);
+        }
+        let seq = -1;
+        for (;;) {
+            const page = catalog.messagesPage(session.id, { after: seq, limit: 1000, compacted: true });
+            for (const item of page.items)
+                res.write(`${JSON.stringify({ type: "message", ...item })}\n`);
+            const last = page.items.at(-1);
+            if (!page.hasMore || !last)
+                break;
+            seq = last.seq;
+        }
+        res.end();
+        return undefined;
+    });
+}

package/dist/routes/sessions.d.ts

@@ -0,0 +1,16 @@
+import type { SQLiteStore, StoredEvent } from "@alisio/core";
+import type { RunEvent } from "@alisio/sdk";
+import type { RunScheduler } from "../host/run-scheduler.ts";
+import type { SessionService } from "../host/sessions.ts";
+import type { WorkspaceHost } from "../host/workspace-host.ts";
+import type { Router } from "../http/router.ts";
+export interface SessionRouteContext {
+    catalog: SQLiteStore;
+    workspaces: WorkspaceHost;
+    sessions: SessionService;
+    scheduler: RunScheduler;
+}
+/** A stored durable event as a `RunEvent` (in pages, `seq` is the global `events.seq`). */
+export declare function storedToRunEvent(sessionId: string, event: StoredEvent): RunEvent;
+/** Sessions: list/create/read/patch (no delete: archive instead), messages, events, runs. */
+export declare function registerSessionRoutes(router: Router, ctx: SessionRouteContext): void;

package/dist/routes/sessions.js

@@ -0,0 +1,160 @@
+import { isAbsolute } from "node:path";
+import { PRESET_IDS, presetInfo } from "../host/presets.js";
+import { readJson } from "../http/body.js";
+import { HttpError } from "../http/errors.js";
+import { is, queryInt, validate } from "../schemas.js";
+/** A stored durable event as a `RunEvent` (in pages, `seq` is the global `events.seq`). */
+export function storedToRunEvent(sessionId, event) {
+    return {
+        schemaVersion: 1,
+        runId: event.runId,
+        sessionId,
+        seq: Number(event.eventId),
+        type: event.type,
+        timestamp: new Date(event.createdAt ?? 0).toISOString(),
+        data: event.data,
+        eventId: event.eventId,
+        ...(event.correlationId ? { correlationId: event.correlationId } : {}),
+    };
+}
+/** Sessions: list/create/read/patch (no delete: archive instead), messages, events, runs. */
+export function registerSessionRoutes(router, ctx) {
+    const { catalog, sessions } = ctx;
+    router.get("/api/sessions", ({ url }) => {
+        const workspace = url.searchParams.get("workspace");
+        const q = url.searchParams.get("q")?.trim().toLowerCase();
+        const archived = url.searchParams.get("archived") ?? "false";
+        if (!["true", "false", "all"].includes(archived))
+            throw new HttpError("validation_failed", "Invalid query parameter", {
+                fields: ["archived"],
+            });
+        const limit = queryInt(url, "limit", 50, 200) ?? 50;
+        const offset = queryInt(url, "cursor", 0) ?? 0;
+        const rows = catalog
+            .list()
+            .map((session) => sessions.summary(session))
+            .filter((s) => (!workspace || s.workspaceId === workspace) &&
+            (!q || (s.title ?? "").toLowerCase().includes(q) || s.id.startsWith(q)) &&
+            (archived === "all" || s.archived === (archived === "true")))
+            .sort(bySidebarOrder);
+        const items = rows.slice(offset, offset + limit);
+        return {
+            body: {
+                items,
+                ...(offset + limit < rows.length ? { next: String(offset + limit) } : {}),
+            },
+        };
+    });
+    router.post("/api/sessions", async ({ req }) => {
+        const input = validate(await readJson(req), {
+            workspace: { check: is.nonEmpty(4096), required: true },
+            model: { check: is.nonEmpty(300) },
+            agent: { check: is.nonEmpty(200) },
+            preset: { check: is.oneOf(PRESET_IDS) },
+            title: { check: is.string(200) },
+        });
+        if (input.preset && !presetInfo(input.preset, sessions.ceiling).available)
+            throw new HttpError("capability_ceiling", "Preset not available under the server flags");
+        const path = isAbsolute(input.workspace)
+            ? await ctx.workspaces.canonical(input.workspace)
+            : await ctx.workspaces.pathOf(input.workspace);
+        if (!path)
+            throw new HttpError("not_found", "Workspace not found");
+        const opened = await ctx.workspaces.openPath(path);
+        let created;
+        try {
+            created = await opened.app.createSession(input.model);
+        }
+        catch (error) {
+            throw new HttpError("validation_failed", error instanceof Error ? error.message : "Model is not available", { fields: ["model"] });
+        }
+        catalog.updateSessionMeta(created.id, {
+            ...(input.title?.trim() ? { title: input.title.trim() } : {}),
+            options: {
+                ...(input.preset ? { preset: input.preset } : {}),
+                ...(input.agent ? { agent: input.agent } : {}),
+            },
+        });
+        sessions.notify(created.id);
+        return { status: 201, body: sessions.detail(sessions.get(created.id)) };
+    });
+    router.get("/api/sessions/:sid", ({ params }) => ({
+        body: sessions.detail(sessions.get(params.sid ?? "")),
+    }));
+    router.patch("/api/sessions/:sid", async ({ req, params }) => {
+        const session = sessions.get(params.sid ?? "");
+        const patch = validate(await readJson(req), {
+            title: { check: is.nullableString(200) },
+            model: { check: is.nonEmpty(300) },
+            effort: { check: is.nullableString(50) },
+            preset: { check: is.oneOf(PRESET_IDS) },
+            agent: { check: is.nullableString(200) },
+            pinned: { check: is.boolean() },
+            archived: { check: is.boolean() },
+        });
+        if (patch.preset && !presetInfo(patch.preset, sessions.ceiling).available)
+            throw new HttpError("capability_ceiling", "Preset not available under the server flags");
+        if (patch.model !== undefined && patch.model !== session.model) {
+            if (ctx.scheduler.busy(session.id))
+                throw new HttpError("session_busy", "Cannot change the model while a run is active");
+            const { app } = await sessions.app(session);
+            app.runner.setModel(session.id, patch.model);
+        }
+        const options = {};
+        if (patch.effort !== undefined)
+            options.effort = patch.effort ?? undefined;
+        if (patch.agent !== undefined)
+            options.agent = patch.agent ?? undefined;
+        if (patch.preset !== undefined)
+            options.preset = patch.preset;
+        catalog.updateSessionMeta(session.id, {
+            ...(patch.title !== undefined ? { title: patch.title?.trim() || null } : {}),
+            ...(patch.pinned !== undefined ? { pinned: patch.pinned } : {}),
+            ...(patch.archived !== undefined ? { archived: patch.archived } : {}),
+            ...(Object.keys(options).length ? { options } : {}),
+        });
+        if (patch.preset !== undefined)
+            sessions.resetPolicy(session.id);
+        sessions.notify(session.id);
+        return { body: sessions.detail(sessions.get(session.id)) };
+    });
+    router.get("/api/sessions/:sid/messages", ({ params, url }) => {
+        const session = sessions.get(params.sid ?? "");
+        const before = queryInt(url, "before", undefined);
+        const after = queryInt(url, "after", undefined);
+        const page = catalog.messagesPage(session.id, {
+            ...(before !== undefined ? { before } : {}),
+            ...(after !== undefined ? { after } : {}),
+            limit: queryInt(url, "limit", 50, 1000) ?? 50,
+            compacted: url.searchParams.get("includeCompacted") === "true",
+        });
+        return { body: page };
+    });
+    router.get("/api/sessions/:sid/events", ({ params, url }) => {
+        const session = sessions.get(params.sid ?? "");
+        const types = url.searchParams.get("types")?.split(",").filter(Boolean);
+        const page = catalog.eventsPage(session.id, {
+            after: queryInt(url, "after", 0) ?? 0,
+            limit: queryInt(url, "limit", 200, 5000) ?? 200,
+        });
+        const last = page.items.at(-1);
+        return {
+            body: {
+                items: page.items
+                    .filter((event) => !types?.length || types.includes(event.type))
+                    .map((event) => storedToRunEvent(session.id, event)),
+                ...(page.hasMore && last ? { next: last.eventId } : {}),
+            },
+        };
+    });
+    router.get("/api/sessions/:sid/runs", ({ params, url }) => {
+        const session = sessions.get(params.sid ?? "");
+        return { body: catalog.runs(session.id, { limit: queryInt(url, "limit", 20, 500) ?? 20 }) };
+    });
+}
+/** Pinned first, then most recently updated; sessions without `updatedAt` last. */
+function bySidebarOrder(a, b) {
+    if (a.pinned !== b.pinned)
+        return a.pinned ? -1 : 1;
+    return (b.updatedAt ?? -1) - (a.updatedAt ?? -1);
+}

package/dist/routes/workspaces.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceHost } from "../host/workspace-host.ts";
+import type { Router } from "../http/router.ts";
+/** `GET/POST /api/workspaces`, `PATCH /api/workspaces/:wid`. */
+export declare function registerWorkspaceRoutes(router: Router, ctx: {
+    workspaces: WorkspaceHost;
+    catalog: import("@alisio/core").SQLiteStore;
+}): void;

package/dist/routes/workspaces.js

@@ -0,0 +1,32 @@
+import { isAbsolute } from "node:path";
+import { readJson } from "../http/body.js";
+import { HttpError } from "../http/errors.js";
+import { is, validate } from "../schemas.js";
+/** `GET/POST /api/workspaces`, `PATCH /api/workspaces/:wid`. */
+export function registerWorkspaceRoutes(router, ctx) {
+    router.get("/api/workspaces", async () => ({ body: await ctx.workspaces.list() }));
+    router.post("/api/workspaces", async ({ req }) => {
+        const { path } = validate(await readJson(req), {
+            path: { check: is.nonEmpty(4096), required: true },
+        });
+        if (!isAbsolute(path))
+            throw new HttpError("validation_failed", "path must be absolute", { fields: ["path"] });
+        const canonical = await ctx.workspaces.canonical(path);
+        const opened = await ctx.workspaces.openPath(canonical);
+        return { body: await ctx.workspaces.info(opened.path) };
+    });
+    router.patch("/api/workspaces/:wid", async ({ req, params }) => {
+        const patch = validate(await readJson(req), {
+            label: { check: is.nullableString(200) },
+            pinned: { check: is.boolean() },
+        });
+        const path = await ctx.workspaces.pathOf(params.wid ?? "");
+        if (!path)
+            throw new HttpError("not_found", "Workspace not found");
+        ctx.catalog.recordWorkspace(path, {
+            ...(patch.label !== undefined ? { label: patch.label?.trim() || null } : {}),
+            ...(patch.pinned !== undefined ? { pinned: patch.pinned } : {}),
+        });
+        return { body: await ctx.workspaces.info(path) };
+    });
+}

package/dist/schemas.d.ts

@@ -0,0 +1,25 @@
+type Check = (value: unknown) => boolean;
+export interface FieldSpec {
+    check: Check;
+    required?: boolean;
+}
+export declare const is: {
+    string: (max?: number) => Check;
+    nonEmpty: (max?: number) => Check;
+    boolean: () => Check;
+    nullableString: (max?: number) => Check;
+    oneOf: (values: readonly string[]) => Check;
+    requestId: () => Check;
+    integer: (min: number, max: number) => Check;
+    array: (item: Check, max?: number) => Check;
+    object: () => Check;
+    any: () => Check;
+};
+/**
+ * Validates a JSON object against `fields`: unknown keys and wrong types are rejected. Returns
+ * the object typed as `T` (the caller's shape must match `fields`).
+ */
+export declare function validate<T>(body: unknown, fields: Record<string, FieldSpec>): T;
+/** An optional positive integer query parameter, clamped to `max`. */
+export declare function queryInt(url: URL, name: string, fallback: number | undefined, max?: number): number | undefined;
+export {};

package/dist/schemas.js

@@ -0,0 +1,54 @@
+/**
+ * Request validation without a schema library (the server adds no runtime dependencies).
+ * Failures are 400 `validation_failed` with the offending field paths, never their values.
+ */
+import { HttpError } from "./http/errors.js";
+export const is = {
+    string: (max = 100_000) => (v) => typeof v === "string" && v.length <= max,
+    nonEmpty: (max = 100_000) => (v) => typeof v === "string" && v.trim().length > 0 && v.length <= max,
+    boolean: () => (v) => typeof v === "boolean",
+    nullableString: (max = 1_000) => (v) => v === null || (typeof v === "string" && v.length <= max),
+    oneOf: (values) => (v) => typeof v === "string" && values.includes(v),
+    requestId: () => (v) => typeof v === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(v),
+    integer: (min, max) => (v) => typeof v === "number" && Number.isInteger(v) && v >= min && v <= max,
+    array: (item, max = 100) => (v) => Array.isArray(v) && v.length <= max && v.every(item),
+    object: () => (v) => !!v && typeof v === "object" && !Array.isArray(v),
+    any: () => () => true,
+};
+/**
+ * Validates a JSON object against `fields`: unknown keys and wrong types are rejected. Returns
+ * the object typed as `T` (the caller's shape must match `fields`).
+ */
+export function validate(body, fields) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        throw new HttpError("validation_failed", "Request body must be a JSON object", {
+            fields: ["(body)"],
+        });
+    const record = body;
+    const invalid = [];
+    for (const key of Object.keys(record))
+        if (!(key in fields))
+            invalid.push(key);
+    for (const [key, spec] of Object.entries(fields)) {
+        const value = record[key];
+        if (value === undefined) {
+            if (spec.required)
+                invalid.push(key);
+        }
+        else if (!spec.check(value))
+            invalid.push(key);
+    }
+    if (invalid.length)
+        throw new HttpError("validation_failed", "Invalid request fields", { fields: invalid });
+    return record;
+}
+/** An optional positive integer query parameter, clamped to `max`. */
+export function queryInt(url, name, fallback, max = Number.MAX_SAFE_INTEGER) {
+    const raw = url.searchParams.get(name);
+    if (raw === null || raw === "")
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0)
+        throw new HttpError("validation_failed", "Invalid query parameter", { fields: [name] });
+    return Math.min(value, max);
+}