From 0ca9ed9d8e5d580fe717d190c8da58a7dfb049c1 Mon Sep 17 00:00:00 2001 From: Roger Chappel Date: Mon, 20 Jul 2026 17:15:50 +1000 Subject: [PATCH 1/4] feat: implement OpenClaw device auth lifecycle --- src/lib/gateway-client-auth-lifecycle.test.ts | 243 +++++++++++++++++ src/lib/gateway-client.ts | 251 +++++++++++++++--- 2 files changed, 464 insertions(+), 30 deletions(-) create mode 100644 src/lib/gateway-client-auth-lifecycle.test.ts diff --git a/src/lib/gateway-client-auth-lifecycle.test.ts b/src/lib/gateway-client-auth-lifecycle.test.ts new file mode 100644 index 0000000..e7ee246 --- /dev/null +++ b/src/lib/gateway-client-auth-lifecycle.test.ts @@ -0,0 +1,243 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const { socketState } = vi.hoisted(() => ({ + socketState: { + sockets: [] as Array<{ reply: (payload: Record) => void }>, + frames: [] as Array>, + respond: null as null | (( + socket: { reply: (payload: Record) => void }, + frame: Record, + socketIndex: number, + ) => void), + }, +})); + +vi.mock("ws", () => { + type Listener = (...args: unknown[]) => void; + + return { + default: class MockSocket { + private listeners = new Map(); + + constructor(_url: string) { + socketState.sockets.push(this); + queueMicrotask(() => { + this.emit("open"); + this.emit("message", Buffer.from(JSON.stringify({ + type: "event", + event: "connect.challenge", + payload: { nonce: `nonce-${socketState.sockets.indexOf(this)}` }, + }))); + }); + } + + on(event: string, listener: Listener) { + const listeners = this.listeners.get(event) ?? []; + listeners.push(listener); + this.listeners.set(event, listeners); + return this; + } + + send(raw: string) { + const frame = JSON.parse(raw) as Record; + socketState.frames.push(frame); + socketState.respond?.(this, frame, socketState.sockets.indexOf(this)); + } + + close() { + this.emit("close", 1000, Buffer.from("closed")); + } + + reply(payload: Record) { + this.emit("message", Buffer.from(JSON.stringify(payload))); + } + + private emit(event: string, ...args: unknown[]) { + for (const listener of this.listeners.get(event) ?? []) listener(...args); + } + }, + }; +}); + +import { GatewayClient, resolveDeviceIdentity } from "./gateway-client"; + +function responseId(frame: Record) { + return String(frame.id); +} + +function connectParams(index: number) { + const frame = socketState.frames[index] as { params?: Record }; + return frame.params ?? {}; +} + +describe("GatewayClient device authentication lifecycle", () => { + beforeEach(() => { + socketState.sockets.length = 0; + socketState.frames.length = 0; + socketState.respond = null; + }); + + afterEach(() => { + vi.restoreAllMocks(); + }); + + it("persists the issued device token and performs one trusted mismatch retry", async () => { + const onDeviceAuthUpdated = vi.fn(); + socketState.respond = (socket, frame, socketIndex) => { + if (socketIndex === 0) { + socket.reply({ + type: "res", + id: responseId(frame), + ok: false, + error: { + code: "INVALID_REQUEST", + message: "unauthorized: gateway token mismatch", + details: { + code: "AUTH_TOKEN_MISMATCH", + canRetryWithDeviceToken: true, + recommendedNextStep: "retry_with_device_token", + }, + }, + }); + return; + } + + socket.reply({ + type: "res", + id: responseId(frame), + ok: true, + payload: { + type: "hello-ok", + server: { version: "2026.7.1" }, + auth: { + deviceToken: "rotated-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }, + }, + }); + }; + + const client = new GatewayClient( + "ws://127.0.0.1:18789", + "stale-shared-token", + resolveDeviceIdentity(), + 15000, + { + deviceAuth: { + token: "stored-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }, + onDeviceAuthUpdated, + }, + ); + + await expect(client.connect()).resolves.toEqual({ + version: "2026.7.1", + deviceAuth: { + token: "rotated-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }, + }); + + expect(socketState.sockets).toHaveLength(2); + expect(connectParams(0)).toMatchObject({ + minProtocol: 4, + maxProtocol: 4, + scopes: ["operator.admin"], + auth: { token: "stale-shared-token" }, + }); + expect(connectParams(1)).toMatchObject({ + scopes: ["operator.read", "operator.write"], + auth: { + token: "stale-shared-token", + deviceToken: "stored-device-token", + }, + }); + expect(onDeviceAuthUpdated).toHaveBeenCalledWith({ + token: "rotated-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }); + }); + + it("does not promote a cached device token on an unpinned remote endpoint", async () => { + socketState.respond = (socket, frame) => { + socket.reply({ + type: "res", + id: responseId(frame), + ok: false, + error: { + code: "INVALID_REQUEST", + message: "unauthorized: gateway token mismatch", + details: { + code: "AUTH_TOKEN_MISMATCH", + canRetryWithDeviceToken: true, + recommendedNextStep: "retry_with_device_token", + }, + }, + }); + }; + + const client = new GatewayClient( + "wss://gateway.example.com", + "stale-shared-token", + resolveDeviceIdentity(), + 15000, + { + deviceAuth: { + token: "stored-device-token", + role: "operator", + scopes: ["operator.read"], + }, + }, + ); + + await expect(client.connect()).rejects.toThrow("gateway token mismatch"); + expect(socketState.sockets).toHaveLength(1); + }); + + it("clears a rejected device token instead of retrying it indefinitely", async () => { + const onDeviceAuthInvalid = vi.fn(); + socketState.respond = (socket, frame) => { + socket.reply({ + type: "res", + id: responseId(frame), + ok: false, + error: { + code: "INVALID_REQUEST", + message: "unauthorized: device token mismatch", + details: { code: "AUTH_DEVICE_TOKEN_MISMATCH" }, + }, + }); + }; + + const client = new GatewayClient( + "ws://localhost:18789", + null, + resolveDeviceIdentity(), + 15000, + { + deviceAuth: { + token: "revoked-device-token", + role: "operator", + scopes: ["operator.read"], + }, + onDeviceAuthInvalid, + }, + ); + + await expect(client.connect()).rejects.toThrow("device token mismatch"); + expect(socketState.sockets).toHaveLength(1); + expect(connectParams(0)).toMatchObject({ + scopes: ["operator.read"], + auth: { + token: "revoked-device-token", + deviceToken: "revoked-device-token", + }, + }); + expect(onDeviceAuthInvalid).toHaveBeenCalledTimes(1); + }); +}); diff --git a/src/lib/gateway-client.ts b/src/lib/gateway-client.ts index 659b7ba..80e010e 100644 --- a/src/lib/gateway-client.ts +++ b/src/lib/gateway-client.ts @@ -18,9 +18,9 @@ import { resolveRuntimeAuthTokenForUse } from "./runtime-token-crypto"; // ─── Constants ────────────────────────────────────────────────────── -const MIN_PROTOCOL_VERSION = 3; +const MIN_PROTOCOL_VERSION = 4; const MAX_PROTOCOL_VERSION = 4; -const DEFAULT_SCOPES = ["operator.read", "operator.write", "operator.admin"]; +const DEFAULT_SCOPES = ["operator.admin"]; const CLIENT_ID = "gateway-client"; const CLIENT_VERSION = "crewcmd/1.0.0"; const CLIENT_MODE = "backend"; @@ -318,6 +318,7 @@ export interface ProbeResult { capabilities?: RuntimeCapabilitySnapshot; defaultAgentId?: string; devicePrivateKeyPem?: string; + deviceAuth?: GatewayDeviceAuth; } export interface DeviceIdentity { @@ -327,6 +328,23 @@ export interface DeviceIdentity { source: "configured" | "generated"; } +export interface GatewayDeviceAuth { + token: string; + role: string; + scopes: string[]; +} + +export interface GatewayConnectResult { + version: string; + deviceAuth?: GatewayDeviceAuth; +} + +export interface GatewayClientAuthLifecycle { + deviceAuth?: GatewayDeviceAuth | null; + onDeviceAuthUpdated?: (deviceAuth: GatewayDeviceAuth) => void | Promise; + onDeviceAuthInvalid?: () => void | Promise; +} + // ─── Crypto Helpers ───────────────────────────────────────────────── function base64UrlEncode(buf: Buffer): string { @@ -447,14 +465,18 @@ function buildDeviceAuthPayloadV3(params: { */ export function resolveDeviceIdentity(existingPrivateKeyPem?: string): DeviceIdentity { if (existingPrivateKeyPem) { - const privateKey = crypto.createPrivateKey(existingPrivateKeyPem); + const resolvedPrivateKeyPem = resolveRuntimeAuthTokenForUse(existingPrivateKeyPem); + if (!resolvedPrivateKeyPem) { + throw new Error("Stored gateway device identity is empty"); + } + const privateKey = crypto.createPrivateKey(resolvedPrivateKeyPem); const publicKey = crypto.createPublicKey(privateKey); const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString(); const raw = derivePublicKeyRaw(publicKeyPem); return { deviceId: crypto.createHash("sha256").update(raw).digest("hex"), publicKeyRawBase64Url: base64UrlEncode(raw), - privateKeyPem: existingPrivateKeyPem, + privateKeyPem: resolvedPrivateKeyPem, source: "configured", }; } @@ -487,6 +509,43 @@ type PendingRequest = { timer: ReturnType | null; }; +type ConnectAuthPlan = { + auth?: { + token?: string; + deviceToken?: string; + }; + scopes: string[]; + signatureToken: string | null; + usesDeviceToken: boolean; +}; + +function gatewayErrorDetailCode(err: unknown): string | null { + if (!err || typeof err !== "object") return null; + const details = (err as { gatewayDetails?: Record }).gatewayDetails; + return typeof details?.code === "string" ? details.code : null; +} + +function canRetryWithDeviceToken(err: unknown): boolean { + if (!err || typeof err !== "object") return false; + const details = (err as { gatewayDetails?: Record }).gatewayDetails; + return gatewayErrorDetailCode(err) === "AUTH_TOKEN_MISMATCH" + && (details?.canRetryWithDeviceToken === true + || details?.recommendedNextStep === "retry_with_device_token"); +} + +function isLoopbackGatewayUrl(rawUrl: string): boolean { + try { + const hostname = new URL(rawUrl).hostname.toLowerCase(); + if (hostname === "localhost" || hostname === "::1" || hostname === "[::1]") return true; + const octets = hostname.split("."); + return octets.length === 4 + && octets[0] === "127" + && octets.every((octet) => /^\d+$/.test(octet) && Number(octet) <= 255); + } catch { + return false; + } +} + // ─── Gateway Client ───────────────────────────────────────────────── export class GatewayClient { @@ -499,6 +558,7 @@ export class GatewayClient { private challengeReject?: (err: Error) => void; private eventListeners = new Map void>>(); private authToken: string | null; + private deviceAuth: GatewayDeviceAuth | null; get isConnected(): boolean { return this.connected; @@ -508,19 +568,117 @@ export class GatewayClient { private gatewayUrl: string, authToken: string | null, private device: DeviceIdentity, - private timeoutMs = 15000 + private timeoutMs = 15000, + private authLifecycle: GatewayClientAuthLifecycle = {}, ) { this.authToken = resolveRuntimeAuthTokenForUse(authToken); + this.deviceAuth = authLifecycle.deviceAuth ?? null; } /** * Connect to the gateway with device auth challenge-response. */ - async connect(): Promise<{ version: string }> { + async connect(): Promise { + const initialPlan = this.buildInitialAuthPlan(); + + try { + return await this.connectOnce(initialPlan); + } catch (err) { + if (initialPlan.usesDeviceToken && gatewayErrorDetailCode(err) === "AUTH_DEVICE_TOKEN_MISMATCH") { + await this.invalidateStoredDeviceAuth(); + } + + if ( + !this.authToken + || !this.deviceAuth + || !isLoopbackGatewayUrl(this.gatewayUrl) + || !canRetryWithDeviceToken(err) + ) { + throw err; + } + + publishAgentModeDiagnostic({ + scope: "gateway-client", + event: "connect.retry-device-token", + detail: { url: this.gatewayUrl, deviceId: this.device.deviceId }, + }); + this.resetTransportForRetry(); + + try { + return await this.connectOnce({ + auth: { + token: this.authToken, + deviceToken: this.deviceAuth.token, + }, + scopes: [...this.deviceAuth.scopes], + signatureToken: this.authToken, + usesDeviceToken: true, + }); + } catch (retryErr) { + if (gatewayErrorDetailCode(retryErr) === "AUTH_DEVICE_TOKEN_MISMATCH") { + await this.invalidateStoredDeviceAuth(); + } + throw retryErr; + } + } + } + + private buildInitialAuthPlan(): ConnectAuthPlan { + if (this.authToken) { + return { + auth: { token: this.authToken }, + scopes: [...DEFAULT_SCOPES], + signatureToken: this.authToken, + usesDeviceToken: false, + }; + } + + if (this.deviceAuth) { + return { + auth: { + token: this.deviceAuth.token, + deviceToken: this.deviceAuth.token, + }, + scopes: [...this.deviceAuth.scopes], + signatureToken: this.deviceAuth.token, + usesDeviceToken: true, + }; + } + + return { + scopes: [...DEFAULT_SCOPES], + signatureToken: null, + usesDeviceToken: false, + }; + } + + private async invalidateStoredDeviceAuth(): Promise { + this.deviceAuth = null; + await this.authLifecycle.onDeviceAuthInvalid?.(); + } + + private resetTransportForRetry(): void { + const ws = this.ws; + this.ws = null; + this.connected = false; + this.challengeResolve = undefined; + this.challengeReject = undefined; + for (const [, pending] of this.pending) { + if (pending.timer) clearTimeout(pending.timer); + } + this.pending.clear(); + try { ws?.close(); } catch { /* ignore */ } + } + + private async connectOnce(authPlan: ConnectAuthPlan): Promise { publishAgentModeDiagnostic({ scope: "gateway-client", event: "connect.start", - detail: { url: this.gatewayUrl, timeoutMs: this.timeoutMs }, + detail: { + url: this.gatewayUrl, + timeoutMs: this.timeoutMs, + usesDeviceToken: authPlan.usesDeviceToken, + }, }); const challengePromise = new Promise((resolve, reject) => { this.challengeResolve = resolve; @@ -536,23 +694,22 @@ export class GatewayClient { event: "connect.timeout", detail: { url: this.gatewayUrl, timeoutMs: this.timeoutMs }, }); - this.close(); + this.resetTransportForRetry(); reject(new Error("Connection timeout")); }, this.timeoutMs); try { - const headers: Record = {}; - if (this.authToken) { - headers.authorization = `Bearer ${this.authToken}`; - } - this.ws = new WebSocket(this.gatewayUrl, { headers }); + this.ws = new WebSocket(this.gatewayUrl); } catch (err) { clearTimeout(timer); reject(new Error(`Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`)); return; } - this.ws.on("error", (err) => { + const ws = this.ws; + + ws.on("error", (err) => { + if (this.ws !== ws) return; clearTimeout(timer); publishAgentModeDiagnostic({ scope: "gateway-client", @@ -563,7 +720,8 @@ export class GatewayClient { reject(new Error(`WebSocket error: ${err.message}`)); }); - this.ws.on("close", (code, reason) => { + ws.on("close", (code, reason) => { + if (this.ws !== ws) return; this.connected = false; const err = new Error(`Connection closed (${code}): ${reason?.toString() || ""}`); publishAgentModeDiagnostic({ @@ -584,21 +742,23 @@ export class GatewayClient { this.pending.clear(); }); - this.ws.on("message", (data) => { + ws.on("message", (data) => { + if (this.ws !== ws) return; this.handleMessage(data.toString()); }); // Wait for challenge, then send signed connect - this.ws.on("open", () => { + ws.on("open", () => { + if (this.ws !== ws) return; challengePromise .then((nonce) => { const signedAtMs = Date.now(); const payloadStr = buildDeviceAuthPayloadV3({ deviceId: this.device.deviceId, role: DEFAULT_ROLE, - scopes: DEFAULT_SCOPES, + scopes: authPlan.scopes, signedAtMs, - token: this.authToken, + token: authPlan.signatureToken, nonce, }); const signature = signPayload(this.device.privateKeyPem, payloadStr); @@ -611,13 +771,42 @@ export class GatewayClient { this.connected = true; const helloOk = value as Record; const server = helloOk?.server as { version?: string } | undefined; + const auth = helloOk?.auth as { + deviceToken?: unknown; + role?: unknown; + scopes?: unknown; + } | undefined; + const nextDeviceAuth = typeof auth?.deviceToken === "string" && auth.deviceToken.trim() + ? { + token: auth.deviceToken.trim(), + role: typeof auth.role === "string" && auth.role.trim() ? auth.role.trim() : DEFAULT_ROLE, + scopes: Array.isArray(auth.scopes) + ? auth.scopes.filter((scope): scope is string => typeof scope === "string" && !!scope.trim()) + : [...authPlan.scopes], + } + : undefined; this.serverVersion = server?.version || "unknown"; - publishAgentModeDiagnostic({ - scope: "gateway-client", - event: "connect.complete", - detail: { version: this.serverVersion }, + Promise.resolve( + nextDeviceAuth + ? this.authLifecycle.onDeviceAuthUpdated?.(nextDeviceAuth) + : undefined, + ).then(() => { + if (nextDeviceAuth) this.deviceAuth = nextDeviceAuth; + publishAgentModeDiagnostic({ + scope: "gateway-client", + event: "connect.complete", + detail: { + version: this.serverVersion, + receivedDeviceToken: !!nextDeviceAuth, + }, + }); + resolve({ version: this.serverVersion!, deviceAuth: nextDeviceAuth }); + }).catch((persistErr) => { + this.resetTransportForRetry(); + reject(new Error( + `Failed to persist gateway device credential: ${persistErr instanceof Error ? persistErr.message : String(persistErr)}`, + )); }); - resolve({ version: this.serverVersion }); }, reject: (err) => { clearTimeout(timer); @@ -640,9 +829,9 @@ export class GatewayClient { mode: CLIENT_MODE, }, role: DEFAULT_ROLE, - scopes: DEFAULT_SCOPES, + scopes: authPlan.scopes, caps: DEFAULT_CAPS, - auth: this.authToken ? { token: this.authToken } : undefined, + auth: authPlan.auth, device: { id: this.device.deviceId, publicKey: this.device.publicKeyRawBase64Url, @@ -653,7 +842,7 @@ export class GatewayClient { }, }; - this.ws!.send(JSON.stringify(connectFrame)); + ws.send(JSON.stringify(connectFrame)); }) .catch((err) => { clearTimeout(timer); @@ -1164,8 +1353,8 @@ export async function probeGateway( // First attempt const client = new GatewayClient(gatewayUrl, authToken, device); try { - const { version } = await client.connect(); - return await discoverFromClient(client, version, device.privateKeyPem); + const { version, deviceAuth } = await client.connect(); + return await discoverFromClient(client, version, device.privateKeyPem, deviceAuth); } catch (err) { const message = err instanceof Error ? err.message : String(err); const isPairingRequired = message.toLowerCase().includes("pairing required"); @@ -1206,7 +1395,8 @@ export async function probeGateway( async function discoverFromClient( client: GatewayClient, version: string, - devicePrivateKeyPem: string + devicePrivateKeyPem: string, + deviceAuth?: GatewayDeviceAuth, ): Promise { try { const [agentsResult, modelsResult, configSnapshot] = await Promise.all([ @@ -1274,6 +1464,7 @@ async function discoverFromClient( : undefined, defaultAgentId: agentsResult.defaultId, devicePrivateKeyPem, + deviceAuth, }; } catch (err) { return { From 63828f33fa903fc23d48783e0fec4a2806cd84ff Mon Sep 17 00:00:00 2001 From: Roger Chappel Date: Mon, 20 Jul 2026 17:18:20 +1000 Subject: [PATCH 2/4] feat: encrypt OpenClaw device credentials --- src/lib/runtime-device-auth.test.ts | 69 +++++++++++++++ src/lib/runtime-device-auth.ts | 133 ++++++++++++++++++++++++++++ 2 files changed, 202 insertions(+) create mode 100644 src/lib/runtime-device-auth.test.ts create mode 100644 src/lib/runtime-device-auth.ts diff --git a/src/lib/runtime-device-auth.test.ts b/src/lib/runtime-device-auth.test.ts new file mode 100644 index 0000000..11b2f9f --- /dev/null +++ b/src/lib/runtime-device-auth.test.ts @@ -0,0 +1,69 @@ +import { describe, expect, it } from "vitest"; +import { + clearRuntimeDeviceAuth, + readRuntimeDeviceAuth, + removeRuntimeAuthSecretsFromMetadata, + sealRuntimeDevicePrivateKey, + storeRuntimeDeviceAuth, +} from "./runtime-device-auth"; +import { isEncryptedRuntimeAuthToken, resolveRuntimeAuthTokenForUse } from "./runtime-token-crypto"; + +const cryptoEnv = { AUTH_SECRET: "runtime-device-auth-test-secret" }; + +describe("runtime device authentication metadata", () => { + it("round-trips an encrypted device credential for the expected identity", () => { + const metadata = storeRuntimeDeviceAuth( + { workspaceId: "workspace-1" }, + "device-1", + { + token: "device-token", + role: "operator", + scopes: ["operator.write", "operator.read", "operator.read"], + }, + cryptoEnv, + ); + + expect(metadata.workspaceId).toBe("workspace-1"); + expect(metadata.openclawDeviceAuth).toMatchObject({ + version: 1, + deviceId: "device-1", + role: "operator", + scopes: ["operator.write", "operator.read"], + }); + expect(JSON.stringify(metadata)).not.toContain("device-token"); + expect(readRuntimeDeviceAuth(metadata, "device-1", cryptoEnv)).toEqual({ + token: "device-token", + role: "operator", + scopes: ["operator.write", "operator.read"], + }); + expect(readRuntimeDeviceAuth(metadata, "different-device", cryptoEnv)).toBeNull(); + }); + + it("clears only the device credential", () => { + const metadata = storeRuntimeDeviceAuth( + { workspaceId: "workspace-1" }, + "device-1", + { token: "device-token", role: "operator", scopes: ["operator.read"] }, + cryptoEnv, + ); + + expect(clearRuntimeDeviceAuth(metadata)).toEqual({ workspaceId: "workspace-1" }); + }); + + it("seals device private keys once", () => { + const sealed = sealRuntimeDevicePrivateKey("private-key-pem", cryptoEnv); + + expect(isEncryptedRuntimeAuthToken(sealed)).toBe(true); + expect(resolveRuntimeAuthTokenForUse(sealed, cryptoEnv)).toBe("private-key-pem"); + expect(sealRuntimeDevicePrivateKey(sealed, cryptoEnv)).toBe(sealed); + }); + + it("removes device secrets from browser-facing metadata", () => { + expect(removeRuntimeAuthSecretsFromMetadata({ + workspaceId: "workspace-1", + devicePrivateKeyPem: "private-key", + openclawDeviceAuth: { tokenCiphertext: "ciphertext" }, + })).toEqual({ workspaceId: "workspace-1" }); + expect(removeRuntimeAuthSecretsFromMetadata(null)).toBeNull(); + }); +}); diff --git a/src/lib/runtime-device-auth.ts b/src/lib/runtime-device-auth.ts new file mode 100644 index 0000000..9deba75 --- /dev/null +++ b/src/lib/runtime-device-auth.ts @@ -0,0 +1,133 @@ +import type { GatewayDeviceAuth } from "./gateway-client"; +import { + isEncryptedRuntimeAuthToken, + resolveRuntimeAuthTokenForUse, + sealRuntimeAuthToken, + type RuntimeTokenCryptoEnv, +} from "./runtime-token-crypto"; + +const DEVICE_AUTH_METADATA_KEY = "openclawDeviceAuth"; +const DEVICE_AUTH_VERSION = 1; + +interface StoredRuntimeDeviceAuth { + version: 1; + deviceId: string; + role: string; + scopes: string[]; + tokenCiphertext: string; + updatedAt: string; +} + +function asMetadata(metadata: unknown): Record { + return metadata && typeof metadata === "object" && !Array.isArray(metadata) + ? { ...(metadata as Record) } + : {}; +} + +function normalizeScopes(scopes: unknown): string[] | null { + if (!Array.isArray(scopes)) return null; + const normalized = [...new Set( + scopes + .filter((scope): scope is string => typeof scope === "string") + .map((scope) => scope.trim()) + .filter(Boolean), + )]; + return normalized.length > 0 ? normalized : null; +} + +function parseStoredDeviceAuth(value: unknown): StoredRuntimeDeviceAuth | null { + if (!value || typeof value !== "object" || Array.isArray(value)) return null; + const stored = value as Record; + const scopes = normalizeScopes(stored.scopes); + if ( + stored.version !== DEVICE_AUTH_VERSION + || typeof stored.deviceId !== "string" + || !stored.deviceId.trim() + || typeof stored.role !== "string" + || !stored.role.trim() + || !scopes + || typeof stored.tokenCiphertext !== "string" + || !stored.tokenCiphertext.trim() + || typeof stored.updatedAt !== "string" + ) { + return null; + } + + return { + version: DEVICE_AUTH_VERSION, + deviceId: stored.deviceId.trim(), + role: stored.role.trim(), + scopes, + tokenCiphertext: stored.tokenCiphertext, + updatedAt: stored.updatedAt, + }; +} + +export function readRuntimeDeviceAuth( + metadata: unknown, + expectedDeviceId: string, + env: RuntimeTokenCryptoEnv = process.env, +): GatewayDeviceAuth | null { + const stored = parseStoredDeviceAuth(asMetadata(metadata)[DEVICE_AUTH_METADATA_KEY]); + if (!stored || stored.deviceId !== expectedDeviceId) return null; + const token = resolveRuntimeAuthTokenForUse(stored.tokenCiphertext, env); + if (!token) return null; + return { + token, + role: stored.role, + scopes: stored.scopes, + }; +} + +export function storeRuntimeDeviceAuth( + metadata: unknown, + deviceId: string, + deviceAuth: GatewayDeviceAuth, + env: RuntimeTokenCryptoEnv = process.env, +): Record { + const normalizedDeviceId = deviceId.trim(); + const role = deviceAuth.role.trim(); + const scopes = normalizeScopes(deviceAuth.scopes); + const token = deviceAuth.token.trim(); + if (!normalizedDeviceId || !role || !scopes || !token) { + throw new Error("Gateway device credential is incomplete"); + } + const tokenCiphertext = sealRuntimeAuthToken(token, env); + if (!tokenCiphertext) throw new Error("Gateway device credential is empty"); + + return { + ...asMetadata(metadata), + [DEVICE_AUTH_METADATA_KEY]: { + version: DEVICE_AUTH_VERSION, + deviceId: normalizedDeviceId, + role, + scopes, + tokenCiphertext, + updatedAt: new Date().toISOString(), + } satisfies StoredRuntimeDeviceAuth, + }; +} + +export function clearRuntimeDeviceAuth(metadata: unknown): Record { + const next = asMetadata(metadata); + delete next[DEVICE_AUTH_METADATA_KEY]; + return next; +} + +export function sealRuntimeDevicePrivateKey( + storedOrPlaintextKey: string, + env: RuntimeTokenCryptoEnv = process.env, +): string { + if (isEncryptedRuntimeAuthToken(storedOrPlaintextKey)) return storedOrPlaintextKey; + const sealed = sealRuntimeAuthToken(storedOrPlaintextKey, env); + if (!sealed) throw new Error("Gateway device private key is empty"); + return sealed; +} + +export function removeRuntimeAuthSecretsFromMetadata(metadata: unknown): Record | null { + if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) return null; + const safe = asMetadata(metadata); + delete safe.devicePrivateKeyPem; + delete safe[DEVICE_AUTH_METADATA_KEY]; + return safe; +} From abf598b70c1a6ae536d318d84b3be6a592642811 Mon Sep 17 00:00:00 2001 From: Roger Chappel Date: Mon, 20 Jul 2026 17:21:05 +1000 Subject: [PATCH 3/4] feat: persist runtime device authentication --- src/lib/gateway-chat-pool.test.ts | 113 +++++++++++++++++++++++++++++- src/lib/gateway-chat-pool.ts | 75 +++++++++++++++++++- 2 files changed, 182 insertions(+), 6 deletions(-) diff --git a/src/lib/gateway-chat-pool.test.ts b/src/lib/gateway-chat-pool.test.ts index 273ffb1..e6aac3b 100644 --- a/src/lib/gateway-chat-pool.test.ts +++ b/src/lib/gateway-chat-pool.test.ts @@ -4,7 +4,18 @@ import type { GatewayClient } from "./gateway-client"; const { mockState } = vi.hoisted(() => ({ mockState: { runtimes: new Map(), - clients: [] as Array<{ url: string; isConnected: boolean; close: ReturnType; connect: ReturnType }>, + clients: [] as Array<{ + url: string; + isConnected: boolean; + close: ReturnType; + connect: ReturnType; + authLifecycle?: { + deviceAuth?: unknown; + onDeviceAuthUpdated?: (deviceAuth: unknown) => void | Promise; + onDeviceAuthInvalid?: () => void | Promise; + }; + }>, + issuedDeviceAuth: null as null | { token: string; role: string; scopes: string[] }, }, })); @@ -27,6 +38,17 @@ vi.mock("@/db", () => ({ }), }, }, + update: () => ({ + set: (values: Record) => ({ + where: ({ right }: { right?: unknown }) => { + if (typeof right === "string") { + const runtime = mockState.runtimes.get(right); + if (runtime && typeof runtime === "object") Object.assign(runtime, values); + } + return Promise.resolve([]); + }, + }), + }), }, withRetry: (fn: () => Promise) => fn(), })); @@ -35,6 +57,8 @@ vi.mock("@/db/schema", () => ({ companyRuntimes: { id: Symbol.for("companyRuntimes.id"), isPrimary: Symbol.for("companyRuntimes.isPrimary"), + metadata: Symbol.for("companyRuntimes.metadata"), + updatedAt: Symbol.for("companyRuntimes.updatedAt"), }, })); @@ -50,11 +74,26 @@ vi.mock("./gateway-client", () => { this.isConnected = false; }); connect = vi.fn(async () => { + if (mockState.issuedDeviceAuth) { + await this.authLifecycle?.onDeviceAuthUpdated?.(mockState.issuedDeviceAuth); + } this.isConnected = true; }); - - constructor(url: string) { + authLifecycle?: { + deviceAuth?: unknown; + onDeviceAuthUpdated?: (deviceAuth: unknown) => void | Promise; + onDeviceAuthInvalid?: () => void | Promise; + }; + + constructor( + url: string, + _authToken: string | null, + _device: unknown, + _timeout: number, + authLifecycle?: MockGatewayClient["authLifecycle"], + ) { this.url = url; + this.authLifecycle = authLifecycle; mockState.clients.push(this); } } @@ -94,10 +133,13 @@ describe("gateway-chat-pool active client holds", () => { vi.useRealTimers(); mockState.runtimes.clear(); mockState.clients.length = 0; + mockState.issuedDeviceAuth = null; + vi.stubEnv("AUTH_SECRET", "gateway-pool-device-auth-test-secret"); }); afterEach(() => { resetGatewayPoolForTests(); + vi.unstubAllEnvs(); vi.useRealTimers(); }); @@ -144,10 +186,13 @@ describe("getGatewayClientForRuntime", () => { vi.useRealTimers(); mockState.runtimes.clear(); mockState.clients.length = 0; + mockState.issuedDeviceAuth = null; + vi.stubEnv("AUTH_SECRET", "gateway-pool-device-auth-test-secret"); }); afterEach(() => { resetGatewayPoolForTests(); + vi.unstubAllEnvs(); vi.useRealTimers(); }); @@ -206,4 +251,66 @@ describe("getGatewayClientForRuntime", () => { poolSize: 1, }); }); + + it("persists issued device credentials and restores them for a new client", async () => { + addRuntime("runtime-a", { + authToken: "shared-token", + metadata: { + label: "local", + devicePrivateKeyPem: "plaintext-private-key", + }, + }); + mockState.issuedDeviceAuth = { + token: "issued-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }; + + await getGatewayClientForRuntime("runtime-a"); + + const runtime = mockState.runtimes.get("runtime-a") as { metadata: Record }; + expect(runtime.metadata).toMatchObject({ + label: "local", + openclawDeviceAuth: { + version: 1, + deviceId: "device-1", + role: "operator", + scopes: ["operator.read", "operator.write"], + }, + }); + expect(runtime.metadata.devicePrivateKeyPem).not.toBe("plaintext-private-key"); + expect(JSON.stringify(runtime.metadata)).not.toContain("issued-device-token"); + + mockState.issuedDeviceAuth = null; + resetGatewayPoolForTests(); + await getGatewayClientForRuntime("runtime-a"); + + expect(mockState.clients.at(-1)?.authLifecycle?.deviceAuth).toEqual({ + token: "issued-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }); + }); + + it("removes a rejected device credential while preserving other runtime metadata", async () => { + addRuntime("runtime-a", { + authToken: "shared-token", + metadata: { + label: "local", + devicePrivateKeyPem: "plaintext-private-key", + }, + }); + mockState.issuedDeviceAuth = { + token: "issued-device-token", + role: "operator", + scopes: ["operator.read"], + }; + await getGatewayClientForRuntime("runtime-a"); + + await mockState.clients[0].authLifecycle?.onDeviceAuthInvalid?.(); + + const runtime = mockState.runtimes.get("runtime-a") as { metadata: Record }; + expect(runtime.metadata.label).toBe("local"); + expect(runtime.metadata).not.toHaveProperty("openclawDeviceAuth"); + }); }); diff --git a/src/lib/gateway-chat-pool.ts b/src/lib/gateway-chat-pool.ts index cf469c4..e2082d5 100644 --- a/src/lib/gateway-chat-pool.ts +++ b/src/lib/gateway-chat-pool.ts @@ -8,11 +8,17 @@ import { readFile } from "node:fs/promises"; import { homedir, networkInterfaces } from "node:os"; import { join } from "node:path"; -import { GatewayClient, resolveDeviceIdentity } from "./gateway-client"; +import { GatewayClient, resolveDeviceIdentity, type GatewayDeviceAuth } from "./gateway-client"; import { db, withRetry } from "@/db"; import { companyRuntimes } from "@/db/schema"; import { eq } from "drizzle-orm"; import { publishAgentModeDiagnostic } from "./agent-mode-diagnostics"; +import { + clearRuntimeDeviceAuth, + readRuntimeDeviceAuth, + sealRuntimeDevicePrivateKey, + storeRuntimeDeviceAuth, +} from "./runtime-device-auth"; interface PoolEntry { client: GatewayClient; @@ -424,13 +430,50 @@ async function repairRuntimeUrl(params: { ); } +async function updateRuntimeAuthMetadata(params: { + runtimeId: string; + update: (metadata: unknown) => Record; +}): Promise> { + return withRetry(async () => { + const runtime = await db!.query.companyRuntimes.findFirst({ + where: eq(companyRuntimes.id, params.runtimeId), + }); + if (!runtime) throw new Error(`Runtime not found: ${params.runtimeId}`); + const metadata = params.update(runtime.metadata); + await db!.update(companyRuntimes) + .set({ metadata, updatedAt: new Date() }) + .where(eq(companyRuntimes.id, params.runtimeId)); + return metadata; + }); +} + async function connectWithFallback(params: { runtimeId: string; storedGatewayUrl: string; authToken: string | null; deviceKeyPem?: string; + runtimeMetadata: unknown; }): Promise<{ client: GatewayClient; connectedUrl: string }> { - const device = resolveDeviceIdentity(params.deviceKeyPem); + let runtimeMetadata = params.runtimeMetadata; + let storedDeviceKey = params.deviceKeyPem; + if (storedDeviceKey) { + const sealedDeviceKey = sealRuntimeDevicePrivateKey(storedDeviceKey); + if (sealedDeviceKey !== storedDeviceKey) { + runtimeMetadata = await updateRuntimeAuthMetadata({ + runtimeId: params.runtimeId, + update: (metadata) => ({ + ...(metadata && typeof metadata === "object" && !Array.isArray(metadata) + ? metadata as Record + : {}), + devicePrivateKeyPem: sealedDeviceKey, + }), + }); + storedDeviceKey = sealedDeviceKey; + } + } + + const device = resolveDeviceIdentity(storedDeviceKey); + let deviceAuth = readRuntimeDeviceAuth(runtimeMetadata, device.deviceId); console.log("[gateway-pool] Device source:", device.source, "hasStoredKey:", !!params.deviceKeyPem); const candidates = await buildGatewayCandidates(params.storedGatewayUrl); @@ -441,7 +484,28 @@ async function connectWithFallback(params: { url, params.authToken, device, - 30000 // 30s timeout for chat + 30000, // 30s timeout for chat + { + deviceAuth, + onDeviceAuthUpdated: async (nextDeviceAuth: GatewayDeviceAuth) => { + runtimeMetadata = await updateRuntimeAuthMetadata({ + runtimeId: params.runtimeId, + update: (metadata) => storeRuntimeDeviceAuth( + metadata, + device.deviceId, + nextDeviceAuth, + ), + }); + deviceAuth = nextDeviceAuth; + }, + onDeviceAuthInvalid: async () => { + runtimeMetadata = await updateRuntimeAuthMetadata({ + runtimeId: params.runtimeId, + update: clearRuntimeDeviceAuth, + }); + deviceAuth = null; + }, + }, ); try { @@ -467,6 +531,10 @@ async function connectWithFallback(params: { url, err instanceof Error ? err.message : err, ); + const classification = classifyGatewayFailure(err); + if (classification === "authentication" || classification === "pairing_required") { + throw err; + } } } @@ -541,6 +609,7 @@ async function getClientForRuntime(runtime: GatewayRuntimeConnection | null | un storedGatewayUrl: runtime.gatewayUrl, authToken: runtime.authToken || null, deviceKeyPem, + runtimeMetadata: meta, }); console.log("[gateway-pool] Connected successfully via:", connectedUrl); From 2c94f06b8c8990f13462f1bfcce8aa51c44d3b6e Mon Sep 17 00:00:00 2001 From: Roger Chappel Date: Mon, 20 Jul 2026 17:23:30 +1000 Subject: [PATCH 4/4] fix: seal OpenClaw probe credentials --- src/app/api/runtimes/probe/route.test.ts | 71 ++++++++++++++++++++++++ src/app/api/runtimes/probe/route.ts | 41 +++++++++++++- 2 files changed, 109 insertions(+), 3 deletions(-) diff --git a/src/app/api/runtimes/probe/route.test.ts b/src/app/api/runtimes/probe/route.test.ts index 99b901d..66f72af 100644 --- a/src/app/api/runtimes/probe/route.test.ts +++ b/src/app/api/runtimes/probe/route.test.ts @@ -11,6 +11,12 @@ vi.mock("@/lib/require-auth", () => ({ vi.mock("@/lib/gateway-client", () => ({ probeGateway: (...args: unknown[]) => mockProbeGateway(...args), + resolveDeviceIdentity: vi.fn(() => ({ + deviceId: "device-1", + publicKeyRawBase64Url: "public-key", + privateKeyPem: "private-key", + source: "configured", + })), })); vi.mock("@/lib/openclaw-config-parser", () => ({ @@ -30,6 +36,7 @@ describe("POST /api/runtimes/probe", () => { beforeEach(() => { vi.clearAllMocks(); vi.unstubAllGlobals(); + vi.stubEnv("AUTH_SECRET", "runtime-probe-device-auth-test-secret"); }); it("probes Hermes runtimes through the HTTP API", async () => { @@ -103,4 +110,68 @@ describe("POST /api/runtimes/probe", () => { expect(response.status).toBe(200); expect(mockProbeGateway).toHaveBeenCalledWith("ws://localhost:18789", "openclaw-token", undefined); }); + + it("seals issued device credentials before returning probe data to the browser", async () => { + mockProbeGateway.mockResolvedValue({ + ok: true, + version: "2026.7.1", + agents: [], + models: [], + devicePrivateKeyPem: "plaintext-private-key", + deviceAuth: { + token: "plaintext-device-token", + role: "operator", + scopes: ["operator.read", "operator.write"], + }, + }); + + const response = await POST(makeRequest({ + mode: "gateway", + url: "localhost:18789", + token: "openclaw-token", + })); + const payload = await response.json(); + + expect(response.status).toBe(200); + expect(payload).not.toHaveProperty("deviceAuth"); + expect(payload.devicePrivateKeyPem).toMatch(/^crewcmd:runtime-token:v1:/); + expect(payload.runtimeAuthMetadata).toMatchObject({ + devicePrivateKeyPem: payload.devicePrivateKeyPem, + openclawDeviceAuth: { + version: 1, + deviceId: "device-1", + role: "operator", + scopes: ["operator.read", "operator.write"], + }, + }); + expect(JSON.stringify(payload)).not.toContain("plaintext-private-key"); + expect(JSON.stringify(payload)).not.toContain("plaintext-device-token"); + }); + + it("seals a pending pairing identity so retries use the same device safely", async () => { + mockProbeGateway.mockResolvedValue({ + ok: false, + error: "pairing_required", + pairingInstructions: "Approve this device", + agents: [], + models: [], + devicePrivateKeyPem: "plaintext-private-key", + }); + + const response = await POST(makeRequest({ + mode: "gateway", + url: "localhost:18789", + token: "openclaw-token", + })); + const payload = await response.json(); + + expect(response.status).toBe(200); + expect(payload).toMatchObject({ + ok: false, + pairingRequired: true, + pairingInstructions: "Approve this device", + }); + expect(payload.devicePrivateKeyPem).toMatch(/^crewcmd:runtime-token:v1:/); + expect(JSON.stringify(payload)).not.toContain("plaintext-private-key"); + }); }); diff --git a/src/app/api/runtimes/probe/route.ts b/src/app/api/runtimes/probe/route.ts index 75a45d9..e139815 100644 --- a/src/app/api/runtimes/probe/route.ts +++ b/src/app/api/runtimes/probe/route.ts @@ -1,8 +1,42 @@ import { NextRequest, NextResponse } from "next/server"; -import { probeGateway } from "@/lib/gateway-client"; +import { probeGateway, resolveDeviceIdentity, type ProbeResult } from "@/lib/gateway-client"; import { parseOpenClawConfig } from "@/lib/openclaw-config-parser"; import { requireAuth } from "@/lib/require-auth"; import { getRuntimeProvider } from "@/lib/runtimes/providers"; +import { + sealRuntimeDevicePrivateKey, + storeRuntimeDeviceAuth, +} from "@/lib/runtime-device-auth"; + +type SealedGatewayProbeResult = Omit & { + runtimeAuthMetadata?: Record; +}; + +function sealGatewayProbeResult(result: ProbeResult): SealedGatewayProbeResult { + const { deviceAuth, devicePrivateKeyPem, ...safeResult } = result; + if (!devicePrivateKeyPem) return safeResult; + + const device = resolveDeviceIdentity(devicePrivateKeyPem); + const sealedDevicePrivateKey = sealRuntimeDevicePrivateKey(devicePrivateKeyPem); + let runtimeAuthMetadata: Record = { + devicePrivateKeyPem: sealedDevicePrivateKey, + }; + if (deviceAuth) { + runtimeAuthMetadata = storeRuntimeDeviceAuth( + runtimeAuthMetadata, + device.deviceId, + deviceAuth, + ); + } + + return { + ...safeResult, + // This opaque ciphertext is returned only so pairing retries can retain + // the same identity. The browser never receives the private key itself. + devicePrivateKeyPem: sealedDevicePrivateKey, + runtimeAuthMetadata, + }; +} /** * POST /api/runtimes/probe @@ -95,11 +129,12 @@ export async function POST(request: NextRequest) { if (!result.ok) { // Special case: pairing required — return 200 with status so UI can show approval instructions if (result.error === "pairing_required") { + const sealedResult = sealGatewayProbeResult(result); return NextResponse.json({ ok: false, pairingRequired: true, pairingInstructions: result.pairingInstructions, - devicePrivateKeyPem: result.devicePrivateKeyPem, + devicePrivateKeyPem: sealedResult.devicePrivateKeyPem, }); } @@ -109,7 +144,7 @@ export async function POST(request: NextRequest) { ); } - return NextResponse.json(result); + return NextResponse.json(sealGatewayProbeResult(result)); } // ── Local config file mode (same-machine fallback) ──