@plingjs/surface-gateway 0.0.0-stage → 0.1.0-alpha.4

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Pling
+Copyright 2026 Pling contributors
+
+This product includes software developed by Pling contributors.
+

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# @plingjs/surface-gateway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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/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/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/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
+      }
+    }
+  ]
+}