hippo-memory 1.59.0 → 1.61.0

package/dist/server/routes/skills.js

@@ -0,0 +1,150 @@
+// /v1/skills routes.
+import { closeSkill, exportSkills, loadSkillById, loadSkills, saveSkill, VALID_SKILL_STATES } from '../../skills.js';
+import { HttpError, sendJson } from '../../http-util.js';
+import { buildContextWithAuth } from '../auth.js';
+import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
+import { isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+// ── skills (E2 first-class object, executable/exportable) ──
+//
+// 6 routes: POST /v1/skills (new; body skillName + instructions + trigger?),
+// GET /v1/skills (list, status filter; shared parseListLimit), GET
+// /v1/skills/export (renders ACTIVE skills as an AGENTS.md/CLAUDE.md markdown
+// block -> {markdown}; literal 'export' is non-numeric so the /:id (\d+) route
+// cannot capture it, but it is ordered first regardless), GET /v1/skills/:id,
+// POST /v1/skills/:id/supersede, POST /v1/skills/:id/close. DoS caps:
+// skillName 256, instructions 8192, trigger 1024, changeSummary 4096. The store
+// validates + throws; the boundary maps validation -> 400, not-found -> 404,
+// not-active -> 409. Mirrors /v1/processes; "executable" = exportable
+// instruction (no code exec).
+export async function handleCreateSkill({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const skillName = body['skillName'];
+    if (!isJsonString(skillName) || skillName.trim().length === 0) {
+        throw new HttpError(400, 'skillName is required (non-empty string)');
+    }
+    if (skillName.length > 256) {
+        throw new HttpError(400, 'skillName exceeds 256-character cap');
+    }
+    const instructions = body['instructions'];
+    if (!isJsonString(instructions) || instructions.trim().length === 0) {
+        throw new HttpError(400, 'instructions are required (non-empty string)');
+    }
+    if (instructions.length > 8192) {
+        throw new HttpError(400, 'instructions exceed 8192-character cap');
+    }
+    const triggerRaw = body['trigger'];
+    let trigger;
+    if (triggerRaw !== undefined && triggerRaw !== null) {
+        if (!isJsonString(triggerRaw)) {
+            throw new HttpError(400, 'trigger must be a string');
+        }
+        if (triggerRaw.length > 1024) {
+            throw new HttpError(400, 'trigger exceeds 1024-character cap');
+        }
+        trigger = triggerRaw;
+    }
+    const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
+        skillName,
+        instructions,
+        trigger,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { skill });
+    return;
+}
+export async function handleListSkills({ req, res, opts, query }) {
+    const status = query.get('status') ?? 'all';
+    const limit = parseListLimit(query.get('limit'));
+    const after = parseCursor(query.get('cursor'), 'string', 'integer');
+    const ctx = await buildContextWithAuth(req, opts);
+    let skills;
+    if (status === 'all') {
+        skills = loadSkills(opts.hippoRoot, ctx.tenantId, { limit: limit + 1, after });
+    }
+    else {
+        if (!isSetMember(VALID_SKILL_STATES, status)) {
+            throw new HttpError(400, `status must be one of: active | superseded | closed | all (got "${status}")`);
+        }
+        skills = loadSkills(opts.hippoRoot, ctx.tenantId, {
+            status,
+            limit: limit + 1,
+            after,
+        });
+    }
+    const page = pageOf(skills, limit, byCreatedAt);
+    sendJson(res, 200, { skills: page.items, next_cursor: page.nextCursor });
+    return;
+}
+// The export renderer: must precede the /:id GET (literal 'export' is
+// non-numeric so the /(\d+)/ route would not match it, but order it first).
+export async function handleExportSkills({ req, res, opts }) {
+    const ctx = await buildContextWithAuth(req, opts);
+    const markdown = exportSkills(opts.hippoRoot, ctx.tenantId);
+    sendJson(res, 200, { markdown });
+    return;
+}
+export async function handleSupersedeSkill({ req, res, opts }, skillSupersedeMatch) {
+    const id = parseInt(skillSupersedeMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const body = await parseJsonBody(req, ctx);
+    const instructions = body['instructions'];
+    if (!isJsonString(instructions) || instructions.trim().length === 0) {
+        throw new HttpError(400, 'instructions are required (non-empty string)');
+    }
+    if (instructions.length > 8192) {
+        throw new HttpError(400, 'instructions exceed 8192-character cap');
+    }
+    const triggerRaw = body['trigger'];
+    let trigger;
+    if (triggerRaw !== undefined && triggerRaw !== null) {
+        if (!isJsonString(triggerRaw)) {
+            throw new HttpError(400, 'trigger must be a string');
+        }
+        if (triggerRaw.length > 1024) {
+            throw new HttpError(400, 'trigger exceeds 1024-character cap');
+        }
+        trigger = triggerRaw;
+    }
+    const changeRaw = body['changeSummary'];
+    let changeSummary;
+    if (changeRaw !== undefined && changeRaw !== null) {
+        if (!isJsonString(changeRaw)) {
+            throw new HttpError(400, 'changeSummary must be a string');
+        }
+        if (changeRaw.length > 4096) {
+            throw new HttpError(400, 'changeSummary exceeds 4096-character cap');
+        }
+        changeSummary = changeRaw;
+    }
+    const existing = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
+    if (!existing) {
+        throw new HttpError(404, `skill ${id} not found`);
+    }
+    const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
+        skillName: existing.skillName,
+        instructions,
+        trigger,
+        changeSummary,
+        supersedesSkillId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { skill });
+    return;
+}
+export async function handleCloseSkill({ req, res, opts }, skillCloseMatch) {
+    const id = parseInt(skillCloseMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const skill = closeSkill(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { skill });
+    return;
+}
+export async function handleGetSkill({ req, res, opts }, skillByIdMatch) {
+    const id = parseInt(skillByIdMatch[1], 10);
+    const ctx = await buildContextWithAuth(req, opts);
+    const skill = loadSkillById(opts.hippoRoot, ctx.tenantId, id);
+    if (!skill) {
+        throw new HttpError(404, `skill ${id} not found`);
+    }
+    sendJson(res, 200, { skill });
+    return;
+}
+//# sourceMappingURL=skills.js.map

package/dist/server/types.d.ts

@@ -0,0 +1,56 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface ServerHandle {
+    port: number;
+    url: string;
+    stop: () => Promise<void>;
+    /** Introspection-only (v1.26.2): the underlying node:http Server, exposed so
+     *  tests can assert keep-alive/headers timeout hardening without reaching
+     *  into serve()'s closure. Additive field — do not depend on it for control
+     *  flow outside tests. */
+    server?: import('node:http').Server;
+}
+/** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
+export interface ResolvedBearer {
+    tenantId: string;
+    subject: string;
+    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys); an add-on revokes them through the exported authRevoke when the IdP deprovisions the minter. */
+    role: 'admin' | 'member';
+    scopes?: readonly string[];
+}
+/** Sole judge of non-`hk_` bearer tokens: null is a 401; a throw or missed deadline is a 503, so throw only when upstream is down. */
+export type AuthResolver = (token: string) => ResolvedBearer | null | Promise<ResolvedBearer | null>;
+export interface ServeOpts {
+    hippoRoot: string;
+    /** Runs on every request and SSE heartbeat, so keep it cache-backed; API keys never reach it. */
+    authResolver?: AuthResolver;
+    /** Deadline for one authResolver call; defaults to 5000 ms. */
+    authResolverTimeoutMs?: number;
+    port?: number;
+    host?: string;
+    /** Stop and exit on SIGINT/SIGTERM. Only `hippo serve` owns the process, so only it sets this. */
+    handleSignals?: boolean;
+    /** How long stop() lets in-flight requests finish before closing their sockets; defaults to 5000 ms. */
+    shutdownDrainMs?: number;
+}
+/** Per-request values the /v1 route handlers read. */
+export interface RouteRequest {
+    req: IncomingMessage;
+    res: ServerResponse;
+    opts: ServeOpts;
+    query: URLSearchParams;
+}
+/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with the handler for one method. */
+export type Route = {
+    method: string;
+    path: string;
+    handler: (r: RouteRequest) => Promise<void>;
+} | {
+    method: string;
+    pattern: string;
+    handler: (r: RouteRequest, params: Record<string, string>) => Promise<void>;
+} | {
+    method: string;
+    regex: RegExp;
+    handler: (r: RouteRequest, match: RegExpMatchArray) => Promise<void>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/server/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/server/validation.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage } from 'node:http';
+import type { Context } from '../api.js';
+import { type JsonValue } from '../http-util.js';
+export declare function isJsonString(value: JsonValue | undefined): value is string;
+export declare function isJsonNumber(value: JsonValue | undefined): value is number;
+export declare function isJsonBoolean(value: JsonValue | undefined): value is boolean;
+export declare function isSetMember<T extends string>(set: ReadonlySet<T>, value: string): value is T;
+export declare function parseListLimit(limitRaw: string | null, defaultLimit?: number, maxLimit?: number): number;
+/** `_authed` is proof the caller passed auth: an unauthenticated request must never make the server read its body. */
+export declare function parseJsonBody(req: IncomingMessage, _authed: Context): Promise<Record<string, JsonValue>>;
+export declare function getString(obj: Record<string, JsonValue>, key: string): string | undefined;
+export declare function getStringArray(obj: Record<string, JsonValue>, key: string): string[] | undefined;
+export declare function validateIdSegment(id: string, fieldName: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/server/validation.js

@@ -0,0 +1,91 @@
+import { HttpError, isJsonObjectRecord, readBody } from '../http-util.js';
+export function isJsonString(value) {
+    return typeof value === 'string';
+}
+export function isJsonNumber(value) {
+    return typeof value === 'number';
+}
+export function isJsonBoolean(value) {
+    return typeof value === 'boolean';
+}
+// Runtime membership check for a `ReadonlySet<T>` of string-literal union
+// members, used at every `body` field validated against a VALID_* set below.
+// Set<T>.has(value: T) itself gives no narrowing (its parameter type is T,
+// not a type predicate) so callers previously needed a separate `as T` cast
+// at both the check and the later usage; this helper is the one place that
+// assertion lives, so downstream call sites narrow via the `value is T`
+// return instead of re-asserting.
+export function isSetMember(set, value) {
+    // SAFETY: `value as T` is discarded unless `set.has` (the real runtime
+    // check) confirms membership; the `value is T` return type is what
+    // performs the actual narrowing for callers.
+    return set.has(value);
+}
+// Parse a `?limit=` query param for the E2 list routes. Defaults to 100; requires
+// a positive INTEGER <= 1000. Number.isInteger rejects fractional values like
+// "1.5" that Number.isFinite would pass but SQLite `LIMIT ?` rejects with a
+// datatype mismatch (a 500). Shared across the decision/incident/process/policy
+// list routes so the guard cannot drift (codex review 2026-05-30 P2: fractional
+// limit reached SQLite on the policy route; the same latent hole existed in the
+// sibling routes this was copied from).
+export function parseListLimit(limitRaw, defaultLimit = 100, maxLimit = 1000) {
+    if (limitRaw === null)
+        return defaultLimit;
+    const limit = Number(limitRaw);
+    if (!Number.isInteger(limit) || limit <= 0 || limit > maxLimit) {
+        throw new HttpError(400, `limit must be a positive integer <= ${maxLimit}`);
+    }
+    return limit;
+}
+/** `_authed` is proof the caller passed auth: an unauthenticated request must never make the server read its body. */
+export async function parseJsonBody(req, _authed) {
+    const raw = await readBody(req);
+    if (raw.length === 0)
+        return {};
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isJsonObjectRecord(parsed)) {
+            throw new HttpError(400, 'request body must be a JSON object');
+        }
+        return parsed;
+    }
+    catch (e) {
+        if (e instanceof HttpError)
+            throw e;
+        throw new HttpError(400, 'invalid JSON body');
+    }
+}
+export function getString(obj, key) {
+    const v = obj[key];
+    return isJsonString(v) ? v : undefined;
+}
+export function getStringArray(obj, key) {
+    const v = obj[key];
+    if (!Array.isArray(v))
+        return undefined;
+    if (!v.every(isJsonString))
+        return undefined;
+    return v;
+}
+/**
+ * v1.6.4: charset + length validation for `:id` route captures. Routes call
+ * this immediately after `matchPath` to reject empty / overlong / illegal
+ * ids with a useful 400 instead of silently falling through to "not found".
+ *
+ * Allowed charset matches all production id shapes Hippo emits: `mem_<hex>`,
+ * `sum_<hex>`, `sess-<id>`, Slack bot ids like `B01ABCD`, etc. The `:` and
+ * `.` are allowed for forward-compat. The `/` is intentionally absent —
+ * Hippo never emits ids with slashes, and `rejectEncodedSlash` already
+ * stops `%2F`-smuggled ones at the front door.
+ */
+const ID_SEGMENT_RE = /^[A-Za-z0-9_:.\-]+$/;
+export function validateIdSegment(id, fieldName) {
+    if (id.length === 0)
+        throw new HttpError(400, `${fieldName} is required`);
+    if (id.length > 256)
+        throw new HttpError(400, `${fieldName} exceeds 256-character cap`);
+    if (!ID_SEGMENT_RE.test(id)) {
+        throw new HttpError(400, `${fieldName} contains invalid characters; allowed: A-Z a-z 0-9 _ : . -`);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/server.d.ts

@@ -1,66 +1,12 @@
-import { type IncomingMessage } from 'node:http';
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
-export declare function __resetSessionRecallHistoryHttp(): void;
-import { authRevoke, type Actor, type Context } from './api.js';
+import { type Actor, authRevoke, type Context } from './api.js';
 import { ForbiddenError } from './api-errors.js';
+import type { ServeOpts, ServerHandle } from './server/types.js';
 export { authRevoke, ForbiddenError, type Context, type Actor };
-export interface ServerHandle {
-    port: number;
-    url: string;
-    stop: () => Promise<void>;
-    /** Introspection-only (v1.26.2): the underlying node:http Server, exposed so
-     *  tests can assert keep-alive/headers timeout hardening without reaching
-     *  into serve()'s closure. Additive field — do not depend on it for control
-     *  flow outside tests. */
-    server?: import('node:http').Server;
-}
-/** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
-export interface ResolvedBearer {
-    tenantId: string;
-    subject: string;
-    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys); an add-on revokes them through the exported authRevoke when the IdP deprovisions the minter. */
-    role: 'admin' | 'member';
-    scopes?: readonly string[];
-}
-/** Sole judge of non-`hk_` bearer tokens: null is a 401; a throw or missed deadline is a 503, so throw only when upstream is down. */
-export type AuthResolver = (token: string) => ResolvedBearer | null | Promise<ResolvedBearer | null>;
-export interface ServeOpts {
-    hippoRoot: string;
-    /** Runs on every request and SSE heartbeat, so keep it cache-backed; API keys never reach it. */
-    authResolver?: AuthResolver;
-    /** Deadline for one authResolver call; defaults to 5000 ms. */
-    authResolverTimeoutMs?: number;
-    port?: number;
-    host?: string;
-    /** Stop and exit on SIGINT/SIGTERM. Only `hippo serve` owns the process, so only it sets this. */
-    handleSignals?: boolean;
-}
-/**
- * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
- * '::ffff:127.0.0.1' on dual-stack sockets, so we accept that alongside
- * the bare v4 and v6 loopbacks. Anything else is treated as remote.
- */
-export declare function isLoopback(remoteAddress: string | undefined): boolean;
-export declare const LOOPBACK_HOST_HEADER: RegExp;
-/** A browser request sent by another site. Non-browser clients send neither header and pass. */
-export declare function isCrossSite(req: IncomingMessage): boolean;
-/**
- * Rate-limit key for a request. Defaults to the socket's remote address.
- *
- * Behind a TLS-terminating proxy (Fly, most PaaS ingress) every socket
- * carries the proxy's address, so per-IP buckets collapse into one global
- * bucket that unauthenticated traffic can drain before auth runs. Set
- * HIPPO_CLIENT_IP_HEADER to the header the proxy stamps with the real
- * client address (fly-client-ip on Fly, which the edge always overwrites)
- * to key buckets per client instead.
- *
- * Only set this when a trusted proxy fronts EVERY request: a directly
- * reachable server honoring the header would let clients mint a fresh
- * bucket per request and bypass the limiter entirely.
- */
-export declare function clientIpForRateLimit(req: IncomingMessage): string;
-/** Add-ons call this to refuse a subject that would collide with a built-in actor. */
-export declare function isReservedActor(subject: string): boolean;
+export { isCrossSite, LOOPBACK_HOST_HEADER } from './http-util.js';
+export { __resetSessionRecallHistoryHttp } from './server/routes/recall.js';
+export { clientIpForRateLimit } from './server/client-ip.js';
+export { isLoopback, isReservedActor } from './server/auth.js';
+export type { AuthResolver, ResolvedBearer, ServeOpts, ServerHandle } from './server/types.js';
 /**
  * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
  *