@lelouchhe/webagent 0.6.0 → 0.8.0

package/lib/share/routes.js

@@ -7,6 +7,7 @@ import { SanitizeError, sanitizeEventsForShare } from "./sanitize.js";
 import { buildContentDisposition, isInlineMime } from "../attachments.js";
 import { enrichStoredEventsForDisplay } from "../attachment-labels.js";
 import { log } from "../log.js";
+import { HTTP_STATUS } from "../http-status.js";
 const slog = log.scope("share");
 // In-flight dedup for concurrent POST /share on the same session.
 // First caller does the work; concurrent callers await the same promise.
@@ -112,7 +113,9 @@ export async function handleShareRoutes(req, res, deps) {
         return true;
     }
     if (url === "/s" || url === "/s/") {
-        res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+        res.writeHead(HTTP_STATUS.NOT_FOUND, {
+            "Content-Type": "text/plain; charset=utf-8",
+        });
         res.end("share token required");
         return true;
     }
@@ -175,7 +178,9 @@ export async function handleShareRoutes(req, res, deps) {
         url.startsWith("/api/v1/shared/") ||
         url === "/api/v1/share" ||
         url.startsWith("/api/v1/share/")) {
-        res.writeHead(404, { "Content-Type": "application/json" });
+        res.writeHead(HTTP_STATUS.NOT_FOUND, {
+            "Content-Type": "application/json",
+        });
         res.end(JSON.stringify({ error: "not found" }));
         return true;
     }
@@ -202,12 +207,12 @@ function resolveDisplayName(deps, validated) {
 async function handlePreviewCreate(req, res, deps, sessionId) {
     const session = deps.store.getSession(sessionId);
     if (!session) {
-        json(res, 404, { error: "session not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "session not found" });
         return;
     }
     // 409 guard: block while the agent is actively streaming into this session.
     if (deps.sessions?.getBusyKind(sessionId) === "agent") {
-        json(res, 409, {
+        json(res, HTTP_STATUS.CONFLICT, {
             error: "session busy",
             detail: "此 session 正在接收 agent 输出,请等 agent 输出结束后再分享",
         });
@@ -221,13 +226,15 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
             body = {};
     }
     catch {
-        json(res, 400, { error: "invalid JSON body" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "invalid JSON body" });
         return;
     }
     let ttlHours = null;
     if (body.ttl_hours != null) {
         if (!Number.isFinite(body.ttl_hours) || body.ttl_hours < 0) {
-            json(res, 400, { error: "ttl_hours must be a non-negative number" });
+            json(res, HTTP_STATUS.BAD_REQUEST, {
+                error: "ttl_hours must be a non-negative number",
+            });
             return;
         }
         ttlHours =
@@ -239,12 +246,12 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
     // control/size rejected at entry rather than silently dropped.
     const dnResult = validateLabel(body.display_name, "display_name", 256);
     if (!dnResult.ok) {
-        json(res, 400, { error: dnResult.reason });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: dnResult.reason });
         return;
     }
     const olResult = validateLabel(body.owner_label, "owner_label", 1024);
     if (!olResult.ok) {
-        json(res, 400, { error: olResult.reason });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: olResult.reason });
         return;
     }
     const displayName = resolveDisplayName(deps, dnResult.value);
@@ -280,7 +287,7 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
         if (!existingInflight)
             pendingShareCreates.set(sessionId, inflight);
         const result = await inflight;
-        json(res, result.reused ? 200 : 201, {
+        json(res, result.reused ? HTTP_STATUS.OK : HTTP_STATUS.CREATED, {
             token: result.row.token,
             session_id: sessionId,
             snapshot_seq: result.row.share_snapshot_seq,
@@ -293,7 +300,7 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
     }
     catch (err) {
         if (err instanceof SanitizeError) {
-            json(res, 400, {
+            json(res, HTTP_STATUS.BAD_REQUEST, {
                 error: "sanitize rejected",
                 event_id: err.event_id,
                 rule: err.rule,
@@ -303,7 +310,10 @@ async function handlePreviewCreate(req, res, deps, sessionId) {
         }
         const errorId = randomUUID();
         slog.error("preview_create", { error_id: errorId, error: err });
-        json(res, 500, { error: "internal error", error_id: errorId });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "internal error",
+            error_id: errorId,
+        });
     }
 }
 function runSanitizeGate(events, cwd, internalHosts) {
@@ -327,25 +337,29 @@ async function handlePreviewRead(req, res, deps, sessionId) {
     const tokenHeader = req.headers["x-share-token"];
     const token = Array.isArray(tokenHeader) ? tokenHeader[0] : tokenHeader;
     if (!token) {
-        json(res, 400, { error: "X-Share-Token header required" });
+        json(res, HTTP_STATUS.BAD_REQUEST, {
+            error: "X-Share-Token header required",
+        });
         return;
     }
     const row = deps.store.getShareByToken(token);
     if (!row) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     if (row.session_id !== sessionId) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     if (row.shared_at != null) {
-        json(res, 409, { error: "share already active (use public viewer)" });
+        json(res, HTTP_STATUS.CONFLICT, {
+            error: "share already active (use public viewer)",
+        });
         return;
     }
     const session = deps.store.getSession(sessionId);
     if (!session) {
-        json(res, 404, { error: "session not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "session not found" });
         return;
     }
     const allEvents = deps.store
@@ -366,7 +380,7 @@ async function handlePreviewRead(req, res, deps, sessionId) {
         });
         // Staleness metadata drives the owner sticky bar text (§2.1 R2-c3).
         const eventsSinceSnapshot = Math.max(0, currentLastSeq - row.share_snapshot_seq);
-        json(res, 200, {
+        json(res, HTTP_STATUS.OK, {
             schema_version: "1.0",
             share: {
                 token: row.token,
@@ -386,7 +400,7 @@ async function handlePreviewRead(req, res, deps, sessionId) {
     }
     catch (err) {
         if (err instanceof SanitizeError) {
-            json(res, 400, {
+            json(res, HTTP_STATUS.BAD_REQUEST, {
                 error: "sanitize rejected",
                 event_id: err.event_id,
                 rule: err.rule,
@@ -395,7 +409,10 @@ async function handlePreviewRead(req, res, deps, sessionId) {
         }
         const errorId = randomUUID();
         slog.error("preview_read", { error_id: errorId, error: err });
-        json(res, 500, { error: "internal error", error_id: errorId });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "internal error",
+            error_id: errorId,
+        });
     }
 }
 /**
@@ -420,24 +437,24 @@ async function handlePublish(req, res, deps, sessionId) {
             body = {};
     }
     catch {
-        json(res, 400, { error: "invalid JSON body" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "invalid JSON body" });
         return;
     }
     if (!body.token || typeof body.token !== "string") {
-        json(res, 400, { error: "token required" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "token required" });
         return;
     }
     const row = deps.store.getShareByToken(body.token);
     if (!row) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     if (row.session_id !== sessionId) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     if (row.shared_at != null) {
-        json(res, 409, {
+        json(res, HTTP_STATUS.CONFLICT, {
             error: "share already active",
             token: row.token,
             shared_at: row.shared_at,
@@ -451,7 +468,7 @@ async function handlePublish(req, res, deps, sessionId) {
     if ("display_name" in body) {
         const r = validateLabel(body.display_name, "display_name", 256);
         if (!r.ok) {
-            json(res, 400, { error: r.reason });
+            json(res, HTTP_STATUS.BAD_REQUEST, { error: r.reason });
             return;
         }
         displayName = r.value === "" ? null : r.value;
@@ -460,7 +477,7 @@ async function handlePublish(req, res, deps, sessionId) {
     if ("owner_label" in body) {
         const r = validateLabel(body.owner_label, "owner_label", 1024);
         if (!r.ok) {
-            json(res, 400, { error: r.reason });
+            json(res, HTTP_STATUS.BAD_REQUEST, { error: r.reason });
             return;
         }
         ownerLabel = r.value === "" ? null : r.value;
@@ -473,18 +490,20 @@ async function handlePublish(req, res, deps, sessionId) {
         // Race: concurrent revoke/activate between getShareByToken and activateShare.
         const fresh = deps.store.getShareByToken(body.token);
         if (!fresh) {
-            json(res, 410, { error: "share revoked" });
+            json(res, HTTP_STATUS.GONE, { error: "share revoked" });
             return;
         }
         if (fresh.shared_at != null) {
-            json(res, 409, {
+            json(res, HTTP_STATUS.CONFLICT, {
                 error: "share already active",
                 token: fresh.token,
                 shared_at: fresh.shared_at,
             });
             return;
         }
-        json(res, 500, { error: "unexpected activate failure" });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "unexpected activate failure",
+        });
         return;
     }
     if (displayName !== undefined && displayName != null) {
@@ -492,13 +511,15 @@ async function handlePublish(req, res, deps, sessionId) {
     }
     const after = deps.store.getShareByToken(body.token);
     if (!after) {
-        json(res, 500, { error: "post-activate read failed" });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "post-activate read failed",
+        });
         return;
     }
     const origin = deps.config.viewer_origin && deps.config.viewer_origin !== ""
         ? deps.config.viewer_origin.replace(/\/$/, "")
         : "";
-    json(res, 200, {
+    json(res, HTTP_STATUS.OK, {
         token: after.token,
         session_id: sessionId,
         shared_at: after.shared_at,
@@ -516,7 +537,7 @@ async function handleViewerHtml(res, deps, token) {
     if (row?.shared_at == null) {
         // Preview tokens (shared_at IS NULL) MUST NOT resolve publicly.
         const csp = viewerCsp(deps.config.csp_enforce);
-        res.writeHead(410, {
+        res.writeHead(HTTP_STATUS.GONE, {
             "Content-Type": "text/html; charset=utf-8",
             [csp.name]: csp.value,
             "Cache-Control": "no-store",
@@ -527,7 +548,7 @@ async function handleViewerHtml(res, deps, token) {
     }
     if (isExpired(row)) {
         const csp = viewerCsp(deps.config.csp_enforce);
-        res.writeHead(410, {
+        res.writeHead(HTTP_STATUS.GONE, {
             "Content-Type": "text/html; charset=utf-8",
             [csp.name]: csp.value,
             "Cache-Control": "no-store",
@@ -537,13 +558,15 @@ async function handleViewerHtml(res, deps, token) {
         return;
     }
     if (!deps.publicDir) {
-        json(res, 500, { error: "publicDir not configured" });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "publicDir not configured",
+        });
         return;
     }
     try {
         const html = await readFile(join(deps.publicDir, "share-viewer.html"), "utf-8");
         const csp = viewerCsp(deps.config.csp_enforce);
-        res.writeHead(200, {
+        res.writeHead(HTTP_STATUS.OK, {
             "Content-Type": "text/html; charset=utf-8",
             [csp.name]: csp.value,
             "Cache-Control": "no-store, no-cache, must-revalidate",
@@ -558,7 +581,9 @@ async function handleViewerHtml(res, deps, token) {
     catch (err) {
         const errorId = randomUUID();
         slog.error("viewer_html", { error_id: errorId, error: err });
-        res.writeHead(500, { "Content-Type": "text/plain" });
+        res.writeHead(HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            "Content-Type": "text/plain",
+        });
         res.end(`viewer unavailable (error_id=${errorId})`);
     }
 }
@@ -569,11 +594,11 @@ async function handleViewerHtml(res, deps, token) {
 async function handleSharedEvents(res, deps, token) {
     const row = deps.store.getShareByToken(token);
     if (row?.shared_at == null) {
-        json(res, 410, { error: "share revoked or not found" });
+        json(res, HTTP_STATUS.GONE, { error: "share revoked or not found" });
         return;
     }
     if (isExpired(row)) {
-        json(res, 410, { error: "share expired" });
+        json(res, HTTP_STATUS.GONE, { error: "share expired" });
         return;
     }
     // Public viewer must keep working after the owner deletes the source
@@ -581,7 +606,7 @@ async function handleSharedEvents(res, deps, token) {
     // them (Store.deleteSession soft-deletes when shares exist).
     const session = deps.store.getSessionIncludingDeleted(row.session_id);
     if (!session) {
-        json(res, 500, { error: "session vanished" });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: "session vanished" });
         return;
     }
     const allEvents = deps.store
@@ -598,7 +623,7 @@ async function handleSharedEvents(res, deps, token) {
             internalHosts: deps.config.internal_hosts,
         });
         // Public response: DOES NOT expose session_id. Only title + display_name + meta.
-        res.writeHead(200, {
+        res.writeHead(HTTP_STATUS.OK, {
             "Content-Type": "application/json",
             "Cache-Control": "no-store",
             "X-Content-Type-Options": "nosniff",
@@ -626,12 +651,15 @@ async function handleSharedEvents(res, deps, token) {
                 rule: err.rule,
                 event_id: err.event_id,
             });
-            json(res, 410, { error: "share unavailable" });
+            json(res, HTTP_STATUS.GONE, { error: "share unavailable" });
             return;
         }
         const errorId = randomUUID();
         slog.error("shared_events", { error_id: errorId, error: err });
-        json(res, 500, { error: "internal error", error_id: errorId });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "internal error",
+            error_id: errorId,
+        });
     }
 }
 /**
@@ -644,7 +672,9 @@ async function handleSharedEvents(res, deps, token) {
  */
 async function handleViewerAsset(res, deps, file) {
     if (!deps.publicDir) {
-        res.writeHead(500, { "Content-Type": "text/plain" });
+        res.writeHead(HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            "Content-Type": "text/plain",
+        });
         res.end("publicDir not configured");
         return;
     }
@@ -654,7 +684,7 @@ async function handleViewerAsset(res, deps, file) {
     const cssMatch = /^(styles|share-viewer)(?:\.[A-Za-z0-9_-]+)?\.css$/.test(file);
     const jsMatch = /^(viewer|chunk)(?:\.[A-Za-z0-9_-]+)?\.js$/.test(file);
     if (!cssMatch && !jsMatch) {
-        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.writeHead(HTTP_STATUS.NOT_FOUND, { "Content-Type": "text/plain" });
         res.end("not found");
         return;
     }
@@ -672,7 +702,7 @@ async function handleViewerAsset(res, deps, file) {
         : "text/css; charset=utf-8";
     try {
         const buf = await readFile(filePath);
-        res.writeHead(200, {
+        res.writeHead(HTTP_STATUS.OK, {
             "Content-Type": contentType,
             "Cache-Control": cacheControl,
             "X-Content-Type-Options": "nosniff",
@@ -681,7 +711,7 @@ async function handleViewerAsset(res, deps, file) {
         res.end(buf);
     }
     catch {
-        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.writeHead(HTTP_STATUS.NOT_FOUND, { "Content-Type": "text/plain" });
         res.end("not found");
     }
 }
@@ -692,28 +722,30 @@ async function handleViewerAsset(res, deps, file) {
  */
 async function handleViewerImage(res, deps, token, file) {
     if (!deps.dataDir) {
-        json(res, 500, { error: "dataDir not configured" });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "dataDir not configured",
+        });
         return;
     }
     const row = deps.store.getShareByToken(token);
     if (row?.shared_at == null) {
-        json(res, 410, { error: "share unavailable" });
+        json(res, HTTP_STATUS.GONE, { error: "share unavailable" });
         return;
     }
     if (isExpired(row)) {
-        json(res, 410, { error: "share expired" });
+        json(res, HTTP_STATUS.GONE, { error: "share expired" });
         return;
     }
     // Only allow simple filenames — reject any path separators / dotfiles / traversal.
     if (!/^[A-Za-z0-9._-]+$/.test(file) || file.startsWith(".")) {
-        json(res, 404, { error: "invalid file" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "invalid file" });
         return;
     }
     const sessionRoot = join(deps.dataDir, "sessions", row.session_id, "attachments");
     const filePath = join(sessionRoot, file);
     // Final realpath-style guard: must stay under <dataDir>/sessions/<sid>/attachments.
     if (!filePath.startsWith(sessionRoot + "/") && filePath !== sessionRoot) {
-        res.writeHead(403);
+        res.writeHead(HTTP_STATUS.FORBIDDEN);
         res.end("Forbidden");
         return;
     }
@@ -740,11 +772,11 @@ async function handleViewerImage(res, deps, token, file) {
             const disposition = isInlineMime(mime) ? "inline" : "attachment";
             headers["Content-Disposition"] = buildContentDisposition(disposition, att.name);
         }
-        res.writeHead(200, headers);
+        res.writeHead(HTTP_STATUS.OK, headers);
         res.end(buf);
     }
     catch {
-        res.writeHead(404, { "Content-Type": "text/plain" });
+        res.writeHead(HTTP_STATUS.NOT_FOUND, { "Content-Type": "text/plain" });
         res.end("Not found");
     }
 }
@@ -810,11 +842,11 @@ async function handleRevoke(req, res, deps, sessionId) {
             body = {};
     }
     catch {
-        json(res, 400, { error: "invalid JSON body" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "invalid JSON body" });
         return;
     }
     if (!body.token || typeof body.token !== "string") {
-        json(res, 400, { error: "token required" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "token required" });
         return;
     }
     const row = deps.store.getShareByToken(body.token);
@@ -822,7 +854,7 @@ async function handleRevoke(req, res, deps, sessionId) {
         // Idempotent DELETE: row already gone (revoked or never existed).
         // We can't verify session ownership without a row, but the token
         // is opaque/random so leaking "revoked or never existed" is fine.
-        json(res, 200, {
+        json(res, HTTP_STATUS.OK, {
             ok: true,
             token: body.token,
             revoked: false,
@@ -831,7 +863,7 @@ async function handleRevoke(req, res, deps, sessionId) {
         return;
     }
     if (row.session_id !== sessionId) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     const revoked = deps.store.revokeShare(body.token);
@@ -847,7 +879,7 @@ async function handleRevoke(req, res, deps, sessionId) {
             }).catch(() => { });
         }
     }
-    json(res, 200, {
+    json(res, HTTP_STATUS.OK, {
         ok: true,
         token: body.token,
         revoked,
@@ -871,27 +903,27 @@ async function handlePatchLabel(req, res, deps, sessionId) {
             body = {};
     }
     catch {
-        json(res, 400, { error: "invalid JSON body" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "invalid JSON body" });
         return;
     }
     if (!body.token || typeof body.token !== "string") {
-        json(res, 400, { error: "token required" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "token required" });
         return;
     }
     const row = deps.store.getShareByToken(body.token);
     if (!row) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     if (row.session_id !== sessionId) {
-        json(res, 404, { error: "share not found" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "share not found" });
         return;
     }
     let ownerLabel = undefined;
     if ("owner_label" in body) {
         const v = validateLabel(body.owner_label, "owner_label", 1024);
         if (!v.ok) {
-            json(res, 400, { error: v.reason });
+            json(res, HTTP_STATUS.BAD_REQUEST, { error: v.reason });
             return;
         }
         ownerLabel = v.value === "" ? null : v.value;
@@ -900,7 +932,7 @@ async function handlePatchLabel(req, res, deps, sessionId) {
     if ("display_name" in body) {
         const v = validateLabel(body.display_name, "display_name", 256);
         if (!v.ok) {
-            json(res, 400, { error: v.reason });
+            json(res, HTTP_STATUS.BAD_REQUEST, { error: v.reason });
             return;
         }
         displayName = v.value === "" ? null : v.value;
@@ -911,10 +943,12 @@ async function handlePatchLabel(req, res, deps, sessionId) {
         deps.store.updateShareDisplayName(body.token, displayName);
     const after = deps.store.getShareByToken(body.token);
     if (!after) {
-        json(res, 500, { error: "post-patch read failed" });
+        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+            error: "post-patch read failed",
+        });
         return;
     }
-    json(res, 200, {
+    json(res, HTTP_STATUS.OK, {
         token: after.token,
         session_id: sessionId,
         owner_label: after.owner_label,
@@ -928,7 +962,7 @@ async function handlePatchLabel(req, res, deps, sessionId) {
  */
 async function handleOwnerList(req, res, deps) {
     const rows = deps.store.listOwnerShares();
-    json(res, 200, { shares: rows });
+    json(res, HTTP_STATUS.OK, { shares: rows });
 }
 /**
  * GET /api/v1/share/by — read the owner's default display_name (used by
@@ -937,7 +971,7 @@ async function handleOwnerList(req, res, deps) {
  */
 async function handleByGet(req, res, deps) {
     const value = deps.store.getOwnerPref(DEFAULT_DISPLAY_NAME_KEY) ?? null;
-    json(res, 200, { value });
+    json(res, HTTP_STATUS.OK, { value });
 }
 /**
  * PUT /api/v1/share/by — set or clear the owner's default display_name.
@@ -953,20 +987,20 @@ async function handleByPut(req, res, deps) {
             body = {};
     }
     catch {
-        json(res, 400, { error: "invalid JSON body" });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: "invalid JSON body" });
         return;
     }
     const v = validateLabel(body.value, "value", 256);
     if (!v.ok) {
-        json(res, 400, { error: v.reason });
+        json(res, HTTP_STATUS.BAD_REQUEST, { error: v.reason });
         return;
     }
     if (v.value === "") {
         deps.store.clearOwnerPref(DEFAULT_DISPLAY_NAME_KEY);
-        json(res, 200, { value: null });
+        json(res, HTTP_STATUS.OK, { value: null });
     }
     else {
         deps.store.setOwnerPref(DEFAULT_DISPLAY_NAME_KEY, v.value);
-        json(res, 200, { value: v.value });
+        json(res, HTTP_STATUS.OK, { value: v.value });
     }
 }

package/lib/share/sanitize.js

@@ -1,5 +1,6 @@
+import { HTTP_STATUS } from "../http-status.js";
 export class SanitizeError extends Error {
-    status = 400;
+    status = HTTP_STATUS.BAD_REQUEST;
     /** The event seq that triggered the hard-reject; surfaced to owner as event_id. */
     event_id;
     rule;

package/lib/sse-manager.js

@@ -1,6 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { reSignAttachmentUrlsInJson } from "./auth.js";
 import { enrichEventForDisplay } from "./attachment-labels.js";
+import { log } from "./log.js";
+const slog = log.scope("sse");
 /**
  * SSE heartbeat frame — a NAMED event so the frontend can hook
  * `es.addEventListener("heartbeat", ...)` and refresh its per-session
@@ -69,7 +71,7 @@ export class SseManager {
                     catch {
                         /* already torn down */
                     }
-                    this.remove(client.id);
+                    this.remove(client.id, "token-revoked");
                     continue;
                 }
                 client.res.write(SSE_HEARTBEAT_FRAME);
@@ -91,8 +93,13 @@ export class SseManager {
     /** Register a new SSE client connection. */
     add(client) {
         this.clients.set(client.id, client);
+        slog.info("connected", {
+            clientId: client.id,
+            sessionId: client.sessionId ?? "*",
+            clients: this.clients.size,
+        });
         client.res.on("close", () => {
-            this.remove(client.id);
+            this.remove(client.id, "closed");
         });
     }
     /** Write a single heartbeat frame to the given client. Used right after
@@ -109,9 +116,16 @@ export class SseManager {
             // socket already dead; res.on("close") will clean up
         }
     }
-    /** Remove a client by ID. */
-    remove(id) {
-        this.clients.delete(id);
+    /** Remove a client by ID. `reason` is recorded so an operator can tell an
+     *  ordinary disconnect apart from a write failure or a revoked token. */
+    remove(id, reason = "closed") {
+        if (this.clients.delete(id)) {
+            slog.info("disconnected", {
+                clientId: id,
+                reason,
+                clients: this.clients.size,
+            });
+        }
         this.onRemoveCallback?.(id);
     }
     /** Send an SSE event to a single client. */
@@ -138,10 +152,11 @@ export class SseManager {
         try {
             client.res.write(msg);
         }
-        catch {
+        catch (err) {
             // Socket torn down between writableEnded check and write.
             // Drop the client so we stop writing to it on every broadcast.
-            this.remove(client.id);
+            slog.warn("write failed", { clientId: client.id, err: String(err) });
+            this.remove(client.id, "write-failed");
         }
     }
     /**
@@ -159,6 +174,15 @@ export class SseManager {
             this.sendEvent(client, event);
         }
     }
+    /** Broadcast global application state regardless of a client's session filter. */
+    broadcastGlobal(event) {
+        const snapshot = [...this.clients.values()];
+        for (const client of snapshot) {
+            if (client.res.writableEnded)
+                continue;
+            this.sendEvent(client, event);
+        }
+    }
     /** Get count of connected clients. */
     get size() {
         return this.clients.size;