refactor(gateway): unify v3 auth payload builders and vectors

2026-03-12 07:20:45 +00:00 · 2026-02-26 15:08:40 +01:00
parent 8315c58675
commit 081b1aa1ed
10 changed files with 313 additions and 168 deletions
--- a/apps/android/app/src/main/java/ai/openclaw/android/gateway/DeviceAuthPayload.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/android/gateway/DeviceAuthPayload.kt
@@ -0,0 +1,52 @@
+package ai.openclaw.android.gateway
+
+internal object DeviceAuthPayload {
+  fun buildV3(
+    deviceId: String,
+    clientId: String,
+    clientMode: String,
+    role: String,
+    scopes: List<String>,
+    signedAtMs: Long,
+    token: String?,
+    nonce: String,
+    platform: String?,
+    deviceFamily: String?,
+  ): String {
+    val scopeString = scopes.joinToString(",")
+    val authToken = token.orEmpty()
+    val platformNorm = normalizeMetadataField(platform)
+    val deviceFamilyNorm = normalizeMetadataField(deviceFamily)
+    return listOf(
+      "v3",
+      deviceId,
+      clientId,
+      clientMode,
+      role,
+      scopeString,
+      signedAtMs.toString(),
+      authToken,
+      nonce,
+      platformNorm,
+      deviceFamilyNorm,
+    ).joinToString("|")
+  }
+
+  internal fun normalizeMetadataField(value: String?): String {
+    val trimmed = value?.trim().orEmpty()
+    if (trimmed.isEmpty()) {
+      return ""
+    }
+    // Keep cross-runtime normalization deterministic (TS/Swift/Kotlin):
+    // lowercase ASCII A-Z only for auth payload metadata fields.
+    val out = StringBuilder(trimmed.length)
+    for (ch in trimmed) {
+      if (ch in 'A'..'Z') {
+        out.append((ch.code + 32).toChar())
+      } else {
+        out.append(ch)
+      }
+    }
+    return out.toString()
+  }
+}
--- a/apps/android/app/src/main/java/ai/openclaw/android/gateway/GatewaySession.kt
+++ b/apps/android/app/src/main/java/ai/openclaw/android/gateway/GatewaySession.kt
@@ -372,7 +372,7 @@ class GatewaySession(

      val signedAtMs = System.currentTimeMillis()
      val payload =
-        buildDeviceAuthPayloadV3(
+        DeviceAuthPayload.buildV3(
          deviceId = identity.deviceId,
          clientId = client.id,
          clientMode = client.mode,
@@ -584,42 +584,6 @@ class GatewaySession(
    }
  }

-  private fun buildDeviceAuthPayloadV3(
-    deviceId: String,
-    clientId: String,
-    clientMode: String,
-    role: String,
-    scopes: List<String>,
-    signedAtMs: Long,
-    token: String?,
-    nonce: String,
-    platform: String?,
-    deviceFamily: String?,
-  ): String {
-    val scopeString = scopes.joinToString(",")
-    val authToken = token.orEmpty()
-    val platformNorm = normalizeDeviceMetadataField(platform)
-    val deviceFamilyNorm = normalizeDeviceMetadataField(deviceFamily)
-    val parts =
-      mutableListOf(
-        "v3",
-        deviceId,
-        clientId,
-        clientMode,
-        role,
-        scopeString,
-        signedAtMs.toString(),
-        authToken,
-        nonce,
-        platformNorm,
-        deviceFamilyNorm,
-      )
-    return parts.joinToString("|")
-  }
-
-  private fun normalizeDeviceMetadataField(value: String?): String =
-    value?.trim()?.lowercase(Locale.ROOT).orEmpty()
-
  private fun normalizeCanvasHostUrl(
    raw: String?,
    endpoint: GatewayEndpoint,
--- a/apps/android/app/src/test/java/ai/openclaw/android/gateway/DeviceAuthPayloadTest.kt
+++ b/apps/android/app/src/test/java/ai/openclaw/android/gateway/DeviceAuthPayloadTest.kt
@@ -0,0 +1,35 @@
+package ai.openclaw.android.gateway
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class DeviceAuthPayloadTest {
+  @Test
+  fun buildV3_matchesCanonicalVector() {
+    val payload =
+      DeviceAuthPayload.buildV3(
+        deviceId = "dev-1",
+        clientId = "openclaw-macos",
+        clientMode = "ui",
+        role = "operator",
+        scopes = listOf("operator.admin", "operator.read"),
+        signedAtMs = 1_700_000_000_000,
+        token = "tok-123",
+        nonce = "nonce-abc",
+        platform = "  IOS  ",
+        deviceFamily = "  iPhone  ",
+      )
+
+    assertEquals(
+      "v3|dev-1|openclaw-macos|ui|operator|operator.admin,operator.read|1700000000000|tok-123|nonce-abc|ios|iphone",
+      payload,
+    )
+  }
+
+  @Test
+  fun normalizeMetadataField_asciiOnlyLowercase() {
+    assertEquals("İos", DeviceAuthPayload.normalizeMetadataField("  İOS  "))
+    assertEquals("mac", DeviceAuthPayload.normalizeMetadataField("  MAC  "))
+    assertEquals("", DeviceAuthPayload.normalizeMetadataField(null))
+  }
+}
--- a/apps/macos/Sources/OpenClawMacCLI/WizardCommand.swift
+++ b/apps/macos/Sources/OpenClawMacCLI/WizardCommand.swift
@@ -280,7 +280,7 @@ actor GatewayWizardClient {
        let connectNonce = try await self.waitForConnectChallenge()
        let identity = DeviceIdentityStore.loadOrCreate()
        let signedAtMs = Int(Date().timeIntervalSince1970 * 1000)
-        let payload = buildDeviceAuthPayloadV3(
+        let payload = GatewayDeviceAuthPayload.buildV3(
            deviceId: identity.deviceId,
            clientId: clientId,
            clientMode: clientMode,
@@ -327,44 +327,6 @@ actor GatewayWizardClient {
        }
    }

-    private func buildDeviceAuthPayloadV3(
-        deviceId: String,
-        clientId: String,
-        clientMode: String,
-        role: String,
-        scopes: [String],
-        signedAtMs: Int,
-        token: String?,
-        nonce: String,
-        platform: String?,
-        deviceFamily: String?) -> String
-    {
-        let scopeString = scopes.joined(separator: ",")
-        let authToken = token ?? ""
-        let normalizedPlatform = normalizeMetadataField(platform)
-        let normalizedDeviceFamily = normalizeMetadataField(deviceFamily)
-        return [
-            "v3",
-            deviceId,
-            clientId,
-            clientMode,
-            role,
-            scopeString,
-            String(signedAtMs),
-            authToken,
-            nonce,
-            normalizedPlatform,
-            normalizedDeviceFamily,
-        ].joined(separator: "|")
-    }
-
-    private func normalizeMetadataField(_ value: String?) -> String {
-        guard let value else { return "" }
-        return value
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-            .lowercased(with: Locale(identifier: "en_US_POSIX"))
-    }
-
    private func waitForConnectChallenge() async throws -> String {
        guard let task = self.task else { throw ConnectChallengeError.timeout }
        return try await AsyncTimeout.withTimeout(
--- a/apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceAuthPayload.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceAuthPayload.swift
@@ -0,0 +1,55 @@
+import Foundation
+
+public enum GatewayDeviceAuthPayload {
+    public static func buildV3(
+        deviceId: String,
+        clientId: String,
+        clientMode: String,
+        role: String,
+        scopes: [String],
+        signedAtMs: Int,
+        token: String?,
+        nonce: String,
+        platform: String?,
+        deviceFamily: String?) -> String
+    {
+        let scopeString = scopes.joined(separator: ",")
+        let authToken = token ?? ""
+        let normalizedPlatform = normalizeMetadataField(platform)
+        let normalizedDeviceFamily = normalizeMetadataField(deviceFamily)
+        return [
+            "v3",
+            deviceId,
+            clientId,
+            clientMode,
+            role,
+            scopeString,
+            String(signedAtMs),
+            authToken,
+            nonce,
+            normalizedPlatform,
+            normalizedDeviceFamily,
+        ].joined(separator: "|")
+    }
+
+    static func normalizeMetadataField(_ value: String?) -> String {
+        guard let value else { return "" }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return ""
+        }
+        // Keep cross-runtime normalization deterministic (TS/Swift/Kotlin):
+        // lowercase ASCII A-Z only for auth payload metadata fields.
+        var output = String()
+        output.reserveCapacity(trimmed.count)
+        for scalar in trimmed.unicodeScalars {
+            let codePoint = scalar.value
+            if codePoint >= 65, codePoint <= 90, let lowered = UnicodeScalar(codePoint + 32) {
+                output.unicodeScalars.append(lowered)
+            } else {
+                output.unicodeScalars.append(scalar)
+            }
+        }
+        return output
+    }
+}
--- a/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift
+++ b/apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayChannel.swift
@@ -399,7 +399,7 @@ public actor GatewayChannelActor {
        let signedAtMs = Int(Date().timeIntervalSince1970 * 1000)
        let connectNonce = try await self.waitForConnectChallenge()
        if includeDeviceIdentity, let identity {
-            let payload = buildDeviceAuthPayloadV3(
+            let payload = GatewayDeviceAuthPayload.buildV3(
                deviceId: identity.deviceId,
                clientId: clientId,
                clientMode: clientMode,
@@ -443,44 +443,6 @@ public actor GatewayChannelActor {
        }
    }

-    private func buildDeviceAuthPayloadV3(
-        deviceId: String,
-        clientId: String,
-        clientMode: String,
-        role: String,
-        scopes: [String],
-        signedAtMs: Int,
-        token: String?,
-        nonce: String,
-        platform: String?,
-        deviceFamily: String?) -> String
-    {
-        let scopeString = scopes.joined(separator: ",")
-        let authToken = token ?? ""
-        let normalizedPlatform = normalizeMetadataField(platform)
-        let normalizedDeviceFamily = normalizeMetadataField(deviceFamily)
-        return [
-            "v3",
-            deviceId,
-            clientId,
-            clientMode,
-            role,
-            scopeString,
-            String(signedAtMs),
-            authToken,
-            nonce,
-            normalizedPlatform,
-            normalizedDeviceFamily,
-        ].joined(separator: "|")
-    }
-
-    private func normalizeMetadataField(_ value: String?) -> String {
-        guard let value else { return "" }
-        return value
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-            .lowercased(with: Locale(identifier: "en_US_POSIX"))
-    }
-
    private func handleConnectResponse(
        _ res: ResponseFrame,
        identity: DeviceIdentity?,
--- a/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeviceAuthPayloadTests.swift
+++ b/apps/shared/OpenClawKit/Tests/OpenClawKitTests/DeviceAuthPayloadTests.swift
@@ -0,0 +1,30 @@
+import Testing
+@testable import OpenClawKit
+
+@Suite("DeviceAuthPayload")
+struct DeviceAuthPayloadTests {
+    @Test("builds canonical v3 payload vector")
+    func buildsCanonicalV3PayloadVector() {
+        let payload = GatewayDeviceAuthPayload.buildV3(
+            deviceId: "dev-1",
+            clientId: "openclaw-macos",
+            clientMode: "ui",
+            role: "operator",
+            scopes: ["operator.admin", "operator.read"],
+            signedAtMs: 1_700_000_000_000,
+            token: "tok-123",
+            nonce: "nonce-abc",
+            platform: "  IOS  ",
+            deviceFamily: "  iPhone  ")
+        #expect(
+            payload
+                == "v3|dev-1|openclaw-macos|ui|operator|operator.admin,operator.read|1700000000000|tok-123|nonce-abc|ios|iphone")
+    }
+
+    @Test("normalizes metadata with ASCII-only lowercase")
+    func normalizesMetadataWithAsciiLowercase() {
+        #expect(GatewayDeviceAuthPayload.normalizeMetadataField("  İOS  ") == "İos")
+        #expect(GatewayDeviceAuthPayload.normalizeMetadataField("  MAC  ") == "mac")
+        #expect(GatewayDeviceAuthPayload.normalizeMetadataField(nil) == "")
+    }
+}