@hotmeshio/long-tail 0.24.0 → 0.24.1

package/build/adapters/express.d.ts

@@ -68,7 +68,9 @@ export declare class LTExpressAdapter {
     /**
      * The OAuth well-known documents. Mount at the host's root, not under the
      * base path: clients look for them at the origin. It answers only its two
-     * paths and passes everything else on.
+     * paths and passes everything else on. Warns when the issuer's path is not
+     * the base path: the router would then publish metadata for a server that
+     * is not the one mounted here, possibly over the host's own.
      */
     getWellKnownRouter(): Router;
     /** Whether a built dashboard was found to serve. */

package/build/adapters/express.js

@@ -15,6 +15,8 @@ const events_1 = require("../lib/events");
 const socketio_1 = require("../lib/events/socketio");
 const nats_1 = require("../lib/events/nats");
 const nats_ws_proxy_1 = require("../lib/events/nats-ws-proxy");
+const logger_1 = require("../lib/logger");
+const oauth_server_1 = require("../modules/oauth-server");
 /**
  * Express adapter for mounting the Long Tail dashboard at an arbitrary subpath
  * inside an existing Express-based application (NestJS, Fastify-Express, etc.).
@@ -153,9 +155,17 @@ class LTExpressAdapter {
     /**
      * The OAuth well-known documents. Mount at the host's root, not under the
      * base path: clients look for them at the origin. It answers only its two
-     * paths and passes everything else on.
+     * paths and passes everything else on. Warns when the issuer's path is not
+     * the base path: the router would then publish metadata for a server that
+     * is not the one mounted here, possibly over the host's own.
      */
     getWellKnownRouter() {
+        const settings = (0, oauth_server_1.getOAuthServerSettings)();
+        const issuerPath = settings ? new URL(settings.issuer).pathname.replace(/\/+$/, '') : null;
+        if (issuerPath !== null && issuerPath !== this.basePath) {
+            logger_1.loggerRegistry.warn(`[long-tail] OAuth issuer path "${issuerPath || '/'}" differs from the mount path "${this.basePath || '/'}"; `
+                + `set the issuer to https://<host>${this.basePath}`);
+        }
         return (0, oauth_well_known_1.createWellKnownRouter)();
     }
     /** Whether a built dashboard was found to serve. */

package/build/api/yaml-workflows/cron.d.ts

@@ -1,4 +1,4 @@
-import type { LTApiResult } from '../../types/sdk';
+import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /**
  * Set or update the cron schedule for a YAML workflow.
  *
@@ -9,6 +9,7 @@ import type { LTApiResult } from '../../types/sdk';
  * @param input.cron_schedule — cron expression (e.g. "0 * * * *")
  * @param input.cron_envelope — optional payload passed to each scheduled invocation
  * @param input.execute_as — optional identity override for scheduled executions
+ * @param auth - the scheduling caller; the run identity must be able to call every built-in tool the workflow uses
  * @returns `{ status: 200, data: YamlWorkflow }` the updated workflow record with cron fields set
  */
 export declare function setCronSchedule(input: {
@@ -16,7 +17,7 @@ export declare function setCronSchedule(input: {
     cron_schedule: string;
     cron_envelope?: any;
     execute_as?: string;
-}): Promise<LTApiResult>;
+}, auth?: LTApiAuth): Promise<LTApiResult>;
 /**
  * Remove the cron schedule from a YAML workflow.
  *

package/build/api/yaml-workflows/cron.js

@@ -38,6 +38,7 @@ exports.clearCronSchedule = clearCronSchedule;
 exports.getCronStatus = getCronStatus;
 const yamlDb = __importStar(require("../../services/yaml-workflow/db"));
 const cron_1 = require("../../services/cron");
+const deploy_1 = require("./deploy");
 const helpers_1 = require("./helpers");
 /**
  * Set or update the cron schedule for a YAML workflow.
@@ -49,14 +50,18 @@ const helpers_1 = require("./helpers");
  * @param input.cron_schedule — cron expression (e.g. "0 * * * *")
  * @param input.cron_envelope — optional payload passed to each scheduled invocation
  * @param input.execute_as — optional identity override for scheduled executions
+ * @param auth - the scheduling caller; the run identity must be able to call every built-in tool the workflow uses
  * @returns `{ status: 200, data: YamlWorkflow }` the updated workflow record with cron fields set
  */
-async function setCronSchedule(input) {
+async function setCronSchedule(input, auth) {
     try {
         const wf = await yamlDb.getYamlWorkflow(input.id);
         if (!wf) {
             return { status: 404, error: 'YAML workflow not found' };
         }
+        const refused = await (0, deploy_1.invokeRefusal)(wf, auth, input.execute_as);
+        if (refused)
+            return refused;
         if (!input.cron_schedule || typeof input.cron_schedule !== 'string') {
             return { status: 400, error: 'cron_schedule is required' };
         }

package/build/api/yaml-workflows/deploy.d.ts

@@ -1,11 +1,16 @@
 import type { LTYamlWorkflowRecord } from '../../types/yaml-workflow';
 /**
- * A compiled workflow's tool steps run with lt-system authority. Deploying or
- * activating one needs the caller to be able to call every built-in tool it
- * uses: automation never does more than its author may. Null when allowed;
- * without a caller (in-process), allowed.
+ * Deploying or activating a compiled workflow needs the caller to be able to
+ * call every built-in tool it uses: automation never does more than its
+ * author may. Null when allowed; without a caller (in-process), allowed.
  */
 export declare function deployRefusal(wf: LTYamlWorkflowRecord, auth: LTApiAuth | undefined): Promise<LTApiResult | null>;
+/**
+ * Invoking or scheduling a compiled workflow needs the identity it runs as
+ * (execute_as, else the caller) to be able to call every built-in tool it
+ * uses. Without a caller (in-process), allowed.
+ */
+export declare function invokeRefusal(wf: LTYamlWorkflowRecord, auth: LTApiAuth | undefined, executeAs?: string): Promise<LTApiResult | null>;
 import type { LTApiResult, LTApiAuth } from '../../types/sdk';
 /**
  * Deploy a YAML workflow and all sibling workflows sharing its app_id namespace.

package/build/api/yaml-workflows/deploy.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deployRefusal = deployRefusal;
+exports.invokeRefusal = invokeRefusal;
 exports.deployYamlWorkflow = deployYamlWorkflow;
 exports.activateYamlWorkflow = activateYamlWorkflow;
 exports.invokeYamlWorkflow = invokeYamlWorkflow;
@@ -45,21 +46,17 @@ const yamlWorkers = __importStar(require("../../services/yaml-workflow/workers")
 const invoke_1 = require("../../services/yaml-workflow/invoke");
 const workflow_invocation_1 = require("../../services/workflow-invocation");
 const capabilities_1 = require("../../modules/capabilities");
+const userService = __importStar(require("../../services/user"));
+const uuid_1 = require("../../lib/uuid");
 const tools_1 = require("../mcp/tools");
 /**
- * A compiled workflow's tool steps run with lt-system authority. Deploying or
- * activating one needs the caller to be able to call every built-in tool it
- * uses: automation never does more than its author may. Null when allowed;
- * without a caller (in-process), allowed.
+ * A refusal when the person cannot call every built-in tool these workflows'
+ * steps use; null when they can. Steps run as the invoker under each tool's
+ * gate, so this answers up front what the run would refuse step by step.
  */
-async function deployRefusal(wf, auth) {
-    if (!auth?.userId)
-        return null;
-    const access = (0, capabilities_1.capabilityAccess)({ userId: auth.userId });
-    // A deploy publishes every workflow sharing the app id, so every one is checked.
-    const siblings = await yamlDb.listYamlWorkflowsByAppId(wf.app_id);
-    const steps = [wf, ...siblings.filter((w) => w.id !== wf.id)].flatMap((w) => w.activity_manifest ?? []);
-    for (const step of steps) {
+async function toolStepRefusal(workflows, userId) {
+    const access = (0, capabilities_1.capabilityAccess)({ userId });
+    for (const step of workflows.flatMap((w) => w.activity_manifest ?? [])) {
         if (step.tool_source !== 'mcp' || !step.mcp_server_id || !step.mcp_tool_name)
             continue;
         const builtin = await (0, tools_1.builtinServerFor)(step.mcp_server_id);
@@ -69,6 +66,33 @@ async function deployRefusal(wf, auth) {
     }
     return null;
 }
+/**
+ * Deploying or activating a compiled workflow needs the caller to be able to
+ * call every built-in tool it uses: automation never does more than its
+ * author may. Null when allowed; without a caller (in-process), allowed.
+ */
+async function deployRefusal(wf, auth) {
+    if (!auth?.userId)
+        return null;
+    // A deploy publishes every workflow sharing the app id, so every one is checked.
+    const siblings = await yamlDb.listYamlWorkflowsByAppId(wf.app_id);
+    return toolStepRefusal([wf, ...siblings.filter((w) => w.id !== wf.id)], auth.userId);
+}
+/**
+ * Invoking or scheduling a compiled workflow needs the identity it runs as
+ * (execute_as, else the caller) to be able to call every built-in tool it
+ * uses. Without a caller (in-process), allowed.
+ */
+async function invokeRefusal(wf, auth, executeAs) {
+    if (!auth?.userId)
+        return null;
+    if (!executeAs)
+        return toolStepRefusal([wf], auth.userId);
+    const runAs = (0, uuid_1.isUuid)(executeAs) ? await userService.getUser(executeAs) : await userService.getUserByExternalId(executeAs);
+    if (!runAs)
+        return { status: 404, error: `execute_as principal "${executeAs}" not found` };
+    return toolStepRefusal([wf], runAs.id);
+}
 const helpers_1 = require("./helpers");
 /**
  * Deploy a YAML workflow and all sibling workflows sharing its app_id namespace.
@@ -189,6 +213,9 @@ async function invokeYamlWorkflow(input, auth) {
                 return { status: 403, error: 'execute_as requires an authenticated caller' };
             await (0, workflow_invocation_1.assertMayActAs)(auth.userId, input.execute_as);
         }
+        const refused = await invokeRefusal(wf, auth, input.execute_as);
+        if (refused)
+            return refused;
         const result = await (0, invoke_1.invokeYamlWorkflow)(wf, {
             data: input.data,
             sync: input.sync,

package/build/lib/db/schemas/039_nats_ws_tickets.sql

@@ -0,0 +1,12 @@
+-- Migration 039: single-use NATS WebSocket proxy tickets
+--
+-- A ticket admits one upgrade. The proxy records its id here when it is
+-- spent; a second upgrade with the same ticket finds the row and is refused.
+-- Rows are kept until the ticket expires.
+
+CREATE TABLE IF NOT EXISTS lt_nats_ws_tickets (
+  jti        TEXT PRIMARY KEY,
+  expires_at TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_lt_nats_ws_tickets_expires ON lt_nats_ws_tickets (expires_at);

package/build/lib/events/browser-view.d.ts

@@ -13,3 +13,8 @@ export declare function eventForViewer(event: LTEvent, viewer: BrowserViewer): L
 export declare function payloadForViewer(payload: Buffer, viewer: BrowserViewer): Buffer | null;
 /** Whether a person is a builder, looked up lazily to keep lib free of an import cycle. */
 export declare function viewerFor(userId: string | null | undefined): Promise<BrowserViewer>;
+/**
+ * How a connection holder sees events, or null when the account is gone or
+ * not active. Looked up lazily to keep lib free of an import cycle.
+ */
+export declare function holderView(userId: string): Promise<BrowserViewer | null>;

package/build/lib/events/browser-view.js

@@ -37,6 +37,7 @@ exports.BROWSER_ESCALATION_FIELDS = void 0;
 exports.eventForViewer = eventForViewer;
 exports.payloadForViewer = payloadForViewer;
 exports.viewerFor = viewerFor;
+exports.holderView = holderView;
 /**
  * What a browser receives of an event. Builders receive events whole. Anyone
  * else receives enough to route and refresh: escalation events keep their
@@ -47,6 +48,7 @@ exports.viewerFor = viewerFor;
  * applies only where events leave for a browser.
  */
 const ESCALATION_SUBJECT = 'system.escalation.';
+const ACTIVE_ACCOUNT = 'active';
 /** Escalation event fields a browser needs to route a refresh and follow a claim. */
 exports.BROWSER_ESCALATION_FIELDS = [
     'id', 'type', 'subtype', 'status', 'priority', 'role',
@@ -99,3 +101,17 @@ async function viewerFor(userId) {
         return { builder: false };
     }
 }
+/**
+ * How a connection holder sees events, or null when the account is gone or
+ * not active. Looked up lazily to keep lib free of an import cycle.
+ */
+async function holderView(userId) {
+    const [{ getUser, getUserByExternalId }, { isUuid }] = await Promise.all([
+        Promise.resolve().then(() => __importStar(require('../../services/user'))),
+        Promise.resolve().then(() => __importStar(require('../uuid'))),
+    ]);
+    const user = isUuid(userId) ? await getUser(userId) : await getUserByExternalId(userId);
+    if (!user || user.status !== ACTIVE_ACCOUNT)
+        return null;
+    return viewerFor(user.id);
+}

package/build/lib/events/nats-ws-filter.d.ts

@@ -5,25 +5,25 @@
  *
  * - CONNECT is rewritten to carry the server's credential (the browser is
  *   never given it), keeping the client's other options.
- * - PUB and HPUB are dropped with their payloads.
- * - SUB, UNSUB, PING and PONG pass through unchanged.
+ * - SUB, UNSUB, PING and PONG are forwarded, rebuilt from their parsed fields.
+ * - Any other operation, PUB and HPUB included, marks the stream malformed
+ *   and the proxy closes the connection.
  *
- * The NATS client protocol is line-oriented (`OP args\r\n`), and a publish is
- * followed by a payload of a declared size. Operations can span WebSocket
- * frames, so the filter keeps whatever it has not yet seen whole.
+ * The filter reads lines as nats-server does: fields split on spaces or tabs,
+ * and a line ends at LF with or without a preceding CR. Operations can span
+ * WebSocket frames, so the filter keeps whatever it has not yet seen whole.
  */
 export declare class NatsClientFilter {
     private readonly authToken;
     private pending;
-    /** Payload bytes (plus the trailing CRLF) of a dropped publish still to skip. */
-    private skip;
     private failed;
     constructor(authToken: string | null);
     /** Whether the stream was malformed; the proxy closes the connection. */
     get malformed(): boolean;
     /** The bytes to forward upstream for one chunk from the browser. */
     feed(chunk: Buffer): Buffer;
-    /** The line to forward, or null to drop it. */
+    private fail;
+    /** The line to forward, or null to forward nothing. */
     private filterLine;
     private rewriteConnect;
 }

package/build/lib/events/nats-ws-filter.js

@@ -6,23 +6,34 @@
  *
  * - CONNECT is rewritten to carry the server's credential (the browser is
  *   never given it), keeping the client's other options.
- * - PUB and HPUB are dropped with their payloads.
- * - SUB, UNSUB, PING and PONG pass through unchanged.
+ * - SUB, UNSUB, PING and PONG are forwarded, rebuilt from their parsed fields.
+ * - Any other operation, PUB and HPUB included, marks the stream malformed
+ *   and the proxy closes the connection.
  *
- * The NATS client protocol is line-oriented (`OP args\r\n`), and a publish is
- * followed by a payload of a declared size. Operations can span WebSocket
- * frames, so the filter keeps whatever it has not yet seen whole.
+ * The filter reads lines as nats-server does: fields split on spaces or tabs,
+ * and a line ends at LF with or without a preceding CR. Operations can span
+ * WebSocket frames, so the filter keeps whatever it has not yet seen whole.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NatsClientFilter = void 0;
-const CRLF = Buffer.from('\r\n');
+const LF = 0x0a;
 const MAX_LINE = 64 * 1024;
+const FIELD_DELIMITER = /[ \t]+/;
+/** The operation name and its argument text. */
+const OPERATION = /^[ \t]*([^ \t]+)[ \t]*(.*)$/s;
+/** Control characters other than tab never appear inside a client line. */
+const CONTROL_CHARACTER = /[\x00-\x08\x0a-\x1f\x7f]/;
+/** Client operations forwarded, with the number of fields each takes. */
+const ALLOWED_OPS = {
+    SUB: { min: 2, max: 3 },
+    UNSUB: { min: 1, max: 2 },
+    PING: { min: 0, max: 0 },
+    PONG: { min: 0, max: 0 },
+};
 class NatsClientFilter {
     constructor(authToken) {
         this.authToken = authToken;
         this.pending = Buffer.alloc(0);
-        /** Payload bytes (plus the trailing CRLF) of a dropped publish still to skip. */
-        this.skip = 0;
         this.failed = false;
     }
     /** Whether the stream was malformed; the proxy closes the connection. */
@@ -36,22 +47,15 @@ class NatsClientFilter {
         this.pending = this.pending.length ? Buffer.concat([this.pending, chunk]) : chunk;
         const out = [];
         for (;;) {
-            if (this.skip > 0) {
-                const n = Math.min(this.skip, this.pending.length);
-                this.pending = this.pending.subarray(n);
-                this.skip -= n;
-                if (this.skip > 0)
-                    break;
-            }
-            const end = this.pending.indexOf(CRLF);
+            const end = this.pending.indexOf(LF);
             if (end === -1) {
                 if (this.pending.length > MAX_LINE)
-                    this.failed = true;
+                    return this.fail();
                 break;
             }
-            const line = this.pending.subarray(0, end).toString('utf8');
-            this.pending = this.pending.subarray(end + CRLF.length);
-            const forwarded = this.filterLine(line);
+            const raw = this.pending.subarray(0, end > 0 && this.pending[end - 1] === 0x0d ? end - 1 : end);
+            this.pending = this.pending.subarray(end + 1);
+            const forwarded = this.filterLine(raw.toString('utf8'));
             if (this.failed)
                 return Buffer.alloc(0);
             if (forwarded !== null)
@@ -59,24 +63,31 @@ class NatsClientFilter {
         }
         return Buffer.concat(out);
     }
-    /** The line to forward, or null to drop it. */
+    fail() {
+        this.failed = true;
+        this.pending = Buffer.alloc(0);
+        return Buffer.alloc(0);
+    }
+    /** The line to forward, or null to forward nothing. */
     filterLine(line) {
-        const space = line.indexOf(' ');
-        const op = (space === -1 ? line : line.slice(0, space)).toUpperCase();
-        const args = space === -1 ? '' : line.slice(space + 1);
+        if (CONTROL_CHARACTER.test(line)) {
+            this.failed = true;
+            return null;
+        }
+        const match = OPERATION.exec(line);
+        if (!match)
+            return null;
+        const op = match[1].toUpperCase();
+        const rest = match[2];
         if (op === 'CONNECT')
-            return this.rewriteConnect(args);
-        if (op === 'PUB' || op === 'HPUB') {
-            // PUB <subject> [reply] <size>; HPUB <subject> [reply] <header size> <total size>
-            const size = Number(args.trim().split(/\s+/).pop());
-            if (!Number.isInteger(size) || size < 0) {
-                this.failed = true;
-                return null;
-            }
-            this.skip = size + CRLF.length;
+            return this.rewriteConnect(rest);
+        const shape = ALLOWED_OPS[op];
+        const fields = rest === '' ? [] : rest.split(FIELD_DELIMITER).filter(Boolean);
+        if (!shape || fields.length < shape.min || fields.length > shape.max) {
+            this.failed = true;
             return null;
         }
-        return line;
+        return [op, ...fields].join(' ');
     }
     rewriteConnect(json) {
         let options;
@@ -87,6 +98,10 @@ class NatsClientFilter {
             this.failed = true;
             return null;
         }
+        if (!options || typeof options !== 'object' || Array.isArray(options)) {
+            this.failed = true;
+            return null;
+        }
         const { auth_token: _token, user: _user, pass: _pass, jwt: _jwt, nkey: _nkey, sig: _sig, ...rest } = options;
         return `CONNECT ${JSON.stringify(this.authToken ? { ...rest, auth_token: this.authToken } : rest)}`;
     }

package/build/lib/events/nats-ws-proxy.d.ts

@@ -18,6 +18,11 @@ export declare function deriveWsUrlFromRequest(req: {
  * through an ALB or reverse proxy). This handler upgrades the connection
  * and bridges bidirectionally to the internal NATS WS target.
  *
+ * A connection needs an unspent ticket for an active account. The holder's
+ * account is rechecked every NATS_WS_RECHECK_SECONDS; a deactivation or a
+ * change in builder access closes the connection, and the dashboard
+ * reconnects with fresh credentials.
+ *
  * The proxy auto-derives the public `wsUrl` from the first incoming
  * request's headers, respecting `X-Forwarded-Proto` and `X-Forwarded-Host`
  * so the correct `wss://` scheme is used behind TLS-terminating load balancers.

package/build/lib/events/nats-ws-proxy.js

@@ -7,6 +7,7 @@ const ws_1 = require("ws");
 const logger_1 = require("../logger");
 const nats_ws_filter_1 = require("./nats-ws-filter");
 const nats_ws_server_filter_1 = require("./nats-ws-server-filter");
+const config_1 = require("../../modules/config");
 const browser_view_1 = require("./browser-view");
 const nats_ws_ticket_1 = require("./nats-ws-ticket");
 /** Default path for the NATS WebSocket proxy endpoint. */
@@ -23,6 +24,31 @@ function deriveWsUrlFromRequest(req, basePath = '') {
     const host = req.headers['x-forwarded-host'] || req.headers.host || 'localhost';
     return `${scheme}://${host}${basePath}${exports.NATS_WS_PROXY_PATH}`;
 }
+/** The path and ticket of an upgrade's request target; null when it does not parse. */
+function upgradeTarget(requestTarget) {
+    try {
+        const url = new URL(requestTarget ?? '/', 'http://proxy');
+        return { pathname: url.pathname, ticket: url.searchParams.get(nats_ws_ticket_1.NATS_WS_TICKET_PARAM) };
+    }
+    catch {
+        return null;
+    }
+}
+function refuseUpgrade(socket) {
+    socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
+    socket.destroy();
+}
+/** Whether the holder's account still stands as it did when the connection opened. */
+async function holderUnchanged(userId, viewer) {
+    try {
+        const now = await (0, browser_view_1.holderView)(userId);
+        return !!now && now.builder === viewer.builder;
+    }
+    catch (err) {
+        logger_1.loggerRegistry.warn(`[lt-nats-ws-proxy] holder recheck failed: ${err?.message}`);
+        return false;
+    }
+}
 /**
  * Attach a WebSocket proxy to an HTTP server that bridges browser
  * connections to an internal NATS WebSocket endpoint.
@@ -31,6 +57,11 @@ function deriveWsUrlFromRequest(req, basePath = '') {
  * through an ALB or reverse proxy). This handler upgrades the connection
  * and bridges bidirectionally to the internal NATS WS target.
  *
+ * A connection needs an unspent ticket for an active account. The holder's
+ * account is rechecked every NATS_WS_RECHECK_SECONDS; a deactivation or a
+ * change in builder access closes the connection, and the dashboard
+ * reconnects with fresh credentials.
+ *
  * The proxy auto-derives the public `wsUrl` from the first incoming
  * request's headers, respecting `X-Forwarded-Proto` and `X-Forwarded-Host`
  * so the correct `wss://` scheme is used behind TLS-terminating load balancers.
@@ -38,22 +69,18 @@ function deriveWsUrlFromRequest(req, basePath = '') {
 function attachNatsWsProxy(server, target, options = {}) {
     const basePath = options.basePath || '';
     const proxyPath = `${basePath}${exports.NATS_WS_PROXY_PATH}`;
-    const wss = new ws_1.WebSocketServer({ noServer: true });
+    const wss = new ws_1.WebSocketServer({ noServer: true, maxPayload: config_1.config.NATS_WS_MAX_PAYLOAD_BYTES });
     let derived = false;
-    server.on('upgrade', async (req, socket, head) => {
-        const url = new URL(req.url ?? '/', 'http://proxy');
-        if (url.pathname !== proxyPath)
-            return;
-        // Only a signed-in person, holding the ticket the credentials route issued.
-        const userId = (0, nats_ws_ticket_1.verifyNatsWsTicket)(url.searchParams.get(nats_ws_ticket_1.NATS_WS_TICKET_PARAM));
-        if (!userId) {
-            socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
-            socket.destroy();
-            return;
-        }
-        // Decided once per connection: a builder receives events whole, anyone
-        // else receives the browser view (lib/events/browser-view.ts).
-        const viewer = await (0, browser_view_1.viewerFor)(userId);
+    const admit = async (req, socket, head, ticketParam) => {
+        // Only a signed-in person, holding an unspent ticket the credentials route issued.
+        const ticket = (0, nats_ws_ticket_1.verifyNatsWsTicket)(ticketParam);
+        if (!ticket || !(await (0, nats_ws_ticket_1.spendNatsWsTicket)(ticket)))
+            return refuseUpgrade(socket);
+        // Decided per connection: a builder receives events whole, anyone else
+        // receives the browser view (lib/events/browser-view.ts).
+        const viewer = await (0, browser_view_1.holderView)(ticket.userId);
+        if (!viewer)
+            return refuseUpgrade(socket);
         if (socket.destroyed)
             return;
         // Derive the public wsUrl from the first request's headers
@@ -63,7 +90,7 @@ function attachNatsWsProxy(server, target, options = {}) {
         }
         wss.handleUpgrade(req, socket, head, (clientWs) => {
             const upstream = new ws_1.WebSocket(target);
-            // The browser reads; the proxy holds the credential and drops its publishes.
+            // The browser reads; the proxy holds the credential and refuses its publishes.
             const filter = new nats_ws_filter_1.NatsClientFilter(options.authToken ?? null);
             const inbound = viewer.builder ? null : new nats_ws_server_filter_1.NatsServerFilter((payload) => (0, browser_view_1.payloadForViewer)(payload, viewer));
             upstream.on('open', () => {
@@ -71,7 +98,7 @@ function attachNatsWsProxy(server, target, options = {}) {
                     const chunk = Buffer.isBuffer(data) ? data : Buffer.from(data);
                     const forward = filter.feed(chunk);
                     if (filter.malformed) {
-                        clientWs.close();
+                        close();
                         return;
                     }
                     if (forward.length && upstream.readyState === ws_1.WebSocket.OPEN)
@@ -90,10 +117,18 @@ function attachNatsWsProxy(server, target, options = {}) {
                         clientWs.send(forward);
                 });
             });
+            const recheck = setInterval(() => {
+                holderUnchanged(ticket.userId, viewer).then((unchanged) => {
+                    if (!unchanged)
+                        close();
+                });
+            }, config_1.config.NATS_WS_RECHECK_SECONDS * 1000);
+            recheck.unref();
             const close = () => {
+                clearInterval(recheck);
                 if (clientWs.readyState === ws_1.WebSocket.OPEN)
                     clientWs.close();
-                if (upstream.readyState === ws_1.WebSocket.OPEN)
+                if (upstream.readyState === ws_1.WebSocket.OPEN || upstream.readyState === ws_1.WebSocket.CONNECTING)
                     upstream.close();
             };
             clientWs.on('close', close);
@@ -107,6 +142,16 @@ function attachNatsWsProxy(server, target, options = {}) {
                 close();
             });
         });
+    };
+    server.on('upgrade', (req, socket, head) => {
+        // A target that does not parse is not this proxy's; other listeners may take it.
+        const upgrade = upgradeTarget(req.url);
+        if (!upgrade || upgrade.pathname !== proxyPath)
+            return;
+        admit(req, socket, head, upgrade.ticket).catch((err) => {
+            logger_1.loggerRegistry.error(`[lt-nats-ws-proxy] upgrade failed: ${err?.message}`);
+            socket.destroy();
+        });
     });
     logger_1.loggerRegistry.info(`[lt-nats-ws-proxy] active: ${proxyPath} -> ${target}`);
 }

package/build/lib/events/nats-ws-ticket.d.ts

@@ -1,10 +1,19 @@
 /**
  * A browser's pass to the NATS WebSocket proxy, in place of the NATS server
  * credential. It names the person in `sub` and carries no `userId`, so it
- * authenticates nothing but the proxy upgrade.
+ * authenticates nothing but the proxy upgrade. Each ticket admits one
+ * upgrade: the dashboard fetches a fresh one for every connection attempt.
  */
 export declare const NATS_WS_TICKET_TYPE = "nats-ws+jwt";
 export declare const NATS_WS_TICKET_PARAM = "ticket";
+export interface NatsWsTicket {
+    userId: string;
+    jti: string;
+    /** Expiry, in seconds since the epoch. */
+    exp: number;
+}
 export declare function signNatsWsTicket(userId: string): string | null;
-/** The person a valid ticket names; null for anything else. */
-export declare function verifyNatsWsTicket(ticket: string | null | undefined): string | null;
+/** The claims of a valid ticket; null for anything else. Does not spend it. */
+export declare function verifyNatsWsTicket(ticket: string | null | undefined): NatsWsTicket | null;
+/** Spend a verified ticket. False when it was already spent. */
+export declare function spendNatsWsTicket(ticket: NatsWsTicket): Promise<boolean>;