fix(ios): route editor REST requests through a native relay under Lockdown Mode

ios/Demo-iOS/Sources/ConfigurationItem.swift

@@ -68,16 +68,17 @@ struct LocalWordPressCredentials: Codable {
     let authHeader: String
 
     /// Loads credentials from the file path specified in the `WP_ENV_CREDENTIALS_PATH` environment variable.
+    ///
+    /// Returns `nil` when the variable is unset or the file cannot be read, so
+    /// a misconfigured environment surfaces as the "not configured" message
+    /// rather than as a confusing failure against some other site.
     static func load() -> LocalWordPressCredentials? {
-        guard let path = ProcessInfo.processInfo.environment["WP_ENV_CREDENTIALS_PATH"] else {
+        guard let path = ProcessInfo.processInfo.environment["WP_ENV_CREDENTIALS_PATH"],
+              let data = FileManager.default.contents(atPath: path),
+              let credentials = try? JSONDecoder().decode(LocalWordPressCredentials.self, from: data) else {
             return nil
         }
-
-        guard let data = FileManager.default.contents(atPath: path) else {
-            return nil
-        }
-
-        return try? JSONDecoder().decode(LocalWordPressCredentials.self, from: data)
+        return credentials
     }
 }
 

ios/Demo-iOS/Sources/GutenbergApp.swift

@@ -43,6 +43,14 @@ struct GutenbergApp: App {
         // Configure logger for GutenbergKit
         EditorLogger.shared = OSLogEditorLogger()
         EditorLogger.logLevel = .debug
+
+        // Opt-in: keep the device awake while the demo app is foregrounded.
+        // The debugging workflows here (Web Inspector, devicectl console)
+        // break when the device auto-locks, but a demo app that never lets
+        // the screen sleep is its own surprise.
+        if ProcessInfo.processInfo.environment["GUTENBERG_DISABLE_IDLE_TIMER"] == "1" {
+            UIApplication.shared.isIdleTimerDisabled = true
+        }
     }
 
     var body: some Scene {

ios/Demo-iOS/Sources/Views/EditorList.swift

@@ -9,6 +9,11 @@ struct EditorList: View {
     @State private var showDebugSettings = false
     @State private var showMediaProxyServer = false
 
+    // Debug automation: jump straight to the Local WordPress editor when
+    // launched with GUTENBERG_AUTO_START_LOCAL_WP=1 (see SitePreparationView).
+    @State private var autoOpenLocalWordPress =
+        ProcessInfo.processInfo.environment["GUTENBERG_AUTO_START_LOCAL_WP"] == "1"
+
     @State var configurationToDelete: ConfigurationItem?
     @State private var errorMessage: String?
 
@@ -91,6 +96,9 @@ struct EditorList: View {
         .navigationDestination(isPresented: $showMediaProxyServer) {
             MediaProxyServerView()
         }
+        .navigationDestination(isPresented: $autoOpenLocalWordPress) {
+            SitePreparationView(site: .localWordPress)
+        }
         .navigationTitle("GutenbergKit")
         .toolbar {
             ToolbarItem(placement: .primaryAction) {

ios/Demo-iOS/Sources/Views/SitePreparationView.swift

@@ -10,6 +10,11 @@ struct SitePreparationView: View {
     @State
     private var viewModel: SitePreparationViewModel
 
+    // Debug automation: start the editor as soon as the configuration is
+    // ready when launched with GUTENBERG_AUTO_START_LOCAL_WP=1.
+    @State
+    private var didAutoStart = false
+
     init(site: ConfigurationItem) {
         self.viewModel = SitePreparationViewModel(configurationItem: site)
     }
@@ -42,6 +47,14 @@ struct SitePreparationView: View {
         .onAppear {
             self.viewModel.startLoading()
         }
+        .onChange(of: viewModel.editorConfiguration) { _, newValue in
+            guard newValue != nil,
+                  !didAutoStart,
+                  ProcessInfo.processInfo.environment["GUTENBERG_AUTO_START_LOCAL_WP"] == "1"
+            else { return }
+            didAutoStart = true
+            viewModel.buildAndLoadConfiguration(navigation: navigation)
+        }
     }
 
     func loadedView(configuration: EditorConfiguration) -> some View {

ios/Sources/GutenbergKit/Sources/EditorLogging.swift

@@ -31,6 +31,9 @@ extension Logger {
 
     /// Logs upload server activity
     static let uploadServer = Logger(subsystem: "GutenbergKit", category: "upload-server")
+
+    /// Logs REST relay activity
+    static let restRelay = Logger(subsystem: "GutenbergKit", category: "rest-relay")
 }
 
 public struct SignpostMonitor: Sendable {

ios/Sources/GutenbergKit/Sources/EditorViewController.swift

@@ -160,6 +160,15 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
     private let lockdownModeMonitor: LockdownModeMonitor
     private var uploadServer: MediaUploadServer?
 
+    /// Whether `uploadServer` was started with a media upload pipeline behind
+    /// it, and so whether its port and token may be advertised to JavaScript.
+    /// See `startUploadServer()`.
+    private var isUploadPipelineEnabled = false
+
+    /// Whether `uploadServer` also hosts the Lockdown Mode REST relay.
+    /// See `RestRelay` and `startUploadServer()`.
+    private var isRestRelayEnabled = false
+
     // MARK: - Private Properties (UI)
 
     /// Progress bar shown during async dependency fetching ("No Dependencies" flow).
@@ -230,6 +239,16 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
         config.preferences.setValue(true, forKey: "allowFileAccessFromFileURLs")
         config.setValue(true, forKey: "allowUniversalAccessFromFileURLs")
 
+        // Debug hook: force Lockdown Mode on this web view so its restrictions
+        // can be reproduced in the Simulator, where the system-wide setting is
+        // unavailable. Debug-only so a release build of a host app cannot have
+        // the editor's transport rerouted by its process environment.
+        #if DEBUG
+        if ProcessInfo.processInfo.environment["GUTENBERG_FORCE_LOCKDOWN_MODE"] == "1" {
+            config.defaultWebpagePreferences.isLockdownModeEnabled = true
+        }
+        #endif
+
         // Set-up communications with the editor.
         config.userContentController.add(controller, name: "editorDelegate")
 
@@ -393,7 +412,8 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
         // Set asset bundle for the URL scheme handler to serve cached plugin/theme assets
         self.bundleProvider.set(bundle: dependencies.assetBundle)
 
-        // Start the local upload server for native media processing
+        // Start the local server for native media processing and, under
+        // Lockdown Mode, the REST relay
         await startUploadServer()
 
         // Build and inject editor configuration as window.GBKit
@@ -428,11 +448,24 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
     /// when it initializes.
     ///
     private func buildEditorConfiguration(dependencies: EditorDependencies) throws -> WKUserScript {
+        // The upload pipeline and the REST relay share one local server, but
+        // each is advertised to JavaScript only when `startUploadServer()`
+        // actually enabled it: routing uploads to a server started without an
+        // uploader behind it would fail every one of them, and `networkProxy`
+        // is only useful under Lockdown Mode.
+        let networkProxyGlobal = isRestRelayEnabled ? uploadServer.map {
+            GBKitGlobal.NetworkProxy(
+                port: Int($0.port),
+                token: $0.token,
+                baseURL: RestRelay.baseURL(port: $0.port)
+            )
+        } : nil
         let gbkitGlobal = try GBKitGlobal(
             configuration: self.configuration,
             dependencies: dependencies,
-            nativeUploadPort: uploadServer.map { Int($0.port) },
-            nativeUploadToken: uploadServer?.token
+            nativeUploadPort: isUploadPipelineEnabled ? uploadServer.map { Int($0.port) } : nil,
+            nativeUploadToken: isUploadPipelineEnabled ? uploadServer?.token : nil,
+            networkProxy: networkProxyGlobal
         )
         let stringValue = try gbkitGlobal.toString()
 
@@ -450,6 +483,15 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
     /// The server binds to localhost on a random port. If it fails to start, the editor
     /// falls back to Gutenberg's default upload behavior (the JS override won't activate
     /// because `nativeUploadPort` will be nil in GBKit).
+    ///
+    /// The same server hosts the Lockdown Mode REST relay: when the web view
+    /// is subject to Lockdown Mode, its `file://` page loses the CORS
+    /// exemption and WordPress rejects its `Origin: file://`, so the editor
+    /// sends every site REST request through this server (see `RestRelay`).
+    /// The relay is the transport, not a fallback — it is advertised only when
+    /// a direct request cannot work, so there is no direct attempt to retry
+    /// from. If this server fails to start, `networkProxy` stays nil and the
+    /// web view keeps its direct (possibly broken) network path.
     private func startUploadServer() async {
         // A delegate that was provided but is already nil here was deallocated before
         // the editor finished loading — the host didn't hold a strong reference to it.
@@ -459,31 +501,34 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
             "mediaUploadDelegate was released before the editor loaded — hold a strong reference to it."
         )
 
-        guard mediaUploadDelegate != nil else {
-            return
-        }
-
         // The native upload server relays through DefaultMediaUploader, which needs a
         // site root and an auth header (every host provides one — the editor injects
         // it because the WebView has no auth cookies). Without both there is nothing
-        // to upload through, so leave the server down and let uploads fall to the
-        // default WebView path rather than start a server that could only fail.
-        guard !configuration.authHeader.isEmpty else {
+        // to upload through, so leave the upload pipeline down and let uploads fall
+        // to the default WebView path rather than start a pipeline that could only fail.
+        isUploadPipelineEnabled = mediaUploadDelegate != nil && !configuration.authHeader.isEmpty
+        isRestRelayEnabled = webView.configuration.defaultWebpagePreferences.isLockdownModeEnabled
+            && !configuration.isOfflineModeEnabled
+
+        guard isUploadPipelineEnabled || isRestRelayEnabled else {
             return
         }
 
-        let defaultUploader = DefaultMediaUploader(
+        let defaultUploader = isUploadPipelineEnabled ? DefaultMediaUploader(
             httpClient: httpClient.uploadClient(),
             siteApiRoot: configuration.siteApiRoot,
             siteApiNamespace: configuration.siteApiNamespace
-        )
+        ) : nil
 
         do {
             self.uploadServer = try await MediaUploadServer.start(
-                uploadDelegate: mediaUploadDelegate,
-                defaultUploader: defaultUploader
+                uploadDelegate: isUploadPipelineEnabled ? mediaUploadDelegate : nil,
+                defaultUploader: defaultUploader,
+                restRelay: isRestRelayEnabled ? RestRelay(configuration: configuration) : nil
             )
         } catch {
+            isUploadPipelineEnabled = false
+            isRestRelayEnabled = false
             Logger.uploadServer.error("Failed to start upload server: \(error). Falling back to default upload behavior.")
         }
     }

ios/Sources/GutenbergKit/Sources/Media/MediaUploadServer.swift

@@ -26,16 +26,35 @@ final class MediaUploadServer: Sendable {
     /// Exposed so tests can await completion. (Mirrors Android's `cleanupJob`.)
     let cleanupTask: Task<Void, Never>
 
+    /// The concurrent connection ceiling for the local server.
+    ///
+    /// The library's default of 5 suits a server that only ever receives one
+    /// upload at a time. This one also carries every REST request the editor
+    /// makes under Lockdown Mode (see ``RestRelay``), and editor boot fans out
+    /// well past five: each connection serves exactly one request
+    /// (`Connection: close`), and a connection past the limit is closed
+    /// immediately, surfacing in JavaScript as an unretried `fetch_error`.
+    /// WebKit caps its own concurrency per host well below this, so the ceiling
+    /// exists to bound a runaway, not to schedule normal traffic.
+    static let maxConnections = 32
+
     /// Creates and starts a new upload server.
     ///
     /// - Parameters:
     ///   - uploadDelegate: Optional delegate for customizing file processing and upload.
     ///   - defaultUploader: Fallback uploader used when no delegate provides `uploadFile`.
+    ///   - restRelay: Optional ``RestRelay``. When present, this server also
+    ///     answers the relay's route, becoming the transport for every REST
+    ///     request the editor makes under iOS Lockdown Mode — which is what
+    ///     `GBKit.networkProxy` advertises to the web view. When `nil`, the
+    ///     server serves only the upload route and the editor calls the site
+    ///     directly.
     ///   - maxRequestBodySize: The maximum allowed request body size in bytes.
     ///     Requests exceeding this limit receive a 413 response. Defaults to 4 GB.
     static func start(
         uploadDelegate: (any MediaUploadDelegate)? = nil,
         defaultUploader: DefaultMediaUploader? = nil,
+        restRelay: RestRelay? = nil,
         maxRequestBodySize: Int64 = HTTPRequestParser.defaultMaxBodySize
     ) async throws -> MediaUploadServer {
         // Sweep temp files orphaned by a prior crash, off the editor-startup
@@ -45,7 +64,7 @@ final class MediaUploadServer: Sendable {
             cleanOrphanedUploads()
         }
 
-        let context = UploadContext(uploadDelegate: uploadDelegate, defaultUploader: defaultUploader)
+        let context = UploadContext(uploadDelegate: uploadDelegate, defaultUploader: defaultUploader, restRelay: restRelay)
 
         // A generous ceiling for receiving the upload body. The body read is
         // primarily bounded by the per-read idle timeout (which reaps a stalled
@@ -58,7 +77,11 @@ final class MediaUploadServer: Sendable {
         let server = try await HTTPServer.start(
             name: "media-upload",
             requiresAuthentication: true,
+            // The editor web view is this server's only legitimate client, and
+            // every request it makes carries these headers.
+            requiresBrowserOrigin: true,
             maxRequestBodySize: maxRequestBodySize,
+            maxConnections: maxConnections,
             bodyReadTimeout: bodyReadTimeout,
             cors: .permissive,
             delegate: ServerDelegate(),
@@ -87,6 +110,13 @@ final class MediaUploadServer: Sendable {
     private static func handleRequest(_ request: HTTPServer.Request, context: UploadContext) async -> HTTPResponse {
         let parsed = request.parsed
 
+        // REST relay route: `/proxy/…` requests are forwarded to the site's REST
+        // API (Lockdown Mode support), the path after the route resolving
+        // against the site API root.
+        if let restRelay = context.restRelay, RestRelay.handles(parsed) {
+            return await restRelay.handle(request)
+        }
+
         // Route: only POST /upload is handled. (OPTIONS preflight is answered by
         // the HTTP library under its permissive CORS policy.) Match on the path
         // alone — the target carries a query string (e.g. `?_embed`) that the
@@ -281,23 +311,20 @@ final class MediaUploadServer: Sendable {
     }
 
     private static func errorResponse(status: Int, message: String) -> HTTPResponse {
-        // Emit a WordPress-REST-style error object so the JS middleware normalizes
-        // it (and surfaces `message`) the same way it does a relayed WordPress
-        // error — the local server's own errors need no special-casing.
-        let payload = ["code": "upload_error", "message": message]
-        let body = (try? JSONSerialization.data(withJSONObject: payload))
-            ?? Data(#"{"code":"upload_error","message":"Upload failed"}"#.utf8)
-        return HTTPResponse(
-            status: status,
-            headers: [("Content-Type", "application/json")],
-            body: body
-        )
+        .wordPressError(status: status, code: "upload_error", message: message)
     }
 
-    /// Answers the server's recoverable parse errors (e.g. an over-limit body)
-    /// with the same JSON `{code, message}` shape the editor expects, so the
-    /// middleware surfaces a real message ("The file is too large…") instead of a
-    /// generic parse-failure. A leaf object — the HTTP server retains it.
+    /// Answers the errors the HTTP server raises itself with the same JSON
+    /// `{code, message}` shape the editor expects, so the middleware surfaces a
+    /// real message instead of a generic parse failure.
+    ///
+    /// Every response on this server reaches `@wordpress/api-fetch`, which parses
+    /// all of them as JSON: a `text/plain` refusal arrives as `invalid_json`
+    /// ("The response is not a valid JSON response."), losing the reason. Under
+    /// the relay that covers every REST request the editor makes, so these are
+    /// the failures a user actually sees.
+    ///
+    /// A leaf object — the HTTP server retains it.
     private final class ServerDelegate: HTTPServerDelegate {
         func response(forRecoverableParseError error: HTTPRequestParseError) -> HTTPResponse {
             let message: String = switch error {
@@ -306,6 +333,24 @@ final class MediaUploadServer: Sendable {
             }
             return MediaUploadServer.errorResponse(status: error.httpStatus, message: message)
         }
+
+        func errorBody(for error: HTTPServerError) -> HTTPErrorBody? {
+            let (code, message): (String, String) = switch error {
+            case .authenticationFailed:
+                ("server_unauthorized", "The editor's credential for the local server was missing or stale.")
+            case .forbiddenOrigin:
+                ("server_forbidden_origin", "The local server accepts requests from the editor only.")
+            case .lengthRequired:
+                ("server_length_required", "The request did not declare its content length.")
+            case .unexpectedBody:
+                ("server_unexpected_body", "A preflight request carried a body.")
+            case .readTimeout:
+                ("server_timeout", "The local server timed out before the request finished arriving.")
+            default:
+                ("server_error", error.localizedDescription)
+            }
+            return .wordPressError(code: code, message: message)
+        }
     }
 
     // MARK: - Helpers
@@ -402,8 +447,8 @@ enum UploadError: Error, LocalizedError {
 
 // MARK: - Upload Context
 
-/// Container for the upload delegate and default uploader, captured by the
-/// HTTPServer handler closure and re-read on each request.
+/// Container for the upload delegate, default uploader, and REST relay,
+/// captured by the HTTPServer handler closure and re-read on each request.
 ///
 /// The delegate is held **weakly**. `EditorViewController.mediaUploadDelegate` is
 /// declared `weak` — the host owns the delegate's lifetime. Capturing it strongly
@@ -417,10 +462,12 @@ enum UploadError: Error, LocalizedError {
 private final class UploadContext: @unchecked Sendable {
     weak var uploadDelegate: (any MediaUploadDelegate)?
     let defaultUploader: DefaultMediaUploader?
+    let restRelay: RestRelay?
 
-    init(uploadDelegate: (any MediaUploadDelegate)?, defaultUploader: DefaultMediaUploader?) {
+    init(uploadDelegate: (any MediaUploadDelegate)?, defaultUploader: DefaultMediaUploader?, restRelay: RestRelay?) {
         self.uploadDelegate = uploadDelegate
         self.defaultUploader = defaultUploader
+        self.restRelay = restRelay
     }
 }