@agenthippo-ai/agenthippo 0.1.0 → 0.2.3-dataplane

package/out/cli/serve-hardening.js

@@ -36,14 +36,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TurnLimiter = exports.RateLimiter = exports.CONTAINER_SERVE_HOST = exports.SERVE_HOST_ENV = exports.DEFAULT_BIND_HOST = exports.DEFAULT_MAX_BODY_BYTES = void 0;
+exports.TurnGate = exports.TURN_LIMIT_BUSY_MESSAGE = exports.RATE_LIMIT_BUSY_MESSAGE = exports.TURN_GATE_BUSY_MESSAGE = exports.TURN_GATE_RETRY_AFTER_SECONDS = exports.TURN_QUEUE_ENV = exports.MAX_CONCURRENT_TURNS_ENV = exports.TurnLimiter = exports.SESSION_WITHOUT_USER_REASON = exports.IDENTITY_HEADER_ENV = exports.RateLimiter = exports.XFF_TRUSTED_HOPS_ENV = exports.CONTAINER_SERVE_HOST = exports.SERVE_HOST_ENV = exports.DEFAULT_BIND_HOST = exports.DEFAULT_MAX_BODY_BYTES = void 0;
 exports.resolveStateDir = resolveStateDir;
+exports.resolveAnalyticsSessionsDir = resolveAnalyticsSessionsDir;
 exports.resolveBindHost = resolveBindHost;
 exports.clientIp = clientIp;
 exports.resolveUserId = resolveUserId;
 exports.resolveDataToken = resolveDataToken;
 exports.peerToUserId = peerToUserId;
+exports.userNamespaceHash = userNamespaceHash;
+exports.resolveServeSessionKey = resolveServeSessionKey;
 exports.corsHeaders = corsHeaders;
+exports.createTurnGateFromEnv = createTurnGateFromEnv;
+exports.createRejectionWarner = createRejectionWarner;
 exports.readBodyWithCap = readBodyWithCap;
 /**
  * Serve helpers: state-dir resolution, identity header reading, CORS, turn limiting, body cap.
@@ -58,6 +63,8 @@ exports.readBodyWithCap = readBodyWithCap;
  */
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+const paths_1 = require("../utils/paths");
 /** Default cap on a single request body (1 MiB). Chat messages are small; large bodies are abuse or bugs. */
 exports.DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
 /**
@@ -80,6 +87,26 @@ function resolveStateDir(stateDirOpt, env = process.env) {
     }
     return { dir: path.join(os.tmpdir(), 'agenthippo-server'), ephemeral: true };
 }
+/**
+ * Where serve's Layer 2 analytics (tool-call/warrant JSONL) should live. Precedence:
+ *   1. AGENT_HOME_DIR / AGENTHIPPO_HOME set → getAgentideHome()/analytics/sessions — the
+ *      exact location sessionJsonlFleet.ts and query-analytics.sh already scan by default,
+ *      so this data stays discoverable to Spotlight/DuckDB.
+ *   2. Neither set, but the resolved state dir is non-ephemeral (an explicit --state-dir
+ *      was given) → <stateDir>/analytics/sessions. Not the canonical scan location, but
+ *      still durable — never regress below whatever durability the caller already
+ *      established just to be discoverable.
+ *   3. Neither set and state is ephemeral (no --state-dir, no home-dir env var at all) →
+ *      falls through to getAgentideHome()'s own os.homedir() default, matching the
+ *      already-correct IDE-local behavior — nothing durable was configured either way.
+ */
+function resolveAnalyticsSessionsDir(stateDir, stateDirEphemeral, env = process.env) {
+    const homeOverride = env.AGENT_HOME_DIR?.trim() || env.AGENTHIPPO_HOME?.trim();
+    if (!homeOverride && !stateDirEphemeral) {
+        return path.join(stateDir, 'analytics', 'sessions');
+    }
+    return path.join((0, paths_1.getAgentideHome)(), 'analytics', 'sessions');
+}
 /** Loopback default — safe everywhere a human runs `serve` locally. */
 exports.DEFAULT_BIND_HOST = '127.0.0.1';
 /** Env var for the listen address (used by generated deploy Dockerfiles). */
@@ -96,21 +123,29 @@ exports.CONTAINER_SERVE_HOST = '0.0.0.0';
 function resolveBindHost(hostOpt, env = process.env) {
     return hostOpt?.trim() || env.AGENTHIPPO_SERVE_HOST?.trim() || exports.DEFAULT_BIND_HOST;
 }
+/** Env var: number of trusted proxy hops in front of serve (default 1 — the single Caddy). */
+exports.XFF_TRUSTED_HOPS_ENV = 'AGENTHIPPO_XFF_TRUSTED_HOPS';
 /**
  * Best-effort client IP for rate-limiting keys.
  *
- * Behind the documented single trusted proxy (Caddy), `X-Forwarded-For` ends with the IP the
- * proxy observed, so the right-most entry is the real client (a client-spoofed left-most entry
- * is just prepended). Falls back to the socket address for direct/local callers. This is a
- * coarse abuse key, not an identity — never use it for authorization.
+ * Each trusted proxy appends the IP it observed to `X-Forwarded-For`, so with N trusted hops
+ * the real client is the Nth entry from the right (a client-spoofed left-most entry is just
+ * prepended and never reached). Default is 1 (the documented single Caddy). Behind
+ * Cloudflare Tunnel → Caddy there are two hops — Caddy appends cloudflared's container IP,
+ * which is identical for every client, so leaving hops at 1 there collapses all users into one
+ * rate-limit bucket. Set AGENTHIPPO_XFF_TRUSTED_HOPS=2 for the tunnel profile.
+ * Falls back to the socket address for direct/local callers. This is a coarse abuse key, not
+ * an identity — never use it for authorization.
  */
-function clientIp(req) {
+function clientIp(req, env = process.env) {
     const xff = req.headers['x-forwarded-for'];
     const raw = Array.isArray(xff) ? xff[0] : xff;
     if (raw) {
         const parts = raw.split(',').map((s) => s.trim()).filter(Boolean);
         if (parts.length > 0) {
-            return parts[parts.length - 1];
+            const hopsRaw = Number(env[exports.XFF_TRUSTED_HOPS_ENV]);
+            const hops = Number.isInteger(hopsRaw) && hopsRaw >= 1 ? hopsRaw : 1;
+            return parts[Math.max(0, parts.length - hops)];
         }
     }
     return req.socket?.remoteAddress || 'unknown';
@@ -176,12 +211,25 @@ const HEADER_ALIASES = [
     'x-goog-authenticated-user-email', // Cloud Run IAP (prefixed value, stripped below)
     'cf-access-authenticated-user-email', // Cloudflare Access
 ];
+/** Env var: pin the single identity header the deploy layer actually sets (and strips). */
+exports.IDENTITY_HEADER_ENV = 'AGENTHIPPO_IDENTITY_HEADER';
 /**
  * Resolve the end-user identity for a request.
  *
- * Proxy headers win over the request body — the header is set by the SSO proxy
- * serve sits behind; the body is client-controlled. Falls back to body.user_id
- * for dev/internal use (e.g. direct curl against a local serve).
+ * Proxy headers win over the request body. When AGENTHIPPO_IDENTITY_HEADER pins
+ * trust to one header, that pin is a hard boundary: if the pinned header is
+ * absent, identity resolves to undefined (never the request body) — a deployment
+ * that pins a header has declared it has a real proxy-verified identity, so an
+ * unauthenticated caller must not be able to name themselves via the client-
+ * controlled body. Body fallback is dev/internal convenience for the *unpinned*
+ * case only (e.g. direct curl against a local serve with no identity proxy).
+ *
+ * The alias-list default (used when unpinned) is only safe when the proxy strips
+ * or overwrites ALL of the aliases; platforms that strip only their own header
+ * (Cloud Run IAP strips `X-Goog-*` but forwards a client-supplied `x-agent-user`
+ * untouched, which the alias list checks first) MUST pin theirs — deploy
+ * artifacts set it (e.g. cloudrun-deploy.sh pins `x-goog-authenticated-user-email`)
+ * so an authenticated caller cannot impersonate another user.
  *
  * Resolves identity for `analyticsUserId` attribution and the request-scoped
  * credential context (per-user data scoping). Not folded into the session key —
@@ -190,8 +238,10 @@ const HEADER_ALIASES = [
  * Per-turn *data credentials* (OBO token, e.g. X-Forwarded-Access-Token) are
  * handled by resolveDataToken — not read here.
  */
-function resolveUserId(headers, body) {
-    for (const name of HEADER_ALIASES) {
+function resolveUserId(headers, body, env = process.env) {
+    const pinned = env[exports.IDENTITY_HEADER_ENV]?.trim().toLowerCase();
+    const names = pinned ? [pinned] : HEADER_ALIASES;
+    for (const name of names) {
         const v = headers[name];
         const raw = (Array.isArray(v) ? v[0] : v)?.trim();
         if (raw) {
@@ -201,6 +251,12 @@ function resolveUserId(headers, body) {
             return value;
         }
     }
+    if (pinned) {
+        // Pinned but absent: fail closed. Falling back to the body here would let any
+        // caller that merely reaches this port (proxy misconfiguration, direct network
+        // access, gcloud run services proxy bypassing IAP) name an arbitrary victim.
+        return undefined;
+    }
     const fromBody = body?.user_id?.trim();
     return fromBody || undefined;
 }
@@ -244,6 +300,36 @@ function peerToUserId(peer) {
     const channel = peer.channel?.trim();
     return channel ? `${channel}:${id}` : id;
 }
+/** Stable reason code when a session_id is presented without a verified user on a pinned-identity deployment. */
+exports.SESSION_WITHOUT_USER_REASON = 'session_without_verified_user';
+/** Filesystem/S3-safe per-user namespace segment (user ids are emails/subjects — never raw path segments). */
+function userNamespaceHash(userId) {
+    return crypto.createHash('sha256').update(userId).digest('hex').slice(0, 16);
+}
+/**
+ * Namespace the session key by the verified user (secure-obo-design §3.4 / §8 Phase 0).
+ *
+ * `session_id` is client-supplied; un-namespaced, any authenticated user who guesses another
+ * user's session_id attaches to that session's conversation state (which holds the other
+ * user's row-filtered query results). Prefixing the key with a hash of the verified user makes
+ * cross-user attachment structurally impossible without changing client behavior.
+ *
+ * Fail-closed rule: when the deployment pins an identity header (it declared a real
+ * proxy-verified identity exists) and a request carries a session_id but no verified user,
+ * reject — never let an unauthenticated caller name a session. Unpinned deployments
+ * (local dev, no identity boundary at all) keep today's raw-key behavior.
+ */
+function resolveServeSessionKey(sessionId, userId, env = process.env) {
+    const sid = sessionId?.trim();
+    const uid = userId?.trim();
+    if (uid) {
+        return { sessionKey: `u${userNamespaceHash(uid)}--${sid || 'default'}` };
+    }
+    if (sid && env[exports.IDENTITY_HEADER_ENV]?.trim()) {
+        return { sessionKey: '', rejected: exports.SESSION_WITHOUT_USER_REASON };
+    }
+    return { sessionKey: sid || 'anon-unknown' };
+}
 /** Build CORS headers. Serve is always behind a proxy; CORS is wide-open here. */
 function corsHeaders() {
     return {
@@ -281,6 +367,125 @@ class TurnLimiter {
     }
 }
 exports.TurnLimiter = TurnLimiter;
+/** Env: max concurrent engine turns per process (default 10). `0` disables the gate. */
+exports.MAX_CONCURRENT_TURNS_ENV = 'AGENTHIPPO_MAX_CONCURRENT_TURNS';
+/** Env: bounded FIFO waiter depth when at inflight cap (default 20). */
+exports.TURN_QUEUE_ENV = 'AGENTHIPPO_TURN_QUEUE';
+/** Fixed Retry-After seconds when the turn gate rejects (matches default queue timeout). */
+exports.TURN_GATE_RETRY_AFTER_SECONDS = 15;
+/** User-visible capacity message for gateway channels (Slack/Telegram can't receive HTTP 429). */
+exports.TURN_GATE_BUSY_MESSAGE = 'At capacity — please retry in a moment';
+/** User-visible message for gateway channels when the per-identity RateLimiter rejects. */
+exports.RATE_LIMIT_BUSY_MESSAGE = 'Rate limit exceeded — please retry in a moment';
+/** User-visible message for gateway channels when the per-session TurnLimiter rejects. */
+exports.TURN_LIMIT_BUSY_MESSAGE = 'Per-session turn limit reached';
+/**
+ * Process-wide concurrency gate for engine turns (semaphore + bounded FIFO).
+ *
+ * Caps simultaneous engine subprocesses so a burst cannot OOM the container.
+ * `maxInflight <= 0` disables. Waiters time out after `queueTimeoutMs` (burst
+ * absorber, not a job queue). Rejected callers get `null` — HTTP maps that to
+ * 429 + Retry-After; the gateway path emits a short channel message instead.
+ */
+class TurnGate {
+    maxInflight;
+    maxQueue;
+    queueTimeoutMs;
+    inflightCount = 0;
+    waiters = [];
+    constructor(maxInflight, maxQueue, queueTimeoutMs = exports.TURN_GATE_RETRY_AFTER_SECONDS * 1000) {
+        this.maxInflight = maxInflight;
+        this.maxQueue = maxQueue;
+        this.queueTimeoutMs = queueTimeoutMs;
+    }
+    /**
+     * Acquire a turn slot. Resolves with a `release()` callback, or `null` when
+     * the queue is full or the wait timed out. Always call `release()` in a
+     * `finally` when non-null.
+     */
+    async acquire() {
+        if (!Number.isFinite(this.maxInflight) || this.maxInflight <= 0) {
+            return () => { };
+        }
+        if (this.inflightCount < this.maxInflight) {
+            this.inflightCount += 1;
+            return () => this.releaseSlot();
+        }
+        if (this.waiters.length >= this.maxQueue) {
+            return null;
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const settle = (release) => {
+                if (settled) {
+                    // Timed out after a slot was already offered — give the slot back.
+                    if (release) {
+                        release();
+                    }
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                resolve(release);
+            };
+            const entry = {
+                resolve: settle,
+                timer: null,
+            };
+            const timer = setTimeout(() => {
+                const idx = this.waiters.indexOf(entry);
+                if (idx >= 0) {
+                    this.waiters.splice(idx, 1);
+                }
+                settle(null);
+            }, this.queueTimeoutMs);
+            entry.timer = timer;
+            this.waiters.push(entry);
+        });
+    }
+    releaseSlot() {
+        const next = this.waiters.shift();
+        if (next) {
+            // Transfer the slot to the head waiter — do not decrement inflight.
+            next.resolve(() => this.releaseSlot());
+            return;
+        }
+        this.inflightCount = Math.max(0, this.inflightCount - 1);
+    }
+    get inflight() {
+        return this.inflightCount;
+    }
+    get queued() {
+        return this.waiters.length;
+    }
+    get max() {
+        return this.maxInflight > 0 ? this.maxInflight : 0;
+    }
+}
+exports.TurnGate = TurnGate;
+/** Build a TurnGate from env (serve-v4 P0.1). Defaults: 10 inflight, 20 queued. */
+function createTurnGateFromEnv(env = process.env) {
+    const inflightRaw = Number(env[exports.MAX_CONCURRENT_TURNS_ENV] ?? 10);
+    const queueRaw = Number(env[exports.TURN_QUEUE_ENV] ?? 20);
+    const maxInflight = Number.isFinite(inflightRaw) ? inflightRaw : 10;
+    const maxQueue = Number.isFinite(queueRaw) && queueRaw >= 0 ? queueRaw : 20;
+    return new TurnGate(maxInflight, maxQueue);
+}
+/**
+ * Rate-limited rejection logger — at most one warn per `intervalMs` so a flood
+ * of 429s does not spam the console.
+ */
+function createRejectionWarner(intervalMs = 5_000) {
+    let lastAt = 0;
+    return (msg) => {
+        const now = Date.now();
+        if (now - lastAt < intervalMs) {
+            return;
+        }
+        lastAt = now;
+        console.warn(msg);
+    };
+}
 /**
  * Read a request body with a hard size cap. Past the cap it stops accumulating
  * and rejects with a `tooLarge`-tagged error so the caller can respond 413.