@openclaw/gateway-client 0.0.0 → 2026.7.2-beta.5

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+- Publish the reference Gateway WebSocket client for the first time.
+- Record the client extraction from the Gateway protocol implementation in #87797.
+- Support the current Gateway wire protocol, protocol v4.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Foundation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,134 @@
-# OpenClaw Gateway Client
+# `@openclaw/gateway-client`
 
-Reserved package name. Release artifacts are published by OpenClaw release automation.
+Reference WebSocket client for the OpenClaw Gateway protocol. It provides the
+connection state machine used by OpenClaw's own Node and browser clients:
+challenge-based authentication, typed protocol frames, request correlation,
+timeouts, reconnect backoff, device-token handling, and event delivery.
+
+The current wire protocol is version 4. General clients must negotiate v4 with
+`minProtocol: 4` and `maxProtocol: 4`. See the
+[Gateway protocol specification](https://docs.openclaw.ai/gateway/protocol) for
+the complete handshake, authentication, role, scope, and method contracts.
+
+## Versioning
+
+Package versions follow the OpenClaw calendar release train: `YYYY.M.PATCH`,
+including the OpenClaw prerelease suffix when applicable. The package version is
+separate from the negotiated wire protocol number.
+
+## Install
+
+```bash
+npm install @openclaw/gateway-client @openclaw/gateway-protocol
+```
+
+Node consumers use the `ws` transport included as a runtime dependency. Browser
+consumers provide their platform WebSocket through the browser-safe protocol
+client surface.
+
+## Entry points
+
+- `@openclaw/gateway-client` exports the Node `GatewayClient`, device-auth
+  helpers, readiness helpers, and timeout utilities.
+- `@openclaw/gateway-client/browser` exports the browser-safe protocol client,
+  browser device-auth lifecycle, reconnect policy, and lightweight protocol
+  constants. Its module graph does not import Node built-ins or `ws`.
+- `@openclaw/gateway-client/readiness` exports helpers that delay client startup
+  until the event loop can process Gateway IO.
+- `@openclaw/gateway-client/timeouts` exports timeout constants and safe timer
+  resolution helpers.
+
+## Node quickstart
+
+```ts
+import { GatewayClient } from "@openclaw/gateway-client";
+import { PROTOCOL_VERSION } from "@openclaw/gateway-protocol/version";
+
+const connected = Promise.withResolvers<void>();
+const client = new GatewayClient({
+  url: "ws://127.0.0.1:18789",
+  token: process.env.OPENCLAW_GATEWAY_TOKEN,
+  minProtocol: PROTOCOL_VERSION, // v4
+  maxProtocol: PROTOCOL_VERSION, // v4
+  onHelloOk: () => connected.resolve(),
+  onConnectError: (error) => connected.reject(error),
+  onEvent: (event) => {
+    console.log(event.event, event.payload);
+  },
+});
+
+client.start();
+await connected.promise;
+
+const status = await client.request("status", {});
+console.log(status);
+
+client.stop();
+```
+
+The client waits for the Gateway's `connect.challenge` event before sending its
+`connect` request. It includes the challenge nonce in device authentication and
+does not fall back to a pre-challenge handshake. `onHelloOk` fires only after the
+Gateway accepts the v4 connection, so requests should wait for that callback.
+
+For remote connections, use `wss://`. Plaintext `ws://` is allowed by default
+only for loopback addresses. Authentication material and Gateway traffic must
+not cross an untrusted network without transport security.
+
+## Browser clients
+
+Import `@openclaw/gateway-client/browser` when the host owns the WebSocket
+adapter and device-key storage. The browser entry includes
+`GatewayProtocolClient` and `GatewayBrowserDeviceAuthLifecycle`; it deliberately
+omits the Node transport, TLS fingerprint handling, and private-network address
+policy.
+
+The host is responsible for:
+
+- creating a `GatewayProtocolSocket` adapter around the browser WebSocket;
+- loading and storing browser device identity and issued device tokens;
+- signing the challenge-bound device payload;
+- supplying the client identity, role, scopes, and authentication selection;
+- choosing close and reconnect behavior for product-specific errors.
+
+The shared protocol client still owns frame parsing, request correlation,
+challenge ordering, timeout cleanup, sequence-gap detection, and reconnect
+scheduling.
+
+## Defaults and reconnect behavior
+
+The Node client starts with a 30 second request timeout, a 15 second
+connect-challenge timeout, and exponential reconnect delays from 1 second to 30
+seconds with a multiplier of 2. Server-provided startup retry hints may override
+the next delay.
+
+The canonical defaults table and the server policy fields that can replace
+pre-handshake values are documented in the
+[Gateway protocol specification](https://docs.openclaw.ai/gateway/protocol#client-constants).
+
+Use the `./timeouts` entry point when a host must align readiness or watchdog
+budgets with these defaults. Use the `./readiness` entry point when startup must
+wait for an event-loop probe before opening the socket.
+
+## Bundled internals
+
+The retry supervisor and the small `@openclaw/net-policy/ip` implementation are
+inlined into the published JavaScript and declarations. They are implementation
+details, not public exports or supported API surfaces. `ipaddr.js` remains an
+external dependency because the inlined IP helpers use its public runtime and
+types.
+
+`ws`, `@openclaw/gateway-protocol`, and `ipaddr.js` remain external in the
+published distribution. Consumers should import protocol types and constants
+from `@openclaw/gateway-protocol`, not from bundled implementation paths.
+
+## Contract notes
+
+- The client is inert at module import and construction time. `start()` opens
+  the socket; `stop()` closes it and rejects pending requests.
+- A request uses `request(method, params)` after `hello-ok`. Passing
+  `timeoutMs: null` creates an intentionally unbounded request.
+- Device identity persistence, signing, proxy routing, TLS formatting, and
+  logging stay host-owned through `GatewayClientHostDeps`.
+- Protocol changes are additive first. Incompatible changes require an explicit
+  wire-version decision and coordinated server/client follow-through.

package/dist/browser-device-auth-Bp297Rtf.d.mts

@@ -0,0 +1,130 @@
+import { ConnectParams, HelloOk } from "@openclaw/gateway-protocol";
+
+//#region packages/gateway-client/src/device-auth.d.ts
+declare function normalizeDeviceMetadataForAuth(value?: string | null): string;
+type DeviceAuthPayloadParams = {
+  deviceId: string;
+  clientId: string;
+  clientMode: string;
+  role: string;
+  scopes: string[];
+  signedAtMs: number;
+  token?: string | null;
+  nonce: string;
+};
+type DeviceAuthPayloadV3Params = DeviceAuthPayloadParams & {
+  platform?: string | null;
+  deviceFamily?: string | null;
+};
+declare function buildDeviceAuthPayload(params: DeviceAuthPayloadParams): string;
+declare function buildDeviceAuthPayloadV3(params: DeviceAuthPayloadV3Params): string;
+//#endregion
+//#region packages/gateway-client/src/connect-auth.d.ts
+type GatewayConnectAuthSelection = {
+  authToken?: string;
+  authBootstrapToken?: string;
+  authDeviceToken?: string;
+  authPassword?: string;
+  authApprovalRuntimeToken?: string;
+  authAgentRuntimeIdentityToken?: string;
+  signatureToken?: string;
+  resolvedDeviceToken?: string;
+  storedToken?: string;
+  storedScopes?: string[];
+  usingStoredDeviceToken?: boolean;
+};
+declare function selectGatewayConnectAuth(params: {
+  token?: string;
+  bootstrapToken?: string;
+  deviceToken?: string;
+  password?: string;
+  approvalRuntimeToken?: string;
+  agentRuntimeIdentityToken?: string;
+  storedToken?: string;
+  storedScopes?: string[];
+  pendingDeviceTokenRetry?: boolean;
+  trustedDeviceTokenRetry?: boolean;
+  preferBootstrapToken?: boolean;
+}): GatewayConnectAuthSelection;
+declare function buildGatewayConnectAuth(selected: GatewayConnectAuthSelection): ConnectParams["auth"];
+declare function resolveGatewayConnectScopes(params: {
+  requestedScopes?: string[];
+  usingStoredDeviceToken?: boolean;
+  storedScopes?: string[];
+  defaultScopes: readonly string[];
+}): string[];
+declare function shouldRetryGatewayWithDeviceToken(params: {
+  retryBudgetUsed: boolean;
+  currentDeviceToken?: string;
+  explicitToken?: string;
+  storedToken?: string;
+  trustedEndpoint: boolean;
+  canRetryWithDeviceTokenHint?: boolean;
+  errorDetails?: unknown;
+}): boolean;
+//#endregion
+//#region packages/gateway-client/src/browser-device-auth.d.ts
+type GatewayBrowserDeviceIdentity = {
+  deviceId: string;
+  publicKey: string;
+  sign: (payload: string) => Promise<string>;
+};
+type GatewayBrowserDeviceTokenRecord = {
+  token: string;
+  scopes: string[];
+};
+type MaybePromise<T> = T | Promise<T>;
+type GatewayBrowserDeviceTokenStore = {
+  load: (params: {
+    clientId: string;
+    deviceId: string;
+    role: string;
+  }) => MaybePromise<GatewayBrowserDeviceTokenRecord | null>;
+  store: (params: {
+    clientId: string;
+    deviceId: string;
+    role: string;
+    token: string;
+    scopes: string[];
+  }) => MaybePromise<void>;
+  clear: (params: {
+    clientId: string;
+    deviceId: string;
+    role: string;
+  }) => MaybePromise<void>;
+};
+type GatewayBrowserDeviceAuthPlan = {
+  clientId: string;
+  role: string;
+  identity: GatewayBrowserDeviceIdentity | null;
+  selectedAuth: GatewayConnectAuthSelection;
+  scopes: string[];
+  device?: NonNullable<ConnectParams["device"]>;
+  auth?: ConnectParams["auth"];
+};
+/** Browser-safe device pairing and issued-token lifecycle shared by first-party UI clients. */
+declare class GatewayBrowserDeviceAuthLifecycle {
+  private readonly deps;
+  constructor(deps: {
+    loadIdentity: () => Promise<GatewayBrowserDeviceIdentity | null>;
+    tokenStore: GatewayBrowserDeviceTokenStore;
+    nowMs?: () => number;
+  });
+  buildPlan(params: {
+    client: ConnectParams["client"];
+    role: string;
+    defaultScopes: readonly string[];
+    bootstrapScopes?: readonly string[];
+    token?: string;
+    bootstrapToken?: string;
+    password?: string;
+    pendingDeviceTokenRetry?: boolean;
+    trustedDeviceTokenRetry?: boolean;
+    preferBootstrapToken?: boolean;
+    nonce: string | null;
+  }): Promise<GatewayBrowserDeviceAuthPlan>;
+  acceptHello(hello: Pick<HelloOk, "auth">, plan: GatewayBrowserDeviceAuthPlan): Promise<void>;
+  clearStoredToken(plan: GatewayBrowserDeviceAuthPlan): Promise<void>;
+}
+//#endregion
+export { GatewayBrowserDeviceTokenStore as a, resolveGatewayConnectScopes as c, buildDeviceAuthPayload as d, buildDeviceAuthPayloadV3 as f, GatewayBrowserDeviceTokenRecord as i, selectGatewayConnectAuth as l, GatewayBrowserDeviceAuthPlan as n, GatewayConnectAuthSelection as o, normalizeDeviceMetadataForAuth as p, GatewayBrowserDeviceIdentity as r, buildGatewayConnectAuth as s, GatewayBrowserDeviceAuthLifecycle as t, shouldRetryGatewayWithDeviceToken as u };

package/dist/browser.d.mts

@@ -0,0 +1,20 @@
+import { a as GatewayBrowserDeviceTokenStore, c as resolveGatewayConnectScopes, d as buildDeviceAuthPayload, f as buildDeviceAuthPayloadV3, i as GatewayBrowserDeviceTokenRecord, l as selectGatewayConnectAuth, n as GatewayBrowserDeviceAuthPlan, o as GatewayConnectAuthSelection, p as normalizeDeviceMetadataForAuth, r as GatewayBrowserDeviceIdentity, s as buildGatewayConnectAuth, t as GatewayBrowserDeviceAuthLifecycle, u as shouldRetryGatewayWithDeviceToken } from "./browser-device-auth-Bp297Rtf.mjs";
+import { a as GatewayProtocolRequestTiming, c as GatewayProtocolTiming, i as GatewayProtocolRequestOptions, n as GatewayProtocolCloseContext, o as GatewayProtocolSocket, r as GatewayProtocolRequestError, s as GatewayProtocolSocketHandlers, t as GatewayProtocolClient } from "./protocol-client-Cj1WAoMt.mjs";
+import { DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS } from "./timeouts.mjs";
+import { ConnectParams, ErrorShape, EventFrame, HelloOk } from "@openclaw/gateway-protocol";
+export * from "@openclaw/gateway-protocol/connect-error-details";
+export * from "@openclaw/gateway-protocol/client-info";
+export * from "@openclaw/gateway-protocol/gateway-error-details";
+export * from "@openclaw/gateway-protocol/startup-unavailable";
+export * from "@openclaw/gateway-protocol/version";
+
+//#region packages/gateway-client/src/reconnect-policy.d.ts
+declare function shouldPauseGatewayReconnect(params: {
+  details?: unknown;
+  deviceTokenRetryPending?: boolean;
+  tokenMismatchIsTerminal?: boolean;
+  protocolMismatchIsTerminal?: boolean;
+  clientVersionMismatchIsTerminal?: boolean;
+}): boolean;
+//#endregion
+export { type ConnectParams, DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS, type ErrorShape, type EventFrame, GatewayBrowserDeviceAuthLifecycle, GatewayBrowserDeviceAuthPlan, GatewayBrowserDeviceIdentity, GatewayBrowserDeviceTokenRecord, GatewayBrowserDeviceTokenStore, GatewayConnectAuthSelection, GatewayProtocolClient, GatewayProtocolCloseContext, GatewayProtocolRequestError, GatewayProtocolRequestOptions, GatewayProtocolRequestTiming, GatewayProtocolSocket, GatewayProtocolSocketHandlers, GatewayProtocolTiming, type HelloOk, buildDeviceAuthPayload, buildDeviceAuthPayloadV3, buildGatewayConnectAuth, normalizeDeviceMetadataForAuth, resolveGatewayConnectScopes, selectGatewayConnectAuth, shouldPauseGatewayReconnect, shouldRetryGatewayWithDeviceToken };

package/dist/browser.mjs

@@ -0,0 +1,8 @@
+import { a as buildGatewayConnectAuth, c as shouldRetryGatewayWithDeviceToken, d as normalizeDeviceMetadataForAuth, i as GatewayBrowserDeviceAuthLifecycle, l as buildDeviceAuthPayload, n as GatewayProtocolClient, o as resolveGatewayConnectScopes, r as GatewayProtocolRequestError, s as selectGatewayConnectAuth, t as shouldPauseGatewayReconnect, u as buildDeviceAuthPayloadV3 } from "./reconnect-policy-CkzLe1_K.mjs";
+import { DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS } from "./timeouts.mjs";
+export * from "@openclaw/gateway-protocol/connect-error-details";
+export * from "@openclaw/gateway-protocol/client-info";
+export * from "@openclaw/gateway-protocol/gateway-error-details";
+export * from "@openclaw/gateway-protocol/startup-unavailable";
+export * from "@openclaw/gateway-protocol/version";
+export { DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS, GatewayBrowserDeviceAuthLifecycle, GatewayProtocolClient, GatewayProtocolRequestError, buildDeviceAuthPayload, buildDeviceAuthPayloadV3, buildGatewayConnectAuth, normalizeDeviceMetadataForAuth, resolveGatewayConnectScopes, selectGatewayConnectAuth, shouldPauseGatewayReconnect, shouldRetryGatewayWithDeviceToken };

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { a as GatewayBrowserDeviceTokenStore, c as resolveGatewayConnectScopes, d as buildDeviceAuthPayload, f as buildDeviceAuthPayloadV3, i as GatewayBrowserDeviceTokenRecord, l as selectGatewayConnectAuth, n as GatewayBrowserDeviceAuthPlan, o as GatewayConnectAuthSelection, p as normalizeDeviceMetadataForAuth, r as GatewayBrowserDeviceIdentity, s as buildGatewayConnectAuth, t as GatewayBrowserDeviceAuthLifecycle, u as shouldRetryGatewayWithDeviceToken } from "./browser-device-auth-Bp297Rtf.mjs";
+import { DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS, DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS, MAX_CONNECT_CHALLENGE_TIMEOUT_MS, MAX_SAFE_TIMEOUT_DELAY_MS, MIN_CONNECT_CHALLENGE_TIMEOUT_MS, addSafeTimeoutDelayGraceMs, clampConnectChallengeTimeoutMs, getConnectChallengeTimeoutMsFromEnv, resolveConnectChallengeTimeoutMs, resolveFiniteTimeoutDelayMs, resolvePreauthHandshakeTimeoutMs, resolveSafeTimeoutDelayMs } from "./timeouts.mjs";
+import { _ as GatewayClientRequestOptions, a as startGatewayClientWithReadinessWait, c as waitForEventLoopReady, d as GatewayClient, f as GatewayClientCloseInfo, g as GatewayClientRequestError, h as GatewayClientOptions, i as startGatewayClientWhenEventLoopReady, l as DeviceAuthTokenRecord, m as GatewayClientHostDeps, n as GatewayClientStartReadinessOptions, o as EventLoopReadyOptions, p as GatewayClientConnectionMetadata, r as GatewayClientStartable, s as EventLoopReadyResult, t as EventLoopReadyWaiter, u as DeviceIdentity, v as GatewayReconnectPausedInfo, y as isGatewayConnectAssemblyError } from "./readiness-CPiKyi1s.mjs";
+export { DEFAULT_GATEWAY_REQUEST_TIMEOUT_MS, DEFAULT_PREAUTH_HANDSHAKE_TIMEOUT_MS, DeviceAuthTokenRecord, DeviceIdentity, EventLoopReadyOptions, EventLoopReadyResult, EventLoopReadyWaiter, GatewayBrowserDeviceAuthLifecycle, GatewayBrowserDeviceAuthPlan, GatewayBrowserDeviceIdentity, GatewayBrowserDeviceTokenRecord, GatewayBrowserDeviceTokenStore, GatewayClient, GatewayClientCloseInfo, GatewayClientConnectionMetadata, GatewayClientHostDeps, GatewayClientOptions, GatewayClientRequestError, GatewayClientRequestOptions, GatewayClientStartReadinessOptions, GatewayClientStartable, GatewayConnectAuthSelection, GatewayReconnectPausedInfo, MAX_CONNECT_CHALLENGE_TIMEOUT_MS, MAX_SAFE_TIMEOUT_DELAY_MS, MIN_CONNECT_CHALLENGE_TIMEOUT_MS, addSafeTimeoutDelayGraceMs, buildDeviceAuthPayload, buildDeviceAuthPayloadV3, buildGatewayConnectAuth, clampConnectChallengeTimeoutMs, getConnectChallengeTimeoutMsFromEnv, isGatewayConnectAssemblyError, normalizeDeviceMetadataForAuth, resolveConnectChallengeTimeoutMs, resolveFiniteTimeoutDelayMs, resolveGatewayConnectScopes, resolvePreauthHandshakeTimeoutMs, resolveSafeTimeoutDelayMs, selectGatewayConnectAuth, shouldRetryGatewayWithDeviceToken, startGatewayClientWhenEventLoopReady, startGatewayClientWithReadinessWait, waitForEventLoopReady };