@opentunnel/client 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# OpenTunnel Client
 
-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.
+`@opentunnel/client` is a pure TypeScript SDK for Bun that creates tunnels and
+forwards them to local services from inside your process. TLS terminates in
+your process, so the relay never sees plaintext or your private key.
+
+It implements the same protocol and on-disk layout as the Rust client and CLI
+(see `docs/protocol.md`), so a tunnel created by the CLI can be used here and
+vice versa.
+
+## Quick start
+
+```ts
+import { create } from "@opentunnel/client"
+
+const client = create()
+const connection = await client.tunnel.connect({
+  routes: { api: "127.0.0.1:3000" },
+})
+console.log(`https://api.${connection.tunnel.hostname}`)
+
+for await (const event of connection.events) console.log(event)
+```
+
+`connect` creates the profile's tunnel if it has none, resolves once the bridge
+first attaches, and reconnects with backoff until you call `close()`. It
+rejects on fatal errors such as an invalid token.
+
+The Effect interface exposes the same capabilities, with scoped connections and
+events as a `Stream`:
+
+```ts
+import { OpenTunnelClient } from "@opentunnel/client/effect"
+```
+
+## Routes
+
+Routes map a name to a `host:port` target. A name is a subdomain label, or `@`
+for the tunnel hostname itself. Path routing is not supported.
+
+```ts
+await connection.setRoutes({ api: "127.0.0.1:4000", "@": "127.0.0.1:8080" })
+```
+
+Changing only targets applies to new connections immediately. Adding or
+removing names re-attaches the bridge.
+
+## API
+
+```ts
+interface Client {
+  profile: { list(): Promise<string[]> }
+  tunnel: {
+    list(): Promise<StoredTunnel[]>
+    get(options?: { profile?: string }): Promise<Identity | undefined>
+    pending(options?): Promise<{ id: string; hostname: string } | undefined>
+    create(options?: { profile?: string; onProgress?(stage): void }): Promise<Identity>
+    resume(options?): Promise<Identity | undefined>
+    ensure(options?: { profile?: string }): Promise<Identity>
+    remove(options?: { profile?: string }): Promise<void>
+    connect(options: { profile?: string; routes: Routes; signal?: AbortSignal }): Promise<Connection>
+  }
+  dispose(): Promise<void>
+}
+
+interface Connection {
+  tunnel: Identity
+  events: AsyncIterable<ClientEvent>
+  status(): Status
+  setRoutes(routes: Routes): Promise<void>
+  closed: Promise<void>
+  close(): Promise<void>
+}
+```
+
+Events are `connecting`, `connected`, `disconnected`, `reconnecting`,
+`connection-opened`, `connection-closed`, and `stopped`.
+
+## Storage
+
+`create()` stores identities under `$XDG_DATA_HOME/opentunnel/<profile>/`, the
+same files the CLI uses. Pass a store to isolate or own persistence:
+
+```ts
+import { create, OpenTunnelStorage } from "@opentunnel/client"
+
+const client = create({ store: OpenTunnelStorage.memory() })
+```
+
+## Backpressure
+
+The SDK stops reading from a local socket while more than 1 MiB is queued on
+the bridge WebSocket, and resets a connection whose local side stops reading
+for long enough to buffer 8 MiB. The protocol has no per-connection flow
+control yet, so one slow public reader can delay others on the same bridge.

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@opentunnel/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenTunnel SDK for Bun: expose local services through a blind TLS tunnel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anomalyco/opentunnel.git",
+    "directory": "packages/client"
+  },
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/promise/index.ts",
+    "./promise": "./src/promise/index.ts",
+    "./effect": "./src/effect/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@opentunnel/protocol": "0.0.0",
+    "@peculiar/x509": "2.0.0",
+    "effect": "4.0.0-beta.42",
+    "reflect-metadata": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "25.5.0",
+    "@typescript/native-preview": "7.0.0-dev.20260328.1",
+    "typescript": "6.0.2",
+    "@types/bun": "1.3.13"
+  }
+}

package/src/effect/api.ts

@@ -0,0 +1,39 @@
+import { Effect, Layer, ServiceMap } from "effect";
+import { FetchHttpClient, HttpClient, HttpClientRequest } from "effect/unstable/http";
+import { HttpApiClient } from "effect/unstable/httpapi";
+import { Api } from "@opentunnel/protocol/api/api";
+import { Tunnel } from "@opentunnel/protocol/tunnel";
+
+type Client = HttpApiClient.ForApi<typeof Api>;
+
+interface OpenTunnelApi {
+  readonly client: Client;
+  readonly authorized: (token: Tunnel.Token) => Effect.Effect<Client>;
+}
+
+export class OpenTunnelApiClient extends ServiceMap.Service<OpenTunnelApiClient, OpenTunnelApi>()(
+  "@opentunnel/client/OpenTunnelApiClient",
+) {
+  static layer(options: { readonly api: URL | string }) {
+    return Layer.effect(
+      OpenTunnelApiClient,
+      Effect.gen(function* () {
+        const httpClient = yield* HttpClient.HttpClient;
+        const client = yield* HttpApiClient.makeWith(Api, {
+          baseUrl: options.api,
+          httpClient,
+        });
+        return {
+          client,
+          authorized: (token) =>
+            HttpApiClient.makeWith(Api, {
+              baseUrl: options.api,
+              httpClient: httpClient.pipe(
+                HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+              ),
+            }),
+        };
+      }),
+    ).pipe(Layer.provide(FetchHttpClient.layer));
+  }
+}

package/src/effect/client.ts

@@ -0,0 +1,315 @@
+import "reflect-metadata";
+import { Cause, Effect, Layer, Queue, ServiceMap, Stream } from "effect";
+import {
+  Pkcs10CertificateRequestGenerator,
+  SubjectAlternativeNameExtension,
+} from "@peculiar/x509";
+import { CSR } from "@opentunnel/protocol/csr";
+import { Tunnel } from "@opentunnel/protocol/tunnel";
+import { OpenTunnelApiClient } from "./api.js";
+import { OpenTunnelClientError } from "./errors.js";
+import { OpenTunnelStorage, type OpenTunnelStorage as Storage } from "./storage.js";
+import type {
+  OpenTunnelClientEvent,
+  OpenTunnelConnection,
+  OpenTunnelEffectClient,
+  OpenTunnelIdentity,
+  OpenTunnelPendingIdentity,
+  OpenTunnelProfileOptions,
+  OpenTunnelProvisionStage,
+} from "./types.js";
+import { Tunnel as RunningTunnel, validateRoutes } from "./tunnel.js";
+
+const profileName = (options?: OpenTunnelProfileOptions) => options?.profile ?? "default";
+const clientError = (message: string, cause: unknown) =>
+  new OpenTunnelClientError({ message, cause });
+
+const privateKeyPem = (buffer: ArrayBuffer): string => {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  const body = btoa(binary);
+  return `-----BEGIN PRIVATE KEY-----\n${body.match(/.{1,64}/g)?.join("\n") ?? body}\n-----END PRIVATE KEY-----\n`;
+};
+
+export interface OpenTunnelClientOptions {
+  readonly api?: URL | string;
+  readonly storage?: Storage;
+}
+
+export class OpenTunnelClient extends ServiceMap.Service<
+  OpenTunnelClient,
+  OpenTunnelEffectClient
+>()("@opentunnel/client/OpenTunnelClient") {
+  static layer(options: OpenTunnelClientOptions = {}) {
+    const storage = options.storage ?? OpenTunnelStorage.xdg();
+    return Layer.effect(
+      OpenTunnelClient,
+      Effect.gen(function* () {
+        const api = yield* OpenTunnelApiClient;
+        const apiUrl = new URL(options.api ?? "https://opentunnel.xyz");
+
+        const get = Effect.fn("OpenTunnelClient.tunnel.get")(function* (
+          input?: OpenTunnelProfileOptions,
+        ) {
+          return yield* storage.load(profileName(input));
+        });
+
+        const completePending = Effect.fn("OpenTunnelClient.tunnel.completePending")(function* (options: {
+          readonly profile: string;
+          readonly pending: OpenTunnelPendingIdentity;
+          readonly onProgress?: (stage: OpenTunnelProvisionStage) => void;
+        }) {
+          const authorized = yield* api.authorized(Tunnel.Token.makeUnsafe(options.pending.token));
+          yield* Effect.sync(() => options.onProgress?.("requesting-certificate"));
+          yield* authorized.tunnel["tunnel.bindCertificate"]({
+            params: { id: Tunnel.ID.makeUnsafe(options.pending.id) },
+            payload: { csr: options.pending.csr as CSR.Raw },
+          }).pipe(
+            // A resumed provision may already have an issuance in flight.
+            Effect.catchTag("CertificateInProgressError", () => Effect.void),
+            Effect.mapError((cause) => clientError("Failed to start certificate issuance", cause)),
+          );
+
+          const certificate = yield* Effect.gen(function* () {
+            while (true) {
+              yield* Effect.sync(() => options.onProgress?.("waiting-certificate"));
+              const value = yield* authorized.tunnel["tunnel.getCertificate"]({
+                params: { id: Tunnel.ID.makeUnsafe(options.pending.id) },
+              }).pipe(
+                Effect.mapError((cause) => clientError("Failed to read certificate", cause)),
+              );
+              if (value.state.type === "ready") return value.state;
+              if (value.state.type === "failed") {
+                return yield* new OpenTunnelClientError({
+                  message: `Certificate issuance failed: ${value.state.reason}`,
+                });
+              }
+              yield* Effect.sleep("2 seconds");
+            }
+          });
+          const identity: OpenTunnelIdentity = {
+            id: options.pending.id,
+            hostname: options.pending.hostname,
+            token: options.pending.token,
+            privateKey: options.pending.privateKey,
+            certificate: certificate.certificate,
+            chain: certificate.chain,
+            certificateExpiry: new Date(certificate.expiry),
+          };
+          yield* Effect.sync(() => options.onProgress?.("saving-identity"));
+          yield* storage.save(options.profile, identity);
+          yield* Effect.sync(() => options.onProgress?.("ready"));
+          return identity;
+        });
+
+        const provision = Effect.fn("OpenTunnelClient.tunnel.provision")(function* (options: {
+          readonly profile: string;
+          readonly id: Tunnel.ID;
+          readonly hostname: string;
+          readonly token: Tunnel.Token;
+          readonly onProgress?: (stage: OpenTunnelProvisionStage) => void;
+        }) {
+          yield* Effect.sync(() => options.onProgress?.("generating-key"));
+          const keys = yield* Effect.tryPromise({
+            try: () =>
+              crypto.subtle.generateKey(
+                { name: "ECDSA", namedCurve: "P-256" },
+                true,
+                ["sign", "verify"],
+              ) as Promise<CryptoKeyPair>,
+            catch: (cause) => clientError("Failed to generate certificate key", cause),
+          });
+          yield* Effect.sync(() => options.onProgress?.("generating-csr"));
+          const csr = yield* Effect.tryPromise({
+            try: () =>
+              Pkcs10CertificateRequestGenerator.create({
+                name: `CN=${options.hostname}`,
+                extensions: [
+                  new SubjectAlternativeNameExtension([
+                    { type: "dns", value: options.hostname },
+                    { type: "dns", value: `*.${options.hostname}` },
+                  ]),
+                ],
+                signingAlgorithm: { name: "ECDSA", hash: "SHA-256" },
+                keys,
+              }),
+            catch: (cause) => clientError("Failed to generate certificate request", cause),
+          });
+          const exported = yield* Effect.tryPromise({
+            try: () => crypto.subtle.exportKey("pkcs8", keys.privateKey),
+            catch: (cause) => clientError("Failed to export certificate key", cause),
+          });
+          const pending: OpenTunnelPendingIdentity = {
+            id: String(options.id),
+            hostname: options.hostname,
+            token: options.token,
+            privateKey: privateKeyPem(exported),
+            csr: csr.toString(),
+          };
+          yield* storage.savePending(options.profile, pending);
+          return yield* completePending({
+            profile: options.profile,
+            pending,
+            onProgress: options.onProgress,
+          });
+        });
+
+        const create = Effect.fn("OpenTunnelClient.tunnel.create")(function* (
+          input?: OpenTunnelProfileOptions & {
+            readonly onProgress?: (stage: OpenTunnelProvisionStage) => void;
+          },
+        ) {
+          const profile = profileName(input);
+          if (yield* storage.load(profile)) {
+            return yield* new OpenTunnelClientError({
+              message: `Profile '${profile}' already has a tunnel`,
+            });
+          }
+
+          const pending = yield* storage.loadPending(profile);
+          if (pending) {
+            yield* Effect.sync(() => input?.onProgress?.("resuming-certificate"));
+            return yield* completePending({ profile, pending, onProgress: input?.onProgress });
+          }
+
+          yield* Effect.sync(() => input?.onProgress?.("creating-tunnel"));
+          const created = yield* api.client.tunnel["tunnel.create"]({
+            payload: {},
+          }).pipe(Effect.mapError((cause) => clientError("Failed to create tunnel", cause)));
+          return yield* provision({
+            profile,
+            id: created.tunnel.id,
+            hostname: String(created.tunnel.hostname),
+            token: created.token,
+            onProgress: input?.onProgress,
+          });
+        });
+
+        const ensure = Effect.fn("OpenTunnelClient.tunnel.ensure")(function* (
+          input?: OpenTunnelProfileOptions,
+        ) {
+          const existing = yield* get(input);
+          if (!existing) return yield* create(input);
+          const authorized = yield* api.authorized(Tunnel.Token.makeUnsafe(existing.token));
+          const certificate = yield* authorized.tunnel["tunnel.getCertificate"]({
+            params: { id: Tunnel.ID.makeUnsafe(existing.id) },
+          }).pipe(
+            Effect.mapError((cause) => clientError("Failed to read certificate", cause)),
+          );
+          const state = certificate.state;
+          // The server renewed the certificate while this machine was offline.
+          if (state.type === "ready" && state.certificate !== existing.certificate) {
+            const renewed: OpenTunnelIdentity = {
+              ...existing,
+              certificate: state.certificate,
+              chain: state.chain,
+              certificateExpiry: new Date(state.expiry),
+            };
+            yield* storage.save(profileName(input), renewed);
+            return renewed;
+          }
+          if (state.type !== "failed") return existing;
+          return yield* provision({
+            profile: profileName(input),
+            id: Tunnel.ID.makeUnsafe(existing.id),
+            hostname: existing.hostname,
+            token: Tunnel.Token.makeUnsafe(existing.token),
+          });
+        });
+
+        const pending = Effect.fn("OpenTunnelClient.tunnel.pending")(function* (
+          input?: OpenTunnelProfileOptions,
+        ) {
+          const value = yield* storage.loadPending(profileName(input));
+          return value ? { id: value.id, hostname: value.hostname } : undefined;
+        });
+
+        const resume = Effect.fn("OpenTunnelClient.tunnel.resume")(function* (
+          input?: OpenTunnelProfileOptions & {
+            readonly onProgress?: (stage: OpenTunnelProvisionStage) => void;
+          },
+        ) {
+          const profile = profileName(input);
+          const value = yield* storage.loadPending(profile);
+          if (!value) return undefined;
+          yield* Effect.sync(() => input?.onProgress?.("resuming-certificate"));
+          return yield* completePending({ profile, pending: value, onProgress: input?.onProgress });
+        });
+
+        const client: OpenTunnelEffectClient = {
+          profile: { list: storage.profiles },
+          tunnel: {
+            list: storage.list,
+            get,
+            pending,
+            resume,
+            create,
+            ensure,
+            remove: Effect.fn("OpenTunnelClient.tunnel.remove")(function* (input) {
+              const profile = profileName(input);
+              const identity = yield* storage.load(profile);
+              if (!identity) return;
+              const authorized = yield* api.authorized(Tunnel.Token.makeUnsafe(identity.token));
+              yield* authorized.tunnel["tunnel.remove"]({
+                params: { id: Tunnel.ID.makeUnsafe(identity.id) },
+              }).pipe(
+                Effect.mapError((cause) => clientError("Failed to remove tunnel", cause)),
+              );
+              yield* storage.remove(profile);
+            }),
+            connect: Effect.fn("OpenTunnelClient.tunnel.connect")(function* (input) {
+              yield* Effect.try({
+                try: () => validateRoutes(input.routes),
+                catch: (cause) => clientError(cause instanceof Error ? cause.message : "Invalid routes", cause),
+              });
+              const identity = yield* ensure(input);
+              const events = yield* Queue.unbounded<OpenTunnelClientEvent, Cause.Done>();
+              const tunnel = yield* Effect.acquireRelease(
+                Effect.sync(() =>
+                  new RunningTunnel({
+                    api: apiUrl,
+                    identity,
+                    routes: input.routes,
+                    onEvent: (event) => {
+                      Queue.offerUnsafe(events, event);
+                      if (event.type === "stopped") Queue.endUnsafe(events);
+                    },
+                    onRenewed: (renewed) => {
+                      Effect.runFork(storage.save(profileName(input), renewed).pipe(Effect.ignore));
+                    },
+                  })
+                ),
+                (tunnel) =>
+                  Effect.promise(() => tunnel.close()).pipe(Effect.andThen(Queue.end(events))),
+              );
+              yield* Effect.tryPromise({
+                try: () => tunnel.ready,
+                catch: (cause) => clientError("Failed to connect tunnel", cause),
+              });
+              return {
+                tunnel: identity,
+                events: Stream.fromQueue(events),
+                status: Effect.sync(() => tunnel.getStatus()),
+                setRoutes: (routes) =>
+                  Effect.try({
+                    try: () => tunnel.setRoutes(routes),
+                    catch: (cause) =>
+                      clientError(cause instanceof Error ? cause.message : "Invalid routes", cause),
+                  }),
+                closed: Effect.tryPromise({
+                  try: () => tunnel.closed,
+                  catch: (cause) => clientError("Tunnel stopped", cause),
+                }),
+                close: Effect.promise(() => tunnel.close()),
+              } satisfies OpenTunnelConnection;
+            }),
+          },
+        };
+        return client;
+      }),
+    ).pipe(
+      Layer.provide(OpenTunnelApiClient.layer({ api: options.api ?? "https://opentunnel.xyz" })),
+    );
+  }
+}

package/src/effect/errors.ts

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+
+export class OpenTunnelClientError extends Schema.TaggedErrorClass<OpenTunnelClientError>()(
+  "OpenTunnelClientError",
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+export class OpenTunnelStorageError extends Schema.TaggedErrorClass<OpenTunnelStorageError>()(
+  "OpenTunnelStorageError",
+  { message: Schema.String, cause: Schema.optional(Schema.Defect) },
+) {}
+
+export type OpenTunnelError = OpenTunnelClientError | OpenTunnelStorageError;

package/src/effect/index.ts

@@ -0,0 +1,6 @@
+export * from "./client.js";
+export * from "./api.js";
+export * from "./tunnel.js";
+export * from "./errors.js";
+export * from "./storage.js";
+export * from "./types.js";