@slack/radar-mcp 1.12.0 → 1.14.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -0
- package/dist/mcp/api-paths.js +2 -0
- package/dist/mcp/flags-tools.d.ts +71 -0
- package/dist/mcp/flags-tools.js +158 -0
- package/dist/mcp/index.js +70 -2
- package/dist/mcp/sources-gate.d.ts +23 -0
- package/dist/mcp/sources-gate.js +63 -0
- package/dist/mcp/tools.js +38 -1
- package/dist/shared/db.d.ts +7 -3
- package/dist/shared/db.js +73 -18
- package/dist/shared/feature-flags.d.ts +6 -0
- package/dist/shared/feature-flags.js +17 -0
- package/dist/web/bin.js +16 -6
- package/dist/web/public/index.html +22 -0
- package/dist/web/public/next/app.js +65 -5
- package/dist/web/public/next/db.js +8 -2
- package/dist/web/public/next/feed.js +9 -2
- package/dist/web/public/next/flags.js +179 -0
- package/dist/web/public/next/registry.js +10 -1
- package/dist/web/public/next/screen.js +10 -4
- package/dist/web/public/next/store.js +104 -11
- package/dist/web/server.d.ts +150 -1
- package/dist/web/server.js +522 -19
- package/dist/web/spec.d.ts +3 -3
- package/dist/web/spec.js +9 -6
- package/package.json +1 -1
|
@@ -27,7 +27,7 @@ export function ScreenOverlay({ open, onClose }) {
|
|
|
27
27
|
// Download whatever /screen/record/stop returns, then unset recording. Shared by the
|
|
28
28
|
// explicit stop button and the close-while-recording teardown so both behave identically.
|
|
29
29
|
const stopAndSave = useCallback(async () => {
|
|
30
|
-
const r = await (await fetch("/screen/record/stop", { method: "POST" })).json().catch(() => ({}));
|
|
30
|
+
const r = await (await fetch("/screen/record/stop", { method: "POST", headers: { "X-Radar-Dashboard": "1" } })).json().catch(() => ({}));
|
|
31
31
|
setRecording(false);
|
|
32
32
|
if (!r.download)
|
|
33
33
|
return;
|
|
@@ -82,7 +82,9 @@ export function ScreenOverlay({ open, onClose }) {
|
|
|
82
82
|
}, [open, consent, caps]);
|
|
83
83
|
const accept = useCallback(async () => {
|
|
84
84
|
try {
|
|
85
|
-
|
|
85
|
+
// X-Radar-Dashboard marks this as coming from our own client. Without it the server refuses
|
|
86
|
+
// the write: consent gates mirroring the device screen, so a foreign page must not set it.
|
|
87
|
+
await fetch("/screen/consent", { method: "POST", headers: { "X-Radar-Dashboard": "1" } });
|
|
86
88
|
setConsent(true);
|
|
87
89
|
}
|
|
88
90
|
catch {
|
|
@@ -116,7 +118,7 @@ export function ScreenOverlay({ open, onClose }) {
|
|
|
116
118
|
}
|
|
117
119
|
if (!recording) {
|
|
118
120
|
setRecording(true);
|
|
119
|
-
await fetch("/screen/record/start", { method: "POST" }).catch(() => { });
|
|
121
|
+
await fetch("/screen/record/start", { method: "POST", headers: { "X-Radar-Dashboard": "1" } }).catch(() => { });
|
|
120
122
|
}
|
|
121
123
|
else {
|
|
122
124
|
await stopAndSave();
|
|
@@ -128,7 +130,11 @@ export function ScreenOverlay({ open, onClose }) {
|
|
|
128
130
|
}, [consent, caps, recording, stopAndSave]);
|
|
129
131
|
const redetect = useCallback(async () => {
|
|
130
132
|
setHint("re-detecting active panel…");
|
|
131
|
-
|
|
133
|
+
// Authored: redetect tears down the live cast and deletes finished recordings, so the server
|
|
134
|
+
// refuses it without proof this is our own client.
|
|
135
|
+
const r = await (await fetch("/screen/redetect", { headers: { "X-Radar-Dashboard": "1" } }))
|
|
136
|
+
.json()
|
|
137
|
+
.catch(() => ({}));
|
|
132
138
|
if (consent && caps && caps.liveCast && imgRef.current)
|
|
133
139
|
imgRef.current.src = streamSrc();
|
|
134
140
|
setHint("display: " + (r.display || "default"));
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { STREAM_KINDS, EAGER_CAPTURE_KINDS } from "./registry.js";
|
|
1
|
+
import { STREAM_KINDS, EAGER_CAPTURE_KINDS, isStateSource } from "./registry.js";
|
|
2
2
|
// Logcat-scale retention. At the live firehose (~400+ events/sec on the unified Live tab) a
|
|
3
3
|
// small ring recycles in seconds, so a rare signal (a once-per-5s heartbeat) gets evicted
|
|
4
4
|
// before you can filter for it. Android Studio / Flipper keep the whole session and filter
|
|
@@ -33,7 +33,24 @@ export const MODES = [
|
|
|
33
33
|
{ key: "log", label: "Logs", spec: { title: "Device Logs", summary: "Live Slack app logcat, color-coded by level. Scroll the full session buffer, select a range, copy raw lines.", source: "log", viz: ["feed", "inspector"], match: { package: "com.Slack.internal.debug" } } },
|
|
34
34
|
{ key: "db", label: "Database", spec: { title: "Device DB", summary: "Browse the on-device SQLite databases (read-only snapshot).", source: "db" } },
|
|
35
35
|
{ key: "prefs", label: "Preferences", spec: { title: "Device Preferences", summary: "Browse the on-device SharedPreferences (including feature-flag overrides), read-only.", source: "prefs" } },
|
|
36
|
+
{ key: "flags", label: "Feature Flags", spec: { title: "Feature Flags", summary: "Every feature flag the Slack app knows about, with its current effective value and whether it is locally overridden. Live-updates as flags change on the device. Filter by name.", source: "flags" } },
|
|
36
37
|
];
|
|
38
|
+
// Dashboard mode key -> the ping `sources` name that must be present for the tab to work. Only
|
|
39
|
+
// sources the device ships as plugins are gateable; the rest (network/rtm/clog/db/prefs/...)
|
|
40
|
+
// always show, and each joins this map when its device-side migration lands. Lives here next to
|
|
41
|
+
// MODES (the thing it keys off) so the two cannot drift apart in separate files.
|
|
42
|
+
export const MODE_SOURCE = {
|
|
43
|
+
trace: "traces",
|
|
44
|
+
flags: "feature_flags",
|
|
45
|
+
};
|
|
46
|
+
// True when the device serves this mode's source. Old builds declare nothing
|
|
47
|
+
// (sources null) and keep every tab.
|
|
48
|
+
export function modeServed(key, sources) {
|
|
49
|
+
if (!sources)
|
|
50
|
+
return true;
|
|
51
|
+
const required = MODE_SOURCE[key];
|
|
52
|
+
return !required || sources.includes(required);
|
|
53
|
+
}
|
|
37
54
|
// A preset is identified by what it DOES, not how it is labelled. canonicalSpecKey reduces a
|
|
38
55
|
// spec to its behavioral identity so a spec that is semantically a preset still matches it
|
|
39
56
|
// despite cosmetic drift:
|
|
@@ -73,6 +90,10 @@ export function specMatchesMode(spec) {
|
|
|
73
90
|
class Store {
|
|
74
91
|
spec = { blank: true, viz: [] };
|
|
75
92
|
conn = { state: "waiting", msg: "connecting…" };
|
|
93
|
+
// Set true once the kill button has shut the server down. The header swaps to a "dashboard
|
|
94
|
+
// stopped" state, and the poll loops are torn down so a now-dead server does not spam the
|
|
95
|
+
// console with failed fetches. Emitted as "stopped".
|
|
96
|
+
stopped = false;
|
|
76
97
|
profileLabel = "detecting…";
|
|
77
98
|
serverVersion = "";
|
|
78
99
|
profiles = [];
|
|
@@ -91,6 +112,9 @@ class Store {
|
|
|
91
112
|
// within 2s and the message vanished before the user read it. This field is owned by
|
|
92
113
|
// selectDevice, survives the health poll, and clears only on a successful pick.
|
|
93
114
|
deviceError = null;
|
|
115
|
+
// Capture-source names the device declares on ping (seam builds). null = old build with no
|
|
116
|
+
// discovery, in which case every tab shows (today's behavior). Emitted as "sources" on change.
|
|
117
|
+
deviceSources = null;
|
|
94
118
|
cache = [];
|
|
95
119
|
cacheKeys = new Set();
|
|
96
120
|
seen = {};
|
|
@@ -136,6 +160,13 @@ class Store {
|
|
|
136
160
|
_lastSerial = null;
|
|
137
161
|
_rafPending = false;
|
|
138
162
|
_intervals = [];
|
|
163
|
+
// Per-tab presence id, generated once when this Store is constructed. Rides pollProfile's 5s
|
|
164
|
+
// /health fetch (below) so the server can tell how many tabs are live and auto-close when the
|
|
165
|
+
// last one is gone. In-memory only, never persisted: a page reload naturally gets a fresh id,
|
|
166
|
+
// which is fine — the old id ages out of the server's presence map. Rides pollProfile, NOT
|
|
167
|
+
// pollHealth: pollHealth early-returns without fetching while a stream is busy (<6s since the
|
|
168
|
+
// last event), so a user actively watching a chatty stream would send zero presence signals.
|
|
169
|
+
_tabId = typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : String(Math.random()).slice(2);
|
|
139
170
|
// ---- shared detail cache (bounded FIFO) ----
|
|
140
171
|
cacheDetail(kind, id, detail) {
|
|
141
172
|
const key = kind + ":" + id;
|
|
@@ -214,6 +245,7 @@ class Store {
|
|
|
214
245
|
_resetForTest() {
|
|
215
246
|
this.spec = { blank: true, viz: [] };
|
|
216
247
|
this.conn = { state: "waiting", msg: "connecting…" };
|
|
248
|
+
this.stopped = false;
|
|
217
249
|
this.profileLabel = "detecting…";
|
|
218
250
|
this.serverVersion = "";
|
|
219
251
|
this.profiles = [];
|
|
@@ -221,6 +253,7 @@ class Store {
|
|
|
221
253
|
this.selectedDevice = null;
|
|
222
254
|
this.devicesError = false;
|
|
223
255
|
this.deviceError = null;
|
|
256
|
+
this.deviceSources = null;
|
|
224
257
|
this.cache = [];
|
|
225
258
|
this.cacheKeys = new Set();
|
|
226
259
|
this.seen = {};
|
|
@@ -252,7 +285,7 @@ class Store {
|
|
|
252
285
|
// spec.series entry, or null when the spec has no graph. Shared by applySpec (fresh spec) and
|
|
253
286
|
// clearDeviceCaches (device switch) so the two paths cannot drift.
|
|
254
287
|
buildGraph() {
|
|
255
|
-
if (this.spec.blank || this.spec.source
|
|
288
|
+
if (this.spec.blank || isStateSource(this.spec.source) || !Array.isArray(this.spec.viz) || !this.spec.viz.includes("graph") || !Array.isArray(this.spec.series)) {
|
|
256
289
|
return null;
|
|
257
290
|
}
|
|
258
291
|
return { N: GRAPH_N, series: this.spec.series.map((s) => ({ def: s, buckets: new Array(GRAPH_N).fill(0), counts: new Array(GRAPH_N).fill(0) })) };
|
|
@@ -276,6 +309,11 @@ class Store {
|
|
|
276
309
|
this.times = [];
|
|
277
310
|
this.perSec = new Array(PERSEC_N).fill(0);
|
|
278
311
|
this.graph = this.buildGraph();
|
|
312
|
+
// The old device's declared sources do not describe the new one; null until its next poll.
|
|
313
|
+
this.updateSources(null);
|
|
314
|
+
// Best-effort latency win: age the fresh-frame stamp so the next pollHealth really fetches.
|
|
315
|
+
// Backfill frames can re-freshen it within ms; pollProfile's 5s read is the backstop.
|
|
316
|
+
this._lastEventTs = 0;
|
|
279
317
|
}
|
|
280
318
|
// ---- start everything ----
|
|
281
319
|
start() {
|
|
@@ -347,7 +385,7 @@ class Store {
|
|
|
347
385
|
try {
|
|
348
386
|
const cur = await (await fetch("/spec")).json();
|
|
349
387
|
if (!cur || cur.blank) {
|
|
350
|
-
await fetch("/setspec", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(MODES[0].spec) }).catch(() => { });
|
|
388
|
+
await fetch("/setspec", { method: "POST", headers: { "Content-Type": "application/json", "X-Radar-Dashboard": "1" }, body: JSON.stringify(MODES[0].spec) }).catch(() => { });
|
|
351
389
|
}
|
|
352
390
|
}
|
|
353
391
|
catch {
|
|
@@ -361,7 +399,9 @@ class Store {
|
|
|
361
399
|
if (opts.local)
|
|
362
400
|
this.markLocalPush(spec);
|
|
363
401
|
try {
|
|
364
|
-
|
|
402
|
+
// X-Radar-Dashboard marks this as an authored write (see the server's handleSetSpec): it is
|
|
403
|
+
// what lets the write count as a keep-alive, and a foreign origin cannot forge it.
|
|
404
|
+
return await (await fetch("/setspec", { method: "POST", headers: { "Content-Type": "application/json", "X-Radar-Dashboard": "1" }, body: JSON.stringify(spec) })).json();
|
|
365
405
|
}
|
|
366
406
|
catch {
|
|
367
407
|
return { ok: false, error: "request failed" };
|
|
@@ -382,9 +422,10 @@ class Store {
|
|
|
382
422
|
this._capQueue.length = 0;
|
|
383
423
|
this.graph = this.buildGraph();
|
|
384
424
|
this.emit("spec", this.spec);
|
|
385
|
-
//
|
|
386
|
-
// point-in-time operations
|
|
387
|
-
|
|
425
|
+
// State browsers (db/prefs/flags) + blank: fully quiet the streaming engine so it does not
|
|
426
|
+
// compete with point-in-time operations (each state tab runs its own fetch/stream). Close the
|
|
427
|
+
// SSE stream AND stop the per-second tick. The 100k cache is left intact.
|
|
428
|
+
if (this.spec.blank || isStateSource(this.spec.source)) {
|
|
388
429
|
this.closeStream();
|
|
389
430
|
if (this._tick) {
|
|
390
431
|
clearInterval(this._tick);
|
|
@@ -723,6 +764,19 @@ class Store {
|
|
|
723
764
|
this.emit("db-resync", this.dbSerialVersion);
|
|
724
765
|
}
|
|
725
766
|
// ---- health + profile ----
|
|
767
|
+
// Track the device's declared capture sources (seam builds). Emits "sources" only on a real
|
|
768
|
+
// change so the modebar does not re-render every 2s poll.
|
|
769
|
+
updateSources(raw) {
|
|
770
|
+
const names = raw
|
|
771
|
+
? raw.map((s) => (typeof s?.name === "string" ? s.name : "")).filter(Boolean)
|
|
772
|
+
: null;
|
|
773
|
+
const key = names ? names.slice().sort().join(",") : null;
|
|
774
|
+
const prev = this.deviceSources ? this.deviceSources.slice().sort().join(",") : null;
|
|
775
|
+
if (key === prev)
|
|
776
|
+
return;
|
|
777
|
+
this.deviceSources = names;
|
|
778
|
+
this.emit("sources", names);
|
|
779
|
+
}
|
|
726
780
|
async pollHealth() {
|
|
727
781
|
if (Date.now() - this._lastEventTs < 6000) {
|
|
728
782
|
this._healthMisses = 0;
|
|
@@ -739,6 +793,9 @@ class Store {
|
|
|
739
793
|
// activity. Between the two, both busy and quiet observer tabs converge within 5s.
|
|
740
794
|
this.checkSerialEdge(h.device_serial ?? null);
|
|
741
795
|
if (h.device) {
|
|
796
|
+
// Only a healthy reply updates the source list: a device:false blip must not flip
|
|
797
|
+
// tabs off and back on recovery. The last list stands until the serial edge clears it.
|
|
798
|
+
this.updateSources(Array.isArray(h.sources) ? h.sources : null);
|
|
742
799
|
this._healthMisses = 0;
|
|
743
800
|
this.recovered();
|
|
744
801
|
this.setConn("connected", "");
|
|
@@ -770,9 +827,23 @@ class Store {
|
|
|
770
827
|
try {
|
|
771
828
|
const [profilesR, healthR] = await Promise.all([
|
|
772
829
|
fetch("/_control/profiles").then((r) => r.json()).catch(() => null),
|
|
773
|
-
fetch(
|
|
830
|
+
// Tab id rides THIS fetch (not pollHealth's) as the poll-only presence signal the
|
|
831
|
+
// server counts for auto-close. pollProfile fires unconditionally every 5s, so a busy
|
|
832
|
+
// stream cannot starve it the way it starves pollHealth's fresh-frame fast path. The
|
|
833
|
+
// X-Radar-Dashboard header is the same CSRF guard /shutdown requires: without it, a
|
|
834
|
+
// foreign origin's plain GET could forge presence (fake a tab open forever, or arm
|
|
835
|
+
// everSeen on an MCP-only session it should never touch). A cross-origin request cannot
|
|
836
|
+
// set a custom header without a CORS preflight it will fail.
|
|
837
|
+
fetch("/health?tab=" + encodeURIComponent(this._tabId), {
|
|
838
|
+
headers: { "X-Radar-Dashboard": "1" },
|
|
839
|
+
}).then((r) => r.json()).catch(() => null),
|
|
774
840
|
]);
|
|
775
841
|
const uid = healthR && healthR.boundUserId;
|
|
842
|
+
// pollHealth's fresh-frame fast path can skip its /health fetch indefinitely on a chatty
|
|
843
|
+
// stream; this 5s poll already fetched /health, so read the sources off it too.
|
|
844
|
+
if (healthR && healthR.device) {
|
|
845
|
+
this.updateSources(Array.isArray(healthR.sources) ? healthR.sources : null);
|
|
846
|
+
}
|
|
776
847
|
this.profiles = (profilesR && profilesR.profiles) || [];
|
|
777
848
|
if (uid == null) {
|
|
778
849
|
this.profileLabel = this._lastBoundLabel ? "last seen " + this._lastBoundLabel + " — reconnecting…" : "waiting for device…";
|
|
@@ -820,7 +891,7 @@ class Store {
|
|
|
820
891
|
// list is refreshed so the dropdown is current and the user can pick a valid device.
|
|
821
892
|
async selectDevice(serial) {
|
|
822
893
|
try {
|
|
823
|
-
const r = await fetch("/enable?device_serial=" + encodeURIComponent(serial), { method: "POST" });
|
|
894
|
+
const r = await fetch("/enable?device_serial=" + encodeURIComponent(serial), { method: "POST", headers: { "X-Radar-Dashboard": "1" } });
|
|
824
895
|
if (!r.ok && r.status === 409) {
|
|
825
896
|
const body = await r.json().catch(() => null);
|
|
826
897
|
// Surface the failure on the device chip itself, not via conn: a healthy pollHealth flips
|
|
@@ -865,14 +936,14 @@ class Store {
|
|
|
865
936
|
resyncStream() {
|
|
866
937
|
this._dropped = false;
|
|
867
938
|
const src = this.spec.source;
|
|
868
|
-
if (this.spec.blank || !src || src
|
|
939
|
+
if (this.spec.blank || !src || isStateSource(src))
|
|
869
940
|
return;
|
|
870
941
|
this.openStream();
|
|
871
942
|
this.backfill();
|
|
872
943
|
}
|
|
873
944
|
async reconnect() {
|
|
874
945
|
try {
|
|
875
|
-
const r = await fetch("/enable", { method: "POST" });
|
|
946
|
+
const r = await fetch("/enable", { method: "POST", headers: { "X-Radar-Dashboard": "1" } });
|
|
876
947
|
// 409 = ambiguous device (multiple attached, none picked). Surface the server's
|
|
877
948
|
// reason through the existing connection-status line so the user sees why enable
|
|
878
949
|
// did not connect, instead of a silent stall on "reconnecting…".
|
|
@@ -890,6 +961,28 @@ class Store {
|
|
|
890
961
|
this.pollSpec();
|
|
891
962
|
this.resyncStream();
|
|
892
963
|
}
|
|
964
|
+
// Kill the dashboard server from the header button. The X-Radar-Dashboard header is the
|
|
965
|
+
// CSRF guard the /shutdown route requires (a foreign origin's fetch cannot set it without a
|
|
966
|
+
// preflight it will fail). On success the server is going away, so tear down every poll
|
|
967
|
+
// loop + the stream: any further fetch would just fail against a dead port and spam the
|
|
968
|
+
// console. Flip `stopped` so the header renders the terminal "dashboard stopped" state.
|
|
969
|
+
async kill() {
|
|
970
|
+
try {
|
|
971
|
+
const r = await fetch("/shutdown", {
|
|
972
|
+
method: "POST",
|
|
973
|
+
headers: { "X-Radar-Dashboard": "1" },
|
|
974
|
+
});
|
|
975
|
+
if (!r.ok)
|
|
976
|
+
return false;
|
|
977
|
+
}
|
|
978
|
+
catch {
|
|
979
|
+
return false;
|
|
980
|
+
}
|
|
981
|
+
this.stop();
|
|
982
|
+
this.stopped = true;
|
|
983
|
+
this.emit("stopped", true);
|
|
984
|
+
return true;
|
|
985
|
+
}
|
|
893
986
|
}
|
|
894
987
|
// ---- aggregate math (moved here from widgets per the plan: it belongs WITH the aggregate
|
|
895
988
|
// engine, not the renderer). seriesValues turns a graph series' raw buckets into plotted
|
package/dist/web/server.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import http from "http";
|
|
2
2
|
import { type LogFrame } from "./log-session.js";
|
|
3
|
+
import { stopRecording, getLive } from "../shared/screen.js";
|
|
3
4
|
declare const WEB_PORT: number;
|
|
4
5
|
/**
|
|
5
6
|
* Decide whether to drop a log frame under backpressure. LIVE frames are dropped
|
|
@@ -29,7 +30,155 @@ export declare function seedInitialSpec(): void;
|
|
|
29
30
|
* Same post-bind discipline as seedInitialSpec: the port owner is the sole legitimate writer.
|
|
30
31
|
*/
|
|
31
32
|
export declare function cleanupOnBind(): void;
|
|
32
|
-
export declare
|
|
33
|
+
export declare const TAB_LIVENESS_MS = 75000;
|
|
34
|
+
export declare const AUTO_CLOSE_GRACE_MS: number;
|
|
35
|
+
/**
|
|
36
|
+
* Pure auto-close decision, mirroring screen.ts's nextViewerAction/shouldRelaunch precedent:
|
|
37
|
+
* the sweep owns the timestamp bookkeeping, this owns only the yes/no. Close only when there
|
|
38
|
+
* are no live tabs, at least one tab has EVER been seen (an MCP-spawned dashboard nobody has
|
|
39
|
+
* opened must never self-destruct), and the empty period has outlived the grace window.
|
|
40
|
+
* Exported for unit testing without a clock or a socket.
|
|
41
|
+
*/
|
|
42
|
+
export declare function shouldAutoClose(liveTabs: number, everSeen: boolean, msSinceEmpty: number | null): boolean;
|
|
43
|
+
export declare function touchTab(id: string, now?: number): void;
|
|
44
|
+
/**
|
|
45
|
+
* Treat an authored MCP write (a /setspec, a successful /enable) as a keep-alive equivalent to
|
|
46
|
+
* a tab being present: clear the empty marker so the idle timer never fires mid-session. NOT
|
|
47
|
+
* gated on any tab being tracked — an hour-long MCP debugging session with zero open tabs is a
|
|
48
|
+
* legitimate reason to stay up, and losing it would drop the session logcat ring, the device
|
|
49
|
+
* pin, and the pulled-DB cache. Deliberately does NOT set everSeen: an MCP-only dashboard that
|
|
50
|
+
* nobody ever opened stays protected by the everSeen guard even after the MCP goes quiet.
|
|
51
|
+
*/
|
|
52
|
+
export declare function markKeepAlive(): void;
|
|
53
|
+
/**
|
|
54
|
+
* Whether a request may buy the process more life. True for our own client and the MCP, false
|
|
55
|
+
* for anything else, so a foreign page cannot postpone auto-close forever.
|
|
56
|
+
*
|
|
57
|
+
* Two accepted proofs, both unforgeable cross-origin without a CORS preflight the foreign
|
|
58
|
+
* origin cannot satisfy: the `X-Radar-Dashboard` header `/shutdown` already requires, or an
|
|
59
|
+
* `application/json` content-type. JSON counts because every MCP version ever published sends
|
|
60
|
+
* it on `/setspec`; requiring only the header would silently strip the keep-alive from an older
|
|
61
|
+
* globally-installed MCP talking to a newer dashboard.
|
|
62
|
+
*
|
|
63
|
+
* The content-type test compares the MIME ESSENCE, never a substring. CORS safelists a
|
|
64
|
+
* content-type by its essence and ignores parameters, so `text/plain; charset=application/json`
|
|
65
|
+
* is a SIMPLE request that any page can send with no preflight while still containing the
|
|
66
|
+
* string "application/json". A substring match there would reopen the exact hole this closes.
|
|
67
|
+
*
|
|
68
|
+
* Exported so the route wiring is directly testable: the decision, not just its effect.
|
|
69
|
+
*/
|
|
70
|
+
export declare function isAuthoredRequest(headers: {
|
|
71
|
+
"x-radar-dashboard"?: string | string[];
|
|
72
|
+
"content-type"?: string | string[];
|
|
73
|
+
}): boolean;
|
|
74
|
+
/**
|
|
75
|
+
* One sweep tick: prune stale tab ids, maintain the emptySince marker across the 1->0 / 0->1
|
|
76
|
+
* transitions, and return whether the dashboard should auto-close now. Owns all timestamp
|
|
77
|
+
* bookkeeping and delegates the decision to shouldAutoClose. `now` is injectable so the
|
|
78
|
+
* transition logic is unit-testable with a fake clock. Returns true only on the tick where the
|
|
79
|
+
* grace window has elapsed with no live tabs.
|
|
80
|
+
*/
|
|
81
|
+
export declare function sweepPresence(now?: number): boolean;
|
|
82
|
+
/** Presence snapshot for tests. */
|
|
83
|
+
export declare function getPresenceState(): {
|
|
84
|
+
liveTabs: number;
|
|
85
|
+
everSeen: boolean;
|
|
86
|
+
emptySince: number | null;
|
|
87
|
+
};
|
|
88
|
+
/** Reset presence between tests (module state is a process singleton). */
|
|
89
|
+
export declare function resetPresenceForTest(): void;
|
|
90
|
+
interface ShutdownDeps {
|
|
91
|
+
getLive?: typeof getLive;
|
|
92
|
+
stopRecording?: typeof stopRecording;
|
|
93
|
+
exit?: (code: number) => void;
|
|
94
|
+
log?: (msg: string) => void;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Gracefully shut the dashboard down. Reached by the manual /shutdown route and the auto-close
|
|
98
|
+
* sweep, so the server.close + timeout-fallback exit logic lives in exactly one place. Before
|
|
99
|
+
* tearing down, if a screen recording is live, finalize it: bin.ts's exit-time cleanup SIGKILLs
|
|
100
|
+
* the cast's ffmpeg child, and an ffmpeg killed mid-write leaves an mp4 with no moov atom
|
|
101
|
+
* (unplayable). Awaiting stopRecording writes the moov and closes the file first.
|
|
102
|
+
*
|
|
103
|
+
* That mp4 safety covers THOSE TWO PATHS ONLY. bin.ts also registers this on SIGINT/SIGTERM,
|
|
104
|
+
* but screen.ts's own signal handlers exit synchronously and are registered first, so Ctrl-C
|
|
105
|
+
* never reaches here and a recording killed that way can still be corrupt. Pre-existing gap;
|
|
106
|
+
* see the bin.ts comment at the SIGINT registration for why fixing it means touching screen.ts.
|
|
107
|
+
*
|
|
108
|
+
* A second call for the same server is a no-op: the sweep tick and a manual /shutdown can both
|
|
109
|
+
* fire, and awaiting stopRecording gives the next tick a window to land mid-flight.
|
|
110
|
+
* Deps are injectable so the recording-safety path is testable without spawning ffmpeg or
|
|
111
|
+
* actually exiting the process.
|
|
112
|
+
*/
|
|
113
|
+
export declare function shutdownDashboard(server: {
|
|
114
|
+
close(cb?: () => void): void;
|
|
115
|
+
}, deps?: ShutdownDeps): Promise<void>;
|
|
116
|
+
/**
|
|
117
|
+
* Start the periodic auto-close sweep. Called once by bin.ts AFTER a successful listen bind, not
|
|
118
|
+
* from createServer, so importing this module (or spinning a throwaway server in a test) never
|
|
119
|
+
* arms a timer that could process.exit the test runner. The interval is unref'd so it never
|
|
120
|
+
* keeps the process alive on its own.
|
|
121
|
+
*/
|
|
122
|
+
export declare function startAutoCloseSweep(server: http.Server): ReturnType<typeof setInterval> | null;
|
|
123
|
+
/**
|
|
124
|
+
* Build the dashboard HTTP server. `onShutdown` is the hook the manual /shutdown route fires
|
|
125
|
+
* after answering; it defaults to the real graceful shutdown and is injectable so a test can
|
|
126
|
+
* exercise the route without exiting the process. bin.ts calls createServer() with no args.
|
|
127
|
+
*/
|
|
128
|
+
export declare function createServer(onShutdown?: (server: http.Server) => void): http.Server;
|
|
129
|
+
/**
|
|
130
|
+
* The /enable response body for a completed device probe, plus its one side effect: a
|
|
131
|
+
* successful re-arm keeps the dashboard alive (an MCP-driven session can re-enable with no tab
|
|
132
|
+
* open, and that must not let the idle timer fire out from under it).
|
|
133
|
+
*
|
|
134
|
+
* `onEnabled` fires only on a successful probe. The route passes `markKeepAlive` when the
|
|
135
|
+
* request was authored (see isAuthoredRequest) and OMITS it otherwise, so an unauthored caller
|
|
136
|
+
* gets the same body but buys no extra process life. Injected rather than called directly so
|
|
137
|
+
* the keep-alive wiring is testable without a real device probe (handleEnable's ping goes over
|
|
138
|
+
* a real socket to RADAR_HOST:RADAR_PORT, which this function does not touch at all).
|
|
139
|
+
*
|
|
140
|
+
* A failed probe gets guidance, not a bare false: the broadcast landed (or exited 0 with no
|
|
141
|
+
* receiver), so the likely causes are a build without the slack-radar modules or the wrong
|
|
142
|
+
* profile. Mirrors the MCP enable message. Exported for unit testing.
|
|
143
|
+
*/
|
|
144
|
+
/**
|
|
145
|
+
* Which keep-alive hook /enable hands to enableResultBody: the real one for an authored request,
|
|
146
|
+
* none otherwise. Its own function purely so a test can assert the CHOICE. Asserting the effect
|
|
147
|
+
* through the route cannot cover this — handleEnable's device probe fails with no hardware, which
|
|
148
|
+
* short-circuits before the hook is ever consulted, so a route-level test passes either way (a
|
|
149
|
+
* mutation deleting the gate survived the whole suite before this existed).
|
|
150
|
+
*/
|
|
151
|
+
export declare function keepAliveHookFor(authored: boolean): (() => void) | undefined;
|
|
152
|
+
/**
|
|
153
|
+
* Whether the dashboard serves this request without proof of origin. Everything else is refused
|
|
154
|
+
* unless authored. Exported so a test can drive the decision directly, and so the open surface is
|
|
155
|
+
* reviewable in one place instead of inferred from twenty route branches.
|
|
156
|
+
*
|
|
157
|
+
* Reads are open by path. Writes are closed with exactly two named exceptions, both justified
|
|
158
|
+
* below. A POST to a read path is NOT open: only GET and HEAD can ever be reads.
|
|
159
|
+
*/
|
|
160
|
+
export declare function isOpenToAnyCaller(urlPath: string, method: string | undefined): boolean;
|
|
161
|
+
/**
|
|
162
|
+
* Whether a request's Host names this loopback dashboard. The listener is bound to 127.0.0.1, but
|
|
163
|
+
* that only limits which interface accepts the TCP connection: a browser resolving an attacker's
|
|
164
|
+
* domain to 127.0.0.1 (DNS rebinding) connects locally and arrives with that domain in Host. The
|
|
165
|
+
* page is then same-origin by the browser's reckoning, so it can set any header it likes and the
|
|
166
|
+
* X-Radar-Dashboard guard buys nothing against it. Checking Host is what makes the loopback bind
|
|
167
|
+
* an actual boundary, and it matters most for /shutdown, which kills the process.
|
|
168
|
+
*
|
|
169
|
+
* Accepts localhost / 127.0.0.1 / [::1] / ::1 / 0.0.0.0, with or without a port, and a missing
|
|
170
|
+
* Host (HTTP/1.0 and a bare socket client send none; those cannot be a rebound browser).
|
|
171
|
+
*
|
|
172
|
+
* SLACK_RADAR_ALLOWED_HOSTS adds names for the setups that reach the dashboard by something other
|
|
173
|
+
* than localhost -- a /etc/hosts alias, a container or Codespaces forwarded URL, a LAN hostname.
|
|
174
|
+
* Comma-separated, `host` or `host:port`; a bare name matches on any port. Without it those users
|
|
175
|
+
* would just get a 403 with nothing to do about it.
|
|
176
|
+
*/
|
|
177
|
+
export declare function isLocalHostHeader(host: string | string[] | undefined, allowedHosts?: string | undefined): boolean;
|
|
178
|
+
export declare function enableResultBody(enabled: boolean, onEnabled?: () => void): {
|
|
179
|
+
enabled: boolean;
|
|
180
|
+
error?: string;
|
|
181
|
+
};
|
|
33
182
|
export declare const DEVICE_SOURCES: Record<string, {
|
|
34
183
|
segment: string;
|
|
35
184
|
arrayKey: string;
|