agim-cli 1.2.21 → 1.2.34

package/dist/web/server.js

@@ -10,7 +10,7 @@ import { parseMessage, routeMessage } from '../core/router.js';
 import { sessionManager } from '../core/session.js';
 import { registry } from '../core/registry.js';
 import { sink, resolveMessenger } from '../core/message-sink.js';
-import { generateTraceId, createLogger, logger as rootLogger } from '../core/logger.js';
+import { generateTraceId, createLogger, logger as rootLogger, sanitizeUserText } from '../core/logger.js';
 import { validateConfig } from '../core/config-schema.js';
 import { isMasked, maskSecret } from './env-mask.js';
 import { consumeToken, peekToken } from '../core/location-token.js';
@@ -66,6 +66,11 @@ function isLoopbackPeer(req) {
     const ip = (req.socket.remoteAddress || '').replace(/^::ffff:/, '');
     return ip === '127.0.0.1' || ip === '::1';
 }
+/** R13 A5 — track once-per-process whether the deprecated `?token=`
+ *  URL fallback has been used, so we warn at most once per service
+ *  lifetime instead of spamming the journal. Cleared by tests via
+ *  re-importing the module fresh. */
+let _queryTokenWarned = false;
 function extractToken(req, url) {
     // 1. Authorization: Bearer <token>
     const auth = req.headers['authorization'];
@@ -83,10 +88,44 @@ function extractToken(req, url) {
                 return decodeURIComponent(rest.join('=').trim());
         }
     }
-    // 3. ?token=...  (last resort, for WS upgrade / iframe)
+    // 3. ?token=...  (deprecated — kept for WS upgrade / iframe compat)
+    //
+    // R13 A5 — query-string tokens leak to:
+    //   * browser history / bookmarks
+    //   * Referer headers when the page links to a third party
+    //   * any HTTP-proxy / WAF / CDN access log between client and agim
+    //
+    // We warn loudly the first time it's used per process lifetime
+    // (rate-limited so a misbehaving client doesn't fill the journal)
+    // + emit a one-shot audit-event row. Operators should migrate
+    // callers to Authorization: Bearer or the agim_token cookie.
     const q = url.searchParams.get('token');
-    if (q)
+    if (q) {
+        if (!_queryTokenWarned) {
+            _queryTokenWarned = true;
+            rootLogger.warn({
+                component: 'web',
+                event: 'web.auth.query_token_used',
+                path: url.pathname,
+                msg: '?token= URL fallback used; prefer Authorization: Bearer or agim_token cookie '
+                    + '(query token leaks to browser history / Referer / proxy logs)',
+            });
+            try {
+                void (async () => {
+                    const { logAuditEvent } = await import('../core/audit-log.js');
+                    logAuditEvent({
+                        eventType: 'config.put',
+                        actor: 'system',
+                        target: 'web.auth.query_token',
+                        outcome: 'ok',
+                        details: { reason: 'query_token_used', path: url.pathname },
+                    });
+                })();
+            }
+            catch { /* best-effort */ }
+        }
         return q;
+    }
     return null;
 }
 /** Returns true if the request is authenticated (or auth not required). */
@@ -143,6 +182,80 @@ function verifyTokenSync(raw) {
     }
     return _tokenModule.verifyToken(raw);
 }
+/** Resolve a stable actor string for audit-event rows. Mirrors checkAuth's
+ *  identity model:
+ *    - auth disabled → 'web:auth-off'
+ *    - loopback peer (no auth needed) → 'web:loopback'
+ *    - verified token → 'web:<tokenId>'
+ *    - otherwise → 'web:unknown' (request should already have been rejected
+ *      by checkAuth — this branch exists for defensive logging). */
+function getRequestActor(req) {
+    if ((process.env.IMHUB_WEB_AUTH || '').toLowerCase() === 'off')
+        return 'web:auth-off';
+    if (isLoopbackPeer(req))
+        return 'web:loopback';
+    let url;
+    try {
+        url = new URL(req.url || '', 'http://localhost');
+    }
+    catch {
+        return 'web:unknown';
+    }
+    const tok = extractToken(req, url);
+    if (tok) {
+        const id = verifyTokenSync(tok);
+        if (id)
+            return `web:${id}`;
+    }
+    return 'web:unknown';
+}
+/** Resolve whether the request's actor has admin role. Used to gate
+ *  mutation + privileged-read endpoints so a stolen viewer-role token
+ *  can't elevate to control plane (R13 A1).
+ *
+ *  Trust order:
+ *    1. IMHUB_WEB_AUTH=off  → admin (operator explicitly disabled auth)
+ *    2. Loopback peer       → admin (operator on the host)
+ *    3. Bearer token        → token.role === 'admin'
+ *    4. Otherwise           → not admin
+ *
+ *  Note: when no token has been created yet (pre-bootstrap), the
+ *  loopback-peer branch still grants admin so the CLI bootstrap flow
+ *  works. */
+function isRequestAdmin(req) {
+    if ((process.env.IMHUB_WEB_AUTH || '').toLowerCase() === 'off')
+        return true;
+    if (isLoopbackPeer(req))
+        return true;
+    let url;
+    try {
+        url = new URL(req.url || '', 'http://localhost');
+    }
+    catch {
+        return false;
+    }
+    const tok = extractToken(req, url);
+    if (!tok)
+        return false;
+    const id = verifyTokenSync(tok);
+    if (!id)
+        return false;
+    if (!_tokenModule)
+        return false;
+    // isAdminTokenId returns true for legacy tokens missing the role
+    // field (back-compat) so existing deployments stay functional after
+    // upgrade — see access-token.ts:getTokenRole.
+    return _tokenModule.isAdminTokenId(id);
+}
+/** Send 403 and return false when the actor isn't admin. Use as guard:
+ *  `if (!requireAdmin(req, res)) return` */
+function requireAdmin(req, res) {
+    if (isRequestAdmin(req))
+        return true;
+    res.writeHead(403, { 'Content-Type': 'application/json; charset=utf-8' });
+    res.end(JSON.stringify({ error: 'forbidden', message: 'admin role required' }));
+    return false;
+}
 export function createSerialQueue() {
     let queue = Promise.resolve();
     return (fn) => {
@@ -187,6 +300,50 @@ export async function startWebServer(options) {
             bind: bindHost,
         }, 'IMHUB_WEB_AUTH=off + public bind — auth deliberately off, ensure your reverse proxy handles access control');
     }
+    // R13 C2 — when binding to a non-loopback address, the operator
+    // almost certainly intends to put a TLS-terminating reverse proxy
+    // in front of agim. We can't reliably detect from inside whether
+    // that's been done (X-Forwarded-Proto could be forged), so we
+    // surface a one-time banner + audit row at boot. Suppress with
+    // IMHUB_WEB_TLS_ACK=1 for the operator who's already done the
+    // checklist and wants quiet logs.
+    if (isPublicBind && process.env.IMHUB_WEB_TLS_ACK !== '1') {
+        const banner = [
+            '',
+            '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+            `⚠️  WEB SERVER BOUND TO ${bindHost}:${port} (non-loopback)`,
+            '',
+            '   Tokens travel as Bearer headers / cookies — if any leg between',
+            '   client and agim is HTTP, they go on the wire in cleartext.',
+            '   Confirm a TLS-terminating reverse proxy fronts this listener',
+            '   (nginx, caddy, traefik, k8s ingress, …) before exposing it to',
+            '   any network you do not control.',
+            '',
+            '   Silence this banner once your terminator is verified:',
+            '       IMHUB_WEB_TLS_ACK=1',
+            '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━',
+            '',
+        ].join('\n');
+        process.stdout.write(banner);
+        webLog.warn({
+            event: 'web.public_bind_no_tls_ack',
+            bind: bindHost,
+            port,
+        }, `non-loopback bind without IMHUB_WEB_TLS_ACK=1 — confirm reverse-proxy TLS termination`);
+        try {
+            void (async () => {
+                const { logAuditEvent } = await import('../core/audit-log.js');
+                logAuditEvent({
+                    eventType: 'config.put',
+                    actor: 'system',
+                    target: 'web.bind',
+                    outcome: 'ok',
+                    details: { bind: bindHost, port, tls_ack: false },
+                });
+            })();
+        }
+        catch { /* best-effort */ }
+    }
     webLog.info({
         event: 'web.auth_mode',
         bind: bindHost,
@@ -200,19 +357,20 @@ export async function startWebServer(options) {
         // Loopback peers + the public paths below bypass.
         if (!checkAuth(req, res, url))
             return;
-        // v2 SPA fallback — opt-in via IMHUB_WEB_V2=1. When enabled, any
-        // GET that doesn't match an API / WS / SSE / static-asset path
-        // and isn't a public SSR page falls through to serving the v2
-        // index.html. The client-side router (react-router) then resolves
-        // the path. Anything served from src/web-app/dist/* is built in
-        // the M5 PR; until then, set IMHUB_WEB_V2=1 only if you've run
-        // `npm --prefix src/web-app run build` and copied dist/* into
-        // src/web/public/`.
+        // v2 SPA fallback — default ON since 1.2.21 (the v2 SPA shell is now
+        // the only `index.html` we ship; the v1 monolithic HTML was retired
+        // during M1 / R10). This branch serves the SPA chunks under
+        // `/assets/*.js`, the favicon / manifest, and falls back to
+        // index.html for any client-side route. Without this branch a fresh
+        // install hits a white screen — `<script src="/assets/…js">` 404s
+        // because no other handler claims that path.
         //
-        // Default IMHUB_WEB_V2=0 → existing behavior unchanged: tasks.html
-        // / reminders.html / memos.html / settings.html / index.html are
-        // served as before. Zero impact on production deployments.
-        if (process.env.IMHUB_WEB_V2 === '1' && req.method === 'GET') {
+        // Operators on a deeply-customised v1 layout can opt out with
+        // `IMHUB_WEB_V2=0`; that drops back into the v1 handler block below,
+        // which still serves the legacy `tasks.html` / `reminders.html` /
+        // `memos.html` / `settings.html` directly. The default-off shape
+        // shipped through 1.2.20.
+        if (process.env.IMHUB_WEB_V2 !== '0' && req.method === 'GET') {
             const p = url.pathname;
             const isApi = p.startsWith('/api/');
             const isWs = p.startsWith('/ws');
@@ -472,15 +630,21 @@ export async function startWebServer(options) {
             return handleGetConfig(req, res);
         }
         if (url.pathname === '/api/config' && req.method === 'PUT') {
+            if (!requireAdmin(req, res))
+                return;
             return handlePutConfig(req, res);
         }
         if (url.pathname === '/api/agents/status' && req.method === 'GET') {
             return handleAgentsStatus(req, res);
         }
         if (url.pathname === '/api/agents/acp/test' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleAcpTest(req, res);
         }
         if (url.pathname === '/api/agents/acp/discover' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleAcpDiscover(req, res);
         }
         // Jobs
@@ -550,30 +714,51 @@ export async function startWebServer(options) {
             return handleGetEnv(req, res, url);
         }
         if (url.pathname === '/api/env' && req.method === 'PUT') {
+            if (!requireAdmin(req, res))
+                return;
             return handlePutEnv(req, res);
         }
         if (url.pathname === '/api/messengers/email/test' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleEmailTest(req, res);
         }
         if (url.pathname === '/api/workspaces' && req.method === 'GET') {
             return handleListWorkspaces(req, res, url);
         }
         if (url.pathname === '/api/workspaces' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleCreateOrUpdateWorkspace(req, res);
         }
         const workspaceIdMatch = url.pathname.match(/^\/api\/workspaces\/([^/]+)$/);
         if (workspaceIdMatch && req.method === 'PATCH') {
+            if (!requireAdmin(req, res))
+                return;
             return handleCreateOrUpdateWorkspace(req, res, workspaceIdMatch[1]);
         }
         if (workspaceIdMatch && req.method === 'DELETE') {
+            if (!requireAdmin(req, res))
+                return;
             return handleDeleteWorkspace(req, res, workspaceIdMatch[1]);
         }
         if (url.pathname === '/api/metrics' && req.method === 'GET') {
             return handleMetrics(req, res, url);
         }
         if (url.pathname === '/api/audit' && req.method === 'GET') {
+            if (!requireAdmin(req, res))
+                return;
             return handleAudit(req, res, url);
         }
+        // R12 ⑤ — governance audit events (approvals, admin changes, config /
+        // env / token / workspace mutations). Separate retention from
+        // invocations (default 180d). Admin-only — these rows can expose
+        // who promoted whom and which config keys were rotated when.
+        if (url.pathname === '/api/audit/events' && req.method === 'GET') {
+            if (!requireAdmin(req, res))
+                return;
+            return handleAuditEvents(req, res, url);
+        }
         // v1.1.2 — Outbox tab. List rows by status, plus aggregate stats and
         // a retry endpoint for the giving_up row state.
         if (url.pathname === '/api/outbox' && req.method === 'GET') {
@@ -584,6 +769,8 @@ export async function startWebServer(options) {
         }
         const outboxRetryMatch = url.pathname.match(/^\/api\/outbox\/(\d+)\/retry$/);
         if (outboxRetryMatch && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleOutboxRetry(req, res, parseInt(outboxRetryMatch[1], 10));
         }
         // v1.1.3 — A2A tab. Stats over inline rows with parent_id; recent
@@ -649,6 +836,8 @@ export async function startWebServer(options) {
             return handleMemoryFacts(req, res, url);
         }
         if (url.pathname === '/api/memory/facts' && req.method === 'DELETE') {
+            if (!requireAdmin(req, res))
+                return;
             return handleMemoryBulkDelete(req, res, url);
         }
         const memFactIdMatch = url.pathname.match(/^\/api\/memory\/facts\/(\d+)$/);
@@ -659,9 +848,13 @@ export async function startWebServer(options) {
             return handleMemoryPersona(req, res, url);
         }
         if (url.pathname === '/api/memory/persona' && req.method === 'PUT') {
+            if (!requireAdmin(req, res))
+                return;
             return handleMemoryPersonaPut(req, res, url);
         }
         if (url.pathname === '/api/memory/persona' && req.method === 'DELETE') {
+            if (!requireAdmin(req, res))
+                return;
             return handleMemoryPersonaDelete(req, res, url);
         }
         if (url.pathname === '/api/memory/export' && req.method === 'GET') {
@@ -672,20 +865,30 @@ export async function startWebServer(options) {
             return handleVectorStatus(req, res, url);
         }
         if (url.pathname === '/api/memory/vector/test' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleVectorTest(req, res);
         }
         if (url.pathname === '/api/memory/vector/download' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleVectorDownload(req, res);
         }
         if (url.pathname === '/api/memory/vector/backfill' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleVectorBackfill(req, res, url);
         }
         if (url.pathname === '/api/memory/vector/clear' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleVectorClear(req, res, url);
         }
         // v1.2.2 — manual trigger for the daily consolidation. Useful when the
         // user just wants a persona summary now without waiting 24h.
         if (url.pathname === '/api/memory/consolidate' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleMemoryConsolidate(req, res);
         }
         if (url.pathname === '/api/memory/consolidate/status' && req.method === 'GET') {
@@ -719,15 +922,21 @@ export async function startWebServer(options) {
             return handleWorkspaceFiles(req, res, url);
         }
         if (url.pathname === '/api/workspace-files' && req.method === 'PUT') {
+            if (!requireAdmin(req, res))
+                return;
             return handleWorkspaceFileWrite(req, res, url);
         }
         // PR-D: Job batch operations. Same semantics as /api/jobs/:id/cancel
         // and /run but accepts an array of ids in one request — saves N
         // round-trips when the user multi-selects a long list.
         if (url.pathname === '/api/jobs/batch-cancel' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleBatchJob(req, res, 'cancel');
         }
         if (url.pathname === '/api/jobs/batch-run' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleBatchJob(req, res, 'run', options.defaultAgent);
         }
         // PR-C: SSE event stream — audit / approval / job / metrics events
@@ -737,9 +946,13 @@ export async function startWebServer(options) {
             return handleEventsSSE(req, res);
         }
         if (url.pathname === '/api/notify' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleNotify(req, res);
         }
         if (url.pathname === '/api/invoke' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleInvoke(req, res, options.defaultAgent);
         }
         // WeChat QR login — drives the "扫码登录" button in the web settings
@@ -748,6 +961,8 @@ export async function startWebServer(options) {
         // credentials to disk AND adds 'wechat-ilink' into config.messengers
         // so the next service restart picks the channel up.
         if (url.pathname === '/api/messengers/wechat/qr-start' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleWechatQrStart(res);
         }
         if (url.pathname === '/api/messengers/wechat/qr-status' && req.method === 'GET') {
@@ -763,12 +978,18 @@ export async function startWebServer(options) {
             return handleServiceStatus(res);
         }
         if (url.pathname === '/api/service/start' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleServiceStart(res);
         }
         if (url.pathname === '/api/service/stop' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleServiceStop(res);
         }
         if (url.pathname === '/api/service/restart' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleServiceRestart(res);
         }
         // Admin allowlist — list + add/remove via the Safety card. Locally
@@ -779,9 +1000,13 @@ export async function startWebServer(options) {
             return handleAdminAllowlistGet(res);
         }
         if (url.pathname === '/api/admin-allowlist' && req.method === 'POST') {
+            if (!requireAdmin(req, res))
+                return;
             return handleAdminAllowlistAdd(req, res, bindHost);
         }
         if (url.pathname === '/api/admin-allowlist' && req.method === 'DELETE') {
+            if (!requireAdmin(req, res))
+                return;
             return handleAdminAllowlistRemove(req, res, bindHost);
         }
         res.writeHead(404);
@@ -796,6 +1021,18 @@ export async function startWebServer(options) {
     const wss = new WebSocketServer({
         server: httpServer,
         verifyClient: (info, cb) => {
+            // R13 A4 — per-IP rate limit runs BEFORE auth so an attacker
+            // hammering verifyClient with bad tokens can't burn CPU on
+            // sha256-hashing every attempt.
+            const limit = checkWsIpRateLimit(info.req);
+            if (!limit.ok) {
+                webLog.warn({
+                    event: 'ws.rate_limited',
+                    ip: peerIp(info.req),
+                    reason: limit.reason,
+                }, 'WS upgrade refused (per-IP rate limit)');
+                return cb(false, 429, 'rate limited');
+            }
             // Auth-off / loopback bypass — mirror checkAuth's two short-circuits
             // so dev / local CLI sessions still work without a token.
             if ((process.env.IMHUB_WEB_AUTH || '').toLowerCase() === 'off')
@@ -846,6 +1083,89 @@ export async function startWebServer(options) {
         }
         return 100;
     })();
+    // R13 A4 — per-IP rate limit. The per-token cap above protects
+    // memory but not connection rate; one attacker IP with a valid
+    // token can still spawn N parallel browser tabs / processes and
+    // saturate the file-descriptor pool.
+    //
+    //   IMHUB_WS_MAX_PER_IP            active connections per IP (default 20)
+    //   IMHUB_WS_MAX_NEW_PER_IP_PER_MIN  new connections per IP per minute (default 30)
+    //
+    // Loopback bypasses both — local dev / CLI tooling makes many
+    // short connections legitimately.
+    const wsMaxPerIp = (() => {
+        const raw = process.env.IMHUB_WS_MAX_PER_IP;
+        if (raw) {
+            const n = parseInt(raw, 10);
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+        return 20;
+    })();
+    const wsMaxNewPerIpPerMin = (() => {
+        const raw = process.env.IMHUB_WS_MAX_NEW_PER_IP_PER_MIN;
+        if (raw) {
+            const n = parseInt(raw, 10);
+            if (Number.isFinite(n) && n > 0)
+                return n;
+        }
+        return 30;
+    })();
+    /** Per-IP active count + recent connection timestamps for sliding-window
+     *  rate limiting. We don't periodically prune unused entries — at
+     *  reasonable defaults the map size is bounded by the number of distinct
+     *  client IPs in any 60-second window, far below memory concerns. */
+    const wsPerIp = new Map();
+    function peerIp(req) {
+        return (req.socket.remoteAddress || '').replace(/^::ffff:/, '');
+    }
+    /** Returns {ok:true} when the IP may open a new WS, else {ok:false, reason}. */
+    function checkWsIpRateLimit(req) {
+        if (isLoopbackPeer(req))
+            return { ok: true };
+        const ip = peerIp(req);
+        if (!ip)
+            return { ok: false, reason: 'empty peer ip' }; // defensive — matches isLoopbackPeer policy
+        const now = Date.now();
+        const cutoff = now - 60_000;
+        const slot = wsPerIp.get(ip) ?? { active: 0, recent: [] };
+        slot.recent = slot.recent.filter((t) => t > cutoff);
+        if (slot.active >= wsMaxPerIp) {
+            return { ok: false, reason: `per-IP active cap (${slot.active}/${wsMaxPerIp})` };
+        }
+        if (slot.recent.length >= wsMaxNewPerIpPerMin) {
+            return { ok: false, reason: `per-IP new-conn cap (${slot.recent.length}/${wsMaxNewPerIpPerMin}/min)` };
+        }
+        return { ok: true };
+    }
+    function recordWsIpOpen(req) {
+        if (isLoopbackPeer(req))
+            return;
+        const ip = peerIp(req);
+        if (!ip)
+            return;
+        const slot = wsPerIp.get(ip) ?? { active: 0, recent: [] };
+        slot.active++;
+        slot.recent.push(Date.now());
+        wsPerIp.set(ip, slot);
+    }
+    function recordWsIpClose(req) {
+        if (isLoopbackPeer(req))
+            return;
+        const ip = peerIp(req);
+        if (!ip)
+            return;
+        const slot = wsPerIp.get(ip);
+        if (!slot)
+            return;
+        slot.active = Math.max(0, slot.active - 1);
+        // GC empty slots so the map doesn't grow unboundedly across the
+        // lifetime of the process. A slot is "empty" iff no active conn
+        // AND no recent connection within the window.
+        if (slot.active === 0 && slot.recent.filter((t) => t > Date.now() - 60_000).length === 0) {
+            wsPerIp.delete(ip);
+        }
+    }
     wss.on('connection', (ws, req) => {
         if (clients.size >= maxWsClients) {
             // 1013 = "Try Again Later" per RFC 6455. Slightly nicer than a flat
@@ -858,6 +1178,9 @@ export async function startWebServer(options) {
             ws.close(1013, 'Server too busy');
             return;
         }
+        // R13 A4 — book the per-IP slot now that we know the upgrade
+        // succeeded. The matching close hook decrements below.
+        recordWsIpOpen(req);
         // R9: token verified at upgrade time by verifyClient; we read the
         // tokenId here so get-history can enforce ownership when the client
         // wants to rekey to a persisted threadId. 'anon' is the loopback /
@@ -978,6 +1301,7 @@ export async function startWebServer(options) {
             const liveId = client.id;
             webLog.info({ clientId: liveId }, 'Client disconnected');
             clients.delete(liveId);
+            recordWsIpClose(req); // R13 A4
             // R9: drop the ownership entry only for server-generated ids that
             // were never rekeyed to a persistent client-side threadId. Rekeyed
             // ids stay registered so the operator's next reconnect with the
@@ -989,6 +1313,7 @@ export async function startWebServer(options) {
             const liveId = client.id;
             webLog.error({ clientId: liveId, err: err instanceof Error ? err.message : String(err) }, 'Client WebSocket error');
             clients.delete(liveId);
+            recordWsIpClose(req); // R13 A4
             if (liveId === clientId)
                 threadOwners.delete(liveId);
         });
@@ -1101,6 +1426,19 @@ export async function startWebServer(options) {
             }
             wss.close();
             httpServer.close();
+            // R14 — force-drop in-flight HTTP connections so the listening
+            // port releases immediately. httpServer.close() alone only stops
+            // accepting NEW connections; existing keep-alive sockets keep
+            // port 3000 bound until they drain, which races a `systemctl
+            // restart` and produces EADDRINUSE on the new process.
+            // closeAllConnections is Node 18.2+; older runtimes get the
+            // legacy (slower) behavior.
+            try {
+                const fn = httpServer.closeAllConnections;
+                if (typeof fn === 'function')
+                    fn.call(httpServer);
+            }
+            catch { /* ignore */ }
         },
     };
 }
@@ -1111,11 +1449,18 @@ async function handleGetConfig(_req, res) {
     try {
         const config = await loadConfig();
         const agentStatus = await getAgentStatuses();
+        // Compliance gates — when the env flag is off, strip the
+        // corresponding keys from the response so the settings UI never
+        // sees them and renders no tabs / cards. On-disk config is left
+        // untouched: flipping the env back on restores visibility.
+        const { isGlobalImEnabled, isRemoteAgentEnabled } = await import('../core/feature-flags.js');
+        const showGlobalIm = isGlobalImEnabled();
+        const showRemoteAgent = isRemoteAgentEnabled();
         sendJson(res, 200, {
             messengers: config.messengers,
             agents: config.agents,
             defaultAgent: config.defaultAgent,
-            telegram: config.telegram
+            telegram: showGlobalIm && config.telegram
                 ? { botToken: mask(config.telegram.botToken), channelId: config.telegram.channelId }
                 : undefined,
             feishu: config.feishu
@@ -1124,7 +1469,7 @@ async function handleGetConfig(_req, res) {
             dingtalk: config.dingtalk
                 ? { clientId: config.dingtalk.clientId, clientSecret: mask(config.dingtalk.clientSecret), channelId: config.dingtalk.channelId }
                 : undefined,
-            discord: config.discord
+            discord: showGlobalIm && config.discord
                 ? {
                     botToken: mask(config.discord.botToken),
                     channelId: config.discord.channelId,
@@ -1132,13 +1477,29 @@ async function handleGetConfig(_req, res) {
                     allowedChannels: config.discord.allowedChannels,
                 }
                 : undefined,
-            acpAgents: config.acpAgents?.map(a => ({
-                ...a,
-                auth: a.auth
-                    ? { ...a.auth, token: a.auth.token ? mask(a.auth.token) : undefined }
-                    : undefined,
-            })),
+            acpAgents: showRemoteAgent
+                ? config.acpAgents?.map(a => ({
+                    ...a,
+                    auth: a.auth
+                        ? { ...a.auth, token: a.auth.token ? mask(a.auth.token) : undefined }
+                        : undefined,
+                }))
+                : undefined,
+            // Feature flags surfaced for the SPA so it can hide the
+            // corresponding tabs / nav entries. Field names are
+            // intentionally neutral — they don't reveal which IMs / agent
+            // types the flag controls beyond what the settings page
+            // already exposes.
+            features: {
+                globalIm: showGlobalIm,
+                remoteAgent: showRemoteAgent,
+            },
             webPort: config.webPort,
+            // R15 — acpPort travels only when remote-agent feature is on.
+            // Pairs with the SPA hiding the ACP-port input under the same
+            // gate (see web-app/src/routes/settings/service.tsx). When off,
+            // PUT /api/config also drops incoming.acpPort (below).
+            acpPort: showRemoteAgent ? config.acpPort : undefined,
             agentStatus,
         });
     }
@@ -1151,6 +1512,29 @@ async function handlePutConfig(req, res) {
         const body = await readBody(req, res);
         const incoming = JSON.parse(body);
         const existing = await loadConfig();
+        // Compliance gates — silently drop keys the operator's deployment
+        // is not allowed to surface. We don't 4xx here because the SPA may
+        // round-trip a stale snapshot that happens to include these keys;
+        // dropping them keeps existing on-disk values untouched (the
+        // round-trip becomes a no-op for that field).
+        //
+        // We also scrub `messengers[]` so a hidden slot can't be toggled
+        // via direct PUT (the SPA filters in render but a stale draft from
+        // before the env flag was disabled would otherwise re-add the
+        // entry on next save).
+        const { isGlobalImEnabled, isRemoteAgentEnabled } = await import('../core/feature-flags.js');
+        if (!isGlobalImEnabled()) {
+            delete incoming.telegram;
+            delete incoming.discord;
+            if (Array.isArray(incoming.messengers)) {
+                incoming.messengers = incoming.messengers
+                    .filter((m) => m !== 'telegram' && m !== 'discord');
+            }
+        }
+        if (!isRemoteAgentEnabled()) {
+            delete incoming.acpAgents;
+            delete incoming.acpPort;
+        }
         const merged = { ...existing };
         for (const key of Object.keys(incoming)) {
             const val = incoming[key];
@@ -1216,6 +1600,20 @@ async function handlePutConfig(req, res) {
             return;
         }
         await saveConfig(result.config);
+        // R12 ⑤ — persistent audit. `details.keys` is the list of top-level
+        // config keys touched (e.g. ['feishu', 'discord']) — never the raw
+        // values, which would leak tokens / app secrets through the audit
+        // table.
+        try {
+            const { logAuditEvent } = await import('../core/audit-log.js');
+            logAuditEvent({
+                eventType: 'config.put',
+                actor: getRequestActor(req),
+                outcome: 'ok',
+                details: { keys: Object.keys(incoming) },
+            });
+        }
+        catch { /* best-effort */ }
         sendJson(res, 200, { ok: true });
     }
     catch (err) {
@@ -1317,13 +1715,26 @@ async function handleCreateOrUpdateWorkspace(req, res, expectedId) {
         const { workspaceRegistry } = await import('../core/workspace.js');
         workspaceRegistry.add(v.cfg);
         await persistWorkspacesToConfig(workspaceRegistry.listFull().filter((w) => w.id !== 'default'));
+        // R12 ⑤ — persistent audit. Only id + agent count go into details;
+        // member list (potentially identifiers) stays out of the audit row.
+        try {
+            const { logAuditEvent } = await import('../core/audit-log.js');
+            logAuditEvent({
+                eventType: 'workspace.add',
+                actor: getRequestActor(req),
+                target: v.cfg.id,
+                outcome: 'ok',
+                details: { agents: v.cfg.agents.length, members: v.cfg.members?.length ?? 0 },
+            });
+        }
+        catch { /* best-effort */ }
         sendJson(res, 200, { ok: true, workspace: v.cfg });
     }
     catch (err) {
         sendJson(res, 500, { ok: false, error: err instanceof Error ? err.message : String(err) });
     }
 }
-async function handleDeleteWorkspace(_req, res, id) {
+async function handleDeleteWorkspace(req, res, id) {
     try {
         const { workspaceRegistry } = await import('../core/workspace.js');
         if (id === 'default') {
@@ -1336,6 +1747,16 @@ async function handleDeleteWorkspace(_req, res, id) {
             return;
         }
         await persistWorkspacesToConfig(workspaceRegistry.listFull().filter((w) => w.id !== 'default'));
+        try {
+            const { logAuditEvent } = await import('../core/audit-log.js');
+            logAuditEvent({
+                eventType: 'workspace.delete',
+                actor: getRequestActor(req),
+                target: id,
+                outcome: 'ok',
+            });
+        }
+        catch { /* best-effort */ }
         sendJson(res, 200, { ok: true });
     }
     catch (err) {
@@ -1456,8 +1877,54 @@ async function handleServiceStatus(res) {
 }
 async function handleServiceStart(res) {
     try {
-        const { detectService, spawnBackground } = await import('../cli-ui/service.js');
+        const { detectService, spawnBackground, reapStrayAgimProcesses } = await import('../cli-ui/service.js');
         const st = detectService();
+        // R14 §四 — when systemd owns the unit, ALL lifecycle commands
+        // must route through systemctl so systemd stays the single
+        // authority. Previously this handler bypassed systemd entirely
+        // (always spawnBackground), creating a second instance
+        // competing for port 3000. Now:
+        //   - systemd active → no-op, report alreadyRunning
+        //   - systemd inactive/failed/activating → systemctl start
+        //     (preceded by reap so any stray pids from a botched
+        //      previous run get cleared first; same cgroup-escape
+        //      recovery as restart).
+        if (st.mode === 'systemd') {
+            if (st.active === 'active') {
+                sendJson(res, 200, { ok: true, alreadyRunning: true, mode: 'systemd', pid: st.pid, active: st.active });
+                return;
+            }
+            try {
+                const reap = await reapStrayAgimProcesses({
+                    excludePids: st.pid != null ? [st.pid] : [],
+                    sigtermTimeoutMs: 5_000,
+                });
+                if (reap.reaped.length > 0 || reap.survived.length > 0) {
+                    webLog.warn({
+                        event: 'web.service.start.reap',
+                        reaped: reap.reaped,
+                        survived: reap.survived,
+                    }, `R14 reap before systemctl start: killed ${reap.reaped.length} stray pid(s)`);
+                }
+            }
+            catch (err) {
+                webLog.warn({ event: 'web.service.start.reap_failed', err: String(err) });
+            }
+            try {
+                const { spawn } = await import('node:child_process');
+                const unitName = existsSync('/etc/systemd/system/agim.service') ? 'agim.service' : 'im-hub.service';
+                // Detached + fire-and-forget so the HTTP response isn't held
+                // for the full systemd activation timeline.
+                const child = spawn('systemctl', ['start', unitName], { detached: true, stdio: 'ignore' });
+                child.unref();
+                sendJson(res, 200, { ok: true, mode: 'systemd', starting: true, previousActive: st.active });
+            }
+            catch (err) {
+                sendJson(res, 500, { error: 'systemctl start spawn failed: ' + (err instanceof Error ? err.message : String(err)) });
+            }
+            return;
+        }
+        // Non-systemd: existing behavior.
         if (st.mode !== 'none') {
             sendJson(res, 200, { ok: true, alreadyRunning: true, mode: st.mode, pid: st.pid });
             return;
@@ -1473,7 +1940,7 @@ async function handleServiceStart(res) {
     }
 }
 async function handleServiceStop(res) {
-    const { detectService } = await import('../cli-ui/service.js');
+    const { detectService, reapStrayAgimProcesses } = await import('../cli-ui/service.js');
     const st = detectService();
     if (st.mode === 'systemd') {
         // systemctl stop handles the kill for us — no self-exit needed.
@@ -1482,6 +1949,24 @@ async function handleServiceStop(res) {
             // Match service.ts's detection: prefer agim.service, fall back.
             const unitName = existsSync('/etc/systemd/system/agim.service') ? 'agim.service' : 'im-hub.service';
             execSync(`systemctl stop ${unitName}`);
+            // R14 §四 — sweep stray pids after systemctl stop, same way
+            // restart does pre-stop. systemctl reports success when its
+            // cgroup-kill returns, even if a child escaped the control
+            // group (the dbus-run-session bug). We finish the job here so
+            // a subsequent web Start doesn't EADDRINUSE-loop. Exclude
+            // process.pid via reap's built-in self-exclusion — we don't
+            // want to kill the very process answering this HTTP request.
+            try {
+                const reap = await reapStrayAgimProcesses({ sigtermTimeoutMs: 5_000 });
+                if (reap.reaped.length > 0 || reap.survived.length > 0) {
+                    webLog.warn({
+                        event: 'web.service.stop.reap',
+                        reaped: reap.reaped,
+                        survived: reap.survived,
+                    }, `R14 reap after systemctl stop: killed ${reap.reaped.length} stray pid(s)`);
+                }
+            }
+            catch { /* best-effort */ }
             sendJson(res, 200, { ok: true, mode: 'systemd' });
         }
         catch (err) {
@@ -1501,9 +1986,48 @@ async function handleServiceStop(res) {
     }, 200);
 }
 async function handleServiceRestart(res) {
-    const { detectService } = await import('../cli-ui/service.js');
+    const { detectService, reapStrayAgimProcesses } = await import('../cli-ui/service.js');
     const st = detectService();
     if (st.mode === 'systemd') {
+        // R14 — reap stray agim processes BEFORE systemctl restart. The
+        // motivating bug: a dbus-run-session wrapper in keyring.conf
+        // detached its children from systemd's cgroup, so old agim
+        // outlived `systemctl stop` and the new instance hit EADDRINUSE
+        // on port 3000. We can't fix the unit file from here, but we can
+        // make web restart self-healing by sweeping pids that pgrep can
+        // still see. excludePids = the current MainPID (systemd will
+        // handle that one) and our own pid (this very web request is
+        // running inside agim).
+        try {
+            const result = await reapStrayAgimProcesses({
+                excludePids: st.pid != null ? [st.pid] : [],
+                sigtermTimeoutMs: 5_000,
+            });
+            if (result.reaped.length > 0 || result.survived.length > 0) {
+                webLog.warn({
+                    event: 'web.service.restart.reap',
+                    reaped: result.reaped,
+                    survived: result.survived,
+                }, `R14 reap: killed ${result.reaped.length} stray agim pid(s), ${result.survived.length} survived to SIGKILL`);
+                try {
+                    const { logAuditEvent } = await import('../core/audit-log.js');
+                    logAuditEvent({
+                        eventType: 'config.put',
+                        actor: 'system',
+                        target: 'service.restart.reap',
+                        outcome: 'ok',
+                        details: { reaped: result.reaped.length, survived: result.survived.length, mainPid: st.pid },
+                    });
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch (err) {
+            // Reap is best-effort — log + continue to systemctl. If reap
+            // failed because pgrep isn't available, systemctl restart will
+            // still try (and may succeed if the cgroup is OK).
+            webLog.warn({ event: 'web.service.restart.reap_failed', err: String(err) });
+        }
         try {
             const { spawn } = await import('node:child_process');
             const unitName = existsSync('/etc/systemd/system/agim.service') ? 'agim.service' : 'im-hub.service';
@@ -2115,6 +2639,18 @@ async function handlePutEnv(req, res) {
             else
                 process.env[k] = v;
         }
+        // R12 ⑤ — persistent audit. Track WHICH keys were touched, never the
+        // values themselves (env can hold SMTP_PASS, BAIDU_AK, etc.).
+        try {
+            const { logAuditEvent } = await import('../core/audit-log.js');
+            logAuditEvent({
+                eventType: 'env.put',
+                actor: getRequestActor(req),
+                outcome: 'ok',
+                details: { keys: Object.keys(safe) },
+            });
+        }
+        catch { /* best-effort */ }
         sendJson(res, 200, { ok: true, updated: Object.keys(safe) });
     }
     catch (err) {
@@ -2264,6 +2800,36 @@ async function handleAudit(_req, res, url) {
         sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
     }
 }
+/** R12 ⑤ — GET /api/audit/events. Queryable by type, actor, days, limit.
+ *  Returns the JSON-encoded `details` field as a string; the client can
+ *  JSON.parse on demand (avoids accidental schema coupling). */
+async function handleAuditEvents(_req, res, url) {
+    try {
+        const { queryAuditEvents } = await import('../core/audit-log.js');
+        const limit = Math.min(Math.max(parseInt(url.searchParams.get('limit') || '100', 10) || 100, 1), 1000);
+        const days = parseInt(url.searchParams.get('days') || '30', 10) || 30;
+        const actor = url.searchParams.get('actor') || undefined;
+        const typesParam = url.searchParams.get('types');
+        // Accept comma-separated event types; reject anything not in the
+        // known union (defensive against open-ended filters that miss the
+        // SQL prepared-statement param check).
+        const KNOWN_TYPES = [
+            'approval.allow', 'approval.deny',
+            'admin.elevate', 'admin.revoke',
+            'config.put', 'env.put',
+            'token.create', 'token.revoke',
+            'workspace.add', 'workspace.delete',
+        ];
+        const types = typesParam
+            ? typesParam.split(',').map((s) => s.trim()).filter((s) => KNOWN_TYPES.includes(s))
+            : undefined;
+        const events = queryAuditEvents({ limit, days, actor, types });
+        sendJson(res, 200, { events });
+    }
+    catch (err) {
+        sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
+    }
+}
 /**
  * Per-agent operational health snapshot. Drives the Health tab in /tasks.
  *
@@ -2794,9 +3360,28 @@ async function handleSkillsList(_req, res) {
 // skillhub.cn proxy with 5-min cache — shows top-50 popular skills so the
 // user can discover new ones without leaving the dashboard. The actual
 // install still happens via the skillhub CLI on the host (see docs).
+//
+// Enterprise / air-gapped deployments can disable this endpoint via
+// `IMHUB_SKILLHUB_ENABLED=0`. When disabled, the API returns a stub
+// shape `{ disabled: true, items: [] }` so the UI can show "disabled
+// by enterprise policy" without breaking the page. This is the only
+// product-default outbound call to a non-IM domain, so the toggle
+// matters for organisations doing tcpdump-level egress audits.
 let remoteHotCache = null;
 const REMOTE_HOT_TTL_MS = 5 * 60_000;
+function isSkillhubEnabled() {
+    const v = (process.env.IMHUB_SKILLHUB_ENABLED ?? '1').trim().toLowerCase();
+    return v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
 async function handleSkillsRemoteHot(_req, res) {
+    if (!isSkillhubEnabled()) {
+        // Disabled by enterprise policy. Return an empty-but-valid shape
+        // so the SPA can render "disabled" copy without a network error
+        // toast. Status 200 because this is a deliberate operator choice,
+        // not a transient failure.
+        sendJson(res, 200, { disabled: true, items: [], reason: 'IMHUB_SKILLHUB_ENABLED=0' });
+        return;
+    }
     try {
         if (remoteHotCache && Date.now() - remoteHotCache.fetchedAt < REMOTE_HOT_TTL_MS) {
             sendJson(res, 200, { ...remoteHotCache.data, cached: true, fetchedAt: remoteHotCache.fetchedAt });
@@ -4027,7 +4612,7 @@ threadOwners) {
                     logger,
                     userId: `web:${clientId}`,
                 };
-                logger.info({ event: 'message.received', text: text.substring(0, 120) });
+                logger.info({ event: 'message.received', ...sanitizeUserText(text) });
                 const result = await routeMessage(parsed, routeCtx);
                 // String response (built-in commands, errors)
                 if (typeof result === 'string') {