@opentunnel/protocol 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# OpenTunnel Protocol
 
-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.
+Shared OpenTunnel wire contracts:
+
+- Tunnel, certificate, and CSR schemas
+- Bridge control messages and binary framing
+- Effect HTTP API definition
+
+This package contains no server or client implementation.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@opentunnel/protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anomalyco/opentunnel.git",
+    "directory": "packages/protocol"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    "./*": "./src/*.ts",
+    "./api/*": "./src/api/*.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "effect": "4.0.0-beta.42"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "bumpp": "11.0.1",
+    "typescript": "6.0.2",
+    "@types/bun": "1.3.13"
+  },
+  "description": "OpenTunnel wire protocol: schemas, bridge framing, and the HTTP API contract"
+}

package/src/api/api.ts

@@ -0,0 +1,12 @@
+import { HttpApi, OpenApi } from "effect/unstable/httpapi";
+import { TunnelGroup } from "./tunnel.js";
+
+export const Api = HttpApi.make("opentunnel")
+  .add(TunnelGroup)
+  .annotateMerge(
+    OpenApi.annotations({
+      title: "OpenTunnel API",
+      version: "0.1.0",
+      description: "Create and manage blind TLS tunnels.",
+    }),
+  );

package/src/api/auth.ts

@@ -0,0 +1,17 @@
+import { ServiceMap } from "effect";
+import { HttpApiMiddleware, HttpApiSecurity } from "effect/unstable/httpapi";
+import { Tunnel } from "../tunnel.js";
+import { UnauthorizedError } from "./errors.js";
+
+export class OpenTunnelAuthorizationToken extends ServiceMap.Service<
+  OpenTunnelAuthorizationToken,
+  Tunnel.Token
+>()("@opentunnel/protocol/OpenTunnelAuthorizationToken") {}
+
+export class OpenTunnelAuthorization extends HttpApiMiddleware.Service<
+  OpenTunnelAuthorization,
+  { provides: OpenTunnelAuthorizationToken }
+>()("@opentunnel/protocol/OpenTunnelAuthorization", {
+  security: { bearer: HttpApiSecurity.bearer },
+  error: UnauthorizedError,
+}) {}

package/src/api/errors.ts

@@ -0,0 +1,49 @@
+import { Schema } from "effect";
+
+export class InvalidRequestError extends Schema.TaggedErrorClass<InvalidRequestError>()(
+  "InvalidRequestError",
+  { message: Schema.String },
+  { httpApiStatus: 400 },
+) {}
+
+export class UnauthorizedError extends Schema.TaggedErrorClass<UnauthorizedError>()(
+  "UnauthorizedError",
+  { message: Schema.String },
+  { httpApiStatus: 401 },
+) {}
+
+export class TunnelNotFoundError extends Schema.TaggedErrorClass<TunnelNotFoundError>()(
+  "TunnelNotFoundError",
+  { tunnelID: Schema.String, message: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+export class CertificateNotFoundError extends Schema.TaggedErrorClass<CertificateNotFoundError>()(
+  "CertificateNotFoundError",
+  { tunnelID: Schema.String, message: Schema.String },
+  { httpApiStatus: 404 },
+) {}
+
+export class InvalidHostnameError extends Schema.TaggedErrorClass<InvalidHostnameError>()(
+  "InvalidHostnameError",
+  { provided: Schema.String, expected: Schema.String, message: Schema.String },
+  { httpApiStatus: 400 },
+) {}
+
+export class HostnameUnavailableError extends Schema.TaggedErrorClass<HostnameUnavailableError>()(
+  "HostnameUnavailableError",
+  { name: Schema.String, message: Schema.String },
+  { httpApiStatus: 409 },
+) {}
+
+export class CertificateInProgressError extends Schema.TaggedErrorClass<CertificateInProgressError>()(
+  "CertificateInProgressError",
+  { tunnelID: Schema.String, message: Schema.String },
+  { httpApiStatus: 409 },
+) {}
+
+export class ServiceUnavailableError extends Schema.TaggedErrorClass<ServiceUnavailableError>()(
+  "ServiceUnavailableError",
+  { message: Schema.String },
+  { httpApiStatus: 503 },
+) {}

package/src/api/index.ts

@@ -0,0 +1,4 @@
+export * from "./api.js";
+export * from "./auth.js";
+export * from "./errors.js";
+export * from "./tunnel.js";

package/src/api/tunnel.ts

@@ -0,0 +1,86 @@
+import { Schema } from "effect";
+import { HttpApiEndpoint, HttpApiGroup, HttpApiSchema, OpenApi } from "effect/unstable/httpapi";
+import { Certificate } from "../certificate.js";
+import { CSR } from "../csr.js";
+import { Tunnel } from "../tunnel.js";
+import {
+  CertificateInProgressError,
+  CertificateNotFoundError,
+  HostnameUnavailableError,
+  InvalidHostnameError,
+  InvalidRequestError,
+  ServiceUnavailableError,
+  TunnelNotFoundError,
+} from "./errors.js";
+import { OpenTunnelAuthorization } from "./auth.js";
+
+export const CreateTunnelRequest = Schema.Struct({
+  /** No longer supported; the server rejects requests that set it. */
+  name: Schema.String.pipe(Schema.optional),
+});
+
+export const CreateTunnelResponse = Schema.Struct({
+  tunnel: Tunnel.Info,
+  token: Tunnel.Token,
+}).pipe(HttpApiSchema.status(201));
+
+export const TunnelGroup = HttpApiGroup.make("tunnel")
+  .add(
+    HttpApiEndpoint.post("tunnel.create", "/api/tunnel", {
+      payload: CreateTunnelRequest,
+      success: CreateTunnelResponse,
+      error: [InvalidRequestError, HostnameUnavailableError, ServiceUnavailableError],
+    }),
+  )
+  .add(
+    HttpApiEndpoint.get("tunnel.get", "/api/tunnel/:id", {
+      params: Schema.Struct({ id: Tunnel.ID }),
+      success: Tunnel.Info,
+      error: [TunnelNotFoundError, ServiceUnavailableError],
+    }).middleware(OpenTunnelAuthorization),
+  )
+  .add(
+    HttpApiEndpoint.post("tunnel.bindCertificate", "/api/tunnel/:id/certificate", {
+      params: Schema.Struct({ id: Tunnel.ID }),
+      payload: Schema.Struct({ csr: CSR.Raw }),
+      success: Certificate.Info.pipe(HttpApiSchema.status(202)),
+      error: [
+        InvalidRequestError,
+        InvalidHostnameError,
+        TunnelNotFoundError,
+        CertificateInProgressError,
+        ServiceUnavailableError,
+      ],
+    }).middleware(OpenTunnelAuthorization),
+  )
+  .add(
+    HttpApiEndpoint.get("tunnel.getCertificate", "/api/tunnel/:id/certificate", {
+      params: Schema.Struct({ id: Tunnel.ID }),
+      success: Certificate.Info,
+      error: [
+        TunnelNotFoundError,
+        CertificateNotFoundError,
+        ServiceUnavailableError,
+      ],
+    }).middleware(OpenTunnelAuthorization),
+  )
+  .add(
+    HttpApiEndpoint.delete("tunnel.remove", "/api/tunnel/:id", {
+      params: Schema.Struct({ id: Tunnel.ID }),
+      success: HttpApiSchema.NoContent,
+      error: [TunnelNotFoundError, ServiceUnavailableError],
+    }).middleware(OpenTunnelAuthorization),
+  )
+  .add(
+    HttpApiEndpoint.get("tunnel.connect", "/api/tunnel/:id/connect", {
+      params: Schema.Struct({ id: Tunnel.ID }),
+      success: Schema.Boolean,
+      error: [TunnelNotFoundError],
+    }).annotateMerge(
+      OpenApi.annotations({
+        summary: "Connect a bridge WebSocket",
+        description: "This endpoint upgrades to the opentunnel WebSocket protocol.",
+      }),
+    ),
+  )
+  .annotateMerge(OpenApi.annotations({ title: "tunnel" }));

package/src/bridge-protocol.ts

@@ -0,0 +1,190 @@
+export * as BridgeProtocol from "./bridge-protocol.js";
+
+import { Option, Schema } from "effect";
+
+/**
+ * Bridge protocol types and schemas for the WebSocket binding.
+ * Based on the bridge protocol specification from specs.md
+ */
+
+// Connection ID - unsigned 32-bit integer assigned by relay
+export const ConnID = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 0xffffffff }));
+export type ConnID = Schema.Schema.Type<typeof ConnID>;
+
+// Client information
+export class ClientInfo extends Schema.Class<ClientInfo>("BridgeProtocol/ClientInfo")({
+  version: Schema.String,
+  max_conns: Schema.Number,
+}) {}
+
+// Attach request - first message after session setup
+export class AttachMessage extends Schema.Class<AttachMessage>("BridgeProtocol/AttachMessage")({
+  type: Schema.Literal("attach"),
+  token: Schema.String,
+  transport: Schema.Literal("ws"),
+  client: ClientInfo,
+  routes: Schema.Array(Schema.String).pipe(Schema.optional),
+}) {}
+
+// Attach success response
+export class AttachedMessage extends Schema.Class<AttachedMessage>(
+  "BridgeProtocol/AttachedMessage",
+)({
+  type: Schema.Literal("attached"),
+  session: Schema.String,
+  routes: Schema.Array(Schema.String),
+  heartbeat_ms: Schema.Number,
+  idle_timeout_ms: Schema.Number,
+}) {}
+
+// Attach failure response
+export class AttachErrorMessage extends Schema.Class<AttachErrorMessage>(
+  "BridgeProtocol/AttachErrorMessage",
+)({
+  type: Schema.Literal("attach_error"),
+  code: Schema.String,
+}) {}
+
+// Ping message
+export class PingMessage extends Schema.Class<PingMessage>("BridgeProtocol/PingMessage")({
+  type: Schema.Literal("ping"),
+  time_sent: Schema.Number,
+}) {}
+
+// Pong message
+export class PongMessage extends Schema.Class<PongMessage>("BridgeProtocol/PongMessage")({
+  type: Schema.Literal("pong"),
+  time_sent: Schema.Number,
+}) {}
+
+// Drain message - graceful shutdown
+export class DrainMessage extends Schema.Class<DrainMessage>("BridgeProtocol/DrainMessage")({
+  type: Schema.Literal("drain"),
+  reason: Schema.String,
+}) {}
+
+// Open channel metadata - relay opens a new public connection
+export class OpenMessage extends Schema.Class<OpenMessage>("BridgeProtocol/OpenMessage")({
+  type: Schema.Literal("open"),
+  conn: ConnID,
+  peer: Schema.String,
+  sni: Schema.String,
+  alpn: Schema.String,
+}) {}
+
+// End message - half-close
+export class EndMessage extends Schema.Class<EndMessage>("BridgeProtocol/EndMessage")({
+  type: Schema.Literal("end"),
+  conn: ConnID,
+}) {}
+
+// Reset message - abortive close
+export class ResetMessage extends Schema.Class<ResetMessage>("BridgeProtocol/ResetMessage")({
+  type: Schema.Literal("reset"),
+  conn: ConnID,
+  code: Schema.String,
+}) {}
+
+// Union of all control message types sent by client
+export const ClientControlMessage = Schema.Union([
+  AttachMessage,
+  PingMessage,
+  PongMessage,
+  DrainMessage,
+  EndMessage,
+  ResetMessage,
+]);
+export type ClientControlMessage = Schema.Schema.Type<typeof ClientControlMessage>;
+
+// Union of all control message types sent by server
+export const ServerControlMessage = Schema.Union([
+  AttachedMessage,
+  AttachErrorMessage,
+  PingMessage,
+  PongMessage,
+  DrainMessage,
+  OpenMessage,
+  EndMessage,
+  ResetMessage,
+]);
+export type ServerControlMessage = Schema.Schema.Type<typeof ServerControlMessage>;
+
+const decodeServerControl = Schema.decodeUnknownOption(ServerControlMessage);
+
+/** Decodes a server control frame. Unknown or invalid messages yield `None`. */
+export function decodeServerMessage(text: string): Option.Option<ServerControlMessage> {
+  try {
+    return decodeServerControl(JSON.parse(text));
+  } catch {
+    return Option.none();
+  }
+}
+
+// Union of all control message types
+export const ControlMessage = Schema.Union([
+  AttachMessage,
+  AttachedMessage,
+  AttachErrorMessage,
+  PingMessage,
+  PongMessage,
+  DrainMessage,
+  OpenMessage,
+  EndMessage,
+  ResetMessage,
+]);
+export type ControlMessage = Schema.Schema.Type<typeof ControlMessage>;
+
+// WebSocket subprotocol name
+export const WEBSOCKET_SUBPROTOCOL = "opentunnel";
+
+// Error codes from specs.md
+export const BridgeErrorCode = {
+  BAD_ATTACH: "bad_attach",
+  BAD_TOKEN: "bad_token",
+  TUNNEL_NOT_BOUND: "tunnel_not_bound",
+  CERT_NOT_READY: "cert_not_ready",
+  REPLACED: "replaced",
+  UPSTREAM_CONNECT_FAILED: "upstream_connect_failed",
+  UPSTREAM_IO_ERROR: "upstream_io_error",
+  CLIENT_IO_ERROR: "client_io_error",
+  IDLE_TIMEOUT: "idle_timeout",
+  ROUTE_CONFLICT: "route_conflict",
+  INVALID_ROUTE: "invalid_route",
+  UNKNOWN_ROUTE: "unknown_route",
+} as const;
+
+// Default timing constants from specs.md
+export const BridgeTiming = {
+  HEARTBEAT_MS: 15000,
+  IDLE_TIMEOUT_MS: 45000,
+  CONNECT_TIMEOUT_MS: 10000,
+  RECONNECT_BACKOFF_MIN_MS: 250,
+  RECONNECT_BACKOFF_MAX_MS: 30000,
+} as const;
+
+// Data frame layout constants for WebSocket binary frames
+// Format: u32_be conn + payload bytes
+export const DataFrame = {
+  CONN_ID_SIZE: 4, // bytes
+  MAX_PAYLOAD_SIZE: 32768, // 32 KiB recommended max per frame
+} as const;
+
+// Parse a binary data frame to extract connection ID and payload
+export function parseDataFrame(data: Uint8Array): { conn: number; payload: Uint8Array } | null {
+  if (data.length < DataFrame.CONN_ID_SIZE) {
+    return null;
+  }
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const conn = view.getUint32(0, false); // big-endian
+  const payload = data.slice(DataFrame.CONN_ID_SIZE);
+  return { conn, payload };
+}
+
+// Build a binary data frame from connection ID and payload
+export function buildDataFrame(conn: number, payload: Uint8Array): Uint8Array<ArrayBuffer> {
+  const result = new Uint8Array(DataFrame.CONN_ID_SIZE + payload.length);
+  const view = new DataView(result.buffer);
+  view.setUint32(0, conn, false); // big-endian
+  result.set(payload, DataFrame.CONN_ID_SIZE);
+  return result;
+}

package/src/certificate.ts

@@ -0,0 +1,39 @@
+export * as Certificate from "./certificate.js";
+
+import { Schema } from "effect";
+import { Newtype } from "./newtype.js";
+
+export class ID extends Newtype<ID>()("CertificateID", Schema.String) {}
+
+export const Token = Schema.String.pipe(Schema.brand("ChallengeToken"));
+export type Token = Schema.Schema.Type<typeof Token>;
+
+export class StateChallenge extends Schema.Class<StateChallenge>("Certificate/StateChallenge")({
+  type: Schema.Literal("challenge"),
+  token: Schema.String,
+  key: Schema.String,
+}) {}
+
+export class StateIssuing extends Schema.Class<StateIssuing>("Certificate/StateIssuing")({
+  type: Schema.Literal("issuing"),
+}) {}
+
+export class StateReady extends Schema.Class<StateReady>("Certificate/StateReady")({
+  type: Schema.Literal("ready"),
+  certificate: Schema.String,
+  chain: Schema.String,
+  expiry: Schema.String,
+}) {}
+
+export class StateFailed extends Schema.Class<StateFailed>("Certificate/StateFailed")({
+  type: Schema.Literal("failed"),
+  reason: Schema.String,
+}) {}
+
+export const State = Schema.Union([StateChallenge, StateIssuing, StateReady, StateFailed]);
+export type State = Schema.Schema.Type<typeof State>;
+
+export class Info extends Schema.Class<Info>("Certificate")({
+  id: ID,
+  state: State,
+}) {}

package/src/csr.ts

@@ -0,0 +1,9 @@
+export * as CSR from "./csr.js";
+
+import { Schema } from "effect";
+
+export const Raw = Schema.String.pipe(Schema.brand("CSR.Raw"));
+export type Raw = Schema.Schema.Type<typeof Raw>;
+
+export const Hostname = Schema.String.pipe(Schema.brand("Hostname"));
+export type Hostname = Schema.Schema.Type<typeof Hostname>;

package/src/index.ts

@@ -0,0 +1,6 @@
+export { BridgeProtocol } from "./bridge-protocol.js";
+export { Certificate } from "./certificate.js";
+export { CSR } from "./csr.js";
+export { Names } from "./names.js";
+export { Tunnel } from "./tunnel.js";
+export * from "./api/index.js";

package/src/names.ts

@@ -0,0 +1,38 @@
+export * as Names from "./names.js";
+
+/** The route name for the tunnel hostname itself. */
+export const ROOT_ROUTE = "@";
+
+const label = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+export const isValidRoute = (value: string): boolean => value === ROOT_ROUTE || label.test(value);
+
+export const isValidProfile = (value: string): boolean => label.test(value);
+
+/** Resolves the route name for a TLS SNI on the given tunnel hostname. */
+export const routeForSni = (sni: string, hostname: string): string | undefined => {
+  const name = sni.toLowerCase();
+  const host = hostname.toLowerCase();
+  if (name === host) return ROOT_ROUTE;
+  const suffix = `.${host}`;
+  if (!name.endsWith(suffix)) return undefined;
+  const route = name.slice(0, -suffix.length);
+  return label.test(route) ? route : undefined;
+};
+
+/** Validates a `host:port` route target and returns its parts. */
+export const parseTarget = (value: string): { readonly host: string; readonly port: number } | undefined => {
+  const separator = value.lastIndexOf(":");
+  if (separator === -1) return undefined;
+  const portText = value.slice(separator + 1);
+  if (!/^\d{1,5}$/.test(portText)) return undefined;
+  const port = Number(portText);
+  if (port < 1 || port > 65535) return undefined;
+  let host = value.slice(0, separator);
+  if (host.startsWith("[")) {
+    if (!host.endsWith("]")) return undefined;
+    host = host.slice(1, -1);
+  }
+  if (!host || !/^[A-Za-z0-9.\-:_]+$/.test(host)) return undefined;
+  return { host, port };
+};

package/src/newtype.ts

@@ -0,0 +1,38 @@
+import { Schema } from "effect";
+
+/**
+ * Nominal wrapper for scalar types with class syntax.
+ * Produces an opaque type that is accepted by Schema constructors
+ * (TaggedErrorClass, Class, Struct) when used as a field.
+ *
+ * @example
+ *   class UserID extends Newtype<UserID>()("UserID", Schema.String) {
+ *     static random() {
+ *       return this.makeUnsafe(crypto.randomUUID());
+ *     }
+ *   }
+ */
+export function Newtype<Self>() {
+  return <const Tag extends string, S extends Schema.Top>(
+    tag: Tag,
+    schema: S,
+  ) => {
+    abstract class Base {
+      declare readonly _newtype: Tag;
+
+      static makeUnsafe(value: Schema.Schema.Type<S>): Self {
+        return value as unknown as Self;
+      }
+    }
+
+    Object.setPrototypeOf(Base, schema);
+
+    return Base as unknown as (abstract new (_: never) => {
+      readonly _newtype: Tag;
+    }) & {
+      readonly makeUnsafe: (value: Schema.Schema.Type<S>) => Self;
+    } & Omit<Schema.Opaque<Self, S, {}>, "makeUnsafe" | "~type.make"> & {
+        readonly "~type.make": Self;
+      };
+  };
+}

package/src/tunnel.ts

@@ -0,0 +1,39 @@
+export * as Tunnel from "./tunnel.js";
+
+import { Schema } from "effect";
+import { CSR } from "./csr.js";
+import { Certificate } from "./certificate.js";
+import { Newtype } from "./newtype.js";
+
+export class ID extends Newtype<ID>()("TunnelID", Schema.String) {}
+
+export const Token = Schema.String.pipe(Schema.brand("TunnelToken"));
+export type Token = Schema.Schema.Type<typeof Token>;
+
+export class NotFoundError extends Schema.TaggedErrorClass()("NotFound", {
+  tunnelID: ID,
+}) {}
+
+export class NoCertificateError extends Schema.TaggedErrorClass()("NoCertificate", {
+  tunnelID: ID,
+}) {}
+
+export class CertificateNotReadyError extends Schema.TaggedErrorClass()(
+  "CertificateNotReady",
+  { tunnelID: ID, currentState: Schema.String },
+) {}
+
+export class InvalidHostnameError extends Schema.TaggedErrorClass()(
+  "InvalidHostname",
+  { provided: CSR.Hostname, expected: CSR.Hostname },
+) {}
+
+export const State = Schema.Literals(["offline", "online"]);
+export type State = Schema.Schema.Type<typeof State>;
+
+export class Info extends Schema.Class<Info>("Tunnel/Info")({
+  id: ID,
+  hostname: CSR.Hostname,
+  state: State,
+  certificateID: Certificate.ID.pipe(Schema.optional),
+}) {}