@impetik/xeer-mcp 0.2.10 → 0.2.13

package/README.md

@@ -71,18 +71,19 @@ The generated registry is the complete MCP tool and exclusion surface:
 | `xeer_promote` | `promote.operator` | `operator` | Promote an exact review receipt in operator mode. | `directory?`: `string`<br>`receiptId`: `string`<br>`controlUrl?`: `string` | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | A human must review the exact artifact and start xeer-mcp with XEER_MCP_PROFILE=operator. |
 | `xeer_auth_status` | `auth.status` | `author` / `operator` | Report builder credential metadata. | `controlUrl?`: `string` | `network-read`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
 | `xeer_inspect` | `inspect` | `author` / `operator` | Read a running application manifest. | `previewUrl`: `string`<br>`view?`: `manifest` / `state` / `logs` / `export`; default `manifest`<br>`after?`: `string` | `network-read`<br>`read-state` | read-only; idempotent; reversible; non-destructive | `app-or-url` | `xeer.command.v0` | none |
-| `xeer_dev_start` | `dev.start` | `author` / `operator` | Start a local development session. | `directory?`: `string`<br>`host?`: `string`<br>`port?`: `integer` [0..65535]<br>`timeoutMilliseconds?`: `integer` [1000..600000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
+| `xeer_dev_start` | `dev.start` | `author` / `operator` | Start a local development session. | `directory?`: `string`<br>`host?`: `string`<br>`port?`: `integer` [0..65535]<br>`share?`: `boolean`<br>`timeoutMilliseconds?`: `integer` [1000..600000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
 | `xeer_dev_status` | `dev.status` | `author` / `operator` | Read new events from a local development session. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0`<br>`waitMilliseconds?`: `integer` [0..600000]; default `0`<br>`limit?`: `integer` [1..1000]; default `200` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
 | `xeer_dev_stop` | `dev.stop` | `author` / `operator` | Stop a local development session and release its lease. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0` | `run-local` | writes; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
 | `xeer_diagnostics` | `diagnostics` | `author` / `operator` | Explain one emitted diagnostic code. | `code`: `string` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
 
-**CLI actions intentionally excluded from MCP (34).**
+**CLI actions intentionally excluded from MCP (35).**
 
 | CLI action | Action | Summary | Effects | Safety | Path policy | Output | Why no MCP tool |
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `xeer agent setup` | `agent.setup` | Install or verify project-confined agent adapters. | `read-source`<br>`write-source` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer deploy` | `deploy` | Build and deploy an application artifact. | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | MCP exposes a separate preview-only deploy action; direct production deploy stays CLI-only. |
 | `xeer promote` | `promote` | Promote a preview artifact to production. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | MCP promotion is a separate action available only when the server starts in operator profile. |
+| `xeer tunnel` | `tunnel.start` | Expose a loopback HTTP server through an authenticated tunnel. | `run-local`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `none` | `xeer.tunnel.cli.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer link` | `link` | Link a checkout to an application the builder owns. | `read-source`<br>`write-source`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Human identity and project ownership decisions are not delegated through MCP. |
 | `xeer deployments` | `deployments` | List deployment history for an application. | `network-read`<br>`read-state`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
 | `xeer rollback` | `rollback` | Redeploy a previously deployed artifact. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |

package/dist/dev-session.d.ts

@@ -34,6 +34,11 @@ export interface DevSessionSummary {
     generation?: number;
     artifactId?: string;
     preview?: PreviewUrls;
+    tunnel?: {
+        url: string;
+        tunnelId: string;
+        leaseExpiresAt: string;
+    };
     /** Diagnostics from the most recent compile attempt. Empty once a rebuild is accepted. */
     openDiagnostics: Diagnostic[];
     exit?: {
@@ -51,6 +56,7 @@ export interface DevSessionOptions {
     directory: string;
     host?: string;
     port?: number;
+    share?: boolean;
 }
 export declare class DevSession {
     #private;

package/dist/dev-session.js

@@ -21,6 +21,8 @@ export class DevSession {
     #cursor = 0;
     #status = 'starting';
     #preview;
+    #tunnel;
+    #expectsTunnel;
     #generation;
     #artifactId;
     #openDiagnostics = [];
@@ -35,10 +37,12 @@ export class DevSession {
     constructor(sessionId, options) {
         this.sessionId = sessionId;
         this.directory = options.directory;
+        this.#expectsTunnel = options.share === true;
         // Port 0 is the documented automation mode: the OS picks a free port and the
         // preview.ready event reports it, so parallel sessions cannot collide.
         const args = ['dev', options.directory, '--json',
-            '--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 0)];
+            '--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 0),
+            ...(options.share ? ['--share'] : [])];
         this.#child = fork(resolveXeerCli(), args, {
             cwd: options.directory,
             stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
@@ -140,9 +144,22 @@ export class DevSession {
                 break;
             case 'preview.ready':
                 this.#preview = event.data;
-                this.#status = 'ready';
+                if (!this.#expectsTunnel)
+                    this.#status = 'ready';
                 this.#compiling = false;
                 break;
+            case 'tunnel.ready': {
+                const data = event.data;
+                if (typeof data.url === 'string' && typeof data.tunnelId === 'string'
+                    && typeof data.leaseExpiresAt === 'string') {
+                    this.#tunnel = { url: data.url, tunnelId: data.tunnelId, leaseExpiresAt: data.leaseExpiresAt };
+                    this.#status = 'ready';
+                }
+                break;
+            }
+            case 'tunnel.closed':
+                this.#tunnel = undefined;
+                break;
             case 'process.exit': {
                 const data = event.data;
                 this.#exit = { ...(typeof data.code === 'number' ? { code: data.code } : {}), ...(data.reason ? { reason: data.reason } : {}) };
@@ -219,6 +236,7 @@ export class DevSession {
             ...(this.#generation === undefined ? {} : { generation: this.#generation }),
             ...(this.#artifactId === undefined ? {} : { artifactId: this.#artifactId }),
             ...(this.#preview ? { preview: this.#preview } : {}),
+            ...(this.#tunnel ? { tunnel: this.#tunnel } : {}),
             openDiagnostics: [...this.#openDiagnostics],
             ...(this.#exit ? { exit: this.#exit } : {}),
             droppedEvents: this.#dropped,

package/dist/server.js

@@ -433,6 +433,11 @@ export function createXeerMcpServer(options = {}) {
             debugUrl: z.string(),
             logsUrl: z.string(),
         }).loose().optional(),
+        tunnel: z.object({
+            url: z.string(),
+            tunnelId: z.string(),
+            leaseExpiresAt: z.string(),
+        }).loose().optional(),
         openDiagnostics: z.array(diagnosticSchema),
         exit: z.object({ code: z.number().optional(), reason: z.string().optional() }).loose().optional(),
         droppedEvents: z.number(),
@@ -454,13 +459,14 @@ export function createXeerMcpServer(options = {}) {
     server.registerTool('xeer_dev_start', {
         ...toolPolicy('dev.start'),
         outputSchema: wrappedOutput(z.object(sessionOutput).loose()),
-    }, async ({ directory, host, port, timeoutMilliseconds }) => withDirectory(directory, 'dev.start', async (resolved) => {
+    }, async ({ directory, host, port, share, timeoutMilliseconds }) => withDirectory(directory, 'dev.start', async (resolved) => {
         let session;
         try {
             session = devSessions.start({
                 directory: resolved,
                 ...(host ? { host } : {}),
                 ...(port === undefined ? {} : { port }),
+                ...(share === undefined ? {} : { share }),
             });
         }
         catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.10",
+  "version": "0.2.13",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.10"
+    "@impetik/xeer": "0.2.13"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/actions.d.ts

@@ -49,6 +49,8 @@ export interface XeerActionDefinition {
     readonly summary: string;
     /** Help syntax without the `xeer ` prefix. May contain `{{templates}}`. */
     readonly usage: readonly string[];
+    /** Optional abbreviated syntax for the global command list. Full usage remains authoritative. */
+    readonly globalUsage?: readonly string[];
     readonly hiddenFromHelp?: boolean;
     readonly helpOrder?: number;
     readonly outputProtocol: string;
@@ -503,10 +505,10 @@ declare const actions: readonly [{
     readonly id: "dev.start";
     readonly command: readonly ["dev"];
     readonly summary: "Start a local development session.";
-    readonly usage: readonly ["dev [directory] [--host <host>] [--port <port>] [--json]"];
+    readonly usage: readonly [string];
     readonly helpOrder: 220;
     readonly outputProtocol: "xeer.dev.v0";
-    readonly effects: readonly ["read-source", "write-generated", "run-local", "write-state"];
+    readonly effects: readonly ["read-source", "write-generated", "run-local", "write-state", "network-read", "network-write"];
     readonly idempotent: false;
     readonly reversible: true;
     readonly destructive: false;
@@ -530,6 +532,10 @@ declare const actions: readonly [{
                     readonly minimum: 0;
                     readonly maximum: 65535;
                 };
+                readonly share: {
+                    readonly description: "Publish the session through an authenticated Xeer tunnel.";
+                    readonly type: "boolean";
+                };
                 readonly timeoutMilliseconds: {
                     readonly type: "integer";
                     readonly minimum: 1000;
@@ -543,6 +549,24 @@ declare const actions: readonly [{
         readonly mcpTool: "xeer_dev_start";
         readonly mcpProfiles: readonly ["author", "operator"];
     };
+}, {
+    readonly id: "tunnel.start";
+    readonly command: readonly ["tunnel"];
+    readonly summary: "Expose a loopback HTTP server through an authenticated tunnel.";
+    readonly usage: readonly [string];
+    readonly globalUsage: readonly ["tunnel <port|loopback-url> [options]"];
+    readonly helpOrder: 225;
+    readonly outputProtocol: "xeer.tunnel.cli.v0";
+    readonly effects: readonly ["run-local", "network-read", "network-write"];
+    readonly idempotent: false;
+    readonly reversible: true;
+    readonly destructive: false;
+    readonly humanPrerequisites: readonly ["A human must sign in and deliberately keep the public tunnel process running."];
+    readonly pathPolicy: "none";
+    readonly surfaces: {
+        readonly cli: true;
+        readonly mcpExclusion: "Not exposed through MCP v0; use the CLI deliberately.";
+    };
 }, {
     readonly id: "dev.status";
     readonly command: readonly ["dev"];

package/vendor/spec/actions.js

@@ -337,8 +337,9 @@ const actions = [
     },
     {
         id: 'dev.start', command: ['dev'], summary: 'Start a local development session.',
-        usage: ['dev [directory] [--host <host>] [--port <port>] [--json]'], helpOrder: 220,
-        outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
+        usage: ['dev [directory] [--host <host>] [--port <port>] [--share] [--control-url <url>] '
+                + '[--tunnel-bootstrap <file>] [--json]'], helpOrder: 220,
+        outputProtocol: 'xeer.dev.v0', effects: ['read-source', 'write-generated', 'run-local', 'write-state', 'network-read', 'network-write'],
         idempotent: false, reversible: true, destructive: false, humanPrerequisites: [],
         pathPolicy: 'project-relative', surfaces: {
             cli: true, mcpTool: 'xeer_dev_start', mcpProfiles: XEER_MCP_PROFILES,
@@ -347,10 +348,24 @@ const actions = [
                     directory: PROJECT_DIRECTORY_INPUT,
                     host: { description: 'Defaults to 127.0.0.1.', type: 'string' },
                     port: { description: 'Defaults to 0 (OS-assigned).', type: 'integer', minimum: 0, maximum: 65_535 },
+                    share: { description: 'Publish the session through an authenticated Xeer tunnel.', type: 'boolean' },
                     timeoutMilliseconds: { type: 'integer', minimum: 1_000, maximum: 600_000 },
                 } },
         },
     },
+    {
+        id: 'tunnel.start', command: ['tunnel'], summary: 'Expose a loopback HTTP server through an authenticated tunnel.',
+        usage: ['tunnel <port|loopback-url> [--label <name>] [--host-header <preserve|rewrite|host>] '
+                + '[--request-header-add <name:value>] [--request-header-remove <name>] '
+                + '[--response-header-add <name:value>] [--response-header-remove <name>] '
+                + '[--upstream-tls-insecure] [--lifetime <seconds>] [--control-url <url>] [--json]'],
+        globalUsage: ['tunnel <port|loopback-url> [options]'],
+        helpOrder: 225, outputProtocol: 'xeer.tunnel.cli.v0',
+        effects: ['run-local', 'network-read', 'network-write'], idempotent: false,
+        reversible: true, destructive: false,
+        humanPrerequisites: ['A human must sign in and deliberately keep the public tunnel process running.'],
+        pathPolicy: 'none', surfaces: { cli: true, mcpExclusion: NOT_EXPOSED_V0 },
+    },
     {
         id: 'dev.status', command: ['dev'], summary: 'Read new events from a local development session.',
         usage: [], outputProtocol: 'xeer.dev.v0', effects: [], idempotent: true, reversible: true,

package/vendor/spec/index.d.ts

@@ -18,3 +18,5 @@ export * from './admin.js';
 export * from './admin-sql.js';
 export * from './network-policy.js';
 export * from './review.js';
+export * from './template.js';
+export * from './tunnel.js';

package/vendor/spec/index.js

@@ -18,3 +18,5 @@ export * from './admin.js';
 export * from './admin-sql.js';
 export * from './network-policy.js';
 export * from './review.js';
+export * from './template.js';
+export * from './tunnel.js';

package/vendor/spec/template.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const TEMPLATE_FORMAT: "xeer.template.v0";
+export declare const TEMPLATE_MANIFEST_SCHEMA_URL: "https://docs.xeer.run/template-v0.schema.json";
+export declare const templateManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    format: z.ZodLiteral<"xeer.template.v0">;
+    title: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    keyHighlights: z.ZodArray<z.ZodString>;
+    screenshots: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        alt: z.ZodString;
+    }, z.core.$strict>>;
+    author: z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        database: "database";
+        storage: "storage";
+    }>>;
+    requiredSecrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
+    previewAppId: z.ZodString;
+}, z.core.$strict>;
+export type TemplateManifestV0 = z.infer<typeof templateManifestSchema>;
+export declare const templateManifestJsonSchema: Readonly<Record<string, unknown>>;
+export declare function parseTemplateManifest(value: unknown): TemplateManifestV0;

package/vendor/spec/template.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { CAPABILITIES } from './types.js';
+export const TEMPLATE_FORMAT = 'xeer.template.v0';
+export const TEMPLATE_MANIFEST_SCHEMA_URL = 'https://docs.xeer.run/template-v0.schema.json';
+const trimmed = (maximum) => z.string().min(1).max(maximum)
+    .refine((value) => value === value.trim(), 'must not have leading or trailing whitespace')
+    .refine((value) => !/[\u0000-\u001f\u007f]/u.test(value), 'must not contain control characters');
+const slug = z.string().regex(/^[a-z][a-z0-9-]{1,62}$/u, 'must be a lowercase slug between 2 and 63 characters');
+const environmentName = z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/u, 'must be an uppercase environment variable name');
+const appId = z.string().regex(/^app_[A-Za-z0-9_-]{8,96}$/u, 'must be a valid Xeer appId');
+const screenshotPath = z.string().regex(/^screenshots\/(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*[A-Za-z0-9][A-Za-z0-9._-]*\.(?:avif|jpe?g|png|webp)$/u, 'must be a repository-local AVIF, JPEG, PNG, or WebP path under screenshots/');
+const authorSchema = z.strictObject({
+    name: trimmed(80),
+    url: z.string().url().optional(),
+});
+const requiredSecretSchema = z.strictObject({
+    name: environmentName,
+    description: trimmed(200),
+});
+const screenshotSchema = z.strictObject({
+    path: screenshotPath,
+    alt: trimmed(200),
+});
+export const templateManifestSchema = z.strictObject({
+    $schema: z.string().url().optional(),
+    format: z.literal(TEMPLATE_FORMAT),
+    title: trimmed(120),
+    description: trimmed(300),
+    category: slug,
+    tags: z.array(trimmed(40)).min(1).max(16),
+    keyHighlights: z.array(trimmed(120)).min(1).max(8),
+    screenshots: z.array(screenshotSchema).min(1).max(8),
+    author: authorSchema,
+    capabilities: z.array(z.enum(CAPABILITIES)).max(CAPABILITIES.length),
+    requiredSecrets: z.array(requiredSecretSchema).max(16),
+    previewAppId: appId,
+}).superRefine((manifest, ctx) => {
+    const unique = (values, path, label) => {
+        const seen = new Set();
+        for (const [index, value] of values.entries()) {
+            const normalized = value.toLocaleLowerCase('en-US');
+            if (seen.has(normalized)) {
+                ctx.addIssue({ code: 'custom', path: [path, index], message: `${label} is declared twice` });
+            }
+            seen.add(normalized);
+        }
+    };
+    unique(manifest.tags, 'tags', 'tag');
+    unique(manifest.keyHighlights, 'keyHighlights', 'highlight');
+    unique(manifest.screenshots.map((screenshot) => screenshot.path), 'screenshots', 'screenshot');
+    unique(manifest.capabilities, 'capabilities', 'capability');
+    unique(manifest.requiredSecrets.map((secret) => secret.name), 'requiredSecrets', 'secret');
+});
+const generatedTemplateManifestJsonSchema = z.toJSONSchema(templateManifestSchema);
+const generatedProperties = generatedTemplateManifestJsonSchema.properties;
+export const templateManifestJsonSchema = Object.freeze({
+    ...generatedTemplateManifestJsonSchema,
+    $id: TEMPLATE_MANIFEST_SCHEMA_URL,
+    title: 'Xeer template manifest v0',
+    description: 'Authored metadata for one application in the Xeer template catalog.',
+    properties: {
+        ...generatedProperties,
+        $schema: {
+            ...generatedProperties.$schema,
+            description: 'Editor schema hint. Xeer does not fetch this URL during validation.',
+        },
+        format: {
+            ...generatedProperties.format,
+            description: `Template metadata protocol discriminator; exactly ${TEMPLATE_FORMAT}.`,
+        },
+        tags: {
+            ...generatedProperties.tags,
+            uniqueItems: true,
+        },
+        keyHighlights: {
+            ...generatedProperties.keyHighlights,
+            uniqueItems: true,
+        },
+        screenshots: {
+            ...generatedProperties.screenshots,
+            description: 'Repository-local raster images used by template galleries.',
+            uniqueItems: true,
+        },
+        capabilities: {
+            ...generatedProperties.capabilities,
+            description: 'Application capabilities, verified against xeer.app.json when the catalog is generated.',
+            uniqueItems: true,
+        },
+        previewAppId: {
+            ...generatedProperties.previewAppId,
+            description: 'Stable first-party application identity used only for the public live preview.',
+        },
+        requiredSecrets: {
+            ...generatedProperties.requiredSecrets,
+            description: 'Secrets a template copy needs before it is usable.',
+        },
+    },
+});
+export function parseTemplateManifest(value) {
+    return templateManifestSchema.parse(value);
+}

package/vendor/spec/tunnel.d.ts

@@ -0,0 +1,109 @@
+export declare const TUNNEL_PROTOCOL: "xeer.tunnel.v0";
+export declare const TUNNEL_GRANT_AUDIENCE: "xeer-tunnel";
+export declare const TUNNEL_GRANT_TYP: "xeer-tunnel-grant+jws";
+export declare const TUNNEL_FALLBACK_AUDIENCE: "xeer-tunnel-fallback";
+export declare const TUNNEL_FALLBACK_TYP: "xeer-tunnel-fallback+jws";
+export declare const TUNNEL_TICKET_HEADER: "x-xeer-tunnel-ticket";
+export declare const TUNNEL_CONTROL_HEADER: "x-xeer-tunnel-control";
+export declare const TUNNEL_SHARED_HEADER: "x-xeer-shared-dev";
+export declare const TUNNEL_SHARED_HOST_HEADER: "x-xeer-shared-host";
+export declare const TUNNEL_PROFILES: readonly ["shared-dev", "raw-http"];
+export type TunnelProfile = (typeof TUNNEL_PROFILES)[number];
+export declare const TUNNEL_BINARY_HEADER_BYTES = 12;
+export declare const TUNNEL_MAX_FRAME_PAYLOAD = 65536;
+export type TunnelBinaryOpcode = 0x01 | 0x02 | 0x03;
+export interface TunnelBinaryFrame {
+    readonly opcode: TunnelBinaryOpcode;
+    readonly final: boolean;
+    readonly streamId: number;
+    /** Starts at zero and advances independently per sender and stream. */
+    readonly seq: number;
+    readonly payload: Uint8Array;
+}
+export interface TunnelLimits {
+    readonly maxBandwidthBytes: number;
+    readonly maxLifetimeSeconds: number;
+    readonly maxConcurrentStreams: number;
+    readonly connectionWindowBytes: number;
+    readonly streamWindowBytes: number;
+    readonly streamIdleSeconds: number;
+}
+export interface TunnelAgentBootstrap {
+    readonly protocol: typeof TUNNEL_PROTOCOL;
+    readonly profile: TunnelProfile;
+    readonly tunnelId: string;
+    readonly url: string;
+    readonly resumeSecret: string;
+    readonly connect: {
+        readonly url: string;
+        readonly ticket: string;
+        readonly ticketExpiresAt: string;
+    };
+    readonly leaseExpiresAt: string;
+    readonly issuerEpoch: number;
+    readonly limits: TunnelLimits;
+}
+export interface TunnelAllocation extends TunnelAgentBootstrap {
+    readonly slug: string;
+    readonly controlSecret: string;
+}
+export type TunnelControlFrame = {
+    readonly t: 'hello';
+    readonly protocol: typeof TUNNEL_PROTOCOL;
+    readonly tunnelId: string;
+    readonly takeover: boolean;
+} | {
+    readonly t: 'ready';
+    readonly tunnelId: string;
+    readonly leaseExpiresAt: string;
+    readonly limits: TunnelLimits;
+    readonly credit: {
+        readonly connectionBytes: number;
+        readonly streamBytes: number;
+    };
+} | {
+    readonly t: 'open';
+    readonly streamId: number;
+    readonly method: string;
+    readonly path: string;
+    readonly headers: readonly (readonly [string, string])[];
+} | {
+    readonly t: 'upgrade';
+    readonly streamId: number;
+    readonly path: string;
+    readonly headers: readonly (readonly [string, string])[];
+    readonly protocols: readonly string[];
+} | {
+    readonly t: 'head';
+    readonly streamId: number;
+    readonly status: number;
+    readonly headers: readonly (readonly [string, string])[];
+} | {
+    readonly t: 'upgrade.result';
+    readonly streamId: number;
+    readonly accepted: boolean;
+    readonly protocol?: string;
+    readonly headers?: readonly (readonly [string, string])[];
+} | {
+    readonly t: 'end';
+    readonly streamId: number;
+} | {
+    readonly t: 'ws.close';
+    readonly streamId: number;
+    readonly code: number;
+    readonly reason: string;
+} | {
+    readonly t: 'window.update';
+    readonly streamId: number;
+    readonly bytes: number;
+} | {
+    readonly t: 'reset';
+    readonly streamId: number;
+    readonly reason: TunnelResetReason;
+};
+export type TunnelResetReason = 'visitor_disconnect' | 'agent_error' | 'agent_refused' | 'revoked' | 'lease_expired' | 'slow_consumer' | 'flow_control_violation' | 'protocol_error' | 'replaced';
+export declare function encodeTunnelBinaryFrame(frame: TunnelBinaryFrame): Uint8Array;
+export declare function decodeTunnelBinaryFrame(input: ArrayBuffer | ArrayBufferView): TunnelBinaryFrame;
+export declare function parseTunnelControlFrame(input: string): TunnelControlFrame;
+export declare function sanitizeTunnelRequestHeaders(headers: Headers, profile?: TunnelProfile): Array<[string, string]>;
+export declare function sanitizeTunnelResponseHeaders(headers: readonly (readonly [string, string])[], profile?: TunnelProfile): Headers;

package/vendor/spec/tunnel.js

@@ -0,0 +1,228 @@
+export const TUNNEL_PROTOCOL = 'xeer.tunnel.v0';
+export const TUNNEL_GRANT_AUDIENCE = 'xeer-tunnel';
+export const TUNNEL_GRANT_TYP = 'xeer-tunnel-grant+jws';
+export const TUNNEL_FALLBACK_AUDIENCE = 'xeer-tunnel-fallback';
+export const TUNNEL_FALLBACK_TYP = 'xeer-tunnel-fallback+jws';
+export const TUNNEL_TICKET_HEADER = 'x-xeer-tunnel-ticket';
+export const TUNNEL_CONTROL_HEADER = 'x-xeer-tunnel-control';
+export const TUNNEL_SHARED_HEADER = 'x-xeer-shared-dev';
+export const TUNNEL_SHARED_HOST_HEADER = 'x-xeer-shared-host';
+export const TUNNEL_PROFILES = ['shared-dev', 'raw-http'];
+export const TUNNEL_BINARY_HEADER_BYTES = 12;
+export const TUNNEL_MAX_FRAME_PAYLOAD = 65_536;
+function uint32(value, field) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > 0xffff_ffff) {
+        throw new RangeError(`${field} must be a uint32.`);
+    }
+}
+export function encodeTunnelBinaryFrame(frame) {
+    uint32(frame.streamId, 'streamId');
+    if (frame.streamId === 0)
+        throw new RangeError('streamId zero is reserved for connection control.');
+    uint32(frame.seq, 'seq');
+    if (![0x01, 0x02, 0x03].includes(frame.opcode))
+        throw new RangeError('Unknown tunnel binary opcode.');
+    if (frame.payload.byteLength > TUNNEL_MAX_FRAME_PAYLOAD) {
+        throw new RangeError(`Tunnel payload exceeds ${TUNNEL_MAX_FRAME_PAYLOAD} bytes.`);
+    }
+    const encoded = new Uint8Array(TUNNEL_BINARY_HEADER_BYTES + frame.payload.byteLength);
+    const view = new DataView(encoded.buffer);
+    view.setUint8(0, 0);
+    view.setUint8(1, frame.opcode);
+    view.setUint8(2, frame.final ? 1 : 0);
+    view.setUint8(3, 0);
+    view.setUint32(4, frame.streamId);
+    view.setUint32(8, frame.seq);
+    encoded.set(frame.payload, TUNNEL_BINARY_HEADER_BYTES);
+    return encoded;
+}
+export function decodeTunnelBinaryFrame(input) {
+    const bytes = input instanceof ArrayBuffer
+        ? new Uint8Array(input)
+        : new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    if (bytes.byteLength < TUNNEL_BINARY_HEADER_BYTES)
+        throw new RangeError('Tunnel binary frame is truncated.');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint8(0) !== 0 || view.getUint8(3) !== 0 || (view.getUint8(2) & 0xfe) !== 0) {
+        throw new RangeError('Tunnel binary frame header is invalid.');
+    }
+    const opcode = view.getUint8(1);
+    if (opcode !== 0x01 && opcode !== 0x02 && opcode !== 0x03) {
+        throw new RangeError('Unknown tunnel binary opcode.');
+    }
+    const streamId = view.getUint32(4);
+    if (streamId === 0)
+        throw new RangeError('streamId zero is reserved for connection control.');
+    const payload = bytes.slice(TUNNEL_BINARY_HEADER_BYTES);
+    if (payload.byteLength > TUNNEL_MAX_FRAME_PAYLOAD)
+        throw new RangeError('Tunnel binary payload is too large.');
+    return { opcode, final: view.getUint8(2) === 1, streamId, seq: view.getUint32(8), payload };
+}
+export function parseTunnelControlFrame(input) {
+    let value;
+    try {
+        value = JSON.parse(input);
+    }
+    catch {
+        throw new TypeError('Tunnel control frame is not JSON.');
+    }
+    if (!value || typeof value !== 'object' || typeof value.t !== 'string') {
+        throw new TypeError('Tunnel control frame has no type.');
+    }
+    const frame = value;
+    const streamId = (allowZero = false) => {
+        if (!Number.isSafeInteger(frame.streamId) || frame.streamId < (allowZero ? 0 : 1)
+            || frame.streamId > 0xffff_ffff)
+            invalidControlFrame();
+    };
+    const text = (field, maximum = 8_192, allowEmpty = false) => {
+        const candidate = frame[field];
+        if (typeof candidate !== 'string' || (!allowEmpty && candidate.length === 0)
+            || candidate.length > maximum)
+            invalidControlFrame();
+    };
+    const headers = (field = 'headers', optional = false) => {
+        const candidate = frame[field];
+        if (optional && candidate === undefined)
+            return;
+        if (!Array.isArray(candidate) || candidate.some((header) => !Array.isArray(header)
+            || header.length !== 2 || typeof header[0] !== 'string' || typeof header[1] !== 'string'
+            || !HEADER_NAME.test(header[0]) || /[\0\r\n]/u.test(header[1]))) {
+            invalidControlFrame();
+        }
+    };
+    switch (frame.t) {
+        case 'hello':
+            text('tunnelId', 256);
+            if (frame.protocol !== TUNNEL_PROTOCOL || typeof frame.takeover !== 'boolean')
+                invalidControlFrame();
+            break;
+        case 'ready': {
+            text('tunnelId', 256);
+            text('leaseExpiresAt', 64);
+            if (Number.isNaN(Date.parse(frame.leaseExpiresAt)) || !validLimits(frame.limits)
+                || !frame.credit || typeof frame.credit !== 'object')
+                invalidControlFrame();
+            const credit = frame.credit;
+            if (!positiveInteger(credit.connectionBytes) || !positiveInteger(credit.streamBytes))
+                invalidControlFrame();
+            break;
+        }
+        case 'open':
+            streamId();
+            text('method', 32);
+            text('path');
+            headers();
+            if (!frame.path.startsWith('/'))
+                invalidControlFrame();
+            break;
+        case 'upgrade':
+            streamId();
+            text('path');
+            headers();
+            if (!frame.path.startsWith('/') || !Array.isArray(frame.protocols)
+                || frame.protocols.some((protocol) => typeof protocol !== 'string' || protocol.length > 256)) {
+                invalidControlFrame();
+            }
+            break;
+        case 'head':
+            streamId();
+            headers();
+            if (!Number.isSafeInteger(frame.status) || frame.status < 100
+                || frame.status > 599)
+                invalidControlFrame();
+            break;
+        case 'upgrade.result':
+            streamId();
+            headers('headers', true);
+            if (typeof frame.accepted !== 'boolean'
+                || (frame.protocol !== undefined && (typeof frame.protocol !== 'string' || frame.protocol.length > 256))) {
+                invalidControlFrame();
+            }
+            break;
+        case 'end':
+            streamId();
+            break;
+        case 'ws.close':
+            streamId();
+            text('reason', 123, true);
+            if (!validWebSocketCloseCode(frame.code)
+                || new TextEncoder().encode(frame.reason).byteLength > 123)
+                invalidControlFrame();
+            break;
+        case 'window.update':
+            streamId(true);
+            if (!positiveInteger(frame.bytes))
+                invalidControlFrame();
+            break;
+        case 'reset':
+            streamId();
+            if (!RESET_REASONS.has(frame.reason))
+                invalidControlFrame();
+            break;
+        default:
+            invalidControlFrame();
+    }
+    return frame;
+}
+const RESET_REASONS = new Set([
+    'visitor_disconnect', 'agent_error', 'agent_refused', 'revoked', 'lease_expired',
+    'slow_consumer', 'flow_control_violation', 'protocol_error', 'replaced',
+]);
+const HEADER_NAME = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u;
+function invalidControlFrame() {
+    throw new TypeError('Tunnel control frame is invalid.');
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value > 0 && value <= 0xffff_ffff;
+}
+function positiveSafeInteger(value) {
+    return Number.isSafeInteger(value) && value > 0;
+}
+function validLimits(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const limits = value;
+    return ['maxBandwidthBytes', 'maxLifetimeSeconds', 'maxConcurrentStreams', 'connectionWindowBytes',
+        'streamWindowBytes', 'streamIdleSeconds'].every((field) => positiveSafeInteger(limits[field]));
+}
+function validWebSocketCloseCode(value) {
+    return Number.isSafeInteger(value)
+        && ((value >= 1000 && value <= 1014) || value >= 3000)
+        && value <= 4999
+        && ![1004, 1005, 1006, 1015].includes(value);
+}
+const HOP_BY_HOP = new Set([
+    'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer',
+    'transfer-encoding', 'upgrade',
+]);
+export function sanitizeTunnelRequestHeaders(headers, profile = 'shared-dev') {
+    const connectionNamed = new Set((headers.get('connection') ?? '').split(',').map((name) => name.trim().toLowerCase()).filter(Boolean));
+    const result = [];
+    for (const [rawName, value] of headers) {
+        const name = rawName.toLowerCase();
+        if ((profile === 'shared-dev' && (name === 'authorization' || name === 'cookie'))
+            || name === 'forwarded'
+            || name === 'x-real-ip' || name.startsWith('x-forwarded-')
+            || name.startsWith('cf-')
+            || name.startsWith('x-xeer-') || name.startsWith('xeer-')
+            || name.startsWith('proxy-') || HOP_BY_HOP.has(name) || connectionNamed.has(name))
+            continue;
+        result.push([name, value]);
+    }
+    return result;
+}
+export function sanitizeTunnelResponseHeaders(headers, profile = 'shared-dev') {
+    const connectionNamed = new Set(headers.filter(([name]) => name.toLowerCase() === 'connection')
+        .flatMap(([, value]) => value.split(',')).map((name) => name.trim().toLowerCase()).filter(Boolean));
+    const result = new Headers();
+    for (const [rawName, value] of headers) {
+        const name = rawName.toLowerCase();
+        if ((profile === 'shared-dev' && name === 'set-cookie') || name.startsWith('proxy-')
+            || HOP_BY_HOP.has(name) || connectionNamed.has(name))
+            continue;
+        result.append(name, value);
+    }
+    result.set('x-robots-tag', 'noindex');
+    return result;
+}