@limrun/api 0.60.0 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limrun/api",
-  "version": "0.60.0",
+  "version": "0.62.0",
   "description": "The official TypeScript library for the Limrun API",
   "author": "Limrun <contact@limrun.com>",
   "types": "./index.d.ts",

package/resources/android-instances.d.mts

@@ -55,9 +55,9 @@ export declare namespace AndroidInstance {
          */
         hardTimeout?: string;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }
@@ -188,9 +188,9 @@ export declare namespace AndroidInstanceCreateParams {
         region?: string;
         sandbox?: Spec.Sandbox;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }

package/resources/android-instances.d.ts

@@ -55,9 +55,9 @@ export declare namespace AndroidInstance {
          */
         hardTimeout?: string;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }
@@ -188,9 +188,9 @@ export declare namespace AndroidInstanceCreateParams {
         region?: string;
         sandbox?: Spec.Sandbox;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }

package/resources/ios-instances.d.mts

@@ -55,9 +55,9 @@ export declare namespace IosInstance {
          */
         hardTimeout?: string;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }
@@ -181,9 +181,9 @@ export declare namespace IosInstanceCreateParams {
          */
         region?: string;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }

package/resources/ios-instances.d.ts

@@ -55,9 +55,9 @@ export declare namespace IosInstance {
          */
         hardTimeout?: string;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }
@@ -181,9 +181,9 @@ export declare namespace IosInstanceCreateParams {
          */
         region?: string;
         /**
-         * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-         * instance. Creation fails while that tunnel is offline, and the instance
-         * becomes ready only after the tunnel attaches.
+         * Names a persistent tunnel, created in the console (Network) or the API, that
+         * serves this instance. Creation fails while no connector (`lim tunnel run`)
+         * holds it, and the instance becomes ready only after the tunnel attaches.
          */
         tunnel?: string;
     }

package/src/destination-tunnel-dialer.ts

@@ -88,6 +88,11 @@ export type DestinationTunnelStartOptions = Pick<
   'selectors' | 'inspection' | 'onInspectionEvent' | 'onInspectionError' | 'window' | 'logLevel'
 >;
 
+/** The inspection every instance client starts with: on, without bodies. */
+export function destinationTunnelInspection(inspection: DestinationTunnelStartOptions['inspection']) {
+  return { enabled: true, captureBodies: false, ...(inspection ?? {}) };
+}
+
 /**
  * Applies the defaults both instance clients share, so the platforms cannot
  * drift: inspection on, bodies off, and the client's log level.
@@ -98,11 +103,7 @@ export function destinationTunnelDialOptions(
 ): DestinationTcpTunnelOptions {
   return {
     selectors: options.selectors,
-    inspection: {
-      enabled: true,
-      captureBodies: false,
-      ...(options.inspection ?? {}),
-    },
+    inspection: destinationTunnelInspection(options.inspection),
     ...(options.onInspectionEvent ? { onInspectionEvent: options.onInspectionEvent } : {}),
     ...(options.onInspectionError ? { onInspectionError: options.onInspectionError } : {}),
     ...(options.window === undefined ? {} : { window: options.window }),

package/src/internal/destination-tunnel-wire-reader.ts

@@ -20,6 +20,15 @@ export function readArray(record: Record<string, unknown>, key: string): unknown
   return value;
 }
 
+export function readStringArray(record: Record<string, unknown>, key: string): string[] {
+  return readArray(record, key).map((value) => {
+    if (typeof value !== 'string') {
+      throw new DestinationTunnelProtocolError(`${key} must hold strings`);
+    }
+    return value;
+  });
+}
+
 export function readString(record: Record<string, unknown>, key: string): string {
   const value = record[key];
   if (typeof value !== 'string') {
@@ -52,6 +61,14 @@ export function readInteger(record: Record<string, unknown>, key: string): numbe
   return value as number;
 }
 
+export function readPositiveInteger(record: Record<string, unknown>, key: string): number {
+  const value = readInteger(record, key);
+  if (value < 1) {
+    throw new DestinationTunnelProtocolError(`${key} must be positive`);
+  }
+  return value;
+}
+
 export function readFiniteNumber(record: Record<string, unknown>, key: string): number {
   const value = record[key];
   if (typeof value !== 'number' || !Number.isFinite(value)) {

package/src/resources/android-instances.ts

@@ -90,9 +90,9 @@ export namespace AndroidInstance {
     hardTimeout?: string;
 
     /**
-     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-     * instance. Creation fails while that tunnel is offline, and the instance
-     * becomes ready only after the tunnel attaches.
+     * Names a persistent tunnel, created in the console (Network) or the API, that
+     * serves this instance. Creation fails while no connector (`lim tunnel run`)
+     * holds it, and the instance becomes ready only after the tunnel attaches.
      */
     tunnel?: string;
   }
@@ -250,9 +250,9 @@ export namespace AndroidInstanceCreateParams {
     sandbox?: Spec.Sandbox;
 
     /**
-     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-     * instance. Creation fails while that tunnel is offline, and the instance
-     * becomes ready only after the tunnel attaches.
+     * Names a persistent tunnel, created in the console (Network) or the API, that
+     * serves this instance. Creation fails while no connector (`lim tunnel run`)
+     * holds it, and the instance becomes ready only after the tunnel attaches.
      */
     tunnel?: string;
   }

package/src/resources/ios-instances.ts

@@ -90,9 +90,9 @@ export namespace IosInstance {
     hardTimeout?: string;
 
     /**
-     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-     * instance. Creation fails while that tunnel is offline, and the instance
-     * becomes ready only after the tunnel attaches.
+     * Names a persistent tunnel, created in the console (Network) or the API, that
+     * serves this instance. Creation fails while no connector (`lim tunnel run`)
+     * holds it, and the instance becomes ready only after the tunnel attaches.
      */
     tunnel?: string;
   }
@@ -239,9 +239,9 @@ export namespace IosInstanceCreateParams {
     region?: string;
 
     /**
-     * Names a persistent tunnel (`lim tunnel run --name`) that serves this
-     * instance. Creation fails while that tunnel is offline, and the instance
-     * becomes ready only after the tunnel attaches.
+     * Names a persistent tunnel, created in the console (Network) or the API, that
+     * serves this instance. Creation fails while no connector (`lim tunnel run`)
+     * holds it, and the instance becomes ready only after the tunnel attaches.
      */
     tunnel?: string;
   }

package/src/tunnel-connector.ts

@@ -9,7 +9,8 @@ import {
 } from './internal/destination-tunnel-management';
 import {
   DestinationTunnelProtocolError,
-  readInteger,
+  readPositiveInteger,
+  readStringArray,
   readNonEmptyString,
   readOptionalString,
   readRecord,
@@ -19,6 +20,7 @@ import {
 import {
   DestinationTunnelSessionError,
   destinationTunnelDialOptions,
+  destinationTunnelInspection,
   startDestinationTcpTunnel,
   type DestinationTcpTunnel,
 } from './destination-tunnel-dialer';
@@ -31,7 +33,7 @@ import {
 import { upgradeStatus, type LogLevel } from './tunnel';
 import { VERSION } from './version';
 
-const CONTROL_PROTOCOL_VERSION = 1;
+const CONTROL_PROTOCOL_VERSION = 2;
 const CONTROL_HANDSHAKE_TIMEOUT_MS = 15_000;
 const CONTROL_PING_INTERVAL_MS = 15_000;
 const CONTROL_DEAD_PEER_MS = 45_000;
@@ -47,15 +49,23 @@ const MAX_REJECTION_REASON_CHARS = 200;
 /** Every tunnel WebSocket counts as instance activity, so retries must end. */
 const ATTACH_GIVE_UP_MS = 5 * 60_000;
 const TAKEN_OVER_MESSAGE = 'another connector for this tunnel took the instance over';
+/** A token this close to its expiry is not dialed with; the hub refreshes it at half its life. */
+const TOKEN_EXPIRY_MARGIN_MS = 5_000;
+/** How long before its token expires the connector starts warning, and how often. */
+const TOKEN_WARNING_WINDOW_MS = 14 * 24 * 60 * 60_000;
+const TOKEN_WARNING_EVERY_MS = 24 * 60 * 60_000;
 
 export interface TunnelConnectorOptions {
-  apiKey: string;
+  /** The tunnel's token; no other credential connects. */
+  token: string;
   /** Limrun API base URL, such as https://api.limrun.com. */
   baseURL: string;
   organizationId: string;
-  /** The name instances set in `spec.tunnel` to attach to this connector. */
-  name: string;
-  selectors: DestinationTunnelSelectors;
+  /**
+   * The ID of a tunnel created in the console or the API. Its name, which
+   * instances set in `spec.tunnel`, and its selectors come from the platform.
+   */
+  tunnelId: string;
   /** Inspection for every instance tunnel. Defaults to enabled without bodies. */
   inspection?: Partial<DestinationTunnelInspectionConfig>;
   /** Take the name over from the connector that holds it now. */
@@ -70,8 +80,10 @@ export interface TunnelConnectorOptions {
 }
 
 export type TunnelConnectorEvent =
-  /** This connector holds the name; emitted once per session and control connection. */
-  | { type: 'active'; sessionId: string }
+  /** This connector holds the tunnel; emitted once per session and control connection. */
+  | { type: 'active'; sessionId: string; name: string }
+  /** The connector's tunnel token expires within two weeks; emitted once a day until it does. */
+  | { type: 'tokenExpiring'; expiresAt: string }
   /** Another connector holds the name; emitted once per holder. */
   | { type: 'standby'; holder: { hostname: string; since?: string } }
   | { type: 'attached'; instanceId: string; tunnelId: string }
@@ -93,7 +105,6 @@ type ControlClientMessage =
   | {
       type: 'hello';
       version: number;
-      selectors: DestinationTunnelSelectors;
       replace: boolean;
       sessionId?: string;
       attached: string[];
@@ -104,9 +115,17 @@ type ControlClientMessage =
   | { type: 'bye' };
 
 type ControlServerMessage =
-  | { type: 'active'; sessionId: string; leaseSeconds: number }
+  | { type: 'active'; sessionId: string; leaseSeconds: number; name: string; tokenExpiresAt?: string }
   | { type: 'standby'; holder: { hostname: string; since?: string } }
-  | { type: 'attach'; instanceId: string; url: string; token: string }
+  | {
+      type: 'attach';
+      instanceId: string;
+      url: string;
+      selectors: string[];
+      token: string;
+      expiresInSeconds: number;
+    }
+  | { type: 'token'; instanceId: string; token: string; expiresInSeconds: number }
   | { type: 'detach'; instanceId: string; reason: string }
   | { type: 'notice'; code: string; message: string; instanceId?: string }
   | { type: 'revoked'; reason: string };
@@ -114,7 +133,11 @@ type ControlServerMessage =
 interface InstanceAttachment {
   /** Instance base URL: the iOS API URL or the Android ADB WebSocket URL. */
   url: string;
+  /** Opens this instance's tunnel and nothing else; the hub keeps it fresh. */
   token: string;
+  tokenExpiresAt: number;
+  /** The tunnel's selectors when the instance first attached; later edits apply to later instances. */
+  selectors: DestinationTunnelSelectors;
   tunnel?: DestinationTcpTunnel | undefined;
   /** This connector's latest tunnel on the instance, live or dropped. */
   lastTunnelId?: string;
@@ -129,23 +152,17 @@ interface InstanceAttachment {
 }
 
 /**
- * Serve a persistent tunnel: hold the name through one control WebSocket to
- * the Limrun API and open a destination tunnel to every instance created
- * with `spec.tunnel` set to it. Instance tunnels stay up while the control
- * channel reconnects, so an API outage never becomes a tunnel outage.
+ * Serve a persistent tunnel: hold it through one control WebSocket to the
+ * Limrun API and open a destination tunnel to every instance created with
+ * `spec.tunnel` set to its name, with a short-lived token the API hands out
+ * for each. Instance tunnels stay up while the control channel reconnects,
+ * so an API outage never becomes a tunnel outage; one that drops re-dials
+ * once the API sends a fresh token.
  */
 export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
-  const selectors = validateDestinationTunnelSelectors(options.selectors);
-  const dialOptions = {
-    ...destinationTunnelDialOptions(
-      { selectors, ...(options.inspection ? { inspection: options.inspection } : {}) },
-      options.logLevel ?? 'warn',
-    ),
-    name: options.name,
-  };
   // Reject a bad inspection config now rather than on every attach.
-  normalizeDestinationTunnelInspection(dialOptions.inspection ?? {});
-  const controlURL = deriveTunnelConnectURL(options.baseURL, options.organizationId, options.name);
+  normalizeDestinationTunnelInspection(destinationTunnelInspection(options.inspection));
+  const controlURL = deriveTunnelConnectURL(options.baseURL, options.organizationId, options.tunnelId);
   const client = {
     hostname: options.hostname ?? os.hostname(),
     version: options.clientVersion ?? VERSION,
@@ -162,6 +179,9 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
   let replace = options.replace ?? false;
   // When the last confirmed lease runs out; zero while on standby.
   let leaseExpiresAt = 0;
+  // The tunnel's name, from the first active; instances set it in spec.tunnel.
+  let tunnelName: string | undefined;
+  let lastTokenWarning = 0;
   let announcedSession: string | undefined;
   let announcedHolder: string | undefined;
 
@@ -211,7 +231,24 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
   const fail = (detail: string): void => {
     if (!shutdown()) return;
     ws?.terminate();
-    rejectClosed(new Error(`tunnel ${options.name}: ${detail}`));
+    rejectClosed(new Error(`tunnel ${tunnelName ?? options.tunnelId}: ${detail}`));
+  };
+
+  const dialOptions = (attachment: InstanceAttachment) => ({
+    ...destinationTunnelDialOptions(
+      { selectors: attachment.selectors, ...(options.inspection ? { inspection: options.inspection } : {}) },
+      options.logLevel ?? 'warn',
+    ),
+    ...(tunnelName === undefined ? {} : { name: tunnelName }),
+  });
+
+  const tokenUsable = (attachment: InstanceAttachment): boolean =>
+    Date.now() < attachment.tokenExpiresAt - TOKEN_EXPIRY_MARGIN_MS;
+
+  // Tells the platform and the caller that the connector gave up on an instance.
+  const reportGivenUp = (instanceId: string, code: string, message: string): void => {
+    send({ type: 'attachFailed', instanceId, code, message, terminal: true });
+    emit({ type: 'attachFailed', instanceId, code, message });
   };
 
   const giveUp = (
@@ -221,8 +258,7 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
     message: string,
   ): void => {
     forget(instanceId, attachment);
-    send({ type: 'attachFailed', instanceId, code, message, terminal: true });
-    emit({ type: 'attachFailed', instanceId, code, message });
+    reportGivenUp(instanceId, code, message);
   };
 
   const scheduleAttachRetry = (instanceId: string, attachment: InstanceAttachment, reason: string): void => {
@@ -254,7 +290,8 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
     try {
       const active = (await getDestinationTunnelStatus(attachment.url, attachment.token)).active;
       return (
-        active?.name === options.name &&
+        active !== undefined &&
+        active.name === tunnelName &&
         active.state !== 'stopping' &&
         active.tunnelId !== attachment.lastTunnelId
       );
@@ -288,7 +325,7 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
       retryAfterFailure(instanceId, attachment, 'already_active', 'the previous tunnel is still stopping');
       return;
     }
-    if (active.name !== options.name) {
+    if (active.name !== tunnelName) {
       giveUp(instanceId, attachment, 'instance_busy', 'the instance already has another tunnel');
       return;
     }
@@ -322,6 +359,12 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
       retryAfterFailure(instanceId, attachment, 'not_holder', 'this connector does not hold the tunnel');
       return;
     }
+    // A token past its life is refused; the API sends a fresh one at half
+    // life, so this only waits while the control channel is down.
+    if (!tokenUsable(attachment)) {
+      retryAfterFailure(instanceId, attachment, 'token_expired', 'waiting for a fresh attach token');
+      return;
+    }
     let tunnel: DestinationTcpTunnel;
     try {
       if (attachment.lastTunnelId !== undefined && (await takenOver(attachment))) {
@@ -334,7 +377,7 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
       tunnel = await startDestinationTcpTunnel(
         deriveDestinationTunnelURL(attachment.url),
         attachment.token,
-        dialOptions,
+        dialOptions(attachment),
       );
     } catch (error) {
       if (attachment.done) return;
@@ -387,17 +430,28 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
     // close() already let every instance go; a late attach must not dial.
     if (stopped) return;
     switch (message.type) {
-      case 'active':
+      case 'active': {
         replace = false;
         leaseExpiresAt = Date.now() + message.leaseSeconds * 1000;
         controlBackoffMs = CONTROL_INITIAL_BACKOFF_MS;
         sessionId = message.sessionId;
+        tunnelName = message.name;
         announcedHolder = undefined;
         if (announcedSession !== message.sessionId) {
           announcedSession = message.sessionId;
-          emit({ type: 'active', sessionId: message.sessionId });
+          emit({ type: 'active', sessionId: message.sessionId, name: message.name });
+        }
+        const now = Date.now();
+        if (
+          message.tokenExpiresAt !== undefined &&
+          Date.parse(message.tokenExpiresAt) - now < TOKEN_WARNING_WINDOW_MS &&
+          now - lastTokenWarning >= TOKEN_WARNING_EVERY_MS
+        ) {
+          lastTokenWarning = now;
+          emit({ type: 'tokenExpiring', expiresAt: message.tokenExpiresAt });
         }
         return;
+      }
       case 'standby': {
         leaseExpiresAt = 0;
         controlBackoffMs = CONTROL_INITIAL_BACKOFF_MS;
@@ -410,20 +464,46 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
         }
         return;
       }
+      case 'token': {
+        // A fresh token at half its life, or after a resume. An instance this
+        // connector gave up on stays given up.
+        const attachment = instances.get(message.instanceId);
+        if (attachment) {
+          attachment.token = message.token;
+          attachment.tokenExpiresAt = Date.now() + message.expiresInSeconds * 1000;
+        }
+        return;
+      }
       case 'attach': {
+        // Expiry is relative, so this host's clock never matters.
+        const tokenExpiresAt = Date.now() + message.expiresInSeconds * 1000;
         const existing = instances.get(message.instanceId);
         if (existing) {
-          // Resume replays attaches; a live tunnel only needs confirming.
+          // A new holder session re-attaches every instance, including ones
+          // this connector still serves; a live tunnel only needs confirming.
+          // The instance keeps the selectors it first got.
           existing.url = message.url;
           existing.token = message.token;
+          existing.tokenExpiresAt = tokenExpiresAt;
           if (existing.tunnel) {
             send({ type: 'attached', instanceId: message.instanceId, tunnelId: existing.tunnel.tunnelId });
           }
           return;
         }
+        // The instance itself refuses what its platform cannot route, such
+        // as Android routes below port 1024.
+        let selectors: DestinationTunnelSelectors;
+        try {
+          selectors = validateDestinationTunnelSelectors(message.selectors);
+        } catch (error) {
+          reportGivenUp(message.instanceId, 'invalid_selectors', errorMessage(error));
+          return;
+        }
         const attachment: InstanceAttachment = {
           url: message.url,
           token: message.token,
+          tokenExpiresAt,
+          selectors,
           mayReclaim: true,
           failingSince: Date.now(),
           backoffMs: ATTACH_INITIAL_BACKOFF_MS,
@@ -485,7 +565,7 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
     if (stopped) return;
     const proxyAgent = nodeProxyTransport.getWebSocketAgent(controlURL);
     const socket = new WebSocket(controlURL, {
-      headers: { Authorization: `Bearer ${options.apiKey}` },
+      headers: { Authorization: `Bearer ${options.token}` },
       ...(proxyAgent ? { agent: proxyAgent } : {}),
       perMessageDeflate: false,
       // A stalled upgrade, such as after a laptop wakes, would otherwise
@@ -518,7 +598,6 @@ export function runTunnel(options: TunnelConnectorOptions): TunnelConnector {
       send({
         type: 'hello',
         version: CONTROL_PROTOCOL_VERSION,
-        selectors,
         replace,
         ...(sessionId === undefined ? {} : { sessionId }),
         attached: Array.from(instances)
@@ -614,11 +693,13 @@ function decodeControlServerMessage(value: unknown): ControlServerMessage | unde
   const type = readString(message, 'type');
   switch (type) {
     case 'active': {
-      const leaseSeconds = readInteger(message, 'leaseSeconds');
-      if (leaseSeconds < 1) {
-        throw new DestinationTunnelProtocolError('leaseSeconds must be positive');
-      }
-      return { type, sessionId: readNonEmptyString(message, 'sessionId'), leaseSeconds };
+      return {
+        type,
+        sessionId: readNonEmptyString(message, 'sessionId'),
+        leaseSeconds: readPositiveInteger(message, 'leaseSeconds'),
+        name: readNonEmptyString(message, 'name'),
+        ...readOptionalString(message, 'tokenExpiresAt'),
+      };
     }
     case 'standby': {
       const holder = readRecord(message['holder'], 'holder');
@@ -632,7 +713,16 @@ function decodeControlServerMessage(value: unknown): ControlServerMessage | unde
         type,
         instanceId: readNonEmptyString(message, 'instanceId'),
         url: readNonEmptyString(message, 'url'),
+        selectors: readStringArray(message, 'selectors'),
+        token: readNonEmptyString(message, 'token'),
+        expiresInSeconds: readPositiveInteger(message, 'expiresInSeconds'),
+      };
+    case 'token':
+      return {
+        type,
+        instanceId: readNonEmptyString(message, 'instanceId'),
         token: readNonEmptyString(message, 'token'),
+        expiresInSeconds: readPositiveInteger(message, 'expiresInSeconds'),
       };
     case 'detach':
       return {
@@ -662,7 +752,7 @@ function revokedMessage(reason: string): string {
     case 'deleted':
       return 'the tunnel was deleted';
     case 'credential':
-      return 'the API key was revoked';
+      return 'its tunnel token was rotated, revoked or has expired';
     default:
       return `the tunnel was revoked (${reason})`;
   }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.60.0'; // x-release-please-version
+export const VERSION = '0.62.0'; // x-release-please-version

package/tunnel-connector.d.mts

@@ -1,13 +1,16 @@
-import { type DestinationTunnelInspectionConfig, type DestinationTunnelSelectors } from "./destination-tunnel.mjs";
+import { type DestinationTunnelInspectionConfig } from "./destination-tunnel.mjs";
 import { type LogLevel } from "./tunnel.mjs";
 export interface TunnelConnectorOptions {
-    apiKey: string;
+    /** The tunnel's token; no other credential connects. */
+    token: string;
     /** Limrun API base URL, such as https://api.limrun.com. */
     baseURL: string;
     organizationId: string;
-    /** The name instances set in `spec.tunnel` to attach to this connector. */
-    name: string;
-    selectors: DestinationTunnelSelectors;
+    /**
+     * The ID of a tunnel created in the console or the API. Its name, which
+     * instances set in `spec.tunnel`, and its selectors come from the platform.
+     */
+    tunnelId: string;
     /** Inspection for every instance tunnel. Defaults to enabled without bodies. */
     inspection?: Partial<DestinationTunnelInspectionConfig>;
     /** Take the name over from the connector that holds it now. */
@@ -21,10 +24,16 @@ export interface TunnelConnectorOptions {
     onEvent?: (event: TunnelConnectorEvent) => void;
 }
 export type TunnelConnectorEvent = 
-/** This connector holds the name; emitted once per session and control connection. */
+/** This connector holds the tunnel; emitted once per session and control connection. */
 {
     type: 'active';
     sessionId: string;
+    name: string;
+}
+/** The connector's tunnel token expires within two weeks; emitted once a day until it does. */
+ | {
+    type: 'tokenExpiring';
+    expiresAt: string;
 }
 /** Another connector holds the name; emitted once per holder. */
  | {
@@ -68,10 +77,12 @@ export interface TunnelConnector {
     close: () => Promise<void>;
 }
 /**
- * Serve a persistent tunnel: hold the name through one control WebSocket to
- * the Limrun API and open a destination tunnel to every instance created
- * with `spec.tunnel` set to it. Instance tunnels stay up while the control
- * channel reconnects, so an API outage never becomes a tunnel outage.
+ * Serve a persistent tunnel: hold it through one control WebSocket to the
+ * Limrun API and open a destination tunnel to every instance created with
+ * `spec.tunnel` set to its name, with a short-lived token the API hands out
+ * for each. Instance tunnels stay up while the control channel reconnects,
+ * so an API outage never becomes a tunnel outage; one that drops re-dials
+ * once the API sends a fresh token.
  */
 export declare function runTunnel(options: TunnelConnectorOptions): TunnelConnector;
 //# sourceMappingURL=tunnel-connector.d.mts.map