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

package/index.d.ts

@@ -0,0 +1,273 @@
+export const BRIDGE_PROTOCOL: "pling.bridge/0.1";
+export const SURFACE_PROTOCOL: "pling.surface/0.1";
+export const PACKAGE_VERSION: string;
+
+export interface SurfacePublicDemoConfig {
+  origins: string[];
+  scope: string[];
+  pageSessionTtlMs: number;
+  maxSessionsPerWindow: number;
+  windowMs: number;
+  maxActiveSessions: number;
+  userIdPrefix: string;
+}
+
+export interface SurfaceTenantConfig {
+  id: string;
+  displayName: string;
+  origins: string[];
+  maxPageSessionTtlMs: number;
+  maxAgentSessionTtlMs: number;
+  publicDemo: SurfacePublicDemoConfig | null;
+}
+
+export interface SurfaceConfig {
+  tenants: SurfaceTenantConfig[];
+}
+
+export interface SurfaceAuditEvent {
+  type: string;
+  at: string;
+  [key: string]: unknown;
+}
+
+export interface SurfacePageSocket {
+  readonly readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+}
+
+export interface SurfacePageSession {
+  id: string;
+  tenantId: string;
+  userId: string;
+  allowedScope: string[];
+  token: string;
+  createdAt: number;
+  expiresAt: number;
+  connectedAt: number | null;
+  socket: SurfacePageSocket | null;
+  activeAgentSessionId: string | null;
+}
+
+export interface SurfaceAgentSession {
+  id: string;
+  token: string;
+  tenantId: string;
+  pageSessionId: string;
+  agentId: string;
+  userId: string;
+  scope: string[];
+  createdAt: number;
+  expiresAt: number;
+  revokedAt: number | null;
+}
+
+export interface PublicPageSession {
+  pageSessionId: string;
+  token: string;
+  expiresAt: number;
+  tenantId: string;
+  surfaceUrl: string;
+  pairingUrl: string;
+  agentSessionsUrl: string;
+  mcpUrl: string;
+  scope: string[];
+}
+
+export interface SurfacePairing {
+  code: string;
+  tenantId: string;
+  tenantName: string;
+  mcpUrl: string;
+  expiresAt: number;
+  scope: string[];
+}
+
+export interface SurfaceAgentAccess {
+  agentSessionId: string;
+  token: string;
+  tenantId: string;
+  pageSessionId: string;
+  agentId: string;
+  scope: string[];
+  expiresAt: number;
+  mcpUrl: string;
+}
+
+export type SurfaceRequestState = "waiting" | "pending_approval" | "done" | "not_found";
+
+export interface SurfaceProtocolFailure {
+  protocol: typeof SURFACE_PROTOCOL;
+  id: string;
+  ok: false;
+  error: { code: string; message: string };
+}
+
+export interface SurfaceProtocolSuccess<T = unknown> {
+  protocol: typeof SURFACE_PROTOCOL;
+  id: string;
+  ok: true;
+  result: T;
+}
+
+export type SurfaceProtocolResponse<T = unknown> = SurfaceProtocolSuccess<T> | SurfaceProtocolFailure;
+
+export interface SurfaceApprovalView {
+  description: string;
+  args: Record<string, unknown>;
+  kind: string;
+  expiresAt: number;
+  flow?: Record<string, unknown>;
+}
+
+export interface SurfaceInvocationResult {
+  state: SurfaceRequestState;
+  requestId: string;
+  capability?: string;
+  approval?: SurfaceApprovalView;
+  response?: SurfaceProtocolResponse;
+}
+
+export interface SurfaceGatewayOptions {
+  config: SurfaceConfig;
+  publicBaseUrl: string;
+  now?: () => number;
+  requestTimeoutMs?: number;
+  approvalTimeoutMs?: number;
+  pageSessionTtlMs?: number;
+  pairingTtlMs?: number;
+  agentSessionTtlMs?: number;
+  resultTtlMs?: number;
+  revokedSessionRetentionMs?: number;
+  maxPairingClaimsPerWindow?: number;
+  pairingClaimWindowMs?: number;
+  onAudit?: (event: SurfaceAuditEvent) => void | Promise<void>;
+}
+
+export interface SurfaceGateway {
+  readonly version: string;
+  readonly config: SurfaceConfig;
+  createPageSession(input: { tenantId: string; userId: string; scope: string[]; ttlMs?: number }): PublicPageSession;
+  createPublicDemoPageSession(input: { tenantId: string; origin: string; clientKey?: string }): PublicPageSession;
+  authenticatePage(token: string | null | undefined, origin: string | null | undefined): SurfacePageSession;
+  attachPage(session: SurfacePageSession, socket: SurfacePageSocket, origin: string | null | undefined): void;
+  disconnectPage(session: SurfacePageSession, reason?: string, socket?: SurfacePageSocket | null): void;
+  createPairing(input: { pageToken: string; ttlMs?: number }): SurfacePairing;
+  claimPairing(input: { code: string; agentId: string; scope?: string[]; ttlMs?: number; clientKey?: string }): SurfaceAgentAccess;
+  authenticateAgent(token: string | null | undefined): SurfaceAgentSession;
+  revokeAgentSession(id: string, reason?: string): Record<string, unknown>;
+  revokePageSession(id: string, reason?: string): { pageSessionId: string; revoked: true };
+  describe(agentToken: string): Promise<SurfaceProtocolResponse>;
+  invoke(agentToken: string, capability: string, input?: Record<string, unknown>): Promise<SurfaceInvocationResult>;
+  status(agentToken: string, requestId: string): SurfaceInvocationResult;
+  notePageMessage(page: SurfacePageSession, message: unknown): void;
+  discover(tenantId: string): Record<string, unknown>;
+  listSessions(): {
+    tenants: Array<Pick<SurfaceTenantConfig, "id" | "displayName" | "origins">>;
+    pageSessions: Array<{
+      id: string;
+      tenantId: string;
+      userId: string;
+      connected: boolean;
+      scope: string[];
+      expiresAt: number;
+      activeAgentSessionId: string | null;
+    }>;
+    agentSessions: Array<{
+      id: string;
+      tenantId: string;
+      pageSessionId: string;
+      agentId: string;
+      userId: string;
+      scope: string[];
+      expiresAt: number;
+      revokedAt: number | null;
+    }>;
+  };
+  expire(): void;
+  shutdown(): void;
+}
+
+export interface SurfaceGatewaySubOptions {
+  now?: () => number;
+  requestTimeoutMs?: number;
+  approvalTimeoutMs?: number;
+  pageSessionTtlMs?: number;
+  pairingTtlMs?: number;
+  agentSessionTtlMs?: number;
+  resultTtlMs?: number;
+  revokedSessionRetentionMs?: number;
+  maxPairingClaimsPerWindow?: number;
+  pairingClaimWindowMs?: number;
+  onAudit?: (event: SurfaceAuditEvent) => void | Promise<void>;
+}
+
+export interface SurfaceServerOptions {
+  config: SurfaceConfig;
+  adminToken: string;
+  publicBaseUrl?: string;
+  host?: string;
+  port?: number;
+  demoTenantId?: string;
+  trustProxy?: boolean;
+  logger?: (message: string) => void;
+  gateway?: SurfaceGatewaySubOptions;
+}
+
+export interface SurfaceServer {
+  readonly gateway: SurfaceGateway | null;
+  readonly baseUrl: string | null;
+  start(): Promise<{ baseUrl: string; port: number }>;
+  stop(): Promise<void>;
+}
+
+export interface McpRequest {
+  jsonrpc: "2.0";
+  id?: string | number | null;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface McpHandler {
+  handle(body: McpRequest, context?: { agentToken?: string }): Promise<Record<string, unknown> | null>;
+}
+
+export interface SurfaceMcpTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+export interface SurfaceCliRun {
+  server: SurfaceServer;
+  config: SurfaceConfig;
+  configPath: string;
+  baseUrl: string;
+  port: number;
+  stop(signal?: string): Promise<void>;
+}
+
+export class ConfigError extends Error {
+  readonly code: string;
+}
+
+export class GatewayError extends Error {
+  readonly code: string;
+  readonly status: number;
+}
+
+export function normalizeConfig(raw: unknown): SurfaceConfig;
+export function loadConfig(file: string): Promise<SurfaceConfig>;
+export function normalizeOrigin(value: string): string;
+export function createSurfaceGateway(options: SurfaceGatewayOptions): SurfaceGateway;
+export function createSurfaceServer(options: SurfaceServerOptions): SurfaceServer;
+export function createMcpHandler(gateway: SurfaceGateway, options?: { version?: string }): McpHandler;
+export function asGatewayError(error: unknown): GatewayError;
+export function runSurfaceGatewayCli(options?: {
+  env?: Record<string, string | undefined>;
+  stderr?: { write(chunk: string): unknown };
+}): Promise<SurfaceCliRun>;
+export function cliHelp(): string;
+
+export const TOOLS: SurfaceMcpTool[];

package/index.mjs

@@ -0,0 +1,7 @@
+export { BRIDGE_PROTOCOL, SURFACE_PROTOCOL, createSurfaceGateway } from "./gateway.mjs";
+export { createSurfaceServer } from "./server.mjs";
+export { createMcpHandler, TOOLS } from "./mcp.mjs";
+export { ConfigError, loadConfig, normalizeConfig, normalizeOrigin } from "./config.mjs";
+export { GatewayError, asGatewayError } from "./errors.mjs";
+export { cliHelp, runSurfaceGatewayCli } from "./cli.mjs";
+export { PACKAGE_VERSION } from "./version.mjs";

package/mcp.mjs

@@ -0,0 +1,145 @@
+import { GatewayError } from "./errors.mjs";
+import { PACKAGE_VERSION } from "./version.mjs";
+
+const TOOLS = [
+  {
+    name: "pling_surface_describe",
+    description:
+      "Read the currently paired business page: exposed capabilities, input schemas, records, regions, page state, and feedback. Call this before invoking an action.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "pling_surface_invoke",
+    description:
+      "Invoke one capability returned by pling_surface_describe. If the result is pending_approval, the user must confirm in the business page. The Agent cannot approve.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        capability: { type: "string", description: "Stable capability id returned by describe" },
+        input: { type: "object", description: "Business input declared by the capability schema", additionalProperties: true },
+      },
+      required: ["capability"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "pling_surface_approval_status",
+    description:
+      "Read the final status of an earlier Surface invocation. pending_approval means the user must finish confirmation in the business page.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        requestId: { type: "string", description: "requestId returned by pling_surface_invoke" },
+      },
+      required: ["requestId"],
+      additionalProperties: false,
+    },
+  },
+];
+
+export function createMcpHandler(gateway, options = {}) {
+  const version = typeof options.version === "string" && options.version.trim()
+    ? options.version.trim()
+    : PACKAGE_VERSION;
+  return {
+    async handle(body, context = {}) {
+      if (!body || typeof body !== "object" || body.jsonrpc !== "2.0" || typeof body.method !== "string") {
+        return { error: { code: -32600, message: "Invalid Request" } };
+      }
+      if (body.id === undefined || body.id === null) return null;
+      if (typeof body.id !== "string" && typeof body.id !== "number") {
+        return { jsonrpc: "2.0", id: null, error: { code: -32600, message: "Invalid Request" } };
+      }
+
+      const id = body.id;
+      try {
+        if (body.params !== undefined && (!body.params || typeof body.params !== "object" || Array.isArray(body.params))) {
+          throw new GatewayError("INVALID_PARAMS", "params must be an object.", 400);
+        }
+        const result = await dispatch(gateway, body.method, body.params ?? {}, context, version);
+        return { jsonrpc: "2.0", id, result };
+      } catch (error) {
+        const code = error instanceof GatewayError
+          ? error.status === 401
+            ? -32001
+            : error.status === 404
+              ? -32601
+              : error.status === 400
+                ? -32602
+                : -32603
+          : -32603;
+        return {
+          jsonrpc: "2.0",
+          id,
+          error: { code, message: error instanceof Error ? error.message : String(error) },
+        };
+      }
+    },
+  };
+}
+
+async function dispatch(gateway, method, params, context, version) {
+  if (method === "initialize") {
+    return {
+      protocolVersion: typeof params.protocolVersion === "string" ? params.protocolVersion : "2025-03-26",
+      capabilities: { tools: { listChanged: false } },
+      serverInfo: { name: "pling-surface-gateway", version },
+      instructions:
+        "Pling Surface Gateway. The user must pair an open business page before tools work. Call pling_surface_describe first. " +
+        "If pling_surface_invoke returns pending_approval, ask the user to confirm in the open business page and then call pling_surface_approval_status. " +
+        "There is no approval tool; never claim an action was approved without a final response.",
+    };
+  }
+  if (method === "ping") return {};
+  if (method === "tools/list") return { tools: TOOLS };
+  if (method === "tools/call") return callTool(gateway, params, context);
+  throw new GatewayError("METHOD_NOT_FOUND", `Unsupported MCP method: ${method}`, 404);
+}
+
+async function callTool(gateway, params, context) {
+  const name = typeof params.name === "string" ? params.name : "";
+  const args = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments) ? params.arguments : {};
+  const agentToken = typeof context?.agentToken === "string" ? context.agentToken : "";
+  try {
+    if (name === "pling_surface_describe") {
+      const response = await gateway.describe(agentToken);
+      if (!response?.ok) return toolError(response?.error?.message ?? "describe failed");
+      return toolText(response.result);
+    }
+    if (name === "pling_surface_invoke") {
+      if (typeof args.capability !== "string" || !args.capability.trim()) return toolError("capability must be a non-empty string");
+      if (args.input !== undefined && (!args.input || typeof args.input !== "object" || Array.isArray(args.input))) {
+        return toolError("input must be an object");
+      }
+      const result = await gateway.invoke(agentToken, args.capability, args.input ?? {});
+      if (result.state === "pending_approval") {
+        return toolText(
+          `Waiting for user confirmation in the business page.\n` +
+            `requestId: ${result.requestId}\n` +
+            `capability: ${result.capability}\n\n` +
+            "Ask the user to complete confirmation in the open business page, then call pling_surface_approval_status. Do not claim approval.",
+        );
+      }
+      return toolText(result);
+    }
+    if (name === "pling_surface_approval_status") {
+      if (typeof args.requestId !== "string" || !args.requestId.trim()) return toolError("requestId must be a non-empty string");
+      return toolText(gateway.status(agentToken, args.requestId));
+    }
+    return toolError(`Unknown tool: ${name}`);
+  } catch (error) {
+    return toolError(error instanceof Error ? error.message : String(error));
+  }
+}
+
+function toolText(value) {
+  return {
+    content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }],
+  };
+}
+
+function toolError(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+export { TOOLS };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@plingjs/surface-gateway",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.4",
+  "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"
+  }
+}