From a362d0d29f14253044ce017fd4ff0475a7fbcfb6 Mon Sep 17 00:00:00 2001
From: Tygo Egmond <35234103+tygoegmond@users.noreply.github.com>
Date: Fri, 16 Oct 2026 15:33:26 +0200
Subject: [PATCH] feat: auth.webSession, Google and Apple sign-in in the system
 sign-in sheet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Google refuses to sign in inside an embedded web view, so the page asks the
shell to open core's sign-in hop in the system's sign-in sheet
(`auth.webSession { url }` → `{ callbackUrl }`, PROTOCOL.md §7.1). The sheet
closes on the plugchoice-link scheme and the URL goes back to the page.

- iOS: ASWebAuthenticationSession with callback scheme plugchoice-link,
  sharing Safari's cookies. Listed always; the host app needs nothing.
- Android: Chrome's Auth Tab (androidx.browser 1.9 AuthTabIntent), which
  answers the activity that opened it, so no intent filter and no app
  competes for the scheme. Listed only when the browser supports Auth Tab;
  a <queries> entry lets the library find a Custom Tabs browser.

The callback URL holds a one-time code that is worth nothing without the
run's credential; shells never log it.
---
 android/plugchoice/build.gradle.kts           |  2 +
 .../plugchoice/src/main/AndroidManifest.xml   |  7 ++
 .../com/plugchoice/internal/BridgeHost.kt     |  5 ++
 .../com/plugchoice/internal/LinkActivity.kt   | 17 +++++
 .../com/plugchoice/internal/LinkBridge.kt     | 11 +++-
 .../java/com/plugchoice/internal/WebSignIn.kt | 65 +++++++++++++++++++
 .../com/plugchoice/internal/BridgeTest.kt     | 18 +++++
 bridge/PROTOCOL.md                            | 20 +++++-
 .../PlugchoiceSDK/Auth/WebSignIn.swift        | 56 ++++++++++++++++
 ios/Sources/PlugchoiceSDK/Bridge/Bridge.swift | 21 +++++-
 .../PlugchoiceSDKTests/BridgeTests.swift      | 28 +++++++-
 11 files changed, 241 insertions(+), 9 deletions(-)
 create mode 100644 android/plugchoice/src/main/java/com/plugchoice/internal/WebSignIn.kt
 create mode 100644 ios/Sources/PlugchoiceSDK/Auth/WebSignIn.swift

diff --git a/android/plugchoice/build.gradle.kts b/android/plugchoice/build.gradle.kts
index 1d89a14..60822a8 100644
--- a/android/plugchoice/build.gradle.kts
+++ b/android/plugchoice/build.gradle.kts
@@ -47,6 +47,8 @@ dependencies {
     api("androidx.activity:activity-ktx:1.12.4")
     implementation("androidx.core:core-ktx:1.17.0")
     implementation("androidx.webkit:webkit:1.15.0")
+    // auth.webSession: Google and Apple sign-in in Chrome's Auth Tab.
+    implementation("androidx.browser:browser:1.9.0")
     implementation("com.squareup.okhttp3:okhttp:4.12.0")
     implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
     // camera.scanCode: the Google code scanner (Play services UI, no camera permission).
diff --git a/android/plugchoice/src/main/AndroidManifest.xml b/android/plugchoice/src/main/AndroidManifest.xml
index 2767a6b..41f7011 100644
--- a/android/plugchoice/src/main/AndroidManifest.xml
+++ b/android/plugchoice/src/main/AndroidManifest.xml
@@ -44,6 +44,13 @@
         android:name="android.hardware.bluetooth_le"
         android:required="false" />
 
+    <!-- auth.webSession: find a browser that supports Custom Tabs, to check for Auth Tab (API 30+). -->
+    <queries>
+        <intent>
+            <action android:name="android.support.customtabs.action.CustomTabsService" />
+        </intent>
+    </queries>
+
     <application>
         <!--
           configChanges: the Link UI must never reload mid-flow (it would lose its
diff --git a/android/plugchoice/src/main/java/com/plugchoice/internal/BridgeHost.kt b/android/plugchoice/src/main/java/com/plugchoice/internal/BridgeHost.kt
index ca17f30..fbcc213 100644
--- a/android/plugchoice/src/main/java/com/plugchoice/internal/BridgeHost.kt
+++ b/android/plugchoice/src/main/java/com/plugchoice/internal/BridgeHost.kt
@@ -1,6 +1,8 @@
 package com.plugchoice.internal
 
 import android.content.Context
+import android.net.Uri
+import androidx.browser.auth.AuthTabIntent
 import com.plugchoice.LinkResult
 
 /** What the bridge needs from the activity hosting it. All calls happen on the main thread. */
@@ -11,6 +13,9 @@ internal interface BridgeHost {
     /** Runtime permission request through the activity; returns permission → granted. */
     suspend fun requestPermissions(permissions: Array<String>): Map<String, Boolean>
 
+    /** `auth.webSession`: opens [url] in an Auth Tab that closes on [scheme], and waits for how it ended. */
+    suspend fun openAuthTab(url: Uri, scheme: String): AuthTabIntent.AuthResult
+
     /** `session.close`, or the shell closing on its own: dismiss the Link screen and hand [result] to the host app. */
     fun closeSession(result: LinkResult)
 
diff --git a/android/plugchoice/src/main/java/com/plugchoice/internal/LinkActivity.kt b/android/plugchoice/src/main/java/com/plugchoice/internal/LinkActivity.kt
index cd72c02..feceaa9 100644
--- a/android/plugchoice/src/main/java/com/plugchoice/internal/LinkActivity.kt
+++ b/android/plugchoice/src/main/java/com/plugchoice/internal/LinkActivity.kt
@@ -29,6 +29,7 @@ import android.widget.ImageView
 import android.widget.LinearLayout
 import android.widget.TextView
 import androidx.activity.ComponentActivity
+import androidx.browser.auth.AuthTabIntent
 import androidx.activity.SystemBarStyle
 import androidx.activity.addCallback
 import androidx.activity.enableEdgeToEdge
@@ -90,6 +91,15 @@ internal class LinkActivity : ComponentActivity() {
             pendingPermissions = null
         }
 
+    private var pendingAuthTab: CompletableDeferred<AuthTabIntent.AuthResult>? = null
+
+    // auth.webSession: the Auth Tab answers this activity directly (no intent filter).
+    private val authTabLauncher =
+        AuthTabIntent.registerActivityResultLauncher(this) { result ->
+            pendingAuthTab?.complete(result)
+            pendingAuthTab = null
+        }
+
     private val host = object : BridgeHost {
         override val hostContext: Context
             get() = this@LinkActivity
@@ -102,6 +112,13 @@ internal class LinkActivity : ComponentActivity() {
                 deferred.await()
             }
 
+        override suspend fun openAuthTab(url: Uri, scheme: String): AuthTabIntent.AuthResult {
+            val deferred = CompletableDeferred<AuthTabIntent.AuthResult>()
+            pendingAuthTab = deferred
+            AuthTabIntent.Builder().build().launch(authTabLauncher, url, scheme)
+            return deferred.await()
+        }
+
         override fun closeSession(result: LinkResult) {
             finishWith(result)
         }
diff --git a/android/plugchoice/src/main/java/com/plugchoice/internal/LinkBridge.kt b/android/plugchoice/src/main/java/com/plugchoice/internal/LinkBridge.kt
index 4674209..c8237cb 100644
--- a/android/plugchoice/src/main/java/com/plugchoice/internal/LinkBridge.kt
+++ b/android/plugchoice/src/main/java/com/plugchoice/internal/LinkBridge.kt
@@ -48,6 +48,7 @@ internal class LinkBridge(
     private val wifi: WifiController = WifiController(host, onNetworkChanged = { net.onNetworkChanged() })
     private val net: LocalNetworkClient = LocalNetworkClient(wifi, emit = this::emitEvent)
     private val scanner = CodeScanner(host)
+    private val webSignIn = WebSignIn(host)
     private val discovery = LanDiscovery(host.hostContext)
     private val sessions = HttpSessions(TlsSessionConnector)
     private val tcp = TcpSockets(emit = this::emitEvent)
@@ -60,6 +61,7 @@ internal class LinkBridge(
     )
     private val clientSecrets = ClientSecrets(scope, fetchClientSecret)
     private val bluetoothAvailable: Boolean by lazy { Transports.bluetoothAvailable(host.hostContext) }
+    private val webSessionAvailable: Boolean by lazy { WebSignIn.isAvailable(host.hostContext) }
     private var disposed = false
 
     /** Bumped for each new document: answers to the previous document's requests are dropped. */
@@ -157,6 +159,7 @@ internal class LinkBridge(
             JSONObject()
         }
         "camera.scanCode" -> scanner.scan(params)
+        "auth.webSession" -> webSignIn.signIn(params)
         "lan.discover" -> discover(LanDiscovery.parseRequest(params))
         "lan.stopDiscovery" -> {
             discovery.stop()
@@ -280,7 +283,7 @@ internal class LinkBridge(
             .put("sdkVersion", Plugchoice.SDK_VERSION)
             .put("platform", "android")
             .put("osVersion", Build.VERSION.RELEASE)
-            .put("capabilities", JSONArray(capabilities(bluetoothAvailable)))
+            .put("capabilities", JSONArray(capabilities(bluetoothAvailable, webSessionAvailable)))
             .put("lanServiceTypes", JSONObject.NULL)
     }
 
@@ -374,11 +377,13 @@ internal class LinkBridge(
         /**
          * `hello`'s capabilities (§5). No `wifi.accessory` on Android (that's AccessorySetupKit on
          * iOS); `ble` when [bluetoothAvailable] (the device has Bluetooth LE and the host kept the
-         * library's Bluetooth permissions).
+         * library's Bluetooth permissions); `auth.webSession` when [webSessionAvailable] (the
+         * browser supports Auth Tab).
          */
-        fun capabilities(bluetoothAvailable: Boolean): List<String> = buildList {
+        fun capabilities(bluetoothAvailable: Boolean, webSessionAvailable: Boolean = false): List<String> = buildList {
             addAll(listOf("wifi.join", "http.request", "ws", "session.close", "camera.scanCode", "ui.closeRequest"))
             addAll(listOf("lan.address", "lan.discover", "http.session", "auth.clientSecret"))
+            if (webSessionAvailable) add("auth.webSession")
             if (bluetoothAvailable) add("ble")
             addAll(listOf("tcp", "udp", "trust.custom"))
         }
diff --git a/android/plugchoice/src/main/java/com/plugchoice/internal/WebSignIn.kt b/android/plugchoice/src/main/java/com/plugchoice/internal/WebSignIn.kt
new file mode 100644
index 0000000..9b0a85a
--- /dev/null
+++ b/android/plugchoice/src/main/java/com/plugchoice/internal/WebSignIn.kt
@@ -0,0 +1,65 @@
+package com.plugchoice.internal
+
+import android.content.Context
+import android.net.Uri
+import androidx.browser.auth.AuthTabIntent
+import androidx.browser.customtabs.CustomTabsClient
+import org.json.JSONObject
+import java.net.URI
+import java.net.URISyntaxException
+
+/**
+ * `auth.webSession` (PROTOCOL.md §7.1): Google or Apple sign-in in Chrome's Auth Tab, since Google
+ * refuses an embedded web view. The tab closes on the `plugchoice-link` scheme and hands that URL
+ * straight back to the activity that opened it, so no intent filter is involved and apps with the
+ * SDK never compete for the scheme. Browsers without Auth Tab don't get the capability. The URL
+ * holds a one-time code: never logged.
+ */
+internal class WebSignIn(private val host: BridgeHost) {
+
+    private var showing = false
+
+    suspend fun signIn(params: JSONObject): JSONObject {
+        val value = params.optStringOrNull("url")
+        if (!isWebSessionUrl(value)) throw BridgeException.invalidParams("url must be an https URL")
+        val url = Uri.parse(value)
+        if (showing) throw BridgeException(ErrorCode.UNAVAILABLE, "a sign-in is already showing")
+        if (!isAvailable(host.hostContext)) throw BridgeException(ErrorCode.UNAVAILABLE, "the browser has no Auth Tab")
+
+        showing = true
+        try {
+            val result = host.openAuthTab(url, CALLBACK_SCHEME)
+            return when (result.resultCode) {
+                AuthTabIntent.RESULT_OK -> {
+                    val callback = result.resultUri ?: throw BridgeException(ErrorCode.UNAVAILABLE, "the sign-in returned no URL")
+                    JSONObject().put("callbackUrl", callback.toString())
+                }
+                AuthTabIntent.RESULT_CANCELED -> throw BridgeException(ErrorCode.USER_CANCELLED, "sign-in closed")
+                else -> throw BridgeException(ErrorCode.UNAVAILABLE, "sign-in failed (${result.resultCode})")
+            }
+        } finally {
+            showing = false
+        }
+    }
+
+    companion object {
+        const val CALLBACK_SCHEME = "plugchoice-link"
+
+        /** Whether the default browser (or another Custom Tabs browser) supports Auth Tab. */
+        fun isAvailable(context: Context): Boolean {
+            val browser = CustomTabsClient.getPackageName(context, null) ?: return false
+            return CustomTabsClient.isAuthTabSupported(context, browser)
+        }
+
+        /** `url`: an `https` URL with a host (core's sign-in hop). Plain JVM, so tests can run it. */
+        fun isWebSessionUrl(value: String?): Boolean {
+            if (value.isNullOrEmpty()) return false
+            val uri = try {
+                URI(value)
+            } catch (_: URISyntaxException) {
+                return false
+            }
+            return uri.scheme.equals("https", ignoreCase = true) && !uri.host.isNullOrEmpty()
+        }
+    }
+}
diff --git a/android/plugchoice/src/test/java/com/plugchoice/internal/BridgeTest.kt b/android/plugchoice/src/test/java/com/plugchoice/internal/BridgeTest.kt
index fab4ed3..ff75e7d 100644
--- a/android/plugchoice/src/test/java/com/plugchoice/internal/BridgeTest.kt
+++ b/android/plugchoice/src/test/java/com/plugchoice/internal/BridgeTest.kt
@@ -53,6 +53,24 @@ class BridgeTest {
         assertEquals(LinkBridge.capabilities(bluetoothAvailable = true) - "ble", LinkBridge.capabilities(bluetoothAvailable = false))
     }
 
+    @Test
+    fun `auth webSession only where the browser has Auth Tab`() {
+        val with = LinkBridge.capabilities(bluetoothAvailable = false, webSessionAvailable = true)
+        assertTrue("auth.webSession" in with)
+        assertEquals(with - "auth.webSession", LinkBridge.capabilities(bluetoothAvailable = false))
+    }
+
+    @Test
+    fun `a web session opens https URLs only`() {
+        assertTrue(WebSignIn.isWebSessionUrl("https://app.plugchoice.com/auth/google/link-run?ticket=t"))
+        assertFalse(WebSignIn.isWebSessionUrl(null))
+        assertFalse(WebSignIn.isWebSessionUrl(""))
+        assertFalse(WebSignIn.isWebSessionUrl("http://app.plugchoice.com/auth"))
+        assertFalse(WebSignIn.isWebSessionUrl("plugchoice-link://auth"))
+        assertFalse(WebSignIn.isWebSessionUrl("https://"))
+        assertFalse(WebSignIn.isWebSessionUrl("https://exa mple.com"))
+    }
+
     // session.close
 
     @Test
diff --git a/bridge/PROTOCOL.md b/bridge/PROTOCOL.md
index 5c3c408..8fc3bb1 100644
--- a/bridge/PROTOCOL.md
+++ b/bridge/PROTOCOL.md
@@ -1,6 +1,6 @@
 # Plugchoice bridge protocol, version 1
 
-The contract between the hosted page at `https://connect.plugchoice.com` and the native shells in this repository (`ios/`, `android/`). The page runs the flow (setting up a charger, today); the shell only does what a web page can't: join a device's Wi-Fi, find devices on the local network and talk HTTP, WebSocket, TCP and UDP to them, talk Bluetooth, scan a code with the camera, fetch the client secret from the host app, and close the screen with a result.
+The contract between the hosted page at `https://connect.plugchoice.com` and the native shells in this repository (`ios/`, `android/`). The page runs the flow (setting up a charger, today); the shell only does what a web page can't: join a device's Wi-Fi, find devices on the local network and talk HTTP, WebSocket, TCP and UDP to them, talk Bluetooth, scan a code with the camera, fetch the client secret from the host app, open the system sign-in sheet for Google and Apple, and close the screen with a result.
 
 Design rules:
 
@@ -111,6 +111,7 @@ The page sends `hello` first and waits for the answer before anything else.
 | `lan.discover` | `lan.discover`, `lan.stopDiscovery` (§9.4) | iOS: the host declares at least one `NSBonjourServices` type. Android: always |
 | `http.session` | `http.session.open`, `.request`, `.close` (§9.5) | Always |
 | `auth.clientSecret` | `auth.clientSecret` (§7) | Always |
+| `auth.webSession` | `auth.webSession` (§7.1) | iOS: always. Android: the default browser supports Auth Tab |
 | `ble` | `ble.*` (§11) | The device has Bluetooth LE, and iOS: the host has `NSBluetoothAlwaysUsageDescription`; Android: the host kept the library's Bluetooth permissions |
 | `tcp` | `tcp.open`, `tcp.write`, `tcp.close` (§9.6) | Always |
 | `udp` | `udp.exchange` (§9.7) | Always |
@@ -165,6 +166,19 @@ When the shell closes by itself, it reports the action it opened with, no `sessi
 - `clientSecretUnavailable`: the callback threw, returned an empty (or blank) string, or took longer than 30 s. The page shows its error screen with **Try again**, which calls `auth.clientSecret` again.
 - The shell never logs the secret and keeps no copy after answering.
 
+### 7.1 `auth.webSession`
+
+| Params | Result | Errors |
+|---|---|---|
+| `{ url: string }` | `{ callbackUrl: string }` | `userCancelled`, `unavailable` |
+
+- Signing in with Google or Apple. Google refuses to sign in inside an embedded web view, so the shell opens `url` (an `https` URL from core's sign-in hop) in the system's sign-in sheet, outside the page. The sheet closes when it reaches a URL with the scheme `plugchoice-link`, and `callbackUrl` is that URL, as the page reads it (core puts the result in its fragment).
+- The host app needs nothing: the sheet catches the scheme itself, and no app has to register it. Whatever comes back is worth nothing without the run's credential, which only the page holds.
+- `userCancelled`: the user closed the sheet. `unavailable`: a sheet is already showing, or the system couldn't show one. A `url` that isn't `https` is `invalidParams`.
+- iOS: `ASWebAuthenticationSession` with callback scheme `plugchoice-link`, sharing Safari's cookies (not ephemeral: someone signed in to Google in Safari picks their account in one tap). iOS asks first whether the app may use the website to sign in.
+- Android: Chrome's Auth Tab (androidx.browser `AuthTabIntent`) with the same scheme. Listed only when the default browser supports Auth Tab; elsewhere the page keeps sign-in by code. No intent filter is involved, so apps with the SDK never compete for the scheme.
+- `callbackUrl` holds a one-time code: shells never log it.
+
 ## 8. Wi-Fi
 
 ### `wifi.ensurePermissions`
@@ -417,7 +431,7 @@ Not AccessorySetupKit: declaring it for Bluetooth limits CoreBluetooth in the wh
 | `udp.exchange` | `timeoutMs` clamped to 100 ms to 30 s; `maxReplies` 1 to 1000; a datagram up to 65 507 bytes |
 | `ble.scan`, `ble.connect` | `timeoutMs` clamped to 1 s to 60 s |
 | Bluetooth request | 10 s; `ble.write` up to 512 bytes; `mtu` 23 to 517 |
-| At once | 1 `lan.discover`, 1 `ble.scan`, 1 `camera.scanCode`; 64 sessions, 16 TCP sockets, 8 Bluetooth connections |
+| At once | 1 `lan.discover`, 1 `ble.scan`, 1 `camera.scanCode`, 1 `auth.webSession`; 64 sessions, 16 TCP sockets, 8 Bluetooth connections |
 
 ## 13. Error codes
 
@@ -433,7 +447,7 @@ Not AccessorySetupKit: declaring it for Bluetooth limits CoreBluetooth in the wh
 | `undeclaredServiceType`, `busy` | `lan.discover` (`undeclaredServiceType` iOS); `busy` also `ble.scan`, `ble.connect` |
 | `unknownSession`, `tooManySessions` | `http.session.*` |
 | `unknownSocket`, `tooManySockets` | `tcp.*` |
-| `userCancelled`, `cameraPermissionDenied`, `unavailable` | `camera.scanCode`; `unavailable` also `ble.*` |
+| `userCancelled`, `cameraPermissionDenied`, `unavailable` | `camera.scanCode`; `userCancelled` and `unavailable` also `auth.webSession`; `unavailable` also `ble.*` |
 | `bluetoothOff`, `bluetoothPermissionDenied`, `unknownDevice`, `notConnected`, `unknownCharacteristic`, `notPermitted`, `tooManyConnections`, `gatt` | `ble.*` |
 
 `LinkResult.error` codes the shell sets itself: `pageLoadFailed` and `internal` (§6.3). Every other code comes from the page.
diff --git a/ios/Sources/PlugchoiceSDK/Auth/WebSignIn.swift b/ios/Sources/PlugchoiceSDK/Auth/WebSignIn.swift
new file mode 100644
index 0000000..c35f927
--- /dev/null
+++ b/ios/Sources/PlugchoiceSDK/Auth/WebSignIn.swift
@@ -0,0 +1,56 @@
+import AuthenticationServices
+import UIKit
+
+/// `auth.webSession` (PROTOCOL.md §7.1): Google or Apple sign-in in the
+/// system's sign-in sheet, since Google refuses an embedded web view. The
+/// sheet closes on the `plugchoice-link` scheme; that URL goes back to the
+/// page. It holds a one-time code: never logged.
+@MainActor
+final class WebSignIn: NSObject, ASWebAuthenticationPresentationContextProviding {
+    static let callbackScheme = "plugchoice-link"
+
+    private var showing: ASWebAuthenticationSession?
+    private weak var anchor: UIWindow?
+
+    func signIn(url: URL, from presenter: UIViewController?) async throws -> JSONObject {
+        guard showing == nil else {
+            throw BridgeError(code: "unavailable", message: "a sign-in is already showing")
+        }
+        guard let window = presenter?.viewIfLoaded?.window else {
+            throw BridgeError(code: "unavailable", message: "nothing to show the sign-in over")
+        }
+        anchor = window
+        defer { showing = nil }
+
+        let callback = try await withTaskCancellationHandler {
+            try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<URL, Error>) in
+                let session = ASWebAuthenticationSession(url: url, callbackURLScheme: Self.callbackScheme) { callbackURL, error in
+                    if let callbackURL {
+                        continuation.resume(returning: callbackURL)
+                    } else if (error as? ASWebAuthenticationSessionError)?.code == .canceledLogin {
+                        continuation.resume(throwing: BridgeError(code: "userCancelled", message: "sign-in closed"))
+                    } else {
+                        continuation.resume(throwing: BridgeError(code: "unavailable", message: "sign-in failed: \(error.map { String(describing: type(of: $0)) } ?? "unknown")"))
+                    }
+                }
+                session.presentationContextProvider = self
+                // Shares Safari's cookies: someone signed in to Google there picks their account in one tap.
+                session.prefersEphemeralWebBrowserSession = false
+                showing = session
+                if !session.start() {
+                    showing = nil
+                    continuation.resume(throwing: BridgeError(code: "unavailable", message: "the sign-in sheet didn't start"))
+                }
+            }
+        } onCancel: {
+            // The page went away or the screen is closing: the session's
+            // completion answers with canceledLogin.
+            Task { @MainActor in self.showing?.cancel() }
+        }
+        return ["callbackUrl": callback.absoluteString]
+    }
+
+    nonisolated func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
+        MainActor.assumeIsolated { anchor ?? ASPresentationAnchor() }
+    }
+}
diff --git a/ios/Sources/PlugchoiceSDK/Bridge/Bridge.swift b/ios/Sources/PlugchoiceSDK/Bridge/Bridge.swift
index 3973d67..5dbcef1 100644
--- a/ios/Sources/PlugchoiceSDK/Bridge/Bridge.swift
+++ b/ios/Sources/PlugchoiceSDK/Bridge/Bridge.swift
@@ -23,7 +23,7 @@ final class Bridge {
     }
 
     weak var webView: WKWebView?
-    /// Presents the `camera.scanCode` scanner.
+    /// Presents the `camera.scanCode` scanner and the `auth.webSession` sheet.
     weak var presenter: UIViewController?
     /// `hello` was answered: the page draws its own close control and
     /// decides about native closes from now on.
@@ -38,6 +38,7 @@ final class Bridge {
     private let wifi = WifiService()
     private lazy var http = HTTPService()
     private lazy var scanner = CodeScanner()
+    private lazy var webSignIn = WebSignIn()
     private lazy var webSockets = WebSocketService { [weak self] event, params in
         self?.emit(event, params)
     }
@@ -193,6 +194,13 @@ final class Bridge {
                     ["clientSecret": try await secrets.clientSecret()]
                 }
 
+            case "auth.webSession":
+                let url = try Self.webSessionURL(params)
+                let presenter = presenter
+                run(reply) { [webSignIn, weak presenter] in
+                    try await webSignIn.signIn(url: url, from: presenter)
+                }
+
             case "camera.scanCode":
                 let request = try Self.scanRequest(params)
                 let presenter = presenter
@@ -316,7 +324,7 @@ final class Bridge {
         if LanDiscovery.isAvailable(declared: declaredServiceTypes) {
             capabilities.append("lan.discover")
         }
-        capabilities += ["http.session", "auth.clientSecret"]
+        capabilities += ["http.session", "auth.clientSecret", "auth.webSession"]
         if bluetoothAvailable {
             capabilities.append("ble")
         }
@@ -374,6 +382,15 @@ final class Bridge {
         )
     }
 
+    /// `auth.webSession`'s `url`: an `https` URL with a host (core's sign-in hop).
+    static func webSessionURL(_ params: Params) throws -> URL {
+        let string = try params.string("url")
+        guard let url = URL(string: string), url.scheme?.lowercased() == "https", url.host?.isEmpty == false else {
+            throw BridgeError.invalidParams("url must be an https URL")
+        }
+        return url
+    }
+
     static func scanRequest(_ params: Params) throws -> CodeScanner.Request {
         let formats = try params.stringArray("formats")
         guard !formats.isEmpty, formats.allSatisfy({ $0 == "qr" }) else {
diff --git a/ios/Tests/PlugchoiceSDKTests/BridgeTests.swift b/ios/Tests/PlugchoiceSDKTests/BridgeTests.swift
index 49c6604..309e3c1 100644
--- a/ios/Tests/PlugchoiceSDKTests/BridgeTests.swift
+++ b/ios/Tests/PlugchoiceSDKTests/BridgeTests.swift
@@ -29,7 +29,7 @@ final class BridgeTests: XCTestCase {
         let capabilities = try XCTUnwrap(result["capabilities"] as? [String])
         XCTAssertEqual(
             capabilities,
-            ["wifi.join", "http.request", "ws", "session.close", "ui.closeRequest", "lan.address", "http.session", "auth.clientSecret", "tcp", "udp", "trust.custom"],
+            ["wifi.join", "http.request", "ws", "session.close", "ui.closeRequest", "lan.address", "http.session", "auth.clientSecret", "auth.webSession", "tcp", "udp", "trust.custom"],
             "the test host has no NSCameraUsageDescription, NSBonjourServices, NSBluetoothAlwaysUsageDescription or NSAccessorySetupKitSupports"
         )
         XCTAssertEqual(result["lanServiceTypes"] as? [String], [], "the test host declares none")
@@ -130,6 +130,32 @@ final class BridgeTests: XCTestCase {
         }
     }
 
+    // MARK: - auth.webSession
+
+    func testWebSessionURL() throws {
+        XCTAssertEqual(
+            try Bridge.webSessionURL(Params(["url": "https://app.plugchoice.com/auth/google/link-run?ticket=t"])).absoluteString,
+            "https://app.plugchoice.com/auth/google/link-run?ticket=t"
+        )
+        XCTAssertThrowsError(try Bridge.webSessionURL(Params([:])))
+        XCTAssertThrowsError(try Bridge.webSessionURL(Params(["url": ""])))
+        XCTAssertThrowsError(try Bridge.webSessionURL(Params(["url": "http://app.plugchoice.com/auth"])))
+        XCTAssertThrowsError(try Bridge.webSessionURL(Params(["url": "plugchoice-link://auth"])))
+        XCTAssertThrowsError(try Bridge.webSessionURL(Params(["url": "https://"])))
+    }
+
+    func testWebSessionIsUnavailableWithoutAWindow() async {
+        // No presenter on screen: answer `unavailable`, never start a sheet.
+        do {
+            _ = try await WebSignIn().signIn(url: URL(string: "https://app.plugchoice.com/auth")!, from: nil)
+            XCTFail("expected unavailable")
+        } catch let error as BridgeError {
+            XCTAssertEqual(error.code, "unavailable")
+        } catch {
+            XCTFail("unexpected \(error)")
+        }
+    }
+
     // MARK: - camera.scanCode
 
     func testScanRequest() throws {