From 977c922fc5e34ca404d7b0cc41778185407e886d Mon Sep 17 00:00:00 2001 From: ImLukeF <92253590+ImLukeF@users.noreply.github.com> Date: Sat, 21 Mar 2026 11:11:20 +1100 Subject: [PATCH] iOS: improve QR pairing flow --- .../Gateway/GatewayConnectionController.swift | 7 +- .../Onboarding/OnboardingWizardView.swift | 6 + .../OpenClawChatUI/ChatViewModel.swift | 51 ++- .../Sources/OpenClawKit/GatewayChannel.swift | 7 +- .../OpenClawKitTests/ChatViewModelTests.swift | 69 ++++ .../GatewayNodeSessionTests.swift | 67 +++- extensions/device-pair/api.ts | 5 +- extensions/device-pair/index.test.ts | 346 ++++++++++++++++ extensions/device-pair/index.ts | 376 ++++++++++++++---- src/infra/device-bootstrap.test.ts | 32 ++ src/infra/device-bootstrap.ts | 13 + src/plugin-sdk/device-bootstrap.ts | 6 +- 12 files changed, 901 insertions(+), 84 deletions(-) create mode 100644 extensions/device-pair/index.test.ts diff --git a/apps/ios/Sources/Gateway/GatewayConnectionController.swift b/apps/ios/Sources/Gateway/GatewayConnectionController.swift index dc94f3d0797..4d44c82258b 100644 --- a/apps/ios/Sources/Gateway/GatewayConnectionController.swift +++ b/apps/ios/Sources/Gateway/GatewayConnectionController.swift @@ -174,7 +174,12 @@ final class GatewayConnectionController { let stored = GatewayTLSStore.loadFingerprint(stableID: stableID) if resolvedUseTLS, stored == nil { guard let url = self.buildGatewayURL(host: host, port: resolvedPort, useTLS: true) else { return } - guard let fp = await self.probeTLSFingerprint(url: url) else { return } + guard let fp = await self.probeTLSFingerprint(url: url) else { + self.appModel?.gatewayStatusText = + "TLS handshake failed for \(host):\(resolvedPort). " + + "Remote gateways must use HTTPS/WSS." + return + } self.pendingTrustConnect = (url: url, stableID: stableID, isManual: true) self.pendingTrustPrompt = TrustPrompt( stableID: stableID, diff --git a/apps/ios/Sources/Onboarding/OnboardingWizardView.swift b/apps/ios/Sources/Onboarding/OnboardingWizardView.swift index 516e7b373eb..764ef54b59f 100644 --- a/apps/ios/Sources/Onboarding/OnboardingWizardView.swift +++ b/apps/ios/Sources/Onboarding/OnboardingWizardView.swift @@ -724,6 +724,12 @@ struct OnboardingWizardView: View { TextField("Discovery Domain (optional)", text: self.$discoveryDomain) .textInputAutocapitalization(.never) .autocorrectionDisabled() + if self.selectedMode == .remoteDomain { + TextField("Gateway Auth Token", text: self.$gatewayToken) + .textInputAutocapitalization(.never) + .autocorrectionDisabled() + SecureField("Gateway Password", text: self.$gatewayPassword) + } self.manualConnectButton } } diff --git a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift index 92413aefe64..f8033212b76 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel.swift @@ -353,6 +353,55 @@ public final class OpenClawChatViewModel { } } + private static func reconcileRunRefreshMessages( + previous: [OpenClawChatMessage], + incoming: [OpenClawChatMessage]) -> [OpenClawChatMessage] + { + guard !previous.isEmpty else { return incoming } + guard !incoming.isEmpty else { return previous } + + var reconciled = Self.reconcileMessageIDs(previous: previous, incoming: incoming) + let incomingIdentityKeys = Set(reconciled.compactMap(Self.messageIdentityKey(for:))) + + var lastMatchedPreviousIndex: Int? + for (index, message) in previous.enumerated() { + guard let key = Self.messageIdentityKey(for: message), + incomingIdentityKeys.contains(key) + else { + continue + } + lastMatchedPreviousIndex = index + } + + let trailingUserMessages = (lastMatchedPreviousIndex != nil + ? previous.suffix(from: previous.index(after: lastMatchedPreviousIndex!)) + : ArraySlice(previous)) + .filter { message in + guard message.role.lowercased() == "user" else { return false } + guard let key = Self.messageIdentityKey(for: message) else { return false } + return !incomingIdentityKeys.contains(key) + } + + guard !trailingUserMessages.isEmpty else { + return reconciled + } + + for message in trailingUserMessages { + guard let messageTimestamp = message.timestamp else { + reconciled.append(message) + continue + } + + let insertIndex = reconciled.firstIndex { existing in + guard let existingTimestamp = existing.timestamp else { return false } + return existingTimestamp > messageTimestamp + } ?? reconciled.endIndex + reconciled.insert(message, at: insertIndex) + } + + return Self.dedupeMessages(reconciled) + } + private static func dedupeMessages(_ messages: [OpenClawChatMessage]) -> [OpenClawChatMessage] { var result: [OpenClawChatMessage] = [] result.reserveCapacity(messages.count) @@ -919,7 +968,7 @@ public final class OpenClawChatViewModel { private func refreshHistoryAfterRun() async { do { let payload = try await self.transport.requestHistory(sessionKey: self.sessionKey) - self.messages = Self.reconcileMessageIDs( + self.messages = Self.reconcileRunRefreshMessages( previous: self.messages, incoming: Self.decodeMessages(payload.messages ?? [])) self.sessionId = payload.sessionId diff --git a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift index 2c3da84af68..ba7bee46c6d 100644 --- a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift +++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift @@ -513,8 +513,11 @@ public actor GatewayChannelActor { storedToken != nil && explicitToken != nil && self.isTrustedDeviceRetryEndpoint() let authToken = explicitToken ?? - (includeDeviceIdentity && explicitPassword == nil && - (explicitBootstrapToken == nil || storedToken != nil) ? storedToken : nil) + // A freshly scanned setup code should force the bootstrap pairing path instead of + // silently reusing an older stored device token. + (includeDeviceIdentity && explicitPassword == nil && explicitBootstrapToken == nil + ? storedToken + : nil) let authBootstrapToken = authToken == nil ? explicitBootstrapToken : nil let authDeviceToken = shouldUseDeviceRetryToken ? storedToken : nil let authSource: GatewayAuthSource diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift index 6d1fa88e569..b3fe369d0d7 100644 --- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift +++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/ChatViewModelTests.swift @@ -439,6 +439,75 @@ extension TestChatTransportState { #expect(await MainActor.run { vm.pendingToolCalls.isEmpty }) } + @Test func keepsOptimisticUserMessageWhenFinalRefreshReturnsOnlyAssistantHistory() async throws { + let sessionId = "sess-main" + let now = Date().timeIntervalSince1970 * 1000 + let history1 = historyPayload(sessionId: sessionId) + let history2 = historyPayload( + sessionId: sessionId, + messages: [ + chatTextMessage( + role: "assistant", + text: "final answer", + timestamp: now + 1), + ]) + + let (transport, vm) = await makeViewModel(historyResponses: [history1, history2]) + try await loadAndWaitBootstrap(vm: vm, sessionId: sessionId) + await sendUserMessage(vm, text: "hello from mac webchat") + try await waitUntil("pending run starts") { await MainActor.run { vm.pendingRunCount == 1 } } + + let runId = try #require(await transport.lastSentRunId()) + transport.emit( + .chat( + OpenClawChatEventPayload( + runId: runId, + sessionKey: "main", + state: "final", + message: nil, + errorMessage: nil))) + + try await waitUntil("assistant history refreshes without dropping user message") { + await MainActor.run { + let texts = vm.messages.map { message in + (message.role, message.content.compactMap(\.text).joined(separator: "\n")) + } + return texts.contains(where: { $0.0 == "assistant" && $0.1 == "final answer" }) && + texts.contains(where: { $0.0 == "user" && $0.1 == "hello from mac webchat" }) + } + } + } + + @Test func keepsOptimisticUserMessageWhenFinalRefreshHistoryIsTemporarilyEmpty() async throws { + let sessionId = "sess-main" + let history1 = historyPayload(sessionId: sessionId) + let history2 = historyPayload(sessionId: sessionId, messages: []) + + let (transport, vm) = await makeViewModel(historyResponses: [history1, history2]) + try await loadAndWaitBootstrap(vm: vm, sessionId: sessionId) + await sendUserMessage(vm, text: "hello from mac webchat") + try await waitUntil("pending run starts") { await MainActor.run { vm.pendingRunCount == 1 } } + + let runId = try #require(await transport.lastSentRunId()) + transport.emit( + .chat( + OpenClawChatEventPayload( + runId: runId, + sessionKey: "main", + state: "final", + message: nil, + errorMessage: nil))) + + try await waitUntil("empty refresh does not clear optimistic user message") { + await MainActor.run { + vm.messages.contains { message in + message.role == "user" && + message.content.compactMap(\.text).joined(separator: "\n") == "hello from mac webchat" + } + } + } + } + @Test func acceptsCanonicalSessionKeyEventsForOwnPendingRun() async throws { let history1 = historyPayload() let history2 = historyPayload( diff --git a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift index 183fc385d8c..b8c57ba6a2b 100644 --- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift +++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/GatewayNodeSessionTests.swift @@ -15,6 +15,7 @@ private final class FakeGatewayWebSocketTask: WebSocketTasking, @unchecked Senda private let lock = NSLock() private var _state: URLSessionTask.State = .suspended private var connectRequestId: String? + private var connectAuth: [String: Any]? private var receivePhase = 0 private var pendingReceiveHandler: (@Sendable (Result) -> Void)? @@ -50,10 +51,18 @@ private final class FakeGatewayWebSocketTask: WebSocketTasking, @unchecked Senda obj["method"] as? String == "connect", let id = obj["id"] as? String { - self.lock.withLock { self.connectRequestId = id } + let auth = ((obj["params"] as? [String: Any])?["auth"] as? [String: Any]) ?? [:] + self.lock.withLock { + self.connectRequestId = id + self.connectAuth = auth + } } } + func latestConnectAuth() -> [String: Any]? { + self.lock.withLock { self.connectAuth } + } + func sendPing(pongReceiveHandler: @escaping @Sendable (Error?) -> Void) { pongReceiveHandler(nil) } @@ -169,6 +178,62 @@ private actor SeqGapProbe { } struct GatewayNodeSessionTests { + @Test + func scannedSetupCodePrefersBootstrapAuthOverStoredDeviceToken() async throws { + let tempDir = FileManager.default.temporaryDirectory + .appendingPathComponent(UUID().uuidString, isDirectory: true) + try FileManager.default.createDirectory(at: tempDir, withIntermediateDirectories: true) + let previousStateDir = ProcessInfo.processInfo.environment["OPENCLAW_STATE_DIR"] + setenv("OPENCLAW_STATE_DIR", tempDir.path, 1) + defer { + if let previousStateDir { + setenv("OPENCLAW_STATE_DIR", previousStateDir, 1) + } else { + unsetenv("OPENCLAW_STATE_DIR") + } + try? FileManager.default.removeItem(at: tempDir) + } + + let identity = DeviceIdentityStore.loadOrCreate() + _ = DeviceAuthStore.storeToken( + deviceId: identity.deviceId, + role: "operator", + token: "stored-device-token") + + let session = FakeGatewayWebSocketSession() + let gateway = GatewayNodeSession() + let options = GatewayConnectOptions( + role: "operator", + scopes: ["operator.read"], + caps: [], + commands: [], + permissions: [:], + clientId: "openclaw-ios-test", + clientMode: "ui", + clientDisplayName: "iOS Test", + includeDeviceIdentity: true) + + try await gateway.connect( + url: URL(string: "ws://example.invalid")!, + token: nil, + bootstrapToken: "fresh-bootstrap-token", + password: nil, + connectOptions: options, + sessionBox: WebSocketSessionBox(session: session), + onConnected: {}, + onDisconnected: { _ in }, + onInvoke: { req in + BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: nil, error: nil) + }) + + let auth = try #require(session.latestTask()?.latestConnectAuth()) + #expect(auth["bootstrapToken"] as? String == "fresh-bootstrap-token") + #expect(auth["token"] == nil) + #expect(auth["deviceToken"] == nil) + + await gateway.disconnect() + } + @Test func normalizeCanvasHostUrlPreservesExplicitSecureCanvasPort() { let normalized = canonicalizeCanvasHostUrl( diff --git a/extensions/device-pair/api.ts b/extensions/device-pair/api.ts index eb4001b8a91..c3c349f120a 100644 --- a/extensions/device-pair/api.ts +++ b/extensions/device-pair/api.ts @@ -1,8 +1,11 @@ export { approveDevicePairing, + clearDeviceBootstrapTokens, issueDeviceBootstrapToken, listDevicePairing, + revokeDeviceBootstrapToken, } from "openclaw/plugin-sdk/device-bootstrap"; export { definePluginEntry, type OpenClawPluginApi } from "openclaw/plugin-sdk/plugin-entry"; export { resolveGatewayBindUrl, resolveTailnetHostWithRunner } from "openclaw/plugin-sdk/core"; -export { runPluginCommandWithTimeout } from "openclaw/plugin-sdk/sandbox"; +export { resolvePreferredOpenClawTmpDir, runPluginCommandWithTimeout } from "openclaw/plugin-sdk/sandbox"; +export { renderQrPngBase64 } from "../whatsapp/src/qr-image.js"; diff --git a/extensions/device-pair/index.test.ts b/extensions/device-pair/index.test.ts new file mode 100644 index 00000000000..e24043e056c --- /dev/null +++ b/extensions/device-pair/index.test.ts @@ -0,0 +1,346 @@ +import fs from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; +import type { OpenClawPluginApi } from "./api.js"; +import type { + OpenClawPluginCommandDefinition, + PluginCommandContext, +} from "../../src/plugins/types.js"; +import { createTestPluginApi } from "../../test/helpers/extensions/plugin-api.js"; + +const pluginApiMocks = vi.hoisted(() => ({ + clearDeviceBootstrapTokens: vi.fn(async () => ({ removed: 2 })), + issueDeviceBootstrapToken: vi.fn(async () => ({ + token: "boot-token", + expiresAtMs: Date.now() + 10 * 60_000, + })), + revokeDeviceBootstrapToken: vi.fn(async () => ({ removed: true })), + renderQrPngBase64: vi.fn(async () => "ZmFrZXBuZw=="), + resolvePreferredOpenClawTmpDir: vi.fn(() => path.join(os.tmpdir(), "openclaw-device-pair-tests")), +})); + +vi.mock("./api.js", async () => { + const actual = await vi.importActual("./api.js"); + return { + ...actual, + approveDevicePairing: vi.fn(), + clearDeviceBootstrapTokens: pluginApiMocks.clearDeviceBootstrapTokens, + issueDeviceBootstrapToken: pluginApiMocks.issueDeviceBootstrapToken, + listDevicePairing: vi.fn(async () => ({ pending: [] })), + renderQrPngBase64: pluginApiMocks.renderQrPngBase64, + revokeDeviceBootstrapToken: pluginApiMocks.revokeDeviceBootstrapToken, + resolvePreferredOpenClawTmpDir: pluginApiMocks.resolvePreferredOpenClawTmpDir, + resolveGatewayBindUrl: vi.fn(), + resolveTailnetHostWithRunner: vi.fn(), + runPluginCommandWithTimeout: vi.fn(), + }; +}); + +vi.mock("./notify.js", () => ({ + armPairNotifyOnce: vi.fn(async () => false), + formatPendingRequests: vi.fn(() => "No pending device pairing requests."), + handleNotifyCommand: vi.fn(async () => ({ text: "notify" })), + registerPairingNotifierService: vi.fn(), +})); + +import registerDevicePair from "./index.js"; + +function createApi(params?: { + runtime?: OpenClawPluginApi["runtime"]; + pluginConfig?: Record; + registerCommand?: (command: OpenClawPluginCommandDefinition) => void; +}): OpenClawPluginApi { + return createTestPluginApi({ + id: "device-pair", + name: "device-pair", + source: "test", + config: { + gateway: { + auth: { + mode: "token", + token: "gateway-token", + }, + }, + }, + pluginConfig: { + publicUrl: "ws://51.79.175.165:18789", + ...(params?.pluginConfig ?? {}), + }, + runtime: (params?.runtime ?? {}) as OpenClawPluginApi["runtime"], + registerCommand: params?.registerCommand, + }) as OpenClawPluginApi; +} + +function createCommandContext(params?: Partial): PluginCommandContext { + return { + channel: "webchat", + isAuthorizedSender: true, + commandBody: "/pair qr", + args: "qr", + config: {}, + ...params, + }; +} + +describe("device-pair /pair qr", () => { + beforeEach(async () => { + vi.clearAllMocks(); + pluginApiMocks.issueDeviceBootstrapToken.mockResolvedValue({ + token: "boot-token", + expiresAtMs: Date.now() + 10 * 60_000, + }); + await fs.mkdir(pluginApiMocks.resolvePreferredOpenClawTmpDir(), { recursive: true }); + }); + + afterEach(async () => { + await fs.rm(pluginApiMocks.resolvePreferredOpenClawTmpDir(), { recursive: true, force: true }); + }); + + it("returns an inline QR image for webchat surfaces", async () => { + let command: OpenClawPluginCommandDefinition | undefined; + registerDevicePair.register( + createApi({ + registerCommand: (nextCommand) => { + command = nextCommand; + }, + }), + ); + + const result = await command?.handler(createCommandContext({ channel: "webchat" })); + + expect(pluginApiMocks.renderQrPngBase64).toHaveBeenCalledTimes(1); + expect(result?.text).toContain("Scan this QR code with the OpenClaw iOS app:"); + expect(result?.text).toContain("![OpenClaw pairing QR](data:image/png;base64,ZmFrZXBuZw==)"); + expect(result?.text).toContain("- Security: single-use bootstrap token"); + expect(result?.text).toContain("**Important:** Run `/pair cleanup` after pairing finishes."); + expect(result?.text).toContain("If this QR code leaks, run `/pair cleanup` immediately."); + expect(result?.text).not.toContain("```"); + }); + + it.each([ + { + label: "Telegram", + runtimeKey: "telegram", + sendKey: "sendMessageTelegram", + ctx: { + channel: "telegram", + senderId: "123", + accountId: "default", + messageThreadId: 271, + }, + expectedTarget: "123", + assertOpts: (opts: Record) => { + expect(opts.accountId).toBe("default"); + expect(opts.messageThreadId).toBe(271); + }, + }, + { + label: "Discord", + runtimeKey: "discord", + sendKey: "sendMessageDiscord", + ctx: { + channel: "discord", + senderId: "123", + accountId: "default", + }, + expectedTarget: "user:123", + assertOpts: (opts: Record) => { + expect(opts.accountId).toBe("default"); + }, + }, + { + label: "Slack", + runtimeKey: "slack", + sendKey: "sendMessageSlack", + ctx: { + channel: "slack", + senderId: "user:U123", + accountId: "default", + messageThreadId: "1234567890.000001", + }, + expectedTarget: "user:U123", + assertOpts: (opts: Record) => { + expect(opts.accountId).toBe("default"); + expect(opts.threadTs).toBe("1234567890.000001"); + }, + }, + { + label: "Signal", + runtimeKey: "signal", + sendKey: "sendMessageSignal", + ctx: { + channel: "signal", + senderId: "signal:+15551234567", + accountId: "default", + }, + expectedTarget: "signal:+15551234567", + assertOpts: (opts: Record) => { + expect(opts.accountId).toBe("default"); + }, + }, + { + label: "iMessage", + runtimeKey: "imessage", + sendKey: "sendMessageIMessage", + ctx: { + channel: "imessage", + senderId: "+15551234567", + accountId: "default", + }, + expectedTarget: "+15551234567", + assertOpts: (opts: Record) => { + expect(opts.accountId).toBe("default"); + }, + }, + { + label: "WhatsApp", + runtimeKey: "whatsapp", + sendKey: "sendMessageWhatsApp", + ctx: { + channel: "whatsapp", + senderId: "+15551234567", + accountId: "default", + }, + expectedTarget: "+15551234567", + assertOpts: (opts: Record) => { + expect(opts.accountId).toBe("default"); + expect(opts.verbose).toBe(false); + }, + }, + ])("sends $label a real QR image attachment", async (testCase) => { + let sentPng = ""; + const sendMessage = vi.fn().mockImplementation(async (_target, _caption, opts) => { + if (opts?.mediaUrl) { + sentPng = await fs.readFile(opts.mediaUrl, "utf8"); + } + return { messageId: "1" }; + }); + let command: OpenClawPluginCommandDefinition | undefined; + registerDevicePair.register( + createApi({ + runtime: { + channel: { + [testCase.runtimeKey]: { + [testCase.sendKey]: sendMessage, + }, + }, + } as unknown as OpenClawPluginApi["runtime"], + registerCommand: (nextCommand) => { + command = nextCommand; + }, + }), + ); + + const result = await command?.handler(createCommandContext(testCase.ctx)); + + expect(sendMessage).toHaveBeenCalledTimes(1); + const [target, caption, opts] = sendMessage.mock.calls[0] as [ + string, + string, + { + mediaUrl?: string; + mediaLocalRoots?: string[]; + accountId?: string; + } & Record, + ]; + expect(target).toBe(testCase.expectedTarget); + expect(caption).toContain("Scan this QR code with the OpenClaw iOS app:"); + expect(caption).toContain("IMPORTANT: After pairing finishes, run /pair cleanup."); + expect(caption).toContain("If this QR code leaks, run /pair cleanup immediately."); + expect(opts.mediaUrl).toMatch(/pair-qr\.png$/); + expect(opts.mediaLocalRoots).toEqual([path.dirname(opts.mediaUrl!)]); + testCase.assertOpts(opts); + expect(sentPng).toBe("fakepng"); + await expect(fs.access(opts.mediaUrl!)).rejects.toBeTruthy(); + expect(result?.text).toContain("QR code sent above."); + expect(result?.text).toContain("IMPORTANT: Run /pair cleanup after pairing finishes."); + }); + + it("reissues the bootstrap token after QR delivery failure before falling back", async () => { + pluginApiMocks.issueDeviceBootstrapToken + .mockResolvedValueOnce({ + token: "first-token", + expiresAtMs: Date.now() + 10 * 60_000, + }) + .mockResolvedValueOnce({ + token: "second-token", + expiresAtMs: Date.now() + 10 * 60_000, + }); + + const sendMessage = vi.fn().mockRejectedValue(new Error("upload failed")); + let command: OpenClawPluginCommandDefinition | undefined; + registerDevicePair.register( + createApi({ + runtime: { + channel: { + discord: { + sendMessageDiscord: sendMessage, + }, + }, + } as unknown as OpenClawPluginApi["runtime"], + registerCommand: (nextCommand) => { + command = nextCommand; + }, + }), + ); + + const result = await command?.handler( + createCommandContext({ + channel: "discord", + senderId: "123", + }), + ); + + expect(pluginApiMocks.revokeDeviceBootstrapToken).toHaveBeenCalledWith({ + token: "first-token", + }); + expect(pluginApiMocks.issueDeviceBootstrapToken).toHaveBeenCalledTimes(2); + expect(result?.text).toContain("Pairing setup code generated."); + expect(result?.text).toContain("If this code leaks or you are done, run /pair cleanup"); + }); + + it("falls back to the setup code instead of ASCII when the channel cannot send media", async () => { + let command: OpenClawPluginCommandDefinition | undefined; + registerDevicePair.register( + createApi({ + registerCommand: (nextCommand) => { + command = nextCommand; + }, + }), + ); + + const result = await command?.handler( + createCommandContext({ + channel: "msteams", + senderId: "8:orgid:123", + }), + ); + + expect(result?.text).toContain("QR image delivery is not available on this channel"); + expect(result?.text).toContain("Setup code:"); + expect(result?.text).toContain("IMPORTANT: After pairing finishes, run /pair cleanup."); + expect(result?.text).not.toContain("```"); + }); + + it("supports invalidating unused setup codes", async () => { + let command: OpenClawPluginCommandDefinition | undefined; + registerDevicePair.register( + createApi({ + registerCommand: (nextCommand) => { + command = nextCommand; + }, + }), + ); + + const result = await command?.handler( + createCommandContext({ + args: "cleanup", + commandBody: "/pair cleanup", + }), + ); + + expect(pluginApiMocks.clearDeviceBootstrapTokens).toHaveBeenCalledTimes(1); + expect(result).toEqual({ text: "Invalidated 2 unused setup codes." }); + }); +}); diff --git a/extensions/device-pair/index.ts b/extensions/device-pair/index.ts index defd3b5c4c6..44c214f298a 100644 --- a/extensions/device-pair/index.ts +++ b/extensions/device-pair/index.ts @@ -1,13 +1,18 @@ +import { mkdtemp, rm, writeFile } from "node:fs/promises"; import os from "node:os"; -import qrcode from "qrcode-terminal"; +import path from "node:path"; import { approveDevicePairing, + clearDeviceBootstrapTokens, definePluginEntry, issueDeviceBootstrapToken, listDevicePairing, + renderQrPngBase64, resolveGatewayBindUrl, - runPluginCommandWithTimeout, + resolvePreferredOpenClawTmpDir, resolveTailnetHostWithRunner, + revokeDeviceBootstrapToken, + runPluginCommandWithTimeout, type OpenClawPluginApi, } from "./api.js"; import { @@ -17,12 +22,24 @@ import { registerPairingNotifierService, } from "./notify.js"; -function renderQrAscii(data: string): Promise { - return new Promise((resolve) => { - qrcode.generate(data, { small: true }, (output: string) => { - resolve(output); - }); - }); +async function renderQrDataUrl(data: string): Promise { + const pngBase64 = await renderQrPngBase64(data); + return `data:image/png;base64,${pngBase64}`; +} + +async function writeQrPngTempFile(data: string): Promise { + const pngBase64 = await renderQrPngBase64(data); + const tmpRoot = resolvePreferredOpenClawTmpDir(); + const qrDir = await mkdtemp(path.join(tmpRoot, "device-pair-qr-")); + const filePath = path.join(qrDir, "pair-qr.png"); + await writeFile(filePath, Buffer.from(pngBase64, "base64")); + return filePath; +} + +function formatDurationMinutes(expiresAtMs: number): string { + const msRemaining = Math.max(0, expiresAtMs - Date.now()); + const minutes = Math.max(1, Math.ceil(msRemaining / 60_000)); + return `${minutes} minute${minutes === 1 ? "" : "s"}`; } const DEFAULT_GATEWAY_PORT = 18789; @@ -34,6 +51,7 @@ type DevicePairPluginConfig = { type SetupPayload = { url: string; bootstrapToken: string; + expiresAtMs: number; }; type ResolveUrlResult = { @@ -47,6 +65,15 @@ type ResolveAuthLabelResult = { error?: string; }; +type QrCommandContext = { + channel: string; + senderId?: string; + from?: string; + to?: string; + accountId?: string; + messageThreadId?: string | number; +}; + function normalizeUrl(raw: string, schemeFallback: "ws" | "wss"): string | null { const candidate = raw.trim(); if (!candidate) { @@ -307,25 +334,215 @@ function formatSetupReply(payload: SetupPayload, authLabel: string): string { "1) Open the iOS app → Settings → Gateway", "2) Paste the setup code below and tap Connect", "3) Back here, run /pair approve", + "4) If this code leaks or you are done, run /pair cleanup", "", "Setup code:", setupCode, "", `Gateway: ${payload.url}`, `Auth: ${authLabel}`, + "Security: single-use bootstrap token", + `Expires: ${formatDurationMinutes(payload.expiresAtMs)}`, + "", + "IMPORTANT: After pairing finishes, run /pair cleanup.", + "If this setup code leaks, run /pair cleanup immediately.", ].join("\n"); } -function formatSetupInstructions(): string { +function formatSetupInstructions(expiresAtMs: number): string { return [ "Pairing setup code generated.", "", "1) Open the iOS app → Settings → Gateway", "2) Paste the setup code from my next message and tap Connect", "3) Back here, run /pair approve", + "4) If this code leaks or you are done, run /pair cleanup", + "", + "Security: single-use bootstrap token", + `Expires: ${formatDurationMinutes(expiresAtMs)}`, + "", + "IMPORTANT: After pairing finishes, run /pair cleanup.", + "If this setup code leaks, run /pair cleanup immediately.", ].join("\n"); } +function formatQrInfoLines(params: { + payload: SetupPayload; + authLabel: string; + autoNotifyArmed: boolean; + expiresAtMs: number; +}) { + return [ + `Gateway: ${params.payload.url}`, + `Auth: ${params.authLabel}`, + "Security: single-use bootstrap token", + `Expires: ${formatDurationMinutes(params.expiresAtMs)}`, + "", + "IMPORTANT: After pairing finishes, run /pair cleanup.", + "If this QR code leaks, run /pair cleanup immediately.", + "", + params.autoNotifyArmed + ? "After scanning, wait here for the pairing request ping." + : "After scanning, run `/pair approve` to complete pairing.", + ...(params.autoNotifyArmed + ? [ + "I’ll auto-ping here when the pairing request arrives, then auto-disable.", + "If the ping does not arrive, run `/pair approve latest` manually.", + ] + : []), + "", + "If your camera still won’t lock on, run `/pair` for a pasteable setup code.", + ]; +} + +function formatQrInfoMarkdown(params: { + payload: SetupPayload; + authLabel: string; + autoNotifyArmed: boolean; + expiresAtMs: number; +}): string { + const guidance = params.autoNotifyArmed + ? [ + "After scanning, wait here for the pairing request ping.", + "I’ll auto-ping here when the pairing request arrives, then auto-disable.", + "If the ping does not arrive, run `/pair approve latest` manually.", + ] + : ["After scanning, run `/pair approve` to complete pairing."]; + return [ + `- Gateway: ${params.payload.url}`, + `- Auth: ${params.authLabel}`, + "- Security: single-use bootstrap token", + `- Expires: ${formatDurationMinutes(params.expiresAtMs)}`, + "", + "**Important:** Run `/pair cleanup` after pairing finishes.", + "If this QR code leaks, run `/pair cleanup` immediately.", + "", + ...guidance, + "", + "If your camera still won’t lock on, run `/pair` for a pasteable setup code.", + ].join("\n"); +} + +function canSendQrPngToChannel(channel: string): boolean { + return ["telegram", "discord", "slack", "signal", "imessage", "whatsapp"].includes(channel); +} + +function resolveQrReplyTarget(ctx: QrCommandContext): string { + if (ctx.channel === "discord") { + const senderId = ctx.senderId?.trim() ?? ""; + if (senderId) { + return senderId.startsWith("user:") || senderId.startsWith("channel:") + ? senderId + : `user:${senderId}`; + } + } + return ctx.senderId?.trim() || ctx.from?.trim() || ctx.to?.trim() || ""; +} + +async function issueSetupPayload(url: string): Promise { + const issuedBootstrap = await issueDeviceBootstrapToken(); + return { + url, + bootstrapToken: issuedBootstrap.token, + expiresAtMs: issuedBootstrap.expiresAtMs, + }; +} + +async function sendQrPngToSupportedChannel(params: { + api: OpenClawPluginApi; + ctx: QrCommandContext; + target: string; + caption: string; + qrFilePath: string; +}): Promise { + const mediaLocalRoots = [path.dirname(params.qrFilePath)]; + const accountId = params.ctx.accountId?.trim() || undefined; + + switch (params.ctx.channel) { + case "telegram": { + const send = params.api.runtime?.channel?.telegram?.sendMessageTelegram; + if (!send) { + return false; + } + await send(params.target, params.caption, { + mediaUrl: params.qrFilePath, + mediaLocalRoots, + ...(typeof params.ctx.messageThreadId === "number" + ? { messageThreadId: params.ctx.messageThreadId } + : {}), + ...(accountId ? { accountId } : {}), + }); + return true; + } + case "discord": { + const send = params.api.runtime?.channel?.discord?.sendMessageDiscord; + if (!send) { + return false; + } + await send(params.target, params.caption, { + mediaUrl: params.qrFilePath, + mediaLocalRoots, + ...(accountId ? { accountId } : {}), + }); + return true; + } + case "slack": { + const send = params.api.runtime?.channel?.slack?.sendMessageSlack; + if (!send) { + return false; + } + await send(params.target, params.caption, { + mediaUrl: params.qrFilePath, + mediaLocalRoots, + ...(params.ctx.messageThreadId != null + ? { threadTs: String(params.ctx.messageThreadId) } + : {}), + ...(accountId ? { accountId } : {}), + }); + return true; + } + case "signal": { + const send = params.api.runtime?.channel?.signal?.sendMessageSignal; + if (!send) { + return false; + } + await send(params.target, params.caption, { + mediaUrl: params.qrFilePath, + mediaLocalRoots, + ...(accountId ? { accountId } : {}), + }); + return true; + } + case "imessage": { + const send = params.api.runtime?.channel?.imessage?.sendMessageIMessage; + if (!send) { + return false; + } + await send(params.target, params.caption, { + mediaUrl: params.qrFilePath, + mediaLocalRoots, + ...(accountId ? { accountId } : {}), + }); + return true; + } + case "whatsapp": { + const send = params.api.runtime?.channel?.whatsapp?.sendMessageWhatsApp; + if (!send) { + return false; + } + await send(params.target, params.caption, { + verbose: false, + mediaUrl: params.qrFilePath, + mediaLocalRoots, + ...(accountId ? { accountId } : {}), + }); + return true; + } + default: + return false; + } +} + export default definePluginEntry({ id: "device-pair", name: "Device Pair", @@ -400,6 +617,16 @@ export default definePluginEntry({ return { text: `✅ Paired ${label}${platformLabel}.` }; } + if (action === "cleanup" || action === "clear" || action === "revoke") { + const cleared = await clearDeviceBootstrapTokens(); + return { + text: + cleared.removed > 0 + ? `Invalidated ${cleared.removed} unused setup code${cleared.removed === 1 ? "" : "s"}.` + : "No unused setup codes were active.", + }; + } + const authLabelResult = resolveAuthLabel(api.config); if (authLabelResult.error) { return { text: `Error: ${authLabelResult.error}` }; @@ -409,19 +636,11 @@ export default definePluginEntry({ if (!urlResult.url) { return { text: `Error: ${urlResult.error ?? "Gateway URL unavailable."}` }; } - - const payload: SetupPayload = { - url: urlResult.url, - bootstrapToken: (await issueDeviceBootstrapToken()).token, - }; + const authLabel = authLabelResult.label ?? "auth"; if (action === "qr") { - const setupCode = encodeSetupCode(payload); - const qrAscii = await renderQrAscii(setupCode); - const authLabel = authLabelResult.label ?? "auth"; - const channel = ctx.channel; - const target = ctx.senderId?.trim() || ctx.from?.trim() || ctx.to?.trim() || ""; + const target = resolveQrReplyTarget(ctx); let autoNotifyArmed = false; if (channel === "telegram" && target) { @@ -436,82 +655,83 @@ export default definePluginEntry({ } } - if (channel === "telegram" && target) { + let payload = await issueSetupPayload(urlResult.url); + let setupCode = encodeSetupCode(payload); + + const infoLines = formatQrInfoLines({ + payload, + authLabel, + autoNotifyArmed, + expiresAtMs: payload.expiresAtMs, + }); + + if (target && canSendQrPngToChannel(channel)) { + let qrFilePath: string | undefined; try { - const send = api.runtime?.channel?.telegram?.sendMessageTelegram; - if (send) { - await send( - target, - ["Scan this QR code with the OpenClaw iOS app:", "", "```", qrAscii, "```"].join( - "\n", - ), - { - ...(ctx.messageThreadId != null - ? { messageThreadId: ctx.messageThreadId } - : {}), - ...(ctx.accountId ? { accountId: ctx.accountId } : {}), - }, - ); + qrFilePath = await writeQrPngTempFile(setupCode); + const sent = await sendQrPngToSupportedChannel({ + api, + ctx, + target, + caption: ["Scan this QR code with the OpenClaw iOS app:", "", ...infoLines].join( + "\n", + ), + qrFilePath, + }); + if (sent) { return { - text: [ - `Gateway: ${payload.url}`, - `Auth: ${authLabel}`, - "", - autoNotifyArmed - ? "After scanning, wait here for the pairing request ping." - : "After scanning, come back here and run `/pair approve` to complete pairing.", - ...(autoNotifyArmed - ? [ - "I’ll auto-ping here when the pairing request arrives, then auto-disable.", - "If the ping does not arrive, run `/pair approve latest` manually.", - ] - : []), - ].join("\n"), + text: + `QR code sent above.\n` + + `Expires: ${formatDurationMinutes(payload.expiresAtMs)}\n` + + "IMPORTANT: Run /pair cleanup after pairing finishes.", }; } } catch (err) { api.logger.warn?.( - `device-pair: telegram QR send failed, falling back (${String( + `device-pair: QR image send failed channel=${channel}, falling back (${String( (err as Error)?.message ?? err, )})`, ); + await revokeDeviceBootstrapToken({ token: payload.bootstrapToken }).catch(() => {}); + payload = await issueSetupPayload(urlResult.url); + setupCode = encodeSetupCode(payload); + } finally { + if (qrFilePath) { + await rm(path.dirname(qrFilePath), { recursive: true, force: true }).catch(() => { + }); + } } } - // Render based on channel capability api.logger.info?.(`device-pair: QR fallback channel=${channel} target=${target}`); - const infoLines = [ - `Gateway: ${payload.url}`, - `Auth: ${authLabel}`, - "", - autoNotifyArmed - ? "After scanning, wait here for the pairing request ping." - : "After scanning, run `/pair approve` to complete pairing.", - ...(autoNotifyArmed - ? [ - "I’ll auto-ping here when the pairing request arrives, then auto-disable.", - "If the ping does not arrive, run `/pair approve latest` manually.", - ] - : []), - ]; + if (channel === "webchat") { + const qrDataUrl = await renderQrDataUrl(setupCode); + return { + text: [ + "Scan this QR code with the OpenClaw iOS app:", + "", + formatQrInfoMarkdown({ + payload, + authLabel, + autoNotifyArmed, + expiresAtMs: payload.expiresAtMs, + }), + "", + `![OpenClaw pairing QR](${qrDataUrl})`, + ].join("\n"), + }; + } - // WebUI + CLI/TUI: ASCII QR return { - text: [ - "Scan this QR code with the OpenClaw iOS app:", - "", - "```", - qrAscii, - "```", - "", - ...infoLines, - ].join("\n"), + text: + "QR image delivery is not available on this channel, so I generated a pasteable setup code instead.\n\n" + + formatSetupReply(payload, authLabel), }; } const channel = ctx.channel; const target = ctx.senderId?.trim() || ctx.from?.trim() || ctx.to?.trim() || ""; - const authLabel = authLabelResult.label ?? "auth"; + const payload = await issueSetupPayload(urlResult.url); if (channel === "telegram" && target) { try { @@ -530,8 +750,10 @@ export default definePluginEntry({ )})`, ); } - await send(target, formatSetupInstructions(), { - ...(ctx.messageThreadId != null ? { messageThreadId: ctx.messageThreadId } : {}), + await send(target, formatSetupInstructions(payload.expiresAtMs), { + ...(typeof ctx.messageThreadId === "number" + ? { messageThreadId: ctx.messageThreadId } + : {}), ...(ctx.accountId ? { accountId: ctx.accountId } : {}), }); api.logger.info?.( diff --git a/src/infra/device-bootstrap.test.ts b/src/infra/device-bootstrap.test.ts index 45fef0a8d84..3fe2b64afa8 100644 --- a/src/infra/device-bootstrap.test.ts +++ b/src/infra/device-bootstrap.test.ts @@ -3,6 +3,7 @@ import path from "node:path"; import { afterEach, describe, expect, it, vi } from "vitest"; import { createTrackedTempDirs } from "../test-utils/tracked-temp-dirs.js"; import { + clearDeviceBootstrapTokens, DEVICE_BOOTSTRAP_TOKEN_TTL_MS, issueDeviceBootstrapToken, verifyDeviceBootstrapToken, @@ -72,6 +73,37 @@ describe("device bootstrap tokens", () => { await expect(fs.readFile(resolveBootstrapPath(baseDir), "utf8")).resolves.toBe("{}"); }); + it("clears outstanding bootstrap tokens on demand", async () => { + const baseDir = await createTempDir(); + const first = await issueDeviceBootstrapToken({ baseDir }); + const second = await issueDeviceBootstrapToken({ baseDir }); + + await expect(clearDeviceBootstrapTokens({ baseDir })).resolves.toEqual({ removed: 2 }); + await expect(fs.readFile(resolveBootstrapPath(baseDir), "utf8")).resolves.toBe("{}"); + + await expect( + verifyDeviceBootstrapToken({ + token: first.token, + deviceId: "device-123", + publicKey: "public-key-123", + role: "operator.admin", + scopes: ["operator.admin"], + baseDir, + }), + ).resolves.toEqual({ ok: false, reason: "bootstrap_token_invalid" }); + + await expect( + verifyDeviceBootstrapToken({ + token: second.token, + deviceId: "device-123", + publicKey: "public-key-123", + role: "operator.admin", + scopes: ["operator.admin"], + baseDir, + }), + ).resolves.toEqual({ ok: false, reason: "bootstrap_token_invalid" }); + }); + it("keeps the token when required verification fields are blank", async () => { const baseDir = await createTempDir(); const issued = await issueDeviceBootstrapToken({ baseDir }); diff --git a/src/infra/device-bootstrap.ts b/src/infra/device-bootstrap.ts index d4d2d6ed526..9ed1346ebc8 100644 --- a/src/infra/device-bootstrap.ts +++ b/src/infra/device-bootstrap.ts @@ -79,6 +79,19 @@ export async function issueDeviceBootstrapToken( }); } +export async function clearDeviceBootstrapTokens( + params: { + baseDir?: string; + } = {}, +): Promise<{ removed: number }> { + return await withLock(async () => { + const state = await loadState(params.baseDir); + const removed = Object.keys(state).length; + await persistState({}, params.baseDir); + return { removed }; + }); +} + export async function verifyDeviceBootstrapToken(params: { token: string; deviceId: string; diff --git a/src/plugin-sdk/device-bootstrap.ts b/src/plugin-sdk/device-bootstrap.ts index c3ecf15ab51..6b2c933fc27 100644 --- a/src/plugin-sdk/device-bootstrap.ts +++ b/src/plugin-sdk/device-bootstrap.ts @@ -1,4 +1,8 @@ // Shared bootstrap/pairing helpers for plugins that provision remote devices. export { approveDevicePairing, listDevicePairing } from "../infra/device-pairing.js"; -export { issueDeviceBootstrapToken } from "../infra/device-bootstrap.js"; +export { + clearDeviceBootstrapTokens, + issueDeviceBootstrapToken, + revokeDeviceBootstrapToken, +} from "../infra/device-bootstrap.js";