A local-first multi-agent app development platform, built on PenguinHarness
/**
* Hand-rolled request body validation helpers (fields follow TypeScript types;
* this adds a runtime safety net).
*
* No validation library: each helper checks one basic shape, throwing a 400 HttpError on failure.
*/
import fs from "node:fs/promises";
import path from "node:path";
import type { Context } from "hono";
import { isValidId } from "@adelie/core";
import type {
ActivityCursor,
SessionListOrder,
SessionListPaging,
} from "../services/session-service.js";
import { HttpError } from "./errors.js";
export function badRequest(message: string): HttpError {
return new HttpError(400, "bad_request", message);
}
/**
* Get a path parameter (under sub-route mounting, hono infers string | undefined; the
* route guarantees presence at runtime — treat a defensive missing value as 404).
*/
export function pathParam(c: Context, name: string): string {
const v = c.req.param(name);
if (v === undefined || v === "") {
throw new HttpError(404, "not_found", "Missing path parameter.");
}
return v;
}
/**
* Get a path parameter and validate the id (alphanumeric, underscore, and hyphen
* only, to prevent path traversal). Hono decodes URL-encoded `%2F` into a single path
* parameter; an id containing `/` or `..` passed straight into path construction could
* escape the resource directory (cross-Project privilege escalation). So validate right
* after reading the value — any invalid id is rejected with 404 (not leaking resource
* existence), before any service-layer or path-construction code runs.
*/
export function requireValidId(c: Context, name: string): string {
const v = pathParam(c, name);
if (!isValidId(v)) {
throw new HttpError(404, "not_found", "Resource does not exist or you do not have access.");
}
return v;
}
/**
* Parse a decimal non-negative integer, or null when the text is not exactly one.
*
* Digits only: Number.parseInt accepts trailing garbage ("12abc" -> 12, "1e3" -> 1), so a
* caller that only range-checks the result silently honours a request it never validated.
* isSafeInteger (not isInteger) additionally rejects overlong runs like
* "99999999999999999999", which parse to an imprecise float (1e20).
*/
export function parseNonNegativeInt(raw: string): number | null {
if (!/^\d+$/.test(raw)) return null;
const v = Number.parseInt(raw, 10);
return Number.isSafeInteger(v) ? v : null;
}
/** Parse a positive-integer path parameter (e.g. Trace file index). */
export function positiveIntParam(c: Context, name: string): number {
const v = parseNonNegativeInt(pathParam(c, name));
if (v === null || v < 1) throw badRequest(`${name} must be a positive integer.`);
return v;
}
/** Parse an already-defaulted offset query param (>= 0). */
function offsetQuery(raw: string): number {
const v = parseNonNegativeInt(raw);
if (v === null) throw badRequest("offset must be a non-negative integer.");
return v;
}
/** Parse an already-defaulted limit query param (1-1000). */
function limitQuery(raw: string): number {
const v = parseNonNegativeInt(raw);
if (v === null || v < 1 || v > 1000) {
throw badRequest("limit must be an integer between 1 and 1000.");
}
return v;
}
/** Parse Trace pagination query params: offset >= 0 (default 0), limit 1-1000 (default 200). */
export function paginationQuery(c: Context): { offset: number; limit: number } {
return {
offset: offsetQuery(c.req.query("offset") ?? "0"),
limit: limitQuery(c.req.query("limit") ?? "200"),
};
}
/**
* Parse OPTIONAL list paging query params: both absent = null (caller returns the full
* list — the pre-paging behavior stays intact for existing callers). When paging, `limit`
* is required (1-1000) and `offset` optional (>= 0, default 0) — an offset alone would
* silently return the full list shifted, which no caller ever means.
*/
export function optionalPagingQuery(c: Context): { offset: number; limit: number } | null {
const rawLimit = c.req.query("limit");
const rawOffset = c.req.query("offset");
if (rawLimit === undefined && rawOffset === undefined) return null;
if (rawLimit === undefined) throw badRequest("offset requires limit.");
const limit = limitQuery(rawLimit);
const offset = offsetQuery(rawOffset ?? "0");
return { offset, limit };
}
/**
* Parse an activity cursor, `<lastActiveAt>,<sessionId>`, or null when the text is not one.
* Split at the FIRST comma — an ISO stamp holds none and a valid id holds none, so the split is
* unambiguous; the stamp must parse as a date and the id must be a valid id. The stamp is kept
* as sent: the list compares it as a string against the rows' own stamps, which is where the
* client read it from.
*/
function parseActivityCursor(raw: string): ActivityCursor | null {
const comma = raw.indexOf(",");
if (comma === -1) return null;
const lastActiveAt = raw.slice(0, comma);
const sessionId = raw.slice(comma + 1);
if (Number.isNaN(Date.parse(lastActiveAt)) || !isValidId(sessionId)) return null;
return { lastActiveAt, sessionId };
}
/**
* The Session list's OPTIONAL paging: {@link optionalPagingQuery}'s offset form, or — under
* `order=activity` — the cursor form `before=<lastActiveAt>,<sessionId>&limit=N`, which serves
* the rows strictly below the cursor. A cursor in another order, beside an offset or without a
* limit is a 400, never a silently different page.
*/
export function optionalSessionListPagingQuery(
c: Context,
order: SessionListOrder,
): SessionListPaging | null {
const rawBefore = c.req.query("before");
if (rawBefore === undefined) return optionalPagingQuery(c);
if (order !== "activity") throw badRequest("before requires order=activity.");
if (c.req.query("offset") !== undefined) throw badRequest("before and offset are exclusive.");
const rawLimit = c.req.query("limit");
if (rawLimit === undefined) throw badRequest("before requires limit.");
const before = parseActivityCursor(rawBefore);
if (!before) throw badRequest("before must be <lastActiveAt>,<sessionId>.");
return { before, limit: limitQuery(rawLimit) };
}
/** Read the JSON request body (parse failure / non-object -> 400). */
export async function readJson(c: Context): Promise<Record<string, unknown>> {
let body: unknown;
try {
body = await c.req.json();
} catch {
throw badRequest("Request body must be valid JSON.");
}
if (body === null || typeof body !== "object" || Array.isArray(body)) {
throw badRequest("Request body must be a JSON object.");
}
return body as Record<string, unknown>;
}
export interface StringRule {
minLen?: number;
maxLen?: number;
pattern?: RegExp;
/** Display name for the field in error messages (defaults to key). */
label?: string;
}
export function requireString(
obj: Record<string, unknown>,
key: string,
rule: StringRule = {},
): string {
const v = obj[key];
const label = rule.label ?? key;
if (typeof v !== "string") throw badRequest(`${label} must be a string.`);
if (rule.minLen !== undefined && v.length < rule.minLen) {
throw badRequest(`${label} must be at least ${rule.minLen} characters.`);
}
if (rule.maxLen !== undefined && v.length > rule.maxLen) {
throw badRequest(`${label} must be at most ${rule.maxLen} characters.`);
}
if (rule.pattern !== undefined && !rule.pattern.test(v)) {
throw badRequest(`${label} has an invalid format.`);
}
return v;
}
export function optionalString(
obj: Record<string, unknown>,
key: string,
rule: StringRule = {},
): string | undefined {
if (obj[key] === undefined) return undefined;
return requireString(obj, key, rule);
}
/**
* Optional array-of-strings body field: absent (or null) yields undefined, anything that is not
* an array of non-empty strings is a 400. The per-item message carries the index, so a caller
* sending one bad entry in a long list is told which one.
*/
export function optionalStringArray(
obj: Record<string, unknown>,
key: string,
label = key,
): string[] | undefined {
const v = obj[key];
if (v === undefined || v === null) return undefined;
if (!Array.isArray(v)) throw badRequest(`${label} must be an array of strings.`);
return v.map((item, i) => {
if (typeof item !== "string" || item.length === 0) {
throw badRequest(`${label}[${i}] must be a non-empty string.`);
}
return item;
});
}
/**
* Admits a client-supplied filesystem path for a Project-scoped route and returns its realpath:
* absolute, existing, and a directory. Shared by every route that takes a path from the client —
* the `dirs` browser, Skill discovery, and Agent creation's `skillsDirectory` — so the three
* cannot drift on what a valid path is or on which error code says so. The caller must already
* have checked Project access.
*/
export async function requireProjectDir(raw: string | undefined): Promise<string> {
const target = raw?.trim();
if (!target || !path.isAbsolute(target)) {
throw new HttpError(400, "dir_not_absolute", "Directory must be an absolute path.");
}
let real: string;
try {
real = await fs.realpath(target);
} catch {
throw new HttpError(
404,
"dir_not_found",
`Directory does not exist or is inaccessible: ${target}.`,
);
}
// stat can still fail if the directory goes away between realpath and here; that is the same
// "not there" the caller is being told about, not a server fault.
const isDir = await fs.stat(real).then(
(s) => s.isDirectory(),
() => {
throw new HttpError(
404,
"dir_not_found",
`Directory does not exist or is inaccessible: ${target}.`,
);
},
);
if (!isDir) throw new HttpError(400, "not_a_dir", "Not a directory.");
return real;
}
export function requireEnum<T extends string>(
obj: Record<string, unknown>,
key: string,
values: readonly T[],
label = key,
): T {
const v = obj[key];
if (typeof v !== "string" || !(values as readonly string[]).includes(v)) {
throw badRequest(`${label} must be one of ${values.join(" / ")}.`);
}
return v as T;
}
export function optionalEnum<T extends string>(
obj: Record<string, unknown>,
key: string,
values: readonly T[],
label = key,
): T | undefined {
if (obj[key] === undefined) return undefined;
return requireEnum(obj, key, values, label);
}
export interface NumberRule {
/** Require positive or -1 (Agent runtime parameter convention: >0 active, -1 disabled). */
positiveOrMinusOne?: boolean;
/** Require non-negative. */
nonNegative?: boolean;
/** Require integer. */
integer?: boolean;
label?: string;
}
export function optionalNumber(
obj: Record<string, unknown>,
key: string,
rule: NumberRule = {},
): number | undefined {
const v = obj[key];
if (v === undefined) return undefined;
const label = rule.label ?? key;
if (typeof v !== "number" || !Number.isFinite(v)) throw badRequest(`${label} must be a number.`);
if (rule.integer && !Number.isInteger(v)) throw badRequest(`${label} must be an integer.`);
if (rule.positiveOrMinusOne && !(v > 0 || v === -1)) {
throw badRequest(`${label} must be greater than 0 or equal to -1.`);
}
if (rule.nonNegative && v < 0) throw badRequest(`${label} must not be negative.`);
return v;
}
export function optionalBoolean(
obj: Record<string, unknown>,
key: string,
label = key,
): boolean | undefined {
const v = obj[key];
if (v === undefined) return undefined;
if (typeof v !== "boolean") throw badRequest(`${label} must be a boolean.`);
return v;
}
/** Validate a yyyy-mm-dd query parameter (defaults to undefined). */
export function optionalDateParam(value: string | undefined, label: string): string | undefined {
if (value === undefined || value === "") return undefined;
const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
// The shape check alone accepts impossible dates (2026-13-40, 2026-02-30); verify it's a real
// calendar day by round-tripping through UTC (which never rolls over into an adjacent month).
if (m) {
const [, y, mo, d] = m;
const dt = new Date(`${value}T00:00:00Z`);
if (
!Number.isNaN(dt.getTime()) &&
dt.getUTCFullYear() === Number(y) &&
dt.getUTCMonth() + 1 === Number(mo) &&
dt.getUTCDate() === Number(d)
) {
return value;
}
}
throw badRequest(`${label} must be a valid date in YYYY-MM-DD format.`);
}