@dreb/dashboard 2.35.0

package/README.md

@@ -0,0 +1,146 @@
+# @dreb/dashboard
+
+Web dashboard for [dreb](https://github.com/aebrer/dreb) — a visual, real-time,
+mobile-friendly interface for browsing projects and sessions, controlling
+multiple dreb agents, watching background subagents live, and using dreb from
+devices that are not sitting at the host terminal.
+
+Live agent control goes through RPC: the dashboard spawns `dreb --mode rpc`
+child processes (one per live session). The server also uses dreb's public
+session APIs for on-disk inventory/delete and serves its own host file API.
+
+## Install & launch
+
+```bash
+npm install -g @dreb/dashboard
+
+# local-only (default): binds 127.0.0.1, no auth needed
+dreb-dashboard
+
+# If you installed the main dreb CLI (@dreb/coding-agent), the same server is
+# also available through:
+dreb dashboard
+
+# remote over Tailscale with HTTPS (mobile PWA + notifications)
+dreb dashboard --remote --allow you@example.com \
+  --https --cert /path/cert.pem --key /path/key.pem
+```
+
+Open `http://127.0.0.1:5343`.
+
+## Screens
+
+- **Fleet** (home) — live-first: every live session in one grid at the top
+  (stable order by project path, then session start time; each card shows its
+  project path, status chip, current activity, live subagents, task progress,
+  ctx%, model, cost, last-assistant preview). Below, past sessions grouped by project — three
+  compact rows each with an "all N on disk" expander — with resume/delete.
+  `+ new session` anywhere.
+- **Session view** — full chat parity: markdown streaming transcript, tool
+  cards, thinking blocks, compaction summaries, per-message copy, tasks panel,
+  suggest-next chip, slash-command autocomplete, image attach/paste,
+  queued-message restore, footer-parity info bar (branch, tokens, cost, ctx%,
+  median tok/s), stats/loaded-context/fork modals, steer/follow-up composer
+  modes, ■ abort, model/thinking switchers, extension-UI modals, export HTML,
+  and live auto-naming.
+- **Subagent drill-in** — read-only transcript of a background agent: live
+  events via the relay, hydrated from the agent's on-disk session log so the
+  view survives browser reloads. No composer: the parent session controls the
+  agent.
+- **Files** — host-wide browse with places shortcuts, upload (collision
+  prompts before overwrite), download, new-folder, "new session here".
+- **Settings** — persistent defaults (provider-grouped model dropdown,
+  thinking, queue modes, image handling, skill commands, nested context,
+  transport, hide-thinking, compaction/retry), per-agent model fallback editor,
+  dashboard-local preferences (thinking expansion and notification permission),
+  current pairing code, and paired-devices management.
+- **Pairing** — remote first-login rotating-code flow.
+
+## Security model — exactly two modes
+
+**Local (default).** The server binds the loopback interface only. LAN packets
+never reach the process. No login. Host/Origin headers are validated on every
+request (DNS-rebinding defense).
+
+**Remote (opt-in).** Requires [Tailscale](https://tailscale.com):
+
+```bash
+dreb-dashboard --remote --allow you@example.com
+```
+
+Enforcement layers, all fail-closed:
+
+1. Tailscale identity resolution of the peer address (`tailscale status`)
+2. Identity allowlist — empty allowlist denies everyone
+3. First-login pairing code: 6 digits, rotates every 30 seconds, shown live in
+   the dashboard Settings tab on the host machine (also printed at startup as a
+   headless fallback)
+4. Signed per-device cookie thereafter; devices are listed and unpair-able in
+   settings
+
+**There is no LAN mode.** Access from another device — even on the same LAN —
+goes through Tailscale.
+
+A paired device has the same power as sitting at the terminal: it can chat
+with agents, run commands through them, browse the host's files, and
+upload/download. Every file operation is logged server-side. Browser
+notifications are opt-in per device from settings; the tab-title attention
+badge works without permission.
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--port <n>` | Port (default 5343) |
+| `--remote` | Enable remote mode (requires Tailscale) |
+| `--allow <identity>` | Tailscale login name allowed to pair (repeatable, required with `--remote`) |
+| `--https` | Terminate TLS on the dashboard itself (native TLS, no reverse proxy, no auth-model change). Requires `--cert` and `--key`. Mainly for `--remote` (loopback is already a secure context); use `tailscale cert` files for a tailnet hostname so mobile PWAs + notifications work. Note: with `--https` the server speaks TLS only, so the host's plain-HTTP local tab (`http://127.0.0.1`) stops working — use the tailnet hostname (`https://…`) there. |
+| `--cert <path>` | PEM certificate file (required with `--https`; hot-reloaded on file change) |
+| `--key <path>` | PEM private key file (required with `--https`; hot-reloaded on file change) |
+
+## PWA + mobile notifications
+
+The dashboard is an **installable PWA** — web app manifest, service worker, and
+icon set. Install to the home screen on Android Chrome and iOS Safari 16.4+ for
+a standalone, no-URL-bar app.
+
+Needs-attention notifications go through the **service worker**
+(`registration.showNotification`) — the only path that works on Android Chrome
+(which removed the page `Notification` constructor) and on iOS (installed PWA
+only, 16.4+). The tab-title `◆` badge is the in-tab fallback. Notifications
+require a **secure context** — `localhost`/`127.0.0.1` already qualifies, so
+local-mode works with no setup. For remote access over the tailnet, enable
+native TLS (`--https --cert --key`) with `tailscale cert` files; the auth model
+is unchanged (the peer address stays the real tailnet IP). See
+`packages/coding-agent/docs/dashboard.md` for the full setup walkthrough.
+
+## Architecture
+
+```
+Browser (SolidJS, hash-routed SPA)
+  ⇄ REST + SSE (Express server, fail-closed auth middleware)
+  ⇄ RpcClient pool — one `dreb --mode rpc` child per live session
+```
+
+- Events stream over a single SSE connection carrying `{seq, key, event}`
+  envelopes; reconnects catch up via `Last-Event-ID` against a bounded ring
+  buffer (a gap triggers a `dashboard_resync` + full refetch). Deleting a
+  runtime publishes a synthetic `runtime_removed` event so clients evict that
+  session's state. Clients that stop draining the stream past a bounded
+  write buffer are disconnected and rely on reconnect catch-up.
+- Background subagent transcripts arrive over the same pipe via the
+  `background_agent_event` relay (see `docs/rpc.md` in
+  `@dreb/coding-agent`) — no session-file tailing.
+- The visual language is `tokens.css` (`src/client/styles/tokens.css`),
+  the dashboard's design system, adopted unmodified from the accepted
+  design phase.
+
+## Development
+
+```bash
+npm run build   # server (tsgo) + client (vite) → dist/
+npm test        # server, reducer, and screen smoke tests
+```
+
+See `packages/coding-agent/docs/dashboard.md` in the repo for the full
+product documentation.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * dreb-dashboard — launch the dreb web dashboard server.
+ *
+ * Modes (exactly two, no LAN mode):
+ *   default        loopback bind (127.0.0.1), no auth, no Tailscale needed
+ *   --remote       requires Tailscale; binds all interfaces but every request
+ *                  passes identity allowlist + pairing code + device cookies
+ *
+ * Usage:
+ *   dreb-dashboard [--port 5343] [--remote --allow me@example.com [--allow ...]]
+ */
+export { DashboardAuth, TailscaleStatusResolver } from "./server/auth.js";
+export { EventHub } from "./server/event-hub.js";
+export { canonicalizePath, FileApi } from "./server/files.js";
+export { FilePairingStorage, loadOrCreateDashboardSecret } from "./server/pairing-storage.js";
+export { RuntimePool, resolveDrebCliPath } from "./server/runtime-pool.js";
+export { createDashboardServer, parseDeviceCookie } from "./server/server.js";
+export type * from "./shared/protocol.js";
+interface CliArgs {
+    port: number;
+    remote: boolean;
+    allow: string[];
+    help: boolean;
+    https: boolean;
+    cert?: string;
+    key?: string;
+}
+export declare function parseArgs(argv: string[]): CliArgs;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAaH,OAAO,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,MAAM,6BAA6B,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,mBAAmB,sBAAsB,CAAC;AAI1C,UAAU,OAAO;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CA6CjD","sourcesContent":["#!/usr/bin/env node\n/**\n * dreb-dashboard — launch the dreb web dashboard server.\n *\n * Modes (exactly two, no LAN mode):\n *   default        loopback bind (127.0.0.1), no auth, no Tailscale needed\n *   --remote       requires Tailscale; binds all interfaces but every request\n *                  passes identity allowlist + pairing code + device cookies\n *\n * Usage:\n *   dreb-dashboard [--port 5343] [--remote --allow me@example.com [--allow ...]]\n */\n\nimport { existsSync, readFileSync, watch } from \"node:fs\";\nimport { createServer as createHttpServer, type Server as HttpServer } from \"node:http\";\nimport { createServer as createHttpsServer, type Server as HttpsServer } from \"node:https\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { DashboardAuth } from \"./server/auth.js\";\nimport { FilePairingStorage, loadOrCreateDashboardSecret } from \"./server/pairing-storage.js\";\nimport { RuntimePool } from \"./server/runtime-pool.js\";\nimport { createDashboardServer } from \"./server/server.js\";\n\nexport { DashboardAuth, TailscaleStatusResolver } from \"./server/auth.js\";\nexport { EventHub } from \"./server/event-hub.js\";\nexport { canonicalizePath, FileApi } from \"./server/files.js\";\nexport { FilePairingStorage, loadOrCreateDashboardSecret } from \"./server/pairing-storage.js\";\nexport { RuntimePool, resolveDrebCliPath } from \"./server/runtime-pool.js\";\nexport { createDashboardServer, parseDeviceCookie } from \"./server/server.js\";\nexport type * from \"./shared/protocol.js\";\n\nconst DEFAULT_PORT = 5343;\n\ninterface CliArgs {\n\tport: number;\n\tremote: boolean;\n\tallow: string[];\n\thelp: boolean;\n\thttps: boolean;\n\tcert?: string;\n\tkey?: string;\n}\n\nexport function parseArgs(argv: string[]): CliArgs {\n\tconst args: CliArgs = { port: DEFAULT_PORT, remote: false, allow: [], help: false, https: false };\n\tfor (let i = 0; i < argv.length; i++) {\n\t\tconst arg = argv[i];\n\t\tif (arg === \"--port\") {\n\t\t\tconst value = argv[++i];\n\t\t\tconst port = Number.parseInt(value ?? \"\", 10);\n\t\t\tif (!Number.isInteger(port) || port < 1 || port > 65535) {\n\t\t\t\tthrow new Error(`Invalid --port value: ${value}`);\n\t\t\t}\n\t\t\targs.port = port;\n\t\t} else if (arg === \"--remote\") {\n\t\t\targs.remote = true;\n\t\t} else if (arg === \"--allow\") {\n\t\t\tconst value = argv[++i];\n\t\t\tif (!value) throw new Error(\"--allow requires an identity (Tailscale login name)\");\n\t\t\targs.allow.push(value);\n\t\t} else if (arg === \"--https\") {\n\t\t\targs.https = true;\n\t\t} else if (arg === \"--cert\") {\n\t\t\tconst value = argv[++i];\n\t\t\tif (!value) throw new Error(\"--cert requires a path to a PEM certificate file\");\n\t\t\targs.cert = value;\n\t\t} else if (arg === \"--key\") {\n\t\t\tconst value = argv[++i];\n\t\t\tif (!value) throw new Error(\"--key requires a path to a PEM private key file\");\n\t\t\targs.key = value;\n\t\t} else if (arg === \"--help\" || arg === \"-h\") {\n\t\t\targs.help = true;\n\t\t} else {\n\t\t\tthrow new Error(`Unknown argument: ${arg}`);\n\t\t}\n\t}\n\tif (args.remote && args.allow.length === 0) {\n\t\tthrow new Error(\"--remote requires at least one --allow <tailscale-login> (empty allowlist denies everyone)\");\n\t}\n\t// Native TLS. `https` is opt-in; it requires cert AND key (no silent\n\t// fallback to plain HTTP). The dashboard terminates TLS itself — no reverse\n\t// proxy, no auth-model change. `req.socket.remoteAddress` stays the real\n\t// tailnet IP, so identity resolution + allowlist + pairing keep working.\n\tif (args.https) {\n\t\tif (!args.cert) throw new Error(\"--https requires --cert <path>\");\n\t\tif (!args.key) throw new Error(\"--https requires --key <path>\");\n\t}\n\treturn args;\n}\n\nconst HELP = `dreb-dashboard — dreb web dashboard server\n\nUsage: dreb-dashboard [options]\n\nOptions:\n  --port <n>          Port to listen on (default ${DEFAULT_PORT})\n  --remote            Enable remote mode (requires Tailscale). Without this\n                      flag the server binds 127.0.0.1 only — no LAN access.\n  --allow <identity>  Tailscale login name allowed to pair (repeatable;\n                      required with --remote)\n  --https             Terminate TLS on the dashboard itself (native TLS). No\n                      reverse proxy, no auth-model change. Requires --cert\n                      and --key. Mainly for --remote (loopback is already a\n                      secure context): use 'tailscale cert' files for a\n                      tailnet hostname so mobile PWAs + notifications work.\n                      NOTE: with --https the server speaks TLS only, so the\n                      host's plain-http local tab (http://127.0.0.1) stops\n                      working — use the tailnet hostname (https://...) there.\n  --cert <path>       PEM certificate file (required with --https)\n  --key <path>        PEM private key file (required with --https)\n  --help              Show this help\n`;\n\nasync function main(): Promise<void> {\n\tlet args: CliArgs;\n\ttry {\n\t\targs = parseArgs(process.argv.slice(2));\n\t} catch (err) {\n\t\tconsole.error(`error: ${err instanceof Error ? err.message : String(err)}`);\n\t\tconsole.error(HELP);\n\t\tprocess.exit(1);\n\t}\n\tif (args.help) {\n\t\tconsole.log(HELP);\n\t\treturn;\n\t}\n\n\tconst agentDir = join(homedir(), \".dreb\", \"agent\");\n\tconst auth = new DashboardAuth({\n\t\tremoteEnabled: args.remote,\n\t\tallowedIdentities: args.allow,\n\t\tstorage: new FilePairingStorage(join(agentDir, \"dashboard-pairings.json\")),\n\t\tsecret: loadOrCreateDashboardSecret(join(agentDir, \"dashboard-auth-secret\")),\n\t\tlogger: (line) => console.warn(`[dashboard-auth] ${line}`),\n\t});\n\tconst pool = new RuntimePool();\n\n\t// Static client assets live next to the compiled server (dist/static).\n\tconst staticDir = join(dirname(fileURLToPath(import.meta.url)), \"static\");\n\n\t// The server's own build version (dist/index.js → ../package.json) — surfaced\n\t// in the settings footer so a stale long-running service is spottable.\n\tlet serverVersion: string | undefined;\n\ttry {\n\t\tconst pkgPath = join(dirname(fileURLToPath(import.meta.url)), \"..\", \"package.json\");\n\t\tserverVersion = JSON.parse(readFileSync(pkgPath, \"utf8\")).version;\n\t} catch {\n\t\tserverVersion = undefined;\n\t}\n\n\t// Restart hook: exit non-zero so a supervisor (systemd Restart=on-failure,\n\t// etc.) respawns the process with the freshly-built dist. Assigned the http\n\t// server below via a mutable holder so the closure can close it first.\n\tlet httpServer: HttpServer | HttpsServer | undefined;\n\tconst onRestart = () => {\n\t\tconsole.log(\"restart requested — exiting for supervisor to respawn\");\n\t\thttpServer?.close();\n\t\tpool.stopAll().finally(() => process.exit(1));\n\t};\n\n\tconst { SessionManager } = await import(\"@dreb/coding-agent\");\n\tconst app = createDashboardServer({\n\t\tauth,\n\t\tpool,\n\t\tstaticDir: existsSync(staticDir) ? staticDir : undefined,\n\t\tserverVersion,\n\t\tonRestart,\n\t\tlistAllSessions: () => SessionManager.listAll(),\n\t\tdeleteSession: async (path: string) => {\n\t\t\tconst result = await SessionManager.deleteSession(path, {});\n\t\t\tif (!result.ok) throw new Error(result.error ?? \"Unknown deletion error\");\n\t\t\treturn { method: result.method };\n\t\t},\n\t});\n\n\tconst host = args.remote ? \"0.0.0.0\" : \"127.0.0.1\";\n\tconst scheme = args.https ? \"https\" : \"http\";\n\n\t// Native TLS: the dashboard terminates TLS itself (no reverse proxy). The\n\t// auth model is unchanged — `req.socket.remoteAddress` is still the real\n\t// tailnet IP, so Tailscale identity resolution + allowlist + pairing keep\n\t// working. Local mode never sets --https (loopback is already a secure\n\t// context), but it's allowed if the operator wants it.\n\tlet server: HttpServer | HttpsServer;\n\tif (args.https && args.cert && args.key) {\n\t\tlet tlsOptions: { cert: string; key: string };\n\t\ttry {\n\t\t\ttlsOptions = {\n\t\t\t\tcert: readFileSync(args.cert, \"utf-8\"),\n\t\t\t\tkey: readFileSync(args.key, \"utf-8\"),\n\t\t\t};\n\t\t} catch (err) {\n\t\t\tconsole.error(`error: failed to read TLS cert/key: ${err instanceof Error ? err.message : String(err)}`);\n\t\t\tprocess.exit(1);\n\t\t}\n\t\tconst httpsServer = createHttpsServer(tlsOptions, app);\n\t\t// Hot-reload the cert on file change (zero-downtime renewal — e.g. a\n\t\t// systemd timer rewrites the `tailscale cert` files daily). New\n\t\t// connections pick up the new cert; existing ones finish on the old.\n\t\tconst reloadTls = () => {\n\t\t\ttry {\n\t\t\t\thttpsServer.setSecureContext({\n\t\t\t\t\tcert: readFileSync(args.cert!, \"utf-8\"),\n\t\t\t\t\tkey: readFileSync(args.key!, \"utf-8\"),\n\t\t\t\t});\n\t\t\t\tconsole.log(\"tls certificate reloaded\");\n\t\t\t} catch (err) {\n\t\t\t\tconsole.warn(`tls reload failed (keeping old cert): ${err instanceof Error ? err.message : String(err)}`);\n\t\t\t}\n\t\t};\n\t\t// Debounce: cert + key are often rewritten in quick succession.\n\t\tlet reloadTimer: ReturnType<typeof setTimeout> | undefined;\n\t\tfor (const file of [args.cert, args.key]) {\n\t\t\twatch(file!, () => {\n\t\t\t\tif (reloadTimer) clearTimeout(reloadTimer);\n\t\t\t\treloadTimer = setTimeout(reloadTls, 500);\n\t\t\t});\n\t\t}\n\t\tserver = httpsServer;\n\t} else {\n\t\tserver = createHttpServer(app);\n\t}\n\tserver.listen(args.port, host, () => {\n\t\tconsole.log(\n\t\t\t`dreb dashboard listening on ${scheme}://${host === \"0.0.0.0\" ? \"<tailscale-ip>\" : host}:${args.port}`,\n\t\t);\n\t\tif (args.remote) {\n\t\t\tconsole.log(`remote mode: allowed identities = ${args.allow.join(\", \")}`);\n\t\t\tconst { code, expiresInMs } = auth.currentPairingCode();\n\t\t\tconsole.log(\n\t\t\t\t`pairing code: ${code} (rotates every 30s; current code rolls in ${Math.ceil(expiresInMs / 1000)}s)`,\n\t\t\t);\n\t\t\tconsole.log(\"new devices enter this code; see it live in dashboard Settings on the host machine\");\n\t\t} else {\n\t\t\tconsole.log(\"local mode: loopback only — use --remote for Tailscale access\");\n\t\t}\n\t\tif (args.https) {\n\t\t\tconsole.log(\"tls: native HTTPS enabled (cert + key hot-reload on file change)\");\n\t\t}\n\t});\n\thttpServer = server;\n\n\tconst shutdown = () => {\n\t\tconsole.log(\"shutting down…\");\n\t\tserver.close();\n\t\tpool.stopAll().finally(() => process.exit(0));\n\t};\n\tprocess.on(\"SIGINT\", shutdown);\n\tprocess.on(\"SIGTERM\", shutdown);\n}\n\n// Only run when executed directly (not when imported for the library exports).\nconst entryPath = process.argv[1];\nif (entryPath && import.meta.url === new URL(`file://${entryPath}`).href) {\n\tmain().catch((err) => {\n\t\tconsole.error(`fatal: ${err instanceof Error ? err.message : String(err)}`);\n\t\tprocess.exit(1);\n\t});\n}\n"]}

package/dist/index.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * dreb-dashboard — launch the dreb web dashboard server.
+ *
+ * Modes (exactly two, no LAN mode):
+ *   default        loopback bind (127.0.0.1), no auth, no Tailscale needed
+ *   --remote       requires Tailscale; binds all interfaces but every request
+ *                  passes identity allowlist + pairing code + device cookies
+ *
+ * Usage:
+ *   dreb-dashboard [--port 5343] [--remote --allow me@example.com [--allow ...]]
+ */
+import { existsSync, readFileSync, watch } from "node:fs";
+import { createServer as createHttpServer } from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { DashboardAuth } from "./server/auth.js";
+import { FilePairingStorage, loadOrCreateDashboardSecret } from "./server/pairing-storage.js";
+import { RuntimePool } from "./server/runtime-pool.js";
+import { createDashboardServer } from "./server/server.js";
+export { DashboardAuth, TailscaleStatusResolver } from "./server/auth.js";
+export { EventHub } from "./server/event-hub.js";
+export { canonicalizePath, FileApi } from "./server/files.js";
+export { FilePairingStorage, loadOrCreateDashboardSecret } from "./server/pairing-storage.js";
+export { RuntimePool, resolveDrebCliPath } from "./server/runtime-pool.js";
+export { createDashboardServer, parseDeviceCookie } from "./server/server.js";
+const DEFAULT_PORT = 5343;
+export function parseArgs(argv) {
+    const args = { port: DEFAULT_PORT, remote: false, allow: [], help: false, https: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--port") {
+            const value = argv[++i];
+            const port = Number.parseInt(value ?? "", 10);
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                throw new Error(`Invalid --port value: ${value}`);
+            }
+            args.port = port;
+        }
+        else if (arg === "--remote") {
+            args.remote = true;
+        }
+        else if (arg === "--allow") {
+            const value = argv[++i];
+            if (!value)
+                throw new Error("--allow requires an identity (Tailscale login name)");
+            args.allow.push(value);
+        }
+        else if (arg === "--https") {
+            args.https = true;
+        }
+        else if (arg === "--cert") {
+            const value = argv[++i];
+            if (!value)
+                throw new Error("--cert requires a path to a PEM certificate file");
+            args.cert = value;
+        }
+        else if (arg === "--key") {
+            const value = argv[++i];
+            if (!value)
+                throw new Error("--key requires a path to a PEM private key file");
+            args.key = value;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            args.help = true;
+        }
+        else {
+            throw new Error(`Unknown argument: ${arg}`);
+        }
+    }
+    if (args.remote && args.allow.length === 0) {
+        throw new Error("--remote requires at least one --allow <tailscale-login> (empty allowlist denies everyone)");
+    }
+    // Native TLS. `https` is opt-in; it requires cert AND key (no silent
+    // fallback to plain HTTP). The dashboard terminates TLS itself — no reverse
+    // proxy, no auth-model change. `req.socket.remoteAddress` stays the real
+    // tailnet IP, so identity resolution + allowlist + pairing keep working.
+    if (args.https) {
+        if (!args.cert)
+            throw new Error("--https requires --cert <path>");
+        if (!args.key)
+            throw new Error("--https requires --key <path>");
+    }
+    return args;
+}
+const HELP = `dreb-dashboard — dreb web dashboard server
+
+Usage: dreb-dashboard [options]
+
+Options:
+  --port <n>          Port to listen on (default ${DEFAULT_PORT})
+  --remote            Enable remote mode (requires Tailscale). Without this
+                      flag the server binds 127.0.0.1 only — no LAN access.
+  --allow <identity>  Tailscale login name allowed to pair (repeatable;
+                      required with --remote)
+  --https             Terminate TLS on the dashboard itself (native TLS). No
+                      reverse proxy, no auth-model change. Requires --cert
+                      and --key. Mainly for --remote (loopback is already a
+                      secure context): use 'tailscale cert' files for a
+                      tailnet hostname so mobile PWAs + notifications work.
+                      NOTE: with --https the server speaks TLS only, so the
+                      host's plain-http local tab (http://127.0.0.1) stops
+                      working — use the tailnet hostname (https://...) there.
+  --cert <path>       PEM certificate file (required with --https)
+  --key <path>        PEM private key file (required with --https)
+  --help              Show this help
+`;
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error(`error: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(HELP);
+        process.exit(1);
+    }
+    if (args.help) {
+        console.log(HELP);
+        return;
+    }
+    const agentDir = join(homedir(), ".dreb", "agent");
+    const auth = new DashboardAuth({
+        remoteEnabled: args.remote,
+        allowedIdentities: args.allow,
+        storage: new FilePairingStorage(join(agentDir, "dashboard-pairings.json")),
+        secret: loadOrCreateDashboardSecret(join(agentDir, "dashboard-auth-secret")),
+        logger: (line) => console.warn(`[dashboard-auth] ${line}`),
+    });
+    const pool = new RuntimePool();
+    // Static client assets live next to the compiled server (dist/static).
+    const staticDir = join(dirname(fileURLToPath(import.meta.url)), "static");
+    // The server's own build version (dist/index.js → ../package.json) — surfaced
+    // in the settings footer so a stale long-running service is spottable.
+    let serverVersion;
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        serverVersion = JSON.parse(readFileSync(pkgPath, "utf8")).version;
+    }
+    catch {
+        serverVersion = undefined;
+    }
+    // Restart hook: exit non-zero so a supervisor (systemd Restart=on-failure,
+    // etc.) respawns the process with the freshly-built dist. Assigned the http
+    // server below via a mutable holder so the closure can close it first.
+    let httpServer;
+    const onRestart = () => {
+        console.log("restart requested — exiting for supervisor to respawn");
+        httpServer?.close();
+        pool.stopAll().finally(() => process.exit(1));
+    };
+    const { SessionManager } = await import("@dreb/coding-agent");
+    const app = createDashboardServer({
+        auth,
+        pool,
+        staticDir: existsSync(staticDir) ? staticDir : undefined,
+        serverVersion,
+        onRestart,
+        listAllSessions: () => SessionManager.listAll(),
+        deleteSession: async (path) => {
+            const result = await SessionManager.deleteSession(path, {});
+            if (!result.ok)
+                throw new Error(result.error ?? "Unknown deletion error");
+            return { method: result.method };
+        },
+    });
+    const host = args.remote ? "0.0.0.0" : "127.0.0.1";
+    const scheme = args.https ? "https" : "http";
+    // Native TLS: the dashboard terminates TLS itself (no reverse proxy). The
+    // auth model is unchanged — `req.socket.remoteAddress` is still the real
+    // tailnet IP, so Tailscale identity resolution + allowlist + pairing keep
+    // working. Local mode never sets --https (loopback is already a secure
+    // context), but it's allowed if the operator wants it.
+    let server;
+    if (args.https && args.cert && args.key) {
+        let tlsOptions;
+        try {
+            tlsOptions = {
+                cert: readFileSync(args.cert, "utf-8"),
+                key: readFileSync(args.key, "utf-8"),
+            };
+        }
+        catch (err) {
+            console.error(`error: failed to read TLS cert/key: ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+        const httpsServer = createHttpsServer(tlsOptions, app);
+        // Hot-reload the cert on file change (zero-downtime renewal — e.g. a
+        // systemd timer rewrites the `tailscale cert` files daily). New
+        // connections pick up the new cert; existing ones finish on the old.
+        const reloadTls = () => {
+            try {
+                httpsServer.setSecureContext({
+                    cert: readFileSync(args.cert, "utf-8"),
+                    key: readFileSync(args.key, "utf-8"),
+                });
+                console.log("tls certificate reloaded");
+            }
+            catch (err) {
+                console.warn(`tls reload failed (keeping old cert): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        };
+        // Debounce: cert + key are often rewritten in quick succession.
+        let reloadTimer;
+        for (const file of [args.cert, args.key]) {
+            watch(file, () => {
+                if (reloadTimer)
+                    clearTimeout(reloadTimer);
+                reloadTimer = setTimeout(reloadTls, 500);
+            });
+        }
+        server = httpsServer;
+    }
+    else {
+        server = createHttpServer(app);
+    }
+    server.listen(args.port, host, () => {
+        console.log(`dreb dashboard listening on ${scheme}://${host === "0.0.0.0" ? "<tailscale-ip>" : host}:${args.port}`);
+        if (args.remote) {
+            console.log(`remote mode: allowed identities = ${args.allow.join(", ")}`);
+            const { code, expiresInMs } = auth.currentPairingCode();
+            console.log(`pairing code: ${code} (rotates every 30s; current code rolls in ${Math.ceil(expiresInMs / 1000)}s)`);
+            console.log("new devices enter this code; see it live in dashboard Settings on the host machine");
+        }
+        else {
+            console.log("local mode: loopback only — use --remote for Tailscale access");
+        }
+        if (args.https) {
+            console.log("tls: native HTTPS enabled (cert + key hot-reload on file change)");
+        }
+    });
+    httpServer = server;
+    const shutdown = () => {
+        console.log("shutting down…");
+        server.close();
+        pool.stopAll().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+// Only run when executed directly (not when imported for the library exports).
+const entryPath = process.argv[1];
+if (entryPath && import.meta.url === new URL(`file://${entryPath}`).href) {
+    main().catch((err) => {
+        console.error(`fatal: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n/**\n * dreb-dashboard — launch the dreb web dashboard server.\n *\n * Modes (exactly two, no LAN mode):\n *   default        loopback bind (127.0.0.1), no auth, no Tailscale needed\n *   --remote       requires Tailscale; binds all interfaces but every request\n *                  passes identity allowlist + pairing code + device cookies\n *\n * Usage:\n *   dreb-dashboard [--port 5343] [--remote --allow me@example.com [--allow ...]]\n */\n\nimport { existsSync, readFileSync, watch } from \"node:fs\";\nimport { createServer as createHttpServer, type Server as HttpServer } from \"node:http\";\nimport { createServer as createHttpsServer, type Server as HttpsServer } from \"node:https\";\nimport { homedir } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { DashboardAuth } from \"./server/auth.js\";\nimport { FilePairingStorage, loadOrCreateDashboardSecret } from \"./server/pairing-storage.js\";\nimport { RuntimePool } from \"./server/runtime-pool.js\";\nimport { createDashboardServer } from \"./server/server.js\";\n\nexport { DashboardAuth, TailscaleStatusResolver } from \"./server/auth.js\";\nexport { EventHub } from \"./server/event-hub.js\";\nexport { canonicalizePath, FileApi } from \"./server/files.js\";\nexport { FilePairingStorage, loadOrCreateDashboardSecret } from \"./server/pairing-storage.js\";\nexport { RuntimePool, resolveDrebCliPath } from \"./server/runtime-pool.js\";\nexport { createDashboardServer, parseDeviceCookie } from \"./server/server.js\";\nexport type * from \"./shared/protocol.js\";\n\nconst DEFAULT_PORT = 5343;\n\ninterface CliArgs {\n\tport: number;\n\tremote: boolean;\n\tallow: string[];\n\thelp: boolean;\n\thttps: boolean;\n\tcert?: string;\n\tkey?: string;\n}\n\nexport function parseArgs(argv: string[]): CliArgs {\n\tconst args: CliArgs = { port: DEFAULT_PORT, remote: false, allow: [], help: false, https: false };\n\tfor (let i = 0; i < argv.length; i++) {\n\t\tconst arg = argv[i];\n\t\tif (arg === \"--port\") {\n\t\t\tconst value = argv[++i];\n\t\t\tconst port = Number.parseInt(value ?? \"\", 10);\n\t\t\tif (!Number.isInteger(port) || port < 1 || port > 65535) {\n\t\t\t\tthrow new Error(`Invalid --port value: ${value}`);\n\t\t\t}\n\t\t\targs.port = port;\n\t\t} else if (arg === \"--remote\") {\n\t\t\targs.remote = true;\n\t\t} else if (arg === \"--allow\") {\n\t\t\tconst value = argv[++i];\n\t\t\tif (!value) throw new Error(\"--allow requires an identity (Tailscale login name)\");\n\t\t\targs.allow.push(value);\n\t\t} else if (arg === \"--https\") {\n\t\t\targs.https = true;\n\t\t} else if (arg === \"--cert\") {\n\t\t\tconst value = argv[++i];\n\t\t\tif (!value) throw new Error(\"--cert requires a path to a PEM certificate file\");\n\t\t\targs.cert = value;\n\t\t} else if (arg === \"--key\") {\n\t\t\tconst value = argv[++i];\n\t\t\tif (!value) throw new Error(\"--key requires a path to a PEM private key file\");\n\t\t\targs.key = value;\n\t\t} else if (arg === \"--help\" || arg === \"-h\") {\n\t\t\targs.help = true;\n\t\t} else {\n\t\t\tthrow new Error(`Unknown argument: ${arg}`);\n\t\t}\n\t}\n\tif (args.remote && args.allow.length === 0) {\n\t\tthrow new Error(\"--remote requires at least one --allow <tailscale-login> (empty allowlist denies everyone)\");\n\t}\n\t// Native TLS. `https` is opt-in; it requires cert AND key (no silent\n\t// fallback to plain HTTP). The dashboard terminates TLS itself — no reverse\n\t// proxy, no auth-model change. `req.socket.remoteAddress` stays the real\n\t// tailnet IP, so identity resolution + allowlist + pairing keep working.\n\tif (args.https) {\n\t\tif (!args.cert) throw new Error(\"--https requires --cert <path>\");\n\t\tif (!args.key) throw new Error(\"--https requires --key <path>\");\n\t}\n\treturn args;\n}\n\nconst HELP = `dreb-dashboard — dreb web dashboard server\n\nUsage: dreb-dashboard [options]\n\nOptions:\n  --port <n>          Port to listen on (default ${DEFAULT_PORT})\n  --remote            Enable remote mode (requires Tailscale). Without this\n                      flag the server binds 127.0.0.1 only — no LAN access.\n  --allow <identity>  Tailscale login name allowed to pair (repeatable;\n                      required with --remote)\n  --https             Terminate TLS on the dashboard itself (native TLS). No\n                      reverse proxy, no auth-model change. Requires --cert\n                      and --key. Mainly for --remote (loopback is already a\n                      secure context): use 'tailscale cert' files for a\n                      tailnet hostname so mobile PWAs + notifications work.\n                      NOTE: with --https the server speaks TLS only, so the\n                      host's plain-http local tab (http://127.0.0.1) stops\n                      working — use the tailnet hostname (https://...) there.\n  --cert <path>       PEM certificate file (required with --https)\n  --key <path>        PEM private key file (required with --https)\n  --help              Show this help\n`;\n\nasync function main(): Promise<void> {\n\tlet args: CliArgs;\n\ttry {\n\t\targs = parseArgs(process.argv.slice(2));\n\t} catch (err) {\n\t\tconsole.error(`error: ${err instanceof Error ? err.message : String(err)}`);\n\t\tconsole.error(HELP);\n\t\tprocess.exit(1);\n\t}\n\tif (args.help) {\n\t\tconsole.log(HELP);\n\t\treturn;\n\t}\n\n\tconst agentDir = join(homedir(), \".dreb\", \"agent\");\n\tconst auth = new DashboardAuth({\n\t\tremoteEnabled: args.remote,\n\t\tallowedIdentities: args.allow,\n\t\tstorage: new FilePairingStorage(join(agentDir, \"dashboard-pairings.json\")),\n\t\tsecret: loadOrCreateDashboardSecret(join(agentDir, \"dashboard-auth-secret\")),\n\t\tlogger: (line) => console.warn(`[dashboard-auth] ${line}`),\n\t});\n\tconst pool = new RuntimePool();\n\n\t// Static client assets live next to the compiled server (dist/static).\n\tconst staticDir = join(dirname(fileURLToPath(import.meta.url)), \"static\");\n\n\t// The server's own build version (dist/index.js → ../package.json) — surfaced\n\t// in the settings footer so a stale long-running service is spottable.\n\tlet serverVersion: string | undefined;\n\ttry {\n\t\tconst pkgPath = join(dirname(fileURLToPath(import.meta.url)), \"..\", \"package.json\");\n\t\tserverVersion = JSON.parse(readFileSync(pkgPath, \"utf8\")).version;\n\t} catch {\n\t\tserverVersion = undefined;\n\t}\n\n\t// Restart hook: exit non-zero so a supervisor (systemd Restart=on-failure,\n\t// etc.) respawns the process with the freshly-built dist. Assigned the http\n\t// server below via a mutable holder so the closure can close it first.\n\tlet httpServer: HttpServer | HttpsServer | undefined;\n\tconst onRestart = () => {\n\t\tconsole.log(\"restart requested — exiting for supervisor to respawn\");\n\t\thttpServer?.close();\n\t\tpool.stopAll().finally(() => process.exit(1));\n\t};\n\n\tconst { SessionManager } = await import(\"@dreb/coding-agent\");\n\tconst app = createDashboardServer({\n\t\tauth,\n\t\tpool,\n\t\tstaticDir: existsSync(staticDir) ? staticDir : undefined,\n\t\tserverVersion,\n\t\tonRestart,\n\t\tlistAllSessions: () => SessionManager.listAll(),\n\t\tdeleteSession: async (path: string) => {\n\t\t\tconst result = await SessionManager.deleteSession(path, {});\n\t\t\tif (!result.ok) throw new Error(result.error ?? \"Unknown deletion error\");\n\t\t\treturn { method: result.method };\n\t\t},\n\t});\n\n\tconst host = args.remote ? \"0.0.0.0\" : \"127.0.0.1\";\n\tconst scheme = args.https ? \"https\" : \"http\";\n\n\t// Native TLS: the dashboard terminates TLS itself (no reverse proxy). The\n\t// auth model is unchanged — `req.socket.remoteAddress` is still the real\n\t// tailnet IP, so Tailscale identity resolution + allowlist + pairing keep\n\t// working. Local mode never sets --https (loopback is already a secure\n\t// context), but it's allowed if the operator wants it.\n\tlet server: HttpServer | HttpsServer;\n\tif (args.https && args.cert && args.key) {\n\t\tlet tlsOptions: { cert: string; key: string };\n\t\ttry {\n\t\t\ttlsOptions = {\n\t\t\t\tcert: readFileSync(args.cert, \"utf-8\"),\n\t\t\t\tkey: readFileSync(args.key, \"utf-8\"),\n\t\t\t};\n\t\t} catch (err) {\n\t\t\tconsole.error(`error: failed to read TLS cert/key: ${err instanceof Error ? err.message : String(err)}`);\n\t\t\tprocess.exit(1);\n\t\t}\n\t\tconst httpsServer = createHttpsServer(tlsOptions, app);\n\t\t// Hot-reload the cert on file change (zero-downtime renewal — e.g. a\n\t\t// systemd timer rewrites the `tailscale cert` files daily). New\n\t\t// connections pick up the new cert; existing ones finish on the old.\n\t\tconst reloadTls = () => {\n\t\t\ttry {\n\t\t\t\thttpsServer.setSecureContext({\n\t\t\t\t\tcert: readFileSync(args.cert!, \"utf-8\"),\n\t\t\t\t\tkey: readFileSync(args.key!, \"utf-8\"),\n\t\t\t\t});\n\t\t\t\tconsole.log(\"tls certificate reloaded\");\n\t\t\t} catch (err) {\n\t\t\t\tconsole.warn(`tls reload failed (keeping old cert): ${err instanceof Error ? err.message : String(err)}`);\n\t\t\t}\n\t\t};\n\t\t// Debounce: cert + key are often rewritten in quick succession.\n\t\tlet reloadTimer: ReturnType<typeof setTimeout> | undefined;\n\t\tfor (const file of [args.cert, args.key]) {\n\t\t\twatch(file!, () => {\n\t\t\t\tif (reloadTimer) clearTimeout(reloadTimer);\n\t\t\t\treloadTimer = setTimeout(reloadTls, 500);\n\t\t\t});\n\t\t}\n\t\tserver = httpsServer;\n\t} else {\n\t\tserver = createHttpServer(app);\n\t}\n\tserver.listen(args.port, host, () => {\n\t\tconsole.log(\n\t\t\t`dreb dashboard listening on ${scheme}://${host === \"0.0.0.0\" ? \"<tailscale-ip>\" : host}:${args.port}`,\n\t\t);\n\t\tif (args.remote) {\n\t\t\tconsole.log(`remote mode: allowed identities = ${args.allow.join(\", \")}`);\n\t\t\tconst { code, expiresInMs } = auth.currentPairingCode();\n\t\t\tconsole.log(\n\t\t\t\t`pairing code: ${code} (rotates every 30s; current code rolls in ${Math.ceil(expiresInMs / 1000)}s)`,\n\t\t\t);\n\t\t\tconsole.log(\"new devices enter this code; see it live in dashboard Settings on the host machine\");\n\t\t} else {\n\t\t\tconsole.log(\"local mode: loopback only — use --remote for Tailscale access\");\n\t\t}\n\t\tif (args.https) {\n\t\t\tconsole.log(\"tls: native HTTPS enabled (cert + key hot-reload on file change)\");\n\t\t}\n\t});\n\thttpServer = server;\n\n\tconst shutdown = () => {\n\t\tconsole.log(\"shutting down…\");\n\t\tserver.close();\n\t\tpool.stopAll().finally(() => process.exit(0));\n\t};\n\tprocess.on(\"SIGINT\", shutdown);\n\tprocess.on(\"SIGTERM\", shutdown);\n}\n\n// Only run when executed directly (not when imported for the library exports).\nconst entryPath = process.argv[1];\nif (entryPath && import.meta.url === new URL(`file://${entryPath}`).href) {\n\tmain().catch((err) => {\n\t\tconsole.error(`fatal: ${err instanceof Error ? err.message : String(err)}`);\n\t\tprocess.exit(1);\n\t});\n}\n"]}

package/dist/server/auth.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Dashboard auth — exactly two modes (this file is the authority):
+ *
+ * Mode A — local-only (default): the server binds loopback only. Requests are
+ * additionally checked for loopback source address AND an allowlisted Host
+ * header (DNS-rebinding defense: a malicious website can point its own domain
+ * at 127.0.0.1 and drive the API from the victim's browser unless Host is
+ * validated). No login, no pairing.
+ *
+ * Mode B — remote (explicit opt-in): requires Tailscale. Enforcement layers,
+ * all fail-closed: (1) Tailscale identity resolution of the peer address,
+ * (2) identity allowlist (empty allowlist = deny all), (3) first-login
+ * rotating pairing code (visible only from the host/local dashboard),
+ * (4) signed per-device cookie thereafter.
+ *
+ * There is no LAN mode. Any auth-subsystem error denies the request.
+ */
+/** Normalize an address for comparison (strip IPv6-mapped IPv4 prefix and zone). */
+export declare function normalizeAddress(address: string | undefined): string;
+/** True when the (normalized) address is a loopback address. */
+export declare function isLoopbackAddress(address: string | undefined): boolean;
+/**
+ * Validate a Host header against the loopback allowlist. Rejecting foreign
+ * hosts breaks DNS rebinding: the attacker's page can reach 127.0.0.1, but its
+ * requests carry the attacker's hostname in Host.
+ */
+export declare function isAllowedLocalHost(hostHeader: string | undefined): boolean;
+export interface TailscaleIdentity {
+    /** Login name (e.g. "alice@example.com") — the allowlist unit. */
+    loginName: string;
+    /** Device host name, when known. */
+    device?: string;
+}
+export interface TailscaleResolver {
+    /** Resolve a peer IP to a Tailscale identity, or null when unknown. */
+    resolve(address: string): Promise<TailscaleIdentity | null>;
+}
+/** Resolves identities via `tailscale status --json`. Any failure resolves null (deny). */
+export declare class TailscaleStatusResolver implements TailscaleResolver {
+    resolve(address: string): Promise<TailscaleIdentity | null>;
+}
+export interface PairedDevice {
+    id: string;
+    identity: string;
+    device?: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export interface StoredPairing extends PairedDevice {
+    /** HMAC of the device token (raw token never stored). */
+    tokenHmac: string;
+}
+export interface PairingState {
+    pairings: StoredPairing[];
+    consumedPairingWindows: number[];
+}
+export interface PairingStorage {
+    load(): Promise<PairingState>;
+    save(state: PairingState): Promise<void>;
+}
+/** In-memory storage — used in tests and as the base for the file store. */
+export declare class MemoryPairingStorage implements PairingStorage {
+    private state;
+    load(): Promise<PairingState>;
+    save(state: PairingState): Promise<void>;
+}
+export interface DashboardAuthOptions {
+    /** Remote (Tailscale) mode. Default false — loopback only. */
+    remoteEnabled?: boolean;
+    /** Allowed Tailscale login names. Empty = deny all remote. */
+    allowedIdentities?: string[];
+    /** Device pairing validity. Default 30 days. */
+    pairingTtlMs?: number;
+    resolver?: TailscaleResolver;
+    storage?: PairingStorage;
+    /** HMAC/TOTP secret for device tokens and pairing codes. Production passes a per-install persisted secret. */
+    secret?: Buffer;
+    /** Failed PIN attempts before temporary lockout. Default 5. */
+    pairingMaxAttempts?: number;
+    /** Temporary lockout duration after too many failed PIN attempts. Default 60s. */
+    pairingLockoutMs?: number;
+    /** Security/audit log sink for repeated failed pairing attempts. */
+    logger?: (line: string) => void;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+export type AuthDecision = {
+    allowed: true;
+    mode: "local";
+} | {
+    allowed: true;
+    mode: "remote";
+    identity: TailscaleIdentity;
+} | {
+    allowed: false;
+    status: number;
+    reason: string;
+    /** Set when an allowed identity needs pairing-code entry. */
+    needsPairing?: boolean;
+    identity?: TailscaleIdentity;
+};
+export interface AuthRequestInfo {
+    remoteAddress: string | undefined;
+    hostHeader: string | undefined;
+    /** Origin header when present. Non-loopback origins are rejected on local requests. */
+    originHeader: string | undefined;
+    /** Value of the dashboard device cookie, when present. */
+    deviceToken: string | undefined;
+}
+export declare class DashboardAuth {
+    private readonly remoteEnabled;
+    private readonly allowedIdentities;
+    private readonly pairingTtlMs;
+    private readonly resolver;
+    private readonly storage;
+    private readonly secret;
+    private readonly pairingMaxAttempts;
+    private readonly pairingLockoutMs;
+    private readonly logger;
+    private readonly now;
+    private pairingMutation;
+    private readonly pairingFailures;
+    constructor(options?: DashboardAuthOptions);
+    get isRemoteEnabled(): boolean;
+    private hmac;
+    private pairingCodeForWindow;
+    /** Current RFC-6238-style rotating code for pairing new remote devices. */
+    currentPairingCode(): {
+        code: string;
+        expiresInMs: number;
+    };
+    private currentPairingWindow;
+    private matchingPairingCodeWindow;
+    private pruneConsumedPairingWindows;
+    private samePairingWindows;
+    private pairingFailureKey;
+    private assertPairingNotLocked;
+    private recordPairingFailure;
+    private clearPairingFailures;
+    private withPairingMutation;
+    /**
+     * Authenticate a request. Fail-closed: any resolver/storage error results in
+     * a deny, never a pass-through.
+     */
+    authenticate(info: AuthRequestInfo): Promise<AuthDecision>;
+    private authenticateInner;
+    /**
+     * Complete pairing for an allowed remote identity using the current rotating
+     * code. Returns the device token to set as a cookie. Throws (with `status`) on
+     * any failure.
+     */
+    pair(info: AuthRequestInfo, code: string): Promise<{
+        token: string;
+        device: PairedDevice;
+    }>;
+    /** List paired devices (live only). */
+    listDevices(): Promise<PairedDevice[]>;
+    /** Remove a paired device by id. Returns true when something was removed. */
+    unpair(deviceId: string): Promise<boolean>;
+    private isPaired;
+    private loadLive;
+    private loadLiveState;
+}
+//# sourceMappingURL=auth.d.ts.map