@streamotter/gateway 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orca Solutions
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @streamotter/gateway
+
+The StreamOtter Node.js gateway. It consumes Kafka (or deterministic fixtures during development), runs **your** handlers to decide identity, access, public payload, and authoritative state, and delivers state channels to browsers using [`@streamotter/client`](https://www.npmjs.com/package/@streamotter/client). Each subscription gets a snapshot, then full-state updates ordered by revision, with bounded queues and explicit `live`/`stale` states.
+
+> **Release candidate.** `0.1.0-rc.1` is published under the `next` tag. Package versions follow SemVer independently of the V1 protocol and `configVersion: 1`.
+
+```bash
+npm install @streamotter/gateway@next
+```
+
+Requires Node.js 24 or later. ESM only, with TypeScript declarations included. Kafka access uses KafkaJS 2.2.4 behind an internal adapter. Browser delivery uses Socket.IO 4.8.3 over WebSocket.
+
+Most projects run the gateway through [`@streamotter/cli`](https://www.npmjs.com/package/@streamotter/cli) (`streamotter dev` / `streamotter start`), which loads a `streamotter.json` and a handler module. The same pieces work programmatically, as shown below.
+
+## Configuration
+
+`streamotter.json` declares sources, JSON schemas, and channels. It never contains code or resolved secrets:
+
+```json
+{
+  "configVersion": 1,
+  "projectId": "orders-app",
+  "gateway": { "host": "127.0.0.1", "port": 7400, "path": "/streamotter/socket.io", "allowedOrigins": ["https://app.example.com"] },
+  "connections": {
+    "cluster": {
+      "brokers": ["kafka-1.example.com:9093"],
+      "tls": { "caFile": "certs/ca.pem" },
+      "sasl": { "mechanism": "scram-sha-512", "username": { "env": "KAFKA_USERNAME" }, "password": { "env": "KAFKA_PASSWORD" } }
+    }
+  },
+  "sources": {
+    "orders": {
+      "kind": "kafka", "generation": "orders-1", "connectionRef": "cluster", "topics": ["orders.status"],
+      "consumerGroup": "orders-app-streamotter", "codec": "json", "startFrom": "latest"
+    }
+  },
+  "schemas": {
+    "OrderParams": {
+      "type": "object", "additionalProperties": false, "required": ["orderId"],
+      "properties": { "orderId": { "type": "string", "minLength": 1, "maxLength": 64 } }
+    },
+    "OrderState": {
+      "type": "object", "additionalProperties": false, "required": ["orderId", "status", "progress"],
+      "properties": {
+        "orderId": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "status": { "type": "string", "enum": ["queued", "processing", "done"] },
+        "progress": { "type": "integer", "minimum": 0, "maximum": 100 }
+      }
+    }
+  },
+  "channels": {
+    "orderStatus": {
+      "version": 1, "source": "orders", "paramsSchema": "OrderParams", "payloadSchema": "OrderState",
+      "handlersRef": "orderStatus", "delivery": { "kind": "state", "overflow": "resync" }
+    }
+  }
+}
+```
+
+Credentials are environment references. CA paths resolve relative to the configuration file. Give each source its own consumer group, and change `generation` whenever you recreate topics or change clusters. Run `streamotter generate` to produce the `AppChannels` type used below.
+
+## Handlers
+
+| Handler | Receives | Returns |
+| --- | --- | --- |
+| `authenticate` | The browser's token and verified `Origin` | A `Principal` (`subject`, `tenantId`, `sessionId`, future `expiresAt`, `claims`), or `null` to reject |
+| `authorize` | The principal and validated channel parameters | `true` to allow. Anything else is `FORBIDDEN`. |
+| `map` | A decoded source record | The public states it produces, or `[]` to filter it out |
+| `snapshot` | The principal and parameters | `{ revision, data }`: the authoritative current state |
+
+```ts
+import type { HandlerRegistry } from "@streamotter/gateway";
+import type { AppChannels, OrderState } from "./generated/streamotter.generated.js";
+import { orders, sessions } from "./app.js"; // your application's session store and database
+
+interface OrderEvent { accountId: string; version: number; order: OrderState }
+
+export const handlers: HandlerRegistry<AppChannels> = {
+  async authenticate({ token, signal }) {
+    const session = await sessions.verify(token, signal);
+    if (session === null) return null;
+    return { subject: session.userId, tenantId: session.accountId, sessionId: session.id, expiresAt: session.expiresAt, claims: {} };
+  },
+  channels: {
+    orderStatus: {
+      authorize: ({ principal, params, signal }) => orders.isVisibleTo(principal.tenantId, principal.subject, params.orderId, signal),
+      map({ record }) {
+        const event = record.value as unknown as OrderEvent; // the Kafka value, decoded as JSON
+        return [{ tenantId: event.accountId, params: { orderId: event.order.orderId }, revision: String(event.version), data: event.order }];
+      },
+      async snapshot({ principal, params, signal }) {
+        const row = await orders.read(principal.tenantId, params.orderId, signal);
+        return { revision: String(row.version), data: row.order };
+      }
+    }
+  }
+};
+```
+
+Every handler receives an `AbortSignal` and a `requestId`. Stop work when the signal aborts: results that arrive after a timeout, unsubscribe, or revocation are ignored. A handler that throws fails closed.
+
+## The snapshot and revision contract
+
+StreamOtter can only be as correct as the state your handlers describe:
+
+- **Revisions** are canonical unsigned decimal strings (`"0"`, `"42"`, up to 39 digits), compared numerically. They increase for every change to a channel instance and never reset, even when an entity is recreated.
+- **Snapshots and mapped updates describe the same progression.** Every change newer than a snapshot must eventually reach the source, for example through a transactional outbox. The gateway captures updates before calling `snapshot` and releases only those newer than the snapshot's revision.
+- **One instance, one partition.** Changes to one channel instance must arrive in revision order from one Kafka partition (key your records by entity).
+- **Full state, not deltas.** Each update replaces the previous state. Represent deletion as explicit state. A Kafka tombstone (null value) has no delete meaning; it pauses the source like any other invalid record.
+- **Same public state for every authorized reader.** The routing identity is channel, version, the mapper's `tenantId`, and canonical parameters. Don't redact per user in `snapshot`; use separate channels or parameters for different views.
+- **Invalid records pause, never skip.** Invalid JSON, an invalid mapped payload or revision, or a handler failure pauses the source at that record, and its subscriptions go `stale`. Fix the cause, then call `gateway.resumeSource(sourceId)` to retry the same record.
+
+## Run it
+
+```ts
+import { readFile } from "node:fs/promises";
+import { createGateway, defineProject } from "@streamotter/gateway";
+import type { AppChannels } from "./generated/streamotter.generated.js";
+import { handlers } from "./handlers.js";
+
+const config = defineProject<AppChannels>(JSON.parse(await readFile("streamotter.json", "utf8")));
+const gateway = createGateway({ config, handlers, mode: "production" });
+const { origin, path } = await gateway.start();   // resolves when every source has joined its group
+console.log(`StreamOtter listening on ${origin} (${path})`);
+process.once("SIGTERM", () => void gateway.stop({ timeoutMs: 10_000 }));
+```
+
+- `defineProject` validates the configuration synchronously and throws `CONFIG_INVALID` with every issue.
+- `start()` rolls back and rejects if startup fails or takes longer than 30 seconds. A stopped gateway cannot restart; create a new one.
+- `mode: "production"` refuses fixture sources, plaintext Kafka, and the `development` option, and requires an exact browser `Origin` on every connection. `mode: "development"` accepts `development: { principals, fixtures }` for local work.
+- `configDir` (optional) is where relative CA paths resolve; it defaults to the working directory (the CLI uses the configuration file's directory). `logger` (optional) receives redacted operator diagnostics: never credentials or payloads.
+
+## Revoke access
+
+Update your durable session or authorization policy first, then tell the gateway:
+
+```ts
+await sessions.revoke(sessionId);                                        // your store: reconnecting now fails
+const { closedSubscriptions, closedConnections } =
+  await gateway.revoke({ kind: "session", tenantId, sessionId });        // or { kind: "subject", tenantId, subject }
+await gateway.revoke({ kind: "channel", tenantId, subject, channel: "orderStatus", channelVersion: 1, params: { orderId } });
+```
+
+Revocation takes effect immediately, including while `authorize` or `snapshot` is still pending. Unsent frames are dropped; bytes already sent cannot be recalled. V1 keeps no revocation database, which is why your own policy must change first.
+
+## Production boundary
+
+Run **exactly one gateway per project** (V1 has no multi-gateway coordination), behind a TLS-terminating proxy that forwards WebSocket upgrades and the browser's `Origin`. There is no management or health endpoint in production. See [Running StreamOtter](https://github.com/jfricano/StreamOtter/blob/main/docs/DEPLOYMENT.md) for the verified reverse-proxy recipe and the [Kafka support matrix](https://github.com/jfricano/StreamOtter/blob/main/docs/IMPLEMENTATION_STATUS.md#kafka-support-matrix-kafkajs-224--apache-kafka-412): TLS, and TLS with SASL PLAIN and SCRAM-SHA-256/512, are verified against Apache Kafka 4.1.2. Other broker versions and managed services are unverified.
+
+`@streamotter/gateway/management` is the development-only management API used by `streamotter dev`; it refuses production gateways. `@streamotter/gateway/internals` exists for StreamOtter's own CLI and is not a stable API.
+
+## More
+
+- [V1 API specification](https://github.com/jfricano/StreamOtter/blob/main/docs/V1_API.md): handlers and lifecycle (§3), synchronization (§5), source progress and limits (§6), access (§7)
+- [Reference application](https://github.com/jfricano/StreamOtter/tree/main/examples/order-dashboard): fixture and Kafka handlers for a real app
+- [Repository](https://github.com/jfricano/StreamOtter) · [Issues](https://github.com/jfricano/StreamOtter/issues)
+
+MIT License © 2026 Orca Solutions

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+import { type ChannelMap, type Gateway, type GatewayOptions, type ProjectConfig } from "@streamotter/contracts";
+export type * from "@streamotter/contracts";
+export { StreamOtterError, validateProjectConfig } from "@streamotter/contracts";
+export { consoleLogger, silentLogger } from "./runtime/util.ts";
+/**
+ * Validates configuration structure and references synchronously. Secret
+ * resolution and connectivity belong to gateway startup. Throws CONFIG_INVALID.
+ */
+export declare function defineProject<C extends ChannelMap>(config: ProjectConfig<C>): ProjectConfig<C>;
+/** Constructs a gateway without opening connections; call start() to listen and consume. */
+export declare function createGateway<C extends ChannelMap>(options: GatewayOptions<C>): Gateway;
+//# 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":"AAAA,OAAO,EAA4B,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAG1I,mBAAmB,wBAAwB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAG9F;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,OAAO,CAEvF"}

package/dist/index.js

@@ -0,0 +1,17 @@
+import { assertValidProjectConfig } from "@streamotter/contracts";
+import { createGatewayRuntime } from "./runtime/gateway.js";
+export { StreamOtterError, validateProjectConfig } from "@streamotter/contracts";
+export { consoleLogger, silentLogger } from "./runtime/util.js";
+/**
+ * Validates configuration structure and references synchronously. Secret
+ * resolution and connectivity belong to gateway startup. Throws CONFIG_INVALID.
+ */
+export function defineProject(config) {
+    assertValidProjectConfig(config);
+    return config;
+}
+/** Constructs a gateway without opening connections; call start() to listen and consume. */
+export function createGateway(options) {
+    return createGatewayRuntime(options).gateway;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAA0E,MAAM,wBAAwB,CAAC;AAC1I,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEhE;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAuB,MAAwB;IAC1E,wBAAwB,CAAC,MAAM,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,aAAa,CAAuB,OAA0B;IAC5E,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC;AAC/C,CAAC"}

package/dist/internals.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Internal access shared by StreamOtter's own CLI, management server, and tests.
+ * Not a stable public API; applications should use createGateway().
+ */
+export { createGatewayRuntime, getGatewayInternals, type GatewayInternals, type InternalGatewayOptions } from "./runtime/gateway.ts";
+//# sourceMappingURL=internals.d.ts.map

package/dist/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,KAAK,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/internals.js

@@ -0,0 +1,6 @@
+/**
+ * Internal access shared by StreamOtter's own CLI, management server, and tests.
+ * Not a stable public API; applications should use createGateway().
+ */
+export { createGatewayRuntime, getGatewayInternals } from "./runtime/gateway.js";
+//# sourceMappingURL=internals.js.map

package/dist/internals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.js","sourceRoot":"","sources":["../src/internals.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAsD,MAAM,sBAAsB,CAAC"}

package/dist/management/index.d.ts

@@ -0,0 +1,26 @@
+import { type Gateway } from "@streamotter/contracts";
+import { type GatewayInternals } from "../runtime/gateway.ts";
+export interface ManagementServerOptions {
+    gateway: Gateway;
+    /** Loopback by default. */
+    host?: string;
+    port?: number;
+    /** Per-run bearer token; generated when omitted. */
+    token?: string;
+    /** Built workbench assets to serve from the same origin; null disables the UI. */
+    workbenchDir?: string | null;
+}
+export interface ManagementServer {
+    readonly origin: string;
+    readonly token: string;
+    close(): Promise<void>;
+}
+/**
+ * Local development management API and workbench host. Every /management/v1
+ * operation requires the per-run bearer token. Browser requests must carry the
+ * exact workbench Origin (or, for same-origin GETs, a same-origin Referer). No
+ * CORS is ever granted. Refuses to start for production gateways.
+ */
+export declare function startManagementServer(options: ManagementServerOptions): Promise<ManagementServer>;
+export type { GatewayInternals };
+//# sourceMappingURL=index.d.ts.map

package/dist/management/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/management/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAEkC,KAAK,OAAO,EACpD,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGnF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA0FD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqPvG;AAED,YAAY,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/management/index.js

@@ -0,0 +1,354 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { extname, join, resolve as resolvePath, sep } from "node:path";
+import { canonicalJsonPretty, CAPABILITIES, DEFAULT_MANAGEMENT_PORT, isPlainObject, streamError, StreamOtterError, validateProjectConfig } from "@streamotter/contracts";
+import { getGatewayInternals } from "../runtime/gateway.js";
+import { newId, sha256Hex, TokenBucket } from "../runtime/util.js";
+const MAX_BODY_BYTES = 1_048_576;
+const STATUS_BY_CODE = {
+    INVALID_REQUEST: 400, INVALID_PARAMS: 400, CONFIG_INVALID: 400, UNSUPPORTED_CAPABILITY: 400,
+    UNAUTHENTICATED: 401, FORBIDDEN: 403, CHANNEL_NOT_FOUND: 404, TRACE_CURSOR_EXPIRED: 410,
+    OVERLOADED: 429, SOURCE_UNAVAILABLE: 503, TIMEOUT: 504
+};
+const CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8"
+};
+class HttpError extends Error {
+    status;
+    error;
+    constructor(status, code, message, details) {
+        super(message ?? code);
+        this.status = status;
+        const options = {};
+        if (message !== undefined)
+            options.message = message;
+        if (details !== undefined)
+            options.details = details;
+        this.error = streamError(code, options);
+    }
+}
+function tokensEqual(expected, provided) {
+    const a = Buffer.from(expected);
+    const b = Buffer.from(provided);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+async function readJsonBody(request) {
+    const declared = Number(request.headers["content-length"] ?? "0");
+    if (declared > MAX_BODY_BYTES)
+        throw new HttpError(413, "INVALID_REQUEST", "The request body exceeds 1 MiB.");
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES)
+            throw new HttpError(413, "INVALID_REQUEST", "The request body exceeds 1 MiB.");
+        chunks.push(chunk);
+    }
+    if (size === 0)
+        throw new HttpError(400, "INVALID_REQUEST", "A JSON body is required.");
+    const type = request.headers["content-type"] ?? "";
+    if (!/^application\/json\b/i.test(type))
+        throw new HttpError(400, "INVALID_REQUEST", "Content-Type must be application/json.");
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        throw new HttpError(400, "INVALID_REQUEST", "The body is not valid JSON.");
+    }
+}
+/** Requires an object with exactly the listed keys (optional keys may be absent). */
+function shape(value, required, optional = []) {
+    if (!isPlainObject(value))
+        throw new HttpError(400, "INVALID_REQUEST", "The body must be a JSON object.");
+    for (const key of Object.keys(value)) {
+        if (!required.includes(key) && !optional.includes(key))
+            throw new HttpError(400, "INVALID_REQUEST", `Unknown field "${key.slice(0, 64)}".`);
+    }
+    for (const key of required) {
+        if (!Object.hasOwn(value, key))
+            throw new HttpError(400, "INVALID_REQUEST", `"${key}" is required.`);
+    }
+    return value;
+}
+function requireString(value, name) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 256)
+        throw new HttpError(400, "INVALID_REQUEST", `${name} must be a non-empty string.`);
+    return value;
+}
+function mapError(error) {
+    if (error instanceof HttpError)
+        return { status: error.status, error: error.error };
+    if (error instanceof StreamOtterError) {
+        const status = typeof error.details?.["status"] === "number" ? error.details["status"] : STATUS_BY_CODE[error.code] ?? 500;
+        const { status: _omit, ...details } = (error.details ?? {});
+        const options = { message: error.message, retryable: error.retryable };
+        if (Object.keys(details).length > 0)
+            options.details = details;
+        return { status, error: streamError(error.code, options) };
+    }
+    return { status: 500, error: streamError("INTERNAL") };
+}
+/**
+ * Local development management API and workbench host. Every /management/v1
+ * operation requires the per-run bearer token. Browser requests must carry the
+ * exact workbench Origin (or, for same-origin GETs, a same-origin Referer). No
+ * CORS is ever granted. Refuses to start for production gateways.
+ */
+export async function startManagementServer(options) {
+    const internals = getGatewayInternals(options.gateway);
+    if (internals.mode !== "development") {
+        throw new StreamOtterError("FORBIDDEN", { message: "The management API is only available in development mode." });
+    }
+    const token = options.token ?? randomBytes(24).toString("base64url");
+    const host = options.host ?? "127.0.0.1";
+    const workbenchDir = options.workbenchDir === undefined || options.workbenchDir === null ? null : await realpath(options.workbenchDir).catch(() => null);
+    const bucket = new TokenBucket(100, 200);
+    let origin = "";
+    const server = createServer((request, response) => {
+        const requestId = newId();
+        response.setHeader("X-Request-Id", requestId);
+        response.setHeader("Cache-Control", "no-store");
+        response.setHeader("X-Content-Type-Options", "nosniff");
+        response.setHeader("Referrer-Policy", "same-origin");
+        response.setHeader("X-Frame-Options", "DENY");
+        handle(request, response, requestId).catch(error => {
+            const mapped = mapError(error);
+            if (mapped.status === 500)
+                internals.logger.error("Management request failed", { requestId, error: String(error?.name ?? "Error") });
+            send(response, mapped.status, { ok: false, requestId, error: { ...mapped.error, requestId } });
+        });
+    });
+    function send(response, status, body) {
+        if (response.headersSent) {
+            response.end();
+            return;
+        }
+        response.statusCode = status;
+        response.setHeader("Content-Type", "application/json; charset=utf-8");
+        response.end(JSON.stringify(body));
+    }
+    function checkBrowserOrigin(request) {
+        const requestOrigin = request.headers.origin;
+        if (requestOrigin !== undefined) {
+            if (requestOrigin !== origin)
+                throw new HttpError(403, "FORBIDDEN", "Cross-origin management requests are not allowed.");
+            return;
+        }
+        const referer = request.headers.referer;
+        if (referer !== undefined) {
+            if (request.method !== "GET" || !(referer === origin || referer.startsWith(`${origin}/`))) {
+                throw new HttpError(403, "FORBIDDEN", "Cross-origin management requests are not allowed.");
+            }
+        }
+    }
+    function query(url, allowed) {
+        const values = {};
+        for (const [key, value] of url.searchParams) {
+            if (!allowed.includes(key))
+                throw new HttpError(400, "INVALID_REQUEST", `Unknown query parameter "${key.slice(0, 64)}".`);
+            if (Object.hasOwn(values, key))
+                throw new HttpError(400, "INVALID_REQUEST", `Duplicate query parameter "${key.slice(0, 64)}".`);
+            values[key] = value;
+        }
+        return values;
+    }
+    async function handle(request, response, requestId) {
+        const url = new URL(request.url ?? "/", "http://management.invalid");
+        if (!url.pathname.startsWith("/management/")) {
+            await serveStatic(request, response, url.pathname);
+            return;
+        }
+        checkBrowserOrigin(request);
+        const authorization = request.headers.authorization ?? "";
+        const provided = /^Bearer (.+)$/.exec(authorization)?.[1] ?? "";
+        if (!tokensEqual(token, provided))
+            throw new HttpError(401, "UNAUTHENTICATED", "A valid management bearer token is required.");
+        if (!bucket.take())
+            throw new HttpError(429, "OVERLOADED", "Too many management requests.");
+        const route = `${request.method ?? "GET"} ${url.pathname}`;
+        const ok = (data) => send(response, 200, { ok: true, requestId, data });
+        const noQuery = () => query(url, []);
+        switch (route) {
+            case "GET /management/v1/capabilities":
+                noQuery();
+                return ok(CAPABILITIES);
+            case "GET /management/v1/health":
+                noQuery();
+                return ok(internals.health());
+            case "GET /management/v1/sources":
+                noQuery();
+                return ok({ items: internals.sources() });
+            case "GET /management/v1/channels":
+                noQuery();
+                return ok({ items: internals.channels() });
+            case "GET /management/v1/config":
+                noQuery();
+                return ok({ config: internals.config, fingerprint: internals.fingerprint });
+            case "GET /management/v1/traces": {
+                const q = query(url, ["limit", "cursor", "sourceId", "channel", "outcome"]);
+                let limit = 100;
+                if (q["limit"] !== undefined) {
+                    if (!/^\d{1,3}$/.test(q["limit"]))
+                        throw new HttpError(400, "INVALID_REQUEST", "limit must be an integer from 1 to 500.");
+                    limit = Number(q["limit"]);
+                    if (limit < 1 || limit > 500)
+                        throw new HttpError(400, "INVALID_REQUEST", "limit must be an integer from 1 to 500.");
+                }
+                const outcome = q["outcome"];
+                if (outcome !== undefined && !["ok", "filtered", "rejected", "failed"].includes(outcome)) {
+                    throw new HttpError(400, "INVALID_REQUEST", "outcome must be ok, filtered, rejected, or failed.");
+                }
+                const page = internals.traces({
+                    limit,
+                    ...(q["cursor"] === undefined ? {} : { cursor: q["cursor"] }),
+                    ...(q["sourceId"] === undefined ? {} : { sourceId: q["sourceId"] }),
+                    ...(q["channel"] === undefined ? {} : { channel: q["channel"] }),
+                    ...(outcome === undefined ? {} : { outcome: outcome })
+                });
+                return ok(page);
+            }
+            case "GET /management/v1/dev/principals":
+                noQuery();
+                return ok({ items: internals.developmentPrincipals() });
+            default:
+                break;
+        }
+        if (request.method !== "POST")
+            throw new HttpError(404, "INVALID_REQUEST", "Unknown management route.");
+        noQuery();
+        const body = await readJsonBody(request);
+        switch (route) {
+            case "POST /management/v1/source-checks": {
+                const sourceId = requireString(shape(body, ["sourceId"])["sourceId"], "sourceId");
+                return ok({ steps: await internals.checkSource(sourceId) });
+            }
+            case "POST /management/v1/config/validate": {
+                const { config } = shape(body, ["config"]);
+                return ok(validateProjectConfig(config));
+            }
+            case "POST /management/v1/config/export": {
+                const { config } = shape(body, ["config"]);
+                const validation = validateProjectConfig(config);
+                if (!validation.valid) {
+                    throw new HttpError(400, "CONFIG_INVALID", "The configuration is invalid and was not exported.", {
+                        issues: validation.issues.map(issue => ({ path: issue.path, code: issue.code, message: issue.message }))
+                    });
+                }
+                return ok({ filename: "streamotter.json", content: canonicalJsonPretty(config), fingerprint: sha256Hex(config) });
+            }
+            case "POST /management/v1/sources/resume": {
+                const sourceId = requireString(shape(body, ["sourceId"])["sourceId"], "sourceId");
+                return ok(await internals.resumeSource(sourceId));
+            }
+            case "POST /management/v1/preview-sessions": {
+                const ref = requireString(shape(body, ["fixturePrincipalRef"])["fixturePrincipalRef"], "fixturePrincipalRef");
+                return ok(internals.createPreviewSession(ref));
+            }
+            case "POST /management/v1/dev/fixtures/advance": {
+                const fields = shape(body, ["sourceId", "count"]);
+                const sourceId = requireString(fields["sourceId"], "sourceId");
+                const count = fields["count"];
+                if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 1 || count > 100) {
+                    throw new HttpError(400, "INVALID_REQUEST", "count must be an integer from 1 to 100.");
+                }
+                return ok({ advanced: await internals.advanceFixture(sourceId, count) });
+            }
+            case "POST /management/v1/dev/disconnect": {
+                const previewSessionId = requireString(shape(body, ["previewSessionId"])["previewSessionId"], "previewSessionId");
+                internals.disconnectPreviewSession(previewSessionId);
+                return ok(null);
+            }
+            default:
+                throw new HttpError(404, "INVALID_REQUEST", "Unknown management route.");
+        }
+    }
+    async function serveStatic(request, response, pathname) {
+        if (workbenchDir === null || (request.method !== "GET" && request.method !== "HEAD")) {
+            response.statusCode = 404;
+            response.end();
+            return;
+        }
+        let decoded;
+        try {
+            decoded = decodeURIComponent(pathname);
+        }
+        catch {
+            response.statusCode = 400;
+            response.end();
+            return;
+        }
+        const relative = decoded === "/" ? "index.html" : decoded.replace(/^\/+/, "");
+        const file = resolvePath(workbenchDir, relative);
+        if (!file.startsWith(workbenchDir + sep) || relative.includes("\0")) {
+            response.statusCode = 404;
+            response.end();
+            return;
+        }
+        let target = file;
+        try {
+            const info = await stat(target);
+            if (info.isDirectory())
+                target = join(target, "index.html");
+            const real = await realpath(target);
+            if (!real.startsWith(workbenchDir + sep))
+                throw new Error("outside");
+            let content = await readFile(real);
+            if (extname(real) === ".html") {
+                // Tell the workbench where the gateway listens (not secret; the token is never embedded).
+                const address = internals.address();
+                const escape = (value) => value.replace(/[&"<>]/g, character => `&#${character.charCodeAt(0)};`);
+                const meta = address === null ? "" :
+                    `<meta name="streamotter-gateway-origin" content="${escape(address.origin)}"><meta name="streamotter-gateway-path" content="${escape(address.path)}">`;
+                content = content.toString("utf8").replace("</head>", `${meta}</head>`);
+            }
+            response.statusCode = 200;
+            response.setHeader("Content-Type", CONTENT_TYPES[extname(real)] ?? "application/octet-stream");
+            const gatewayOrigin = internals.address()?.origin ?? "";
+            const socketOrigin = gatewayOrigin.replace(/^http/, "ws");
+            response.setHeader("Content-Security-Policy", [
+                "default-src 'self'",
+                `connect-src 'self' ${gatewayOrigin} ${socketOrigin}`.trim(),
+                "img-src 'self' data:",
+                "style-src 'self'",
+                "script-src 'self'",
+                "frame-ancestors 'none'",
+                "base-uri 'none'",
+                "form-action 'none'"
+            ].join("; "));
+            response.end(request.method === "HEAD" ? undefined : content);
+        }
+        catch {
+            response.statusCode = 404;
+            response.end();
+        }
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port ?? DEFAULT_MANAGEMENT_PORT, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    origin = `http://${host.includes(":") ? `[${host}]` : host}:${address.port}`;
+    internals.allowDevelopmentOrigin(origin);
+    let closing = null;
+    const close = () => {
+        closing ??= new Promise(resolve => {
+            server.close(() => resolve());
+            server.closeAllConnections();
+        });
+        return closing;
+    };
+    internals.onStop(close);
+    return { origin, token, close };
+}
+//# sourceMappingURL=index.js.map