@agenthippo-ai/agenthippo 0.1.0 → 0.1.1

package/out/analytics/sessionEvents.js

@@ -51,6 +51,7 @@ exports.wrapEmitterWithObservability = wrapEmitterWithObservability;
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const branding_1 = require("../branding");
+const credential_context_1 = require("../cli/credential-context");
 const os = __importStar(require("os"));
 // -----------------------------------------------------------------------------
 // Session Event Writer
@@ -175,6 +176,9 @@ class ObservableStreamEmitter {
             callId: loggedCallId,
             // Truncate input to avoid huge JSONL files
             inputPreview: input?.slice(0, 500),
+            // The warrant: who this tool call ran as, read live at call time (never cached).
+            // Undefined outside a runWithCredential scope (e.g. IDE-local, non-serve usage).
+            userId: (0, credential_context_1.currentCredential)()?.userId,
         });
         return this.inner.toolStart(toolName, input, toolCallId, metadata);
     }
@@ -188,6 +192,7 @@ class ObservableStreamEmitter {
             isError: isError ?? false,
             // Truncate result to avoid huge JSONL files
             resultPreview: result?.slice(0, 500),
+            userId: (0, credential_context_1.currentCredential)()?.userId,
         });
         return this.inner.toolEnd(toolName, toolCallId, result, isError, metadata);
     }

package/out/auth-broker/pkce.js

@@ -53,5 +53,7 @@ function codeChallengeFromVerifier(verifier) {
     return crypto.createHash('sha256').update(verifier).digest('base64url');
 }
 function verifyPkceChallenge(verifier, challenge) {
-    return codeChallengeFromVerifier(verifier) === challenge;
+    const expected = Buffer.from(codeChallengeFromVerifier(verifier));
+    const actual = Buffer.from(challenge);
+    return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
 }

package/out/auth-broker/server.js

@@ -508,10 +508,16 @@ function createAuthBrokerServer(config) {
             sendJson(res, 404, { error: 'not_found' });
         }
         catch (err) {
-            if (err.status === 413) {
+            const status = err.status;
+            if (status === 413) {
                 sendJson(res, 413, { error: 'request_entity_too_large' });
                 return;
             }
+            if (status === 403) {
+                audit('forbidden', { reason: 'email_domain' });
+                sendJson(res, 403, { error: 'forbidden', error_description: 'email domain not allowed' });
+                return;
+            }
             // Log the real error internally; return a generic message so clients don't see
             // stack fragments / internal paths in the 500 body.
             console.error('[auth-broker] internal error', err);

package/out/auth-broker/store.js

@@ -123,7 +123,9 @@ class AuthBrokerStore {
     upsertUser(email, displayName) {
         const normalized = email.trim().toLowerCase();
         if (!(0, config_js_1.emailDomainAllowed)(normalized, this.config.allowedEmailDomains)) {
-            throw new Error(`Email domain not allowed for sign-in: ${normalized}`);
+            const err = new Error(`Email domain not allowed for sign-in: ${normalized}`);
+            err.status = 403;
+            throw err;
         }
         for (const user of this.users.values()) {
             if (user.email === normalized) {
@@ -219,7 +221,6 @@ class AuthBrokerStore {
         };
     }
     buildBootstrap(user) {
-        const expiresAt = new Date(Date.now() + this.config.accessTokenTtlSec * 1000).toISOString();
         return {
             version: 1,
             user: {
@@ -240,7 +241,8 @@ class AuthBrokerStore {
             routing: {
                 litellmBaseUrl: this.config.team.litellmBaseUrl,
                 litellmApiKey: this.config.team.litellmApiKey,
-                litellmApiKeyExpiresAt: expiresAt,
+                // No litellmApiKeyExpiresAt: the team key is static — a fabricated expiry
+                // would only pretend rotation exists. Per-user virtual keys are the upgrade path.
             },
             policy: {
                 byokAllowed: true,
@@ -249,10 +251,9 @@ class AuthBrokerStore {
         };
     }
     refreshRoutingCredentials() {
-        const litellmApiKeyExpiresAt = new Date(Date.now() + this.config.accessTokenTtlSec * 1000).toISOString();
+        // The team key is static (no rotation backend yet), so no expiry is reported.
         return {
             litellmApiKey: this.config.team.litellmApiKey,
-            litellmApiKeyExpiresAt,
         };
     }
     buildMe(user) {

package/out/cli/commands/serve.js

@@ -49,6 +49,8 @@ const utils_1 = require("../utils");
 const runtime_1 = require("../runtime");
 const serve_hardening_1 = require("../serve-hardening");
 const credential_context_1 = require("../credential-context");
+const sessionEvents_1 = require("../../analytics/sessionEvents");
+const base_1 = require("../../engines/base");
 const state_sync_1 = require("../state-sync");
 const cli_agent_id_js_1 = require("../../gateway/cli-agent-id.js");
 const openclaw_channel_routing_js_1 = require("../../gateway/openclaw-channel-routing.js");
@@ -93,11 +95,20 @@ async function serveCommand(options) {
     // Resolve persistent session state (serve-v3 §A1: replaces the tmpdir default).
     const { dir: storagePath, ephemeral } = (0, serve_hardening_1.resolveStateDir)(options.stateDir);
     const bindHost = (0, serve_hardening_1.resolveBindHost)(options.host);
+    // Same durable root + subpath the runner's own SessionEventWriter uses (headless/index.ts),
+    // so a fail-closed warrant denial lands in the same per-session JSONL as the tool events it
+    // precedes — the denial happens before runner.run() is ever called, so it needs its own writer.
+    const sessionEventWriter = new sessionEvents_1.SessionEventWriter(path.join(storagePath, 'analytics', 'sessions'));
+    const logWarrantDenied = (sessionKey) => (reason) => sessionEventWriter.append(sessionKey, (0, base_1.generateRequestId)(), 'warrant_denied', { reason });
     const turnLimiter = new serve_hardening_1.TurnLimiter(options.maxTurnsPerSession ?? 0);
     // Per-identity request-rate cap (req/min). Keyed on the trusted user id (falling back to
     // client IP) so rotating session_id can't bypass it. AGENTHIPPO_SERVE_RATE_LIMIT=0 disables.
     const rateLimitPerMin = Number(process.env.AGENTHIPPO_SERVE_RATE_LIMIT ?? 120);
     const rateLimiter = new serve_hardening_1.RateLimiter(Number.isFinite(rateLimitPerMin) ? rateLimitPerMin : 120);
+    // Process-wide inflight cap (serve-v4 P0.1). Prevents a burst from spawning N engine
+    // subprocesses and OOMing the container. AGENTHIPPO_MAX_CONCURRENT_TURNS=0 disables.
+    const turnGate = (0, serve_hardening_1.createTurnGateFromEnv)();
+    const warnGateReject = (0, serve_hardening_1.createRejectionWarner)();
     let landingPageHtml;
     if (options.wwwDir?.trim()) {
         const indexPath = path.join(path.resolve(options.wwwDir.trim()), 'index.html');
@@ -111,21 +122,34 @@ async function serveCommand(options) {
     if (ephemeral) {
         console.warn(`${utils_1.COLORS.yellow}Warning:${utils_1.COLORS.reset} Session state is in a tmpdir (ephemeral). Pass --state-dir or set AGENTHIPPO_HOME to persist sessions across restarts.`);
     }
-    // Q1: object-store state sync (no-op unless AGENTHIPPO_STATE_S3_URI is set).
-    // Boot-restore so sessions survive a fresh instance with no FS mount (R2/S3/Databricks).
+    // Q1 + serve-v4 P1.2: object-store state sync (no-op unless AGENTHIPPO_STATE_S3_URI is set).
+    // Multi-replica: AGENTHIPPO_STATE_RESTORE_BOOT=none + restore-on-miss per session.
+    // Single-instance default: boot-restore the whole prefix (backward compatible).
     const s3State = (0, state_sync_1.resolveS3StateConfig)();
+    const restoreBoot = (0, state_sync_1.resolveRestoreBootMode)();
     if (s3State) {
         // Preflight: state sync shells out to `aws`. If it's missing, sessions would
         // silently never persist — fail fast since durable state was explicitly opted into.
         if (!(await (0, state_sync_1.isAwsCliAvailable)())) {
             console.error(`${utils_1.COLORS.red}Error: AGENTHIPPO_STATE_S3_URI is set but the \`aws\` CLI was not found.${utils_1.COLORS.reset}`);
-            console.error('   State sync requires the AWS CLI. Install it (https://aws.amazon.com/cli/) or unset AGENTHIPPO_STATE_S3_URI.');
+            console.error('   State sync requires the AWS CLI (S3-compatible via --endpoint-url). Install it or unset AGENTHIPPO_STATE_S3_URI.');
             process.exit(1);
         }
-        console.log(`State sync: restoring from ${s3State.uri} …`);
-        await (0, state_sync_1.restoreState)(s3State, storagePath, (m) => console.log(`  ${m}`));
+        if (restoreBoot === 'all') {
+            console.log(`State sync: boot-restore from ${s3State.uri} …`);
+            await (0, state_sync_1.restoreState)(s3State, storagePath, (m) => console.log(`  ${m}`));
+        }
+        else {
+            console.log(`State sync: restore-on-miss from ${s3State.uri} (boot restore disabled)`);
+        }
     }
     const statePusher = s3State ? (0, state_sync_1.makeStatePusher)(s3State, storagePath, options.verbose ? (m) => console.error(m) : undefined) : null;
+    const stateLog = options.verbose ? (m) => console.error(m) : undefined;
+    const prepareSession = async (sessionKey) => {
+        if (s3State) {
+            await (0, state_sync_1.ensureSessionLocal)(s3State, storagePath, sessionKey, stateLog);
+        }
+    };
     const logger = options.verbose ? new headless_1.ConsoleLogger('[Server]') : new headless_1.NoOpLogger();
     // Find SDK CLI paths
     const claudeCodePath = (0, utils_1.findClaudeCodePath)();
@@ -192,9 +216,15 @@ async function serveCommand(options) {
                 return;
             }
             // Readiness — pack synced (+ gateway connected when bridged).
+            // Inflight/queue depth for operators and load balancers (serve-v4 P0.1).
             if (req.method === 'GET' && req.url === '/ready') {
                 res.writeHead(ready ? 200 : 503, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ ready }));
+                res.end(JSON.stringify({
+                    ready,
+                    inflight: turnGate.inflight,
+                    queued: turnGate.queued,
+                    max: turnGate.max,
+                }));
                 return;
             }
             const urlPath = req.url?.split('?')[0] ?? '';
@@ -208,22 +238,41 @@ async function serveCommand(options) {
                 const body = await parseBody(req);
                 const userId = (0, serve_hardening_1.resolveUserId)(req.headers, body);
                 const dataToken = (0, serve_hardening_1.resolveDataToken)(req.headers);
-                const rlKey = userId ?? (0, serve_hardening_1.clientIp)(req);
+                // Rate-limit on the trusted proxy identity (or client IP), never the client-supplied
+                // body user_id — otherwise a caller rotates user_id per request to reset the bucket.
+                const rlKey = (0, serve_hardening_1.resolveUserId)(req.headers, undefined) ?? (0, serve_hardening_1.clientIp)(req);
                 if (!rateLimiter.tryConsume(rlKey)) {
                     res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': String(rateLimiter.retryAfterSeconds(rlKey)) });
                     res.end(JSON.stringify({ error: 'Rate limit exceeded' }));
                     return;
                 }
                 const sessionKey = body.session_id || `anon-${userId ?? 'unknown'}`;
-                if (!turnLimiter.tryConsume(sessionKey)) {
-                    res.writeHead(429, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                // Acquire before turn-limiter so a capacity reject does not burn a turn slot.
+                const release = await turnGate.acquire();
+                if (!release) {
+                    warnGateReject(`TurnGate: rejecting /v1/chat (inflight=${turnGate.inflight} queued=${turnGate.queued} max=${turnGate.max})`);
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(serve_hardening_1.TURN_GATE_RETRY_AFTER_SECONDS),
+                    });
+                    res.end(JSON.stringify({ error: 'At capacity' }));
                     return;
                 }
-                const result = await (0, credential_context_1.runWithCredential)({ userId: userId ?? 'anonymous', dataToken }, () => handleChat(runner, body, defaultEngine, defaultModel, options.workspace, permissions, userId), { dataTokenDir: storagePath });
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify(result));
-                statePusher?.schedule(); // async-delta push, off the response path
+                try {
+                    if (!turnLimiter.tryConsume(sessionKey)) {
+                        res.writeHead(429, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                        return;
+                    }
+                    await prepareSession(sessionKey);
+                    const result = await (0, credential_context_1.runWithCredential)({ userId, dataToken }, () => handleChat(runner, body, defaultEngine, defaultModel, options.workspace, permissions, userId), { dataTokenDir: storagePath, onDenied: logWarrantDenied(sessionKey) });
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(result));
+                    statePusher?.schedule(sessionKey); // per-session delta push, off the response path
+                }
+                finally {
+                    release();
+                }
                 return;
             }
             // Streaming chat endpoint
@@ -231,25 +280,44 @@ async function serveCommand(options) {
                 const body = await parseBody(req);
                 const userId = (0, serve_hardening_1.resolveUserId)(req.headers, body);
                 const dataToken = (0, serve_hardening_1.resolveDataToken)(req.headers);
-                const rlKey = userId ?? (0, serve_hardening_1.clientIp)(req);
+                // Rate-limit on the trusted proxy identity (or client IP), never the client-supplied
+                // body user_id — otherwise a caller rotates user_id per request to reset the bucket.
+                const rlKey = (0, serve_hardening_1.resolveUserId)(req.headers, undefined) ?? (0, serve_hardening_1.clientIp)(req);
                 if (!rateLimiter.tryConsume(rlKey)) {
                     res.writeHead(429, { 'Content-Type': 'application/json', 'Retry-After': String(rateLimiter.retryAfterSeconds(rlKey)) });
                     res.end(JSON.stringify({ error: 'Rate limit exceeded' }));
                     return;
                 }
                 const sessionKey = body.session_id || `anon-${userId ?? 'unknown'}`;
-                if (!turnLimiter.tryConsume(sessionKey)) {
-                    res.writeHead(429, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                // Acquire BEFORE writeHead(200, SSE) so a reject still gets a clean 429.
+                const release = await turnGate.acquire();
+                if (!release) {
+                    warnGateReject(`TurnGate: rejecting /v1/chat/stream (inflight=${turnGate.inflight} queued=${turnGate.queued} max=${turnGate.max})`);
+                    res.writeHead(429, {
+                        'Content-Type': 'application/json',
+                        'Retry-After': String(serve_hardening_1.TURN_GATE_RETRY_AFTER_SECONDS),
+                    });
+                    res.end(JSON.stringify({ error: 'At capacity' }));
                     return;
                 }
-                res.writeHead(200, {
-                    'Content-Type': 'text/event-stream',
-                    'Cache-Control': 'no-cache',
-                    'Connection': 'keep-alive',
-                });
-                await (0, credential_context_1.runWithCredential)({ userId: userId ?? 'anonymous', dataToken }, () => handleStreamingChat(runner, body, defaultEngine, defaultModel, options.workspace, permissions, res, userId), { dataTokenDir: storagePath });
-                statePusher?.schedule(); // async-delta push, off the response path
+                try {
+                    if (!turnLimiter.tryConsume(sessionKey)) {
+                        res.writeHead(429, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Per-session turn limit reached' }));
+                        return;
+                    }
+                    await prepareSession(sessionKey);
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        'Connection': 'keep-alive',
+                    });
+                    await (0, credential_context_1.runWithCredential)({ userId, dataToken }, () => handleStreamingChat(runner, body, defaultEngine, defaultModel, options.workspace, permissions, res, userId), { dataTokenDir: storagePath, onDenied: logWarrantDenied(sessionKey) });
+                    statePusher?.schedule(sessionKey); // per-session delta push, off the response path
+                }
+                finally {
+                    release();
+                }
                 return;
             }
             // 404
@@ -322,7 +390,11 @@ async function serveCommand(options) {
                         defaultModel,
                         runner,
                         permissions,
-                        onTurnComplete: () => statePusher?.schedule(),
+                        turnGate,
+                        warnGateReject,
+                        prepareSession,
+                        onTurnComplete: (sessionId) => statePusher?.schedule(sessionId),
+                        logWarrantDenied,
                     });
                 }
                 catch (err) {
@@ -426,19 +498,39 @@ async function startServeGatewayBridge(params) {
                 : (requestedEngine || params.engine);
             // #4: the channel sender becomes the per-user user_id (analytics + per-user data scoping).
             const userId = (0, serve_hardening_1.peerToUserId)(opts.peerInfo);
-            const result = await (0, credential_context_1.runWithCredential)({ userId: userId ?? 'gateway' }, () => params.runner.run({
-                engineId: effectiveEngine,
-                modelId: params.defaultModel,
-                message,
-                workspaceRoot: params.workspace,
-                sessionId: opts.sessionId,
-                gatewaySessionKey: opts.gatewaySessionKey,
-                analyticsUserId: userId,
-                emitter: opts.emitter,
-                permissions: params.permissions,
-            }), { dataTokenDir: params.stateDir });
-            params.onTurnComplete?.();
-            return { success: result.success, error: result.error };
+            // Gateway can't return HTTP 429 — emit a short channel message and return busy.
+            const release = await params.turnGate.acquire();
+            if (!release) {
+                params.warnGateReject(`TurnGate: rejecting gateway turn (inflight=${params.turnGate.inflight} queued=${params.turnGate.queued} max=${params.turnGate.max})`);
+                try {
+                    await opts.emitter?.text(serve_hardening_1.TURN_GATE_BUSY_MESSAGE);
+                    await opts.emitter?.done();
+                }
+                catch {
+                    // best-effort channel notice
+                }
+                return { success: false, error: 'busy' };
+            }
+            try {
+                const sessionKey = opts.sessionId?.trim() || opts.gatewaySessionKey?.trim() || `gateway-${userId ?? 'anon'}`;
+                await params.prepareSession(sessionKey);
+                const result = await (0, credential_context_1.runWithCredential)({ userId }, () => params.runner.run({
+                    engineId: effectiveEngine,
+                    modelId: params.defaultModel,
+                    message,
+                    workspaceRoot: params.workspace,
+                    sessionId: opts.sessionId,
+                    gatewaySessionKey: opts.gatewaySessionKey,
+                    analyticsUserId: userId,
+                    emitter: opts.emitter,
+                    permissions: params.permissions,
+                }), { dataTokenDir: params.stateDir, onDenied: params.logWarrantDenied(sessionKey) });
+                params.onTurnComplete?.(sessionKey);
+                return { success: result.success, error: result.error };
+            }
+            finally {
+                release();
+            }
         },
     });
     console.log(`${utils_1.COLORS.green}✓${utils_1.COLORS.reset} Gateway bridge: registered "${params.gatewayAgentId}" at ${gatewayUrl}`);

package/out/cli/credential-context.js

@@ -36,6 +36,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.WARRANT_DENIED_REASON = void 0;
 exports.runWithCredential = runWithCredential;
 exports.currentCredential = currentCredential;
 exports.requireUserId = requireUserId;
@@ -58,12 +59,27 @@ const async_hooks_1 = require("async_hooks");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const path = __importStar(require("path"));
+/** Stable, queryable reason code for the one case prepareCredentialScope rejects. */
+exports.WARRANT_DENIED_REASON = 'token_without_verified_user';
 const storage = new async_hooks_1.AsyncLocalStorage();
 function tokenDir(baseDir) {
     return path.join(baseDir, 'mcp-data-tokens');
 }
 async function prepareCredentialScope(cred, options) {
     const token = cred.dataToken?.trim();
+    // A per-turn OBO credential without a verified identity would hand a tool someone's
+    // live data-plane token while the turn can't attribute or scope its use to anyone —
+    // fail closed before the credential is ever materialized (file or in-process), rather
+    // than let a tool run with a real credential attached to an unknown/placeholder user.
+    if (token && !cred.userId?.trim()) {
+        try {
+            await options?.onDenied?.(exports.WARRANT_DENIED_REASON);
+        }
+        catch {
+            // Evidence logging must never suppress or replace the fail-closed error below.
+        }
+        throw new Error(`OBO data token present without a verified user in request scope (fail-closed: ${exports.WARRANT_DENIED_REASON})`);
+    }
     const baseDir = options?.dataTokenDir?.trim();
     if (!token || !baseDir) {
         return cred;

package/out/cli/deploy-init.js

@@ -108,11 +108,11 @@ exports.DEFAULT_DEPLOY_PUBLIC_HOSTNAME = 'auth.agenthippo.ai';
 /** @deprecated Use {@link DEFAULT_DEPLOY_PUBLIC_HOSTNAME}. */
 exports.DEPLOY_PUBLIC_HOSTNAME = exports.DEFAULT_DEPLOY_PUBLIC_HOSTNAME;
 /** npm package for Databricks Apps source deploy (org: agenthippo-ai). */
-exports.AGENTHIPPO_CLI_NPM_PACKAGE = '@agenthippo-ai/cli';
+exports.AGENTHIPPO_CLI_NPM_PACKAGE = '@agenthippo-ai/agenthippo';
 /** Fallback when monorepo package.json is not present (customer runs published CLI). */
 exports.AGENTHIPPO_CLI_NPM_VERSION_FALLBACK = 'latest';
 /**
- * Pin @agenthippo-ai/cli to the monorepo release version when `deploy init` runs from
+ * Pin @agenthippo-ai/agenthippo to the monorepo release version when `deploy init` runs from
  * a dev checkout; otherwise fall back to `latest`.
  */
 function resolveAgentHippoCliNpmVersion() {
@@ -202,7 +202,7 @@ function renderEnvExample(vars, opts) {
         }
     }
     if (opts?.edge) {
-        lines.push('', '# Public hostname — set once; Caddyfile reads {$AGENTHIPPO_PUBLIC_HOSTNAME}.', `AGENTHIPPO_PUBLIC_HOSTNAME=${hostname}`, '', '# Edge auth secrets (JWT signing key, Google OAuth client/cookie) live in .env.auth,', '# which is loaded ONLY by the auth-broker and oauth2-proxy services — never the agent.', '# Keeping the token-signing key out of the agent container limits blast radius if the', '# agent (which runs model-driven tool calls) is compromised. Copy .env.auth.example.', '', '# Cloudflare Tunnel (free — no Access seats), config-file mode in compose:', '#   cloudflared tunnel create <name>  → save the JSON as deploy/tunnel-credentials.json (gitignored)', '#   set the tunnel id in deploy/cloudflared.yml; cloudflared tunnel route dns <name> <hostname>', '# No token/env needed — the credentials JSON is mounted into the cloudflared container.');
+        lines.push('', '# Public hostname — set once; Caddyfile reads {$AGENTHIPPO_PUBLIC_HOSTNAME}.', `AGENTHIPPO_PUBLIC_HOSTNAME=${hostname}`, '', '# Multi-replica (serve-v4 P1): sticky by X-Agent-User in Caddyfile.', '#   docker compose up --scale agent=N', '#   AGENTHIPPO_STATE_S3_URI=s3://bucket/prefix   # S3-compatible (MinIO/R2/GCS/AWS)', '#   AGENTHIPPO_STATE_S3_ENDPOINT=                 # optional, e.g. http://minio:9000', '#   AGENTHIPPO_STATE_RESTORE_BOOT=none            # restore-on-miss (required when N>1)', '# Scale-down: drain (/ready inflight=0) then remove replica — see serve-v3-RUNBOOK.', '', '# Edge auth secrets (JWT signing key, Google OAuth client/cookie) live in .env.auth,', '# which is loaded ONLY by the auth-broker and oauth2-proxy services — never the agent.', '# Keeping the token-signing key out of the agent container limits blast radius if the', '# agent (which runs model-driven tool calls) is compromised. Copy .env.auth.example.', '', '# Cloudflare Tunnel (free — no Access seats), config-file mode in compose:', '#   cloudflared tunnel create <name>  → save the JSON as deploy/tunnel-credentials.json (gitignored)', '#   set the tunnel id in deploy/cloudflared.yml; cloudflared tunnel route dns <name> <hostname>', '# No token/env needed — the credentials JSON is mounted into the cloudflared container.');
     }
     return lines.join('\n') + '\n';
 }
@@ -229,6 +229,7 @@ function renderAuthEnvExample(opts) {
             'AGENTHIPPO_AUTH_JWT_SECRET=   # copy from auth.agenthippo.ai (openssl rand -hex 32 to generate one)',
             `AGENTHIPPO_AUTH_PUBLIC_URL=https://${hostname}`,
             'AGENTHIPPO_AUTH_ALLOWED_DOMAINS=agenthippo.ai',
+            'AGENTHIPPO_AUTH_DEV=0         # 1 enables /oauth/dev/login (tests only; never in production)',
             `AGENTHIPPO_AUTH_COOKIE_DOMAIN=${cookieDomain}   # scope the shared cookie to all subdomains`,
             `AGENTHIPPO_AUTH_IDP_URL=${idp}   # where browsers are sent to log in`,
             'AGENTHIPPO_AUTH_COOKIE_NAME=ah_token',
@@ -267,6 +268,7 @@ function renderAuthEnvExample(opts) {
         'AGENTHIPPO_AUTH_JWT_SECRET=   # openssl rand -hex 32',
         'AGENTHIPPO_AUTH_PUBLIC_URL=https://' + hostname,
         'AGENTHIPPO_AUTH_ALLOWED_DOMAINS=example.com',
+        'AGENTHIPPO_AUTH_DEV=0         # 1 enables /oauth/dev/login (tests only; never in production)',
         'AGENTHIPPO_AUTH_COOKIE_NAME=ah_token   # federated cookie holding the AgentHippo JWT',
         'AGENTHIPPO_AUTH_COOKIE_DOMAIN=.agenthippo.ai   # set so /oauth/browser-login stamps a cross-subdomain cookie',
         'AGENTHIPPO_TEAM_ID=team_default',
@@ -448,6 +450,23 @@ function renderLandingPage(packName) {
         '',
     ].join('\n');
 }
+/** Sticky upstream for multi-replica serve (serve-v4 P1.1).
+ * Hash on X-Agent-User (SSO identity the edge already injects) so a user's
+ * sessions stay on one replica — keeps local state + in-process RateLimiter
+ * correct without Redis. Fallback ip_hash for tokened API callers without SSO.
+ * Scale: `docker compose up --scale agent=N` (set AGENTHIPPO_STATE_RESTORE_BOOT=none).
+ */
+function renderStickyAgentProxy(port, indent = '    ') {
+    return [
+        `${indent}# serve-v4 P1.1: sticky by user identity (not session body — edge can't hash POST).`,
+        `${indent}# In-process RateLimiter is globally correct per user under this policy.`,
+        `${indent}reverse_proxy agent:${port} {`,
+        `${indent}  lb_policy header X-Agent-User {`,
+        `${indent}    fallback ip_hash`,
+        `${indent}  }`,
+        `${indent}}`,
+    ];
+}
 /** Caddy config for the `edge` compose profile (oauth2-proxy + agent on Docker network). */
 function renderCaddyfile(ctx) {
     return [
@@ -458,6 +477,24 @@ function renderCaddyfile(ctx) {
         '}',
         '',
         'http://{$AGENTHIPPO_PUBLIC_HOSTNAME} {',
+        '  # IDE PKCE sign-in: broker requires X-Auth-Request-Email from oauth2-proxy. Must come',
+        '  # before the generic /oauth/* handle so authorize is gated (not dumped straight to broker).',
+        '  handle /oauth/authorize {',
+        '    forward_auth oauth2-proxy:4180 {',
+        '      uri /oauth2/auth',
+        '      copy_headers X-Auth-Request-Email',
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '      @unauth status 401',
+        '      handle_response @unauth {',
+        '        redir * "/oauth2/sign_in?rd={http.request.uri}"',
+        '      }',
+        '    }',
+        '    reverse_proxy auth-broker:9780 {',
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '    }',
+        '  }',
         '  # Federated SSO (A′): browsers from *.agenthippo.ai subdomains land here to log in.',
         '  # Gated behind oauth2-proxy (Google) → auth-broker mints + sets the shared .agenthippo.ai',
         '  # cookie (ah_token), then redirects back to the agent subdomain (`return_to`). Must come',
@@ -498,7 +535,7 @@ function renderCaddyfile(ctx) {
         '  }',
         '  @health path /health /ready',
         '  handle @health {',
-        `    reverse_proxy agent:${ctx.port}`,
+        ...renderStickyAgentProxy(ctx.port, '    '),
         '  }',
         '  # API clients (IDE) with a Bearer token: validate via auth-broker, copy identity header.',
         '  @apiWithAuth {',
@@ -516,7 +553,7 @@ function renderCaddyfile(ctx) {
         '        respond "Unauthorized" 401',
         '      }',
         '    }',
-        `    reverse_proxy agent:${ctx.port}`,
+        ...renderStickyAgentProxy(ctx.port, '    '),
         '  }',
         '  # Browser clients: SSO via oauth2-proxy, identity injected as X-Agent-User.',
         '  handle {',
@@ -532,7 +569,7 @@ function renderCaddyfile(ctx) {
         '    }',
         '    @api path /v1/*',
         '    handle @api {',
-        `      reverse_proxy agent:${ctx.port}`,
+        ...renderStickyAgentProxy(ctx.port, '      '),
         '    }',
         '    root * /srv/www',
         '    file_server',
@@ -967,6 +1004,11 @@ function renderCloudrunServiceYaml(ctx) {
         '          env:',
         '            - { name: AGENTHIPPO_HOME, value: /state }',
         '            - { name: AGENTHIPPO_NO_AUTO_INSTALL, value: "1" }',
+        // Pin serve to trust ONLY the IAP-verified header, so an authenticated caller
+        // cannot impersonate another user via a spoofed X-Agent-User header. The deploy
+        // script fills this with x-goog-authenticated-user-email when IAP is enabled, or
+        // leaves it empty (unpinned) during an ENABLE_IAP=0 bootstrap deploy.
+        '            - { name: AGENTHIPPO_IDENTITY_HEADER, value: "${IDENTITY_HEADER_VALUE}" }',
         agentServeHostEnvYaml(),
         '            - { name: AGENTHIPPO_LITELLM_BASE_URL, value: http://localhost:4443 }',
         '            - name: AGENTHIPPO_LITELLM_API_KEY',
@@ -1088,10 +1130,18 @@ function renderCloudrunSpotlightDeploy(ctx) {
         'ensure_secret "${SERVICE}-litellm-key"; printf %s "$LITELLM_KEY" | gcloud secrets versions add "${SERVICE}-litellm-key" --data-file=-',
         'ensure_secret "${SERVICE}-provider-key"; printf %s "$PROVIDER_KEY" | gcloud secrets versions add "${SERVICE}-provider-key" --data-file=-',
         '',
+        '# IAP (finalized below) forwards X-Goog-Authenticated-User-Email; pin serve to trust ONLY',
+        '# that header so an authenticated caller cannot impersonate another user via a spoofed',
+        '# X-Agent-User header. Skipped when ENABLE_IAP=0 (first-deploy bootstrap) since IAP never',
+        '# sets the header then.',
+        'IDENTITY_HEADER_VALUE=""',
+        '[[ "${ENABLE_IAP:-1}" == "1" ]] && IDENTITY_HEADER_VALUE="x-goog-authenticated-user-email" || true',
+        '',
         '# Render the multi-container template for this project (sed — no gettext dependency) and deploy.',
         'RENDERED="$(mktemp)"',
         'sed -e "s|\\${SERVICE}|${SERVICE}|g" -e "s|\\${IMAGE}|${IMAGE}|g" \\',
         '    -e "s|\\${LITELLM_IMAGE}|${LITELLM_IMAGE}|g" -e "s|\\${STATE_BUCKET}|${STATE_BUCKET}|g" \\',
+        '    -e "s|\\${IDENTITY_HEADER_VALUE}|${IDENTITY_HEADER_VALUE}|g" \\',
         '    deploy/service.yaml > "$RENDERED"',
         'gcloud run services replace "$RENDERED" --region "$REGION"',
         '',
@@ -1128,7 +1178,43 @@ function renderCloudrunEdgeCaddyfile() {
         '}',
         '',
         ':{$PORT} {',
-        '  # Auth-broker: IDE sign-in callback + JWT validation endpoint.',
+        '  # IDE PKCE sign-in: broker requires X-Auth-Request-Email from oauth2-proxy. Must come',
+        '  # before the generic /oauth/* handle so authorize is gated (not dumped straight to broker).',
+        '  handle /oauth/authorize {',
+        '    forward_auth localhost:4180 {',
+        '      uri /oauth2/auth',
+        '      copy_headers X-Auth-Request-Email',
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '      @unauth status 401',
+        '      handle_response @unauth {',
+        '        redir * "/oauth2/sign_in?rd={http.request.uri}"',
+        '      }',
+        '    }',
+        '    reverse_proxy localhost:9780 {',
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '    }',
+        '  }',
+        '  # Federated SSO (A′): browsers from other subdomains land here to stamp the shared cookie.',
+        '  # Same oauth2-proxy gate as authorize; must precede the generic /oauth/* handle.',
+        '  handle /oauth/browser-login {',
+        '    forward_auth localhost:4180 {',
+        '      uri /oauth2/auth',
+        '      copy_headers X-Auth-Request-Email',
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '      @unauth status 401',
+        '      handle_response @unauth {',
+        '        redir * "/oauth2/sign_in?rd=/oauth/browser-login{http.request.uri.query}"',
+        '      }',
+        '    }',
+        '    reverse_proxy localhost:9780 {',
+        '      header_up X-Forwarded-Proto https',
+        '      header_up X-Forwarded-Host {http.request.host}',
+        '    }',
+        '  }',
+        '  # Auth-broker: token exchange + other /oauth/* routes that must stay ungated.',
         '  handle /oauth/* {',
         '    reverse_proxy localhost:9780 {',
         '      header_up X-Forwarded-Proto https',
@@ -1456,6 +1542,14 @@ function cloudrunArtifacts(ctx) {
         'docker build --pull --platform linux/amd64 -f "$DF_TMP" -t "$IMAGE" .',
         'docker push "$IMAGE"',
         '',
+        '# IAP (when enabled below) forwards X-Goog-Authenticated-User-Email; pin serve to trust',
+        '# ONLY that header so an authenticated caller cannot impersonate another user via a',
+        '# spoofed X-Agent-User header. Skipped when ENABLE_IAP=0 (first-deploy bootstrap) since',
+        '# IAP never sets the header then — pinning to an absent header would make every request',
+        '# anonymous instead of leaving body-supplied identity usable during bootstrap.',
+        'IDENTITY_ENV=""',
+        '[[ "${ENABLE_IAP:-1}" == "1" ]] && IDENTITY_ENV=",AGENTHIPPO_IDENTITY_HEADER=x-goog-authenticated-user-email" || true',
+        '',
         '# Deploy private (no --allow-unauthenticated). IAP + role grants are applied below on the beta track.',
         'gcloud run deploy "$SERVICE" \\',
         '  --image "$IMAGE" \\',
@@ -1465,7 +1559,7 @@ function cloudrunArtifacts(ctx) {
         '  --timeout 3600 \\',
         '  --add-volume name=state,type=cloud-storage,bucket="$STATE_BUCKET" \\',
         '  --add-volume-mount volume=state,mount-path=/state \\',
-        `  --set-env-vars ${runEnvVars} \\`,
+        `  --set-env-vars "${runEnvVars}\${IDENTITY_ENV}" \\`,
         ...(runSecrets ? [`  --set-secrets ${runSecrets} \\`] : []),
         '  --region "$REGION"',
         '',
@@ -1929,7 +2023,14 @@ function databricksAppArtifacts(ctx) {
         "  '--workspace', '/tmp/agenthippo/workspace',",
         "  '--state-dir', '/tmp/agenthippo/state',",
         "  '--port', port,",
-        "], { stdio: 'inherit', env: { ...process.env, AGENTHIPPO_SERVE_HOST: '0.0.0.0' } });",
+        "], { stdio: 'inherit', env: {",
+        "  ...process.env,",
+        "  AGENTHIPPO_SERVE_HOST: '0.0.0.0',",
+        "  // Databricks Apps workspace SSO sets X-Forwarded-Email; pin serve to trust ONLY that",
+        "  // header so an authenticated caller cannot impersonate another user via a spoofed",
+        "  // X-Agent-User header (Databricks does not know about or strip that header).",
+        "  AGENTHIPPO_IDENTITY_HEADER: 'x-forwarded-email',",
+        "} });",
         "child.on('exit', (code) => process.exit(code ?? 0));",
         '',
     ].join('\n');