Add local pairing bridge for web-based iOS signers

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.

[Mora140]

Summary

Adds a loopback-only HTTP bridge so a web-based iOS signer running in Safari can ask LocalDevVPN to run the device pairing flow and hand back the resulting pairing record — the native piece a web app can't provide for itself.

The app already had two ways in (localdevvpn://enable/disable and the App Intent), but both are one-shot commands with no way to return data. This extends the URL scheme with a pair verb as the entry point from a website, and adds the missing return path as a 127.0.0.1-only HTTP server. The packet tunnel is untouched — loopback traffic never enters it, so pairing works whether or not the VPN is connected.

Authorization, not an anonymous read

GET /v1/pairing-record never answers a page that just probes localhost:

• It requires a bearer token from a session the user approved in the app. Probing without one gets a 401.
• The prompt shows the browser-supplied Origin (which a page can't forge) plus a six-digit code the requesting page must display, so the user confirms the tab in front of them rather than a hidden one.
• Every request needs a non-CORS-safelisted header, forcing a preflight, and Host must be the literal loopback authority, which blocks DNS rebinding.
• Tokens are 256-bit, in memory only, constant-time compared, and expire. Prompts expire after two minutes, one at a time, rate limited.
• The record is stored with complete data protection, excluded from backups, never logged (only a truncated fingerprint), and never sent anywhere.

The bridge is off by default and only listens while the app is in the foreground, with a short background assertion so a page that was just handed a token can still fetch the record after Safari comes forward.

On the pairing flow itself

No public iOS API lets an app mint a lockdown pairing record for the device it runs on — iOS ≤16 needs a trusted host driving lockdownd, iOS 17+ uses remotepairingd behind an Apple-internal entitlement, and DeviceDiscoveryUI yields an NWEndpoint, not a pairing record. So the system-flow provider reports its availability honestly instead of reaching for private API, and the shipped path falls back to a user-driven pairing-file import through the document picker. A PairingFlowProvider seam behind -D LOCALDEVVPN_NATIVE_PAIRING lets an entitled build drop in a real PIN flow later without changing the API, the states, or the UI.

No new entitlements, no .pbxproj changes (the project uses synchronized folder groups).

Test plan

• Builds clean in Xcode for iOS and tvOS
• Enable Settings → Pairing Bridge → Allow local web clients; confirm the server comes up on one of 19842–19844
• Serve docs/pairing-bridge-demo.html and run both flows end to end: the localdevvpn://pair deep link and the polling/verification-code flow
• Confirm GET /v1/pairing-record returns 401 with no token, and only succeeds after approving in the app
• Import a pairing file in Settings and confirm the bridge serves it back to an authorized session
• Confirm revoking access, disabling the bridge, and backgrounding the app each tear down sessions and the listener

docs/pairing-bridge.md has the full API reference, the security model, and the iOS API, entitlement, App Store, background-execution, Safari/CORS and networking limitations worth knowing about.