@plingjs/surface-gateway 0.1.0-alpha.5 → 0.1.0-alpha.6

package/dist/README.md

@@ -0,0 +1,178 @@
+# @plingjs/surface-gateway
+
+Reference Node.js transport and control plane for a Pling Agent Surface. It
+connects an open business page to a user-owned Agent runtime without moving page
+execution or business permissions into the gateway.
+
+```text
+Agent runtime (Codex / Claude / Hermes / WorkBuddy)
+        │ MCP over HTTPS (Bearer Agent session token)
+        ▼
+surface.example.com
+        │ opaque describe / invoke envelopes over WebSocket
+        ▼
+business page (the page the user already has open)
+        │
+        ▼
+application backend + existing authorization
+```
+
+The gateway is deliberately narrow:
+
+- it authenticates a page session created by the application backend;
+- it binds a one-time pairing code to one Agent session;
+- it forwards `describe`, `invoke`, approval-pending, and final responses;
+- it enforces session TTLs, Agent scope, revocation, expiry, and audit callbacks;
+- it never exposes DOM, `click(selector)`, script evaluation, cookies, or provider keys.
+
+The page's Surface session remains the capability and approval authority. The
+application backend remains the business authorization authority.
+
+## Install
+
+Node.js 20.12 or newer is required.
+
+```bash
+npm install @plingjs/surface-gateway
+```
+
+Run the bundled reference server:
+
+```bash
+SURFACE_ADMIN_TOKEN="$(openssl rand -hex 32)" npx pling-surface-gateway
+```
+
+It listens on `http://127.0.0.1:5219` and uses the bundled
+`config.example.json`. For a real deployment, create your own JSON config and set:
+
+```bash
+SURFACE_CONFIG=/etc/pling/surface.json
+SURFACE_ADMIN_TOKEN=<server-side secret>
+SURFACE_PUBLIC_BASE_URL=https://surface.example.com
+SURFACE_HOST=127.0.0.1
+SURFACE_PORT=5219
+```
+
+Set `SURFACE_TRUST_PROXY=1` only when a trusted reverse proxy overwrites
+`X-Forwarded-For`. If the gateway is directly reachable, leave it disabled or a
+client can forge its rate-limit identity.
+
+`SURFACE_ADMIN_TOKEN` is server-to-server only. Never put it in browser code,
+an MCP server configuration, logs, or a public repository.
+
+## Library API
+
+```js
+import {
+  createSurfaceGateway,
+  createSurfaceServer,
+  loadConfig,
+} from "@plingjs/surface-gateway";
+
+const config = await loadConfig("./surface.json");
+const server = createSurfaceServer({
+  config,
+  adminToken: process.env.SURFACE_ADMIN_TOKEN,
+  publicBaseUrl: "https://surface.example.com",
+  host: "127.0.0.1",
+  port: 5219,
+});
+
+await server.start();
+// server.gateway exposes the control-plane API for tests or custom transports.
+```
+
+The package also exports `createSurfaceGateway`, `createMcpHandler`,
+`normalizeConfig`, `GatewayError`, and `ConfigError`. TypeScript declarations are
+included.
+
+## Application flow
+
+1. The business backend verifies the signed-in user and calls
+   `POST /v1/page-sessions` with the narrow set of capability ids that page may
+   expose. It returns a short-lived page token to that page only.
+2. The page opens `WS /surface?token=...`, sends a `pling.bridge/0.1` hello, and
+   keeps its existing Pling Surface session active.
+3. The page calls `POST /v1/pairings` to display a one-time code. Pairing is
+   refused unless the page WebSocket is connected and the `Origin` is allowed for
+   its tenant.
+4. The user gives the code to their Agent runtime. The runtime claims it at
+   `POST /v1/agent-sessions` and receives an Agent token and MCP URL.
+5. The Agent configures `https://surface.example.com/mcp` with
+   `Authorization: Bearer <agent token>`. It first calls
+   `pling_surface_describe`, then `pling_surface_invoke`.
+6. If the page requires human confirmation, the gateway returns
+   `pending_approval`. The user confirms in the business page. The Agent polls
+   `pling_surface_approval_status`; there is no approval tool and no way for the
+   Agent to approve its own request.
+
+Pairing codes are single-use, expire after two minutes by default, and contain
+48 random bits. Agent `invoke` calls are checked against both the page session
+scope and the narrowed Agent scope.
+
+## HTTP routes
+
+| Method | Route | Authentication | Purpose |
+| --- | --- | --- | --- |
+| `GET` | `/health` | public | Liveness only |
+| `GET` | `/v1/discovery/:tenantId` | public | Draft discovery metadata |
+| `POST` | `/v1/page-sessions` | admin Bearer | Create a page session after the application has authenticated the user |
+| `POST` | `/v1/demo/page-sessions` | configured Origin | Create a rate-limited public-demo page session |
+| `POST` | `/v1/pairings` | page token + Origin | Create a one-time pairing code |
+| `POST` | `/v1/agent-sessions` | pairing code | Claim a pairing and receive an Agent token |
+| `POST` | `/v1/agent-sessions/revoke` | page token + Origin | Let the signed-in page revoke its Agent |
+| `GET` | `/admin/sessions` | admin Bearer | Inspect live sessions |
+| `DELETE` | `/admin/page-sessions/:id` | admin Bearer | Revoke a page and all of its Agents |
+| `DELETE` | `/admin/agent-sessions/:id` | admin Bearer | Revoke one Agent session |
+| `POST` | `/mcp` | Agent Bearer | JSON-RPC MCP endpoint (JSON response mode) |
+| `WS` | `/surface?token=...` | page token + Origin | Page transport for Surface envelopes |
+
+## MCP tools
+
+- `pling_surface_describe` reads the paired page's current capabilities,
+  records, regions, state, and feedback.
+- `pling_surface_invoke` invokes one capability returned by `describe`.
+- `pling_surface_approval_status` reads the final state of an earlier invocation.
+
+The Agent token is bound to the active HTTP request. It is not a model-visible
+tool argument, and tool arguments cannot override it.
+
+## Scope matching
+
+Scopes follow `@plingjs/surface` semantics:
+
+- `add_task` also covers `add_task:row` and `add_task@row` families;
+- `delete@` covers concrete ids such as `delete@task`;
+- `delete@task` does not cover the broader `delete@` family;
+- `*` is accepted only when the page session itself allows `*`.
+
+## Production boundary
+
+This package is a reference implementation, not an enterprise control plane.
+Its default stores are in memory. Before exposing it to untrusted traffic:
+
+- terminate TLS at a reverse proxy and bind Node to loopback;
+- use scoped, per-tenant admin credentials instead of one global control token;
+- put shared rate limiting and abuse detection in front of pairing and MCP;
+- persist session metadata and audit events in the application's system of record;
+- connect approval receipts to the application's approval backend;
+- configure one pairing per user/page, short Agent TTLs, and explicit scopes;
+- monitor failed pairing, repeated auth failures, revocations, and approval latency.
+
+The gateway cannot stop an Agent that already owns the browser through CDP from
+clicking the page directly. Its security value is that declared operations have
+identity, scope, confirmation, and audit evidence, while business authorization
+stays in the backend.
+
+## Test
+
+```bash
+pnpm --filter @plingjs/surface-gateway test
+pnpm --filter @plingjs/surface-gateway check
+```
+
+Source and issues: [github.com/plingjs/pling](https://github.com/plingjs/pling).
+
+## License
+
+Apache-2.0.

package/dist/bin/surface-gateway.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { cliHelp, PACKAGE_VERSION, runSurfaceGatewayCli } from "../index.mjs";
+
+const args = new Set(process.argv.slice(2));
+if (args.has("--help") || args.has("-h")) {
+  process.stdout.write(cliHelp());
+  process.exit(0);
+}
+if (args.has("--version") || args.has("-v")) {
+  process.stdout.write(`${PACKAGE_VERSION}\n`);
+  process.exit(0);
+}
+
+try {
+  await runSurfaceGatewayCli();
+} catch (error) {
+  process.stderr.write(`[surface-gateway] ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/dist/config.example.json

@@ -0,0 +1,33 @@
+{
+  "tenants": [
+    {
+      "id": "demo",
+      "displayName": "Pling Todo Demo",
+      "origins": [
+        "http://127.0.0.1:5220",
+        "http://localhost:5220",
+        "http://127.0.0.1:5191",
+        "http://localhost:5191",
+        "https://todo.plingjs.dev",
+        "https://plingjs.dev"
+      ],
+      "maxPageSessionTtlMs": 86400000,
+      "maxAgentSessionTtlMs": 86400000,
+      "publicDemo": {
+        "origins": ["http://127.0.0.1:5191", "http://localhost:5191", "https://plingjs.dev"],
+        "scope": [
+          "todo.overview",
+          "todo.add",
+          "todo.update",
+          "todo.toggle",
+          "todo.delete",
+          "todo.clear_completed"
+        ],
+        "pageSessionTtlMs": 86400000,
+        "maxSessionsPerWindow": 30,
+        "windowMs": 600000,
+        "maxActiveSessions": 40
+      }
+    }
+  ]
+}

package/dist/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@plingjs/surface-gateway",
+  "version": "0.1.0-alpha.6",
+  "description": "Reference Node gateway for Pling Agent Surface: page sessions, pairing, MCP, scopes, revocation, and audit.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/plingjs/pling.git",
+    "directory": "packages/surface-gateway"
+  },
+  "homepage": "https://plingjs.dev",
+  "bugs": "https://github.com/plingjs/pling/issues",
+  "type": "module",
+  "main": "./index.mjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "default": "./index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "pling-surface-gateway": "./bin/surface-gateway.mjs"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=20.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/dist/version.mjs

@@ -0,0 +1 @@
+export const PACKAGE_VERSION = "0.1.0-alpha.6";

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@plingjs/surface-gateway",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.6",
+  "private": false,
+  "type": "module",
   "description": "Reference Node gateway for Pling Agent Surface: page sessions, pairing, MCP, scopes, revocation, and audit.",
   "license": "Apache-2.0",
   "repository": {
@@ -10,28 +12,31 @@
   },
   "homepage": "https://plingjs.dev",
   "bugs": "https://github.com/plingjs/pling/issues",
-  "type": "module",
-  "main": "./index.mjs",
-  "module": "./index.mjs",
-  "types": "./index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs",
-      "default": "./index.mjs"
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "bin": {
     "pling-surface-gateway": "./bin/surface-gateway.mjs"
   },
+  "scripts": {
+    "build": "node ../../scripts/build-surface-gateway.mjs",
+    "prepack": "pnpm build",
+    "start": "node bin/surface-gateway.mjs",
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check src/index.mjs && node --check src/gateway.mjs && node --check src/server.mjs && node --check src/mcp.mjs && node --check src/config.mjs && node --check src/errors.mjs && node --check src/cli.mjs && node --check src/version.mjs && node --check bin/surface-gateway.mjs"
+  },
   "dependencies": {
     "ws": "^8.18.0"
   },
   "engines": {
     "node": ">=20.12"
-  },
-  "publishConfig": {
-    "access": "public"
   }
-}
+}

package/src/cli.mjs

@@ -0,0 +1,132 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { ConfigError, loadConfig } from "./config.mjs";
+import { createSurfaceServer } from "./server.mjs";
+
+/**
+ * The same module runs from `src/` during workspace development and from the
+ * package root after publishing. Resolve both layouts instead of assuming one.
+ */
+export function resolveDefaultConfig(moduleUrl) {
+  const candidates = [
+    new URL("../config.example.json", moduleUrl),
+    new URL("./config.example.json", moduleUrl),
+  ];
+  return fileURLToPath(candidates.find((candidate) => existsSync(candidate)) ?? candidates[0]);
+}
+
+const DEFAULT_CONFIG = resolveDefaultConfig(import.meta.url);
+
+/**
+ * Start the gateway from environment variables.
+ *
+ * This function is also used by the thin deployment wrapper in services/. It
+ * installs SIGINT/SIGTERM handlers by default so a container can stop cleanly.
+ */
+export async function runSurfaceGatewayCli(options = {}) {
+  const env = options.env ?? process.env;
+  const stderr = options.stderr ?? process.stderr;
+  const configPath = env.SURFACE_CONFIG?.trim() || DEFAULT_CONFIG;
+  const adminToken = env.SURFACE_ADMIN_TOKEN?.trim();
+  const publicBaseUrl = env.SURFACE_PUBLIC_BASE_URL?.trim() || undefined;
+  const host = env.SURFACE_HOST?.trim() || "127.0.0.1";
+  const port = numberFromEnv(env, "SURFACE_PORT", 5219);
+  const demoTenantId = env.SURFACE_DEMO_TENANT_ID?.trim() || "demo";
+  const trustProxy = booleanFromEnv(env, "SURFACE_TRUST_PROXY", false);
+
+  if (!adminToken) {
+    throw new ConfigError(
+      "SURFACE_ADMIN_TOKEN_REQUIRED",
+      "SURFACE_ADMIN_TOKEN is required. It creates page sessions and reads admin state; never expose it to browsers.",
+    );
+  }
+
+  const config = await loadConfig(configPath);
+  const server = createSurfaceServer({
+    config,
+    adminToken,
+    publicBaseUrl,
+    host,
+    port,
+    demoTenantId,
+    trustProxy,
+  });
+
+  let address;
+  try {
+    address = await server.start();
+  } catch (error) {
+    throw new ConfigError(
+      "SURFACE_START_FAILED",
+      `Failed to start Surface Gateway: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  stderr.write(`[surface-gateway] config ${configPath}\n`);
+  stderr.write(`[surface-gateway] page WebSocket ${address.baseUrl.replace(/^http/, "ws")}/surface\n`);
+  stderr.write(`[surface-gateway] remote MCP ${address.baseUrl}/mcp\n`);
+
+  let stopping = false;
+  async function stop(signal = "shutdown") {
+    if (stopping) return;
+    stopping = true;
+    stderr.write(`[surface-gateway] ${signal}: stopping\n`);
+    removeSignalHandlers();
+    await server.stop();
+  }
+
+  const onSigint = () => void stop("SIGINT").catch((error) => handleStopFailure(stderr, error));
+  const onSigterm = () => void stop("SIGTERM").catch((error) => handleStopFailure(stderr, error));
+  process.once("SIGINT", onSigint);
+  process.once("SIGTERM", onSigterm);
+
+  function removeSignalHandlers() {
+    process.off("SIGINT", onSigint);
+    process.off("SIGTERM", onSigterm);
+  }
+
+  return { server, config, configPath, ...address, stop };
+}
+
+export function cliHelp() {
+  return [
+    "Pling Surface Gateway",
+    "",
+    "Usage: pling-surface-gateway",
+    "",
+    "Required environment:",
+    "  SURFACE_ADMIN_TOKEN       Server-to-server admin token",
+    "",
+    "Optional environment:",
+    "  SURFACE_CONFIG            JSON config path (default: bundled config.example.json)",
+    "  SURFACE_PUBLIC_BASE_URL   Public origin used in generated URLs",
+    "  SURFACE_HOST              Listen host (default: 127.0.0.1)",
+    "  SURFACE_PORT              Listen port (default: 5219)",
+    "  SURFACE_DEMO_TENANT_ID    Tenant used by the public demo route (default: demo)",
+    "  SURFACE_TRUST_PROXY       Set to 1 only behind a trusted proxy that overwrites X-Forwarded-For",
+    "",
+  ].join("\n");
+}
+
+function numberFromEnv(env, name, fallback) {
+  const value = env[name];
+  if (!value) return fallback;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 1 || number > 65535) {
+    throw new ConfigError("CONFIG_INVALID", `${name} must be a TCP port between 1 and 65535.`);
+  }
+  return number;
+}
+
+function booleanFromEnv(env, name, fallback) {
+  const value = env[name]?.trim().toLowerCase();
+  if (!value) return fallback;
+  if (["1", "true", "yes", "on"].includes(value)) return true;
+  if (["0", "false", "no", "off"].includes(value)) return false;
+  throw new ConfigError("CONFIG_INVALID", `${name} must be 1/0, true/false, yes/no, or on/off.`);
+}
+
+function handleStopFailure(stderr, error) {
+  stderr.write(`[surface-gateway] shutdown failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/src/config.mjs

@@ -0,0 +1,214 @@
+import { readFile } from "node:fs/promises";
+
+const MAX_SCOPE_ENTRIES = 256;
+
+export class ConfigError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "ConfigError";
+    this.code = code;
+  }
+}
+
+export async function loadConfig(file) {
+  let raw;
+  try {
+    raw = JSON.parse(await readFile(file, "utf8"));
+  } catch (error) {
+    throw new ConfigError(
+      "CONFIG_READ_FAILED",
+      `Cannot read Surface Gateway config ${file}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  return normalizeConfig(raw);
+}
+
+export function normalizeConfig(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw) || !Array.isArray(raw.tenants)) {
+    throw new ConfigError("CONFIG_INVALID", "Config must be an object with a tenants array.");
+  }
+
+  const seen = new Set();
+  const tenants = raw.tenants.map((tenant, index) => {
+    if (!tenant || typeof tenant !== "object" || Array.isArray(tenant)) {
+      throw new ConfigError("CONFIG_INVALID", `tenants[${index}] must be an object.`);
+    }
+
+    const id = stringValue(tenant.id, `tenants[${index}].id`);
+    if (seen.has(id)) throw new ConfigError("CONFIG_INVALID", `Duplicate tenant id: ${id}`);
+    seen.add(id);
+
+    const rawOrigins = Array.isArray(tenant.origins)
+      ? tenant.origins
+      : typeof tenant.origin === "string"
+        ? [tenant.origin]
+        : [];
+    if (rawOrigins.length === 0) {
+      throw new ConfigError("CONFIG_INVALID", `tenant ${id} must configure at least one origin.`);
+    }
+    const origins = [...new Set(rawOrigins.map((origin, originIndex) => {
+      if (typeof origin !== "string" || !origin.trim()) {
+        throw new ConfigError("CONFIG_INVALID", `tenants[${index}].origins[${originIndex}] must be a non-empty string.`);
+      }
+      return normalizeOrigin(origin);
+    }))];
+
+    const maxPageSessionTtlMs = positiveInteger(
+      tenant.maxPageSessionTtlMs,
+      24 * 60 * 60_000,
+      `tenant ${id}.maxPageSessionTtlMs`,
+    );
+    const maxAgentSessionTtlMs = positiveInteger(
+      tenant.maxAgentSessionTtlMs,
+      24 * 60 * 60_000,
+      `tenant ${id}.maxAgentSessionTtlMs`,
+    );
+
+    return {
+      id,
+      displayName:
+        typeof tenant.displayName === "string" && tenant.displayName.trim()
+          ? tenant.displayName.trim()
+          : id,
+      origins,
+      maxPageSessionTtlMs,
+      maxAgentSessionTtlMs,
+      publicDemo: normalizePublicDemo(
+        tenant.publicDemo,
+        id,
+        origins,
+        maxPageSessionTtlMs,
+      ),
+    };
+  });
+
+  if (tenants.length === 0) {
+    throw new ConfigError("CONFIG_INVALID", "At least one tenant is required.");
+  }
+  return { tenants };
+}
+
+function normalizePublicDemo(value, tenantId, tenantOrigins, maxPageSessionTtlMs) {
+  if (value === undefined || value === null) return null;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ConfigError("CONFIG_INVALID", `tenant ${tenantId}.publicDemo must be an object.`);
+  }
+
+  if (!Array.isArray(value.origins) || value.origins.length === 0) {
+    throw new ConfigError("CONFIG_INVALID", `tenant ${tenantId}.publicDemo must configure at least one origin.`);
+  }
+  const tenantOriginSet = new Set(tenantOrigins);
+  const origins = [...new Set(value.origins.map((origin, index) => {
+    if (typeof origin !== "string" || !origin.trim()) {
+      throw new ConfigError(
+        "CONFIG_INVALID",
+        `tenant ${tenantId}.publicDemo.origins[${index}] must be a non-empty string.`,
+      );
+    }
+    return normalizeOrigin(origin);
+  }))];
+  const unknownOrigin = origins.find((origin) => !tenantOriginSet.has(origin));
+  if (unknownOrigin) {
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `tenant ${tenantId}.publicDemo origins must also appear in tenant.origins: ${unknownOrigin}`,
+    );
+  }
+
+  if (!Array.isArray(value.scope)) {
+    throw new ConfigError("CONFIG_INVALID", `tenant ${tenantId}.publicDemo.scope must be an array.`);
+  }
+  const scope = [...new Set(value.scope.map((item, index) => {
+    if (typeof item !== "string" || !item.trim()) {
+      throw new ConfigError(
+        "CONFIG_INVALID",
+        `tenant ${tenantId}.publicDemo.scope[${index}] must be a non-empty string.`,
+      );
+    }
+    return item.trim();
+  }))];
+  if (scope.length === 0) {
+    throw new ConfigError("CONFIG_INVALID", `tenant ${tenantId}.publicDemo.scope must not be empty.`);
+  }
+  if (scope.length > MAX_SCOPE_ENTRIES) {
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `tenant ${tenantId}.publicDemo.scope must contain at most ${MAX_SCOPE_ENTRIES} entries.`,
+    );
+  }
+
+  const pageSessionTtlMs = positiveInteger(
+    value.pageSessionTtlMs,
+    24 * 60 * 60_000,
+    `tenant ${tenantId}.publicDemo.pageSessionTtlMs`,
+  );
+  if (pageSessionTtlMs > maxPageSessionTtlMs) {
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `tenant ${tenantId}.publicDemo.pageSessionTtlMs cannot exceed tenant.maxPageSessionTtlMs.`,
+    );
+  }
+
+  return {
+    origins,
+    scope,
+    pageSessionTtlMs,
+    maxSessionsPerWindow: positiveInteger(
+      value.maxSessionsPerWindow,
+      30,
+      `tenant ${tenantId}.publicDemo.maxSessionsPerWindow`,
+    ),
+    windowMs: positiveInteger(
+      value.windowMs,
+      10 * 60_000,
+      `tenant ${tenantId}.publicDemo.windowMs`,
+    ),
+    maxActiveSessions: positiveInteger(
+      value.maxActiveSessions,
+      40,
+      `tenant ${tenantId}.publicDemo.maxActiveSessions`,
+    ),
+    userIdPrefix:
+      typeof value.userIdPrefix === "string" && value.userIdPrefix.trim()
+        ? value.userIdPrefix.trim()
+        : "public-demo",
+  };
+}
+
+export function normalizeOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new ConfigError("CONFIG_INVALID", `Invalid origin: ${value}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ConfigError("CONFIG_INVALID", `Origin must use http or https: ${value}`);
+  }
+  if (url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new ConfigError(
+      "CONFIG_INVALID",
+      `Origin must not contain a path, query, fragment, or credentials: ${value}`,
+    );
+  }
+  return url.origin;
+}
+
+function stringValue(value, path) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new ConfigError("CONFIG_INVALID", `${path} must be a non-empty string.`);
+  }
+  const text = value.trim();
+  if (text.length > 128) {
+    throw new ConfigError("CONFIG_INVALID", `${path} must be at most 128 characters.`);
+  }
+  return text;
+}
+
+function positiveInteger(value, fallback, path) {
+  if (value === undefined || value === null) return fallback;
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new ConfigError("CONFIG_INVALID", `${path} must be a positive integer.`);
+  }
+  return value;
+}

package/src/errors.mjs

@@ -0,0 +1,15 @@
+export class GatewayError extends Error {
+  constructor(code, message, status = 400, options) {
+    super(message, options);
+    this.name = "GatewayError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+export function asGatewayError(error) {
+  if (error instanceof GatewayError) return error;
+  return new GatewayError("INTERNAL_ERROR", "Internal gateway error.", 500, {
+    cause: error,
+  });
+}