diff --git a/cmd_ui.go b/cmd_ui.go
index 412084339..dd5c31be5 100644
--- a/cmd_ui.go
+++ b/cmd_ui.go
@@ -1,46 +1,38 @@
 package main
 
 import (
-	"bytes"
-	"encoding/base64"
+	"context"
 	"encoding/json"
 	"fmt"
 	"io"
-	"net/http"
-	"net/url"
 	"os"
-	"path"
 	"strconv"
 	"strings"
 	"time"
 
+	"github.com/danielpaulus/go-ios/ios/uidriver"
 	"github.com/docopt/docopt-go"
 )
 
 const (
-	defaultUIDriver      = "devicekit"
-	defaultWDAURL        = "http://127.0.0.1:8100"
-	defaultDeviceKitURL  = "http://127.0.0.1:12004"
-	uiDriverWDA          = "wda"
-	uiDriverDeviceKit    = "devicekit"
-	uiDriverAuto         = "auto"
-	deviceKitRPCProtocol = "2.0"
+	defaultUIDriver     = "devicekit"
+	defaultWDAURL       = uidriver.DefaultWDAURL
+	defaultDeviceKitURL = uidriver.DefaultDeviceKitURL
+	uiDriverWDA         = "wda"
+	uiDriverDeviceKit   = "devicekit"
+	uiDriverAuto        = "auto"
 )
 
+// uiClient wires the CLI arguments to a reusable uidriver.Driver. Argument
+// parsing, backend resolution and output formatting live here; all HTTP work
+// is delegated to the ios/uidriver package.
 type uiClient struct {
 	driver       string
 	wdaURL       string
 	deviceKitURL string
-	httpClient   *http.Client
 	sessionID    string
 }
 
-type uiHTTPResponse struct {
-	StatusCode int
-	Header     http.Header
-	Body       []byte
-}
-
 func runUICommand(ctx commandContext) {
 	if boolArg(ctx.Args, "download") {
 		runUIDownloadCommand(ctx)
@@ -51,26 +43,26 @@ func runUICommand(ctx commandContext) {
 
 	switch {
 	case boolArg(ctx.Args, "status"):
-		client.printStatus()
+		printUIResponse(client.driverOrExit().Status())
 	case boolArg(ctx.Args, "api") || boolArg(ctx.Args, "raw"):
 		client.api(ctx)
 	case boolArg(ctx.Args, "tap"):
-		client.tap(requiredIntArg(ctx.Args, "--x"), requiredIntArg(ctx.Args, "--y"))
+		printUIResponse(client.driverOrExit().Tap(requiredIntArg(ctx.Args, "--x"), requiredIntArg(ctx.Args, "--y")))
 	case boolArg(ctx.Args, "swipe"):
-		client.swipe(
+		printUIResponse(client.driverOrExit().Swipe(
 			requiredIntArg(ctx.Args, "--from-x"),
 			requiredIntArg(ctx.Args, "--from-y"),
 			requiredIntArg(ctx.Args, "--to-x"),
 			requiredIntArg(ctx.Args, "--to-y"),
 			optionalFloatArg(ctx.Args, "--duration", 0),
-		)
+		))
 	case boolArg(ctx.Args, "longpress"):
-		client.longPress(requiredIntArg(ctx.Args, "--x"), requiredIntArg(ctx.Args, "--y"), optionalFloatArg(ctx.Args, "--duration", 1))
+		printUIResponse(client.driverOrExit().LongPress(requiredIntArg(ctx.Args, "--x"), requiredIntArg(ctx.Args, "--y"), optionalFloatArg(ctx.Args, "--duration", 1)))
 	case boolArg(ctx.Args, "type"):
-		client.typeText(requiredStringArg(ctx.Args, "--text"))
+		printUIResponse(client.driverOrExit().Type(requiredStringArg(ctx.Args, "--text")))
 	case boolArg(ctx.Args, "button"):
 		button, _ := ctx.Args.String("<button>")
-		client.button(button)
+		printUIResponse(client.driverOrExit().PressButton(button))
 	case boolArg(ctx.Args, "screenshot"):
 		output, _ := ctx.Args.String("--output")
 		client.screenshot(output)
@@ -78,7 +70,7 @@ func runUICommand(ctx commandContext) {
 		output, _ := ctx.Args.String("--output")
 		client.source(output)
 	case boolArg(ctx.Args, "size"):
-		client.size()
+		printUIResponse(client.driverOrExit().WindowSize())
 	case boolArg(ctx.Args, "orientation"):
 		client.orientation(ctx)
 	case boolArg(ctx.Args, "app"):
@@ -113,123 +105,70 @@ func newUIClient(args docopt.Opts) uiClient {
 		deviceKitURL = defaultDeviceKitURL
 	}
 	sessionID, _ := args.String("--session-id")
-	client := uiClient{
+	return uiClient{
 		driver:       driver,
 		wdaURL:       strings.TrimRight(wdaURL, "/"),
 		deviceKitURL: strings.TrimRight(deviceKitURL, "/"),
-		httpClient:   &http.Client{Timeout: 60 * time.Second},
 		sessionID:    sessionID,
 	}
-	client.resolveDriver()
-	return client
 }
 
-func (c *uiClient) resolveDriver() {
+// resolveBackend maps the CLI --driver value (wda/devicekit/auto) to a concrete
+// uidriver.Backend and its base URL, probing health for the auto mode.
+func (c uiClient) resolveBackend() (uidriver.Backend, string) {
 	switch c.driver {
-	case uiDriverWDA, uiDriverDeviceKit:
-		return
+	case uiDriverWDA:
+		return uidriver.BackendWDA, c.wdaURL
+	case uiDriverDeviceKit:
+		return uidriver.BackendDeviceKit, c.deviceKitURL
 	case uiDriverAuto:
-		if c.deviceKitHealthy() {
-			c.driver = uiDriverDeviceKit
-			return
+		if d, err := uidriver.New(uidriver.BackendDeviceKit, c.deviceKitURL); err == nil && d.Healthy() {
+			return uidriver.BackendDeviceKit, c.deviceKitURL
 		}
-		if c.wdaHealthy() {
-			c.driver = uiDriverWDA
-			return
+		if d, err := uidriver.New(uidriver.BackendWDA, c.wdaURL); err == nil && d.Healthy() {
+			return uidriver.BackendWDA, c.wdaURL
 		}
 		logFatal("no UI automation backend reachable; start DeviceKit on 127.0.0.1:12004 or WDA on 127.0.0.1:8100, or pass --driver and --*-url")
+		return "", ""
 	default:
 		logFatal("unknown --driver: " + c.driver)
+		return "", ""
 	}
 }
 
-func (c uiClient) printStatus() {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitHTTP(http.MethodGet, "/health", nil))
-	case uiDriverWDA:
-		printUIResponse(c.wdaHTTP(http.MethodGet, "/status", nil))
-	}
-}
-
-func (c *uiClient) api(ctx commandContext) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		methodName := requiredStringArg(ctx.Args, "--rpc-method")
-		params := rawParamsFromArgs(ctx)
-		printUIResponse(c.deviceKitRPC(methodName, params))
-	case uiDriverWDA:
+// driverOrExit builds a uidriver.Driver for the resolved backend or exits on error.
+func (c uiClient) driverOrExit() *uidriver.Driver {
+	backend, baseURL := c.resolveBackend()
+	opts := []uidriver.Option{uidriver.WithTimeout(60 * time.Second)}
+	if c.sessionID != "" {
+		opts = append(opts, uidriver.WithSessionID(c.sessionID))
+	}
+	d, err := uidriver.New(backend, baseURL, opts...)
+	exitIfError("failed creating ui driver", err)
+	return d
+}
+
+func (c uiClient) api(ctx commandContext) {
+	d := c.driverOrExit()
+	switch d.Backend() {
+	case uidriver.BackendDeviceKit:
+		printUIResponse(d.API(uidriver.APIRequest{
+			RPCMethod: requiredStringArg(ctx.Args, "--rpc-method"),
+			RPCParams: rawParamsFromArgs(ctx),
+		}))
+	case uidriver.BackendWDA:
 		method, _ := ctx.Args.String("--method")
-		if method == "" {
-			method = http.MethodGet
-		}
-		httpPath := requiredStringArg(ctx.Args, "--http-path")
-		body := requestBodyFromArgs(ctx)
-		printUIResponse(c.wdaHTTP(strings.ToUpper(method), httpPath, body))
-	}
-}
-
-func (c *uiClient) tap(x, y int) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.io.tap", map[string]interface{}{"x": x, "y": y}))
-	case uiDriverWDA:
-		printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "wda", "tap", strconv.Itoa(x), strconv.Itoa(y)), nil))
-	}
-}
-
-func (c *uiClient) swipe(fromX, fromY, toX, toY int, duration float64) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.io.swipe", map[string]interface{}{"fromX": fromX, "fromY": fromY, "toX": toX, "toY": toY, "duration": duration}))
-	case uiDriverWDA:
-		body := map[string]interface{}{"fromX": fromX, "fromY": fromY, "toX": toX, "toY": toY, "duration": duration}
-		printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "wda", "dragfromtoforduration"), mustJSON(body)))
-	}
-}
-
-func (c *uiClient) longPress(x, y int, duration float64) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.io.longpress", map[string]interface{}{"x": x, "y": y, "duration": duration}))
-	case uiDriverWDA:
-		body := map[string]interface{}{"x": x, "y": y, "duration": duration}
-		printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "wda", "touchAndHold"), mustJSON(body)))
+		printUIResponse(d.API(uidriver.APIRequest{
+			Method: method,
+			Path:   requiredStringArg(ctx.Args, "--http-path"),
+			Body:   requestBodyFromArgs(ctx),
+		}))
 	}
 }
 
-func (c *uiClient) typeText(text string) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.io.text", map[string]interface{}{"text": text}))
-	case uiDriverWDA:
-		printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "keys"), mustJSON(textBody(text))))
-	}
-}
-
-func (c *uiClient) button(button string) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.io.button", map[string]interface{}{"button": button}))
-	case uiDriverWDA:
-		if strings.EqualFold(button, "home") {
-			printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "wda", "homescreen"), nil))
-			return
-		}
-		logFatal("WDA only supports the home button through this command; use --driver=devicekit for lock/volume buttons")
-	}
-}
-
-func (c *uiClient) screenshot(output string) {
-	var image []byte
-	switch c.driver {
-	case uiDriverDeviceKit:
-		resp := c.deviceKitRPC("device.screenshot", map[string]interface{}{})
-		image = decodeBase64Response(resp.Body)
-	case uiDriverWDA:
-		resp := c.wdaHTTP(http.MethodGet, wdaPath("session", c.wdaSession(), "screenshot"), nil)
-		image = decodeBase64Response(resp.Body)
-	}
+func (c uiClient) screenshot(output string) {
+	image, err := c.driverOrExit().Screenshot()
+	exitIfError("failed capturing screenshot", err)
 	if output == "" || output == "-" {
 		_, err := os.Stdout.Write(image)
 		exitIfError("failed writing screenshot", err)
@@ -238,56 +177,33 @@ func (c *uiClient) screenshot(output string) {
 	exitIfError("failed writing screenshot", os.WriteFile(output, image, 0644))
 }
 
-func (c *uiClient) source(output string) {
-	var resp uiHTTPResponse
-	switch c.driver {
-	case uiDriverDeviceKit:
-		resp = c.deviceKitRPC("device.dump.ui", map[string]interface{}{})
-	case uiDriverWDA:
-		resp = c.wdaHTTP(http.MethodGet, wdaPath("session", c.wdaSession(), "source"), nil)
-	}
-	writeOrPrintResponse(resp, output)
-}
-
-func (c *uiClient) size() {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.info", map[string]interface{}{}))
-	case uiDriverWDA:
-		printUIResponse(c.wdaHTTP(http.MethodGet, wdaPath("session", c.wdaSession(), "window", "size"), nil))
-	}
+func (c uiClient) source(output string) {
+	resp, err := c.driverOrExit().Source()
+	writeOrPrintResponse(resp, err, output)
 }
 
-func (c *uiClient) orientation(ctx commandContext) {
-	switch {
-	case boolArg(ctx.Args, "set"):
+func (c uiClient) orientation(ctx commandContext) {
+	d := c.driverOrExit()
+	if boolArg(ctx.Args, "set") {
 		orientation, _ := ctx.Args.String("<orientation>")
 		if orientation == "" {
 			orientation = requiredStringArg(ctx.Args, "--orientation")
 		}
-		switch c.driver {
-		case uiDriverDeviceKit:
-			printUIResponse(c.deviceKitRPC("device.io.orientation.set", map[string]interface{}{"orientation": orientation}))
-		case uiDriverWDA:
-			printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "orientation"), mustJSON(map[string]string{"orientation": orientation})))
-		}
-	default:
-		switch c.driver {
-		case uiDriverDeviceKit:
-			printUIResponse(c.deviceKitRPC("device.io.orientation.get", map[string]interface{}{}))
-		case uiDriverWDA:
-			printUIResponse(c.wdaHTTP(http.MethodGet, wdaPath("session", c.wdaSession(), "orientation"), nil))
-		}
+		printUIResponse(d.SetOrientation(orientation))
+		return
 	}
+	printUIResponse(d.Orientation())
 }
 
-func (c *uiClient) app(ctx commandContext) {
+func (c uiClient) app(ctx commandContext) {
+	d := c.driverOrExit()
 	switch {
 	case boolArg(ctx.Args, "foreground"):
-		if c.driver != uiDriverDeviceKit {
+		resp, err := d.AppForeground()
+		if err == uidriver.ErrForegroundUnsupported {
 			logFatal("app foreground is only available with --driver=devicekit")
 		}
-		printUIResponse(c.deviceKitRPC("device.apps.foreground", map[string]interface{}{}))
+		printUIResponse(resp, err)
 	default:
 		bundleID, _ := ctx.Args.String("<bundleID>")
 		if bundleID == "" {
@@ -295,151 +211,50 @@ func (c *uiClient) app(ctx commandContext) {
 		}
 		switch {
 		case boolArg(ctx.Args, "launch"):
-			c.appWithBundleID("launch", bundleID)
+			printUIResponse(d.AppLaunch(bundleID))
 		case boolArg(ctx.Args, "terminate"):
-			c.appWithBundleID("terminate", bundleID)
+			printUIResponse(d.AppTerminate(bundleID))
 		default:
 			logFatal("unknown ui app command")
 		}
 	}
 }
 
-func (c *uiClient) appWithBundleID(action string, bundleID string) {
-	switch c.driver {
-	case uiDriverDeviceKit:
-		printUIResponse(c.deviceKitRPC("device.apps."+action, map[string]interface{}{"bundleId": bundleID}))
-	case uiDriverWDA:
-		printUIResponse(c.wdaHTTP(http.MethodPost, wdaPath("session", c.wdaSession(), "wda", "apps", action), mustJSON(map[string]string{"bundleId": bundleID})))
-	}
-}
-
-func (c *uiClient) stream(ctx commandContext) {
-	streamType := "mjpeg"
-	if boolArg(ctx.Args, "h264") {
-		streamType = "h264"
-	}
-	query := url.Values{}
-	addQueryArg(ctx.Args, query, "--fps", "fps")
-	addQueryArg(ctx.Args, query, "--quality", "quality")
-	addQueryArg(ctx.Args, query, "--scale", "scale")
-	addQueryArg(ctx.Args, query, "--bitrate", "bitrate")
-	endpoint := "/" + streamType
-	if encoded := query.Encode(); encoded != "" {
-		endpoint += "?" + encoded
-	}
-	switch c.driver {
-	case uiDriverDeviceKit:
-		c.pipeHTTP(c.deviceKitURL + endpoint)
-	case uiDriverWDA:
-		if streamType != "mjpeg" {
-			logFatal("WDA stream supports mjpeg only; use --driver=devicekit for h264")
-		}
-		c.pipeHTTP(c.wdaURL + endpoint)
-	}
-}
-
-func (c *uiClient) wdaSession() string {
-	if c.sessionID != "" {
-		return c.sessionID
-	}
-	resp := c.wdaHTTP(http.MethodPost, "/session", mustJSON(map[string]interface{}{
-		"capabilities":        map[string]interface{}{},
-		"desiredCapabilities": map[string]interface{}{},
-	}))
-	sessionID := extractSessionID(resp.Body)
-	if sessionID == "" {
-		logFatal("WDA did not return a session id")
-	}
-	c.sessionID = sessionID
-	return sessionID
-}
-
-func (c uiClient) deviceKitHealthy() bool {
-	resp, err := c.httpClient.Get(c.deviceKitURL + "/health")
-	if err != nil {
-		return false
-	}
-	defer func() { _ = resp.Body.Close() }()
-	return resp.StatusCode >= 200 && resp.StatusCode < 300
-}
-
-func (c uiClient) wdaHealthy() bool {
-	resp, err := c.httpClient.Get(c.wdaURL + "/status")
-	if err != nil {
-		return false
-	}
-	defer func() { _ = resp.Body.Close() }()
-	return resp.StatusCode >= 200 && resp.StatusCode < 300
-}
-
-func (c uiClient) deviceKitRPC(method string, params interface{}) uiHTTPResponse {
-	body := mustJSON(map[string]interface{}{
-		"jsonrpc": deviceKitRPCProtocol,
-		"method":  method,
-		"params":  params,
-		"id":      1,
-	})
-	return c.deviceKitHTTP(http.MethodPost, "/rpc", body)
-}
-
-func (c uiClient) deviceKitHTTP(method string, endpoint string, body []byte) uiHTTPResponse {
-	return c.doHTTP(method, c.deviceKitURL, endpoint, body)
-}
-
-func (c uiClient) wdaHTTP(method string, endpoint string, body []byte) uiHTTPResponse {
-	return c.doHTTP(method, c.wdaURL, endpoint, body)
-}
-
-func (c uiClient) doHTTP(method string, baseURL string, endpoint string, body []byte) uiHTTPResponse {
-	if !strings.HasPrefix(endpoint, "/") {
-		endpoint = "/" + endpoint
+func (c uiClient) stream(ctx commandContext) {
+	d := c.driverOrExit()
+	opts := uidriver.StreamOptions{H264: boolArg(ctx.Args, "h264")}
+	opts.FPS, _ = ctx.Args.String("--fps")
+	opts.Quality, _ = ctx.Args.String("--quality")
+	opts.Scale, _ = ctx.Args.String("--scale")
+	opts.Bitrate, _ = ctx.Args.String("--bitrate")
+	body, err := d.Stream(context.Background(), opts)
+	if err == uidriver.ErrStreamUnsupported {
+		logFatal("WDA stream supports mjpeg only; use --driver=devicekit for h264")
 	}
-	req, err := http.NewRequest(method, baseURL+endpoint, bytes.NewReader(body))
-	exitIfError("failed creating UI request", err)
-	req.Header.Set("Accept", "application/json")
-	if len(body) > 0 {
-		req.Header.Set("Content-Type", "application/json")
-	}
-	resp, err := c.httpClient.Do(req)
-	exitIfError("UI request failed", err)
-	defer func() { _ = resp.Body.Close() }()
-	respBody, err := io.ReadAll(resp.Body)
-	exitIfError("failed reading UI response", err)
-	if resp.StatusCode < 200 || resp.StatusCode > 299 {
-		fmt.Fprintln(os.Stderr, string(respBody))
-		os.Exit(1)
-	}
-	return uiHTTPResponse{StatusCode: resp.StatusCode, Header: resp.Header, Body: respBody}
-}
-
-func (c uiClient) pipeHTTP(rawURL string) {
-	resp, err := c.httpClient.Get(rawURL)
 	exitIfError("stream request failed", err)
-	defer func() { _ = resp.Body.Close() }()
-	if resp.StatusCode < 200 || resp.StatusCode > 299 {
-		body, _ := io.ReadAll(resp.Body)
-		fmt.Fprintln(os.Stderr, string(body))
-		os.Exit(1)
-	}
-	_, err = io.Copy(os.Stdout, resp.Body)
+	defer func() { _ = body.Close() }()
+	_, err = io.Copy(os.Stdout, body)
 	exitIfError("stream copy failed", err)
 }
 
-func printUIResponse(resp uiHTTPResponse) {
+// printUIResponse pretty-prints a driver response, exiting on a non-nil error.
+func printUIResponse(resp uidriver.Response, err error) {
+	exitIfError("ui request failed", err)
 	if len(resp.Body) == 0 {
 		return
 	}
 	var data interface{}
-	if err := json.Unmarshal(resp.Body, &data); err != nil {
+	if uerr := json.Unmarshal(resp.Body, &data); uerr != nil {
 		fmt.Print(string(resp.Body))
 		return
 	}
 	fmt.Println(convertToJSONString(data))
 }
 
-func writeOrPrintResponse(resp uiHTTPResponse, output string) {
+func writeOrPrintResponse(resp uidriver.Response, err error, output string) {
+	exitIfError("ui request failed", err)
 	if output == "" || output == "-" {
-		printUIResponse(resp)
+		printUIResponse(resp, nil)
 		return
 	}
 	exitIfError("failed writing output", os.WriteFile(output, resp.Body, 0644))
@@ -481,17 +296,6 @@ func rawParamsFromArgs(ctx commandContext) interface{} {
 	return decoded
 }
 
-func textBody(text string) map[string]interface{} {
-	return map[string]interface{}{
-		"text":  text,
-		"value": []string{text},
-	}
-}
-
-func wdaPath(parts ...string) string {
-	return "/" + path.Join(parts...)
-}
-
 func requiredStringArg(args docopt.Opts, name string) string {
 	value, _ := args.String(name)
 	if value == "" {
@@ -517,69 +321,3 @@ func optionalFloatArg(args docopt.Opts, name string, fallback float64) float64 {
 	exitIfError("failed parsing "+name, err)
 	return floatValue
 }
-
-func mustJSON(data interface{}) []byte {
-	body, err := json.Marshal(data)
-	exitIfError("failed encoding UI request body", err)
-	return body
-}
-
-func decodeBase64Response(body []byte) []byte {
-	encoded := findBase64Value(body)
-	if encoded == "" {
-		logFatal("response did not contain a base64 image")
-	}
-	image, err := base64.StdEncoding.DecodeString(encoded)
-	exitIfError("failed decoding base64 image", err)
-	return image
-}
-
-func findBase64Value(body []byte) string {
-	var decoded interface{}
-	if err := json.Unmarshal(body, &decoded); err != nil {
-		return ""
-	}
-	return findBase64String(decoded)
-}
-
-func findBase64String(value interface{}) string {
-	switch typed := value.(type) {
-	case string:
-		return typed
-	case map[string]interface{}:
-		for _, key := range []string{"value", "result", "image", "screenshot", "data"} {
-			if nested, ok := typed[key]; ok {
-				if result := findBase64String(nested); result != "" {
-					return result
-				}
-			}
-		}
-	}
-	return ""
-}
-
-func extractSessionID(body []byte) string {
-	var decoded map[string]interface{}
-	if err := json.Unmarshal(body, &decoded); err != nil {
-		return ""
-	}
-	if sessionID, ok := decoded["sessionId"].(string); ok {
-		return sessionID
-	}
-	if value, ok := decoded["value"].(map[string]interface{}); ok {
-		if sessionID, ok := value["sessionId"].(string); ok {
-			return sessionID
-		}
-		if sessionID, ok := value["session_id"].(string); ok {
-			return sessionID
-		}
-	}
-	return ""
-}
-
-func addQueryArg(args docopt.Opts, query url.Values, argName string, queryName string) {
-	value, _ := args.String(argName)
-	if value != "" {
-		query.Set(queryName, value)
-	}
-}
diff --git a/go.work.sum b/go.work.sum
index ad68472f2..137bb0bcd 100644
--- a/go.work.sum
+++ b/go.work.sum
@@ -55,6 +55,7 @@ github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da h1:oI5xCqsCo564l
 github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=
 github.com/golang/mock v1.7.0-rc.1 h1:YojYx61/OLFsiv6Rw1Z96LpldJIy31o+UHmwAUMJ6/U=
 github.com/golang/mock v1.7.0-rc.1/go.mod h1:s42URUywIqd+OcERslBJvOjepvNymP31m3q8d/GkuRs=
+github.com/golang/protobuf v1.5.3/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
 github.com/google/btree v1.0.1/go.mod h1:xXMiIv4Fb/0kKde4SpL7qlzvu5cMJDRkFDxJfI9uaxA=
 github.com/google/go-github/v56 v56.0.0 h1:TysL7dMa/r7wsQi44BjqlwaHvwlFlqkK8CtBWCX3gb4=
 github.com/google/go-github/v56 v56.0.0/go.mod h1:D8cdcX98YWJvi7TLo7zM4/h8ZTx6u6fwGEkCdisopo0=
diff --git a/ios/instruments/screenshot.go b/ios/instruments/screenshot.go
index cd821742e..19971ffc4 100644
--- a/ios/instruments/screenshot.go
+++ b/ios/instruments/screenshot.go
@@ -3,6 +3,7 @@ package instruments
 import (
 	"bufio"
 	"bytes"
+	"context"
 	"fmt"
 	"github.com/danielpaulus/go-ios/ios"
 	dtx "github.com/danielpaulus/go-ios/ios/dtx_codec"
@@ -51,70 +52,100 @@ func (d *ScreenshotService) TakeScreenshot() ([]byte, error) {
 	return imageBytes, nil
 }
 
-// MJPEG server code
-var (
-	consumers       sync.Map
-	conversionQueue = make(chan []byte, 20)
-)
-
-func StartMJPEGStreamingServer(device ios.DeviceEntry, port string) error {
-	conn, err := NewScreenshotService(device)
+// pngToJPEG decodes a PNG frame (as returned by TakeScreenshot) and re-encodes
+// it as JPEG at the given quality. It is the shared conversion step used by both
+// the built-in MJPEG server and any external MJPEG consumer (for example the
+// REST API).
+func pngToJPEG(pngBytes []byte, quality int) ([]byte, error) {
+	img, err := png.Decode(bytes.NewReader(pngBytes))
 	if err != nil {
-		return err
+		return nil, fmt.Errorf("pngToJPEG: decode png: %w", err)
 	}
-	defer conn.Close()
-
-	go startScreenshotting(conn)
-	go startConversionQueue()
-	http.HandleFunc("/", mjpegHandler)
-	location := fmt.Sprintf("0.0.0.0:%s", port)
-	golog.Info("starting server, open your browser here", "module", logModule, "udid", device.Properties.SerialNumber, "host", "0.0.0.0", "port", port, "url", fmt.Sprintf("http://%s/", location))
-	return http.ListenAndServe(location, nil)
+	var b bytes.Buffer
+	w := bufio.NewWriter(&b)
+	if err := jpeg.Encode(w, img, &jpeg.Options{Quality: quality}); err != nil {
+		return nil, fmt.Errorf("pngToJPEG: encode jpeg: %w", err)
+	}
+	if err := w.Flush(); err != nil {
+		return nil, fmt.Errorf("pngToJPEG: flush jpeg: %w", err)
+	}
+	return b.Bytes(), nil
 }
 
-func startConversionQueue() {
-	var opt jpeg.Options
-	opt.Quality = 80
-
+// StreamJPEGFrames is the reusable frame source shared by every MJPEG consumer.
+// It takes screenshots on conn in a loop, converts each PNG to a JPEG frame at
+// the given quality (a quality <= 0 selects the default of 80), and calls emit
+// with the raw JPEG bytes for every frame. The emit callback owns the slice for
+// the duration of the call; it must not retain it across calls.
+//
+// It runs until ctx is canceled or a screenshot/conversion error occurs, then
+// returns. A screenshot error is returned; ctx cancellation returns nil. The
+// caller owns conn and its lifecycle.
+func StreamJPEGFrames(ctx context.Context, conn *ScreenshotService, quality int, emit func([]byte)) error {
+	if quality <= 0 {
+		quality = 80
+	}
 	for {
-		pngBytes := <-conversionQueue
+		if err := ctx.Err(); err != nil {
+			return nil
+		}
 		start := time.Now()
-		img, err := png.Decode(bytes.NewReader(pngBytes))
+		pngBytes, err := conn.TakeScreenshot()
 		if err != nil {
-			golog.Warn("failed decoding png", "module", logModule, "error", err)
-			continue
+			// Stop the streaming loop instead of killing the host process; a
+			// screenshot failure must not take down a caller embedding go-ios.
+			golog.Error("screenshot failed, stopping screenshot loop", "module", logModule, "error", err)
+			return err
 		}
-		var b bytes.Buffer
-		foo := bufio.NewWriter(&b)
-		err = jpeg.Encode(foo, img, &opt)
+		golog.Debug("shot done", "module", logModule, "seconds", time.Since(start).Seconds())
+		jpg, err := pngToJPEG(pngBytes, quality)
 		if err != nil {
-			golog.Warn("failed encoding jpg", "module", logModule, "error", err)
+			golog.Warn("failed converting frame", "module", logModule, "error", err)
 			continue
 		}
-		elapsed := time.Since(start)
-		golog.Debug("conversion done", "module", logModule, "seconds", elapsed.Seconds())
-		consumers.Range(func(key, value interface{}) bool {
-			c := value.(chan []byte)
-			go func() { c <- b.Bytes() }()
-			return true
-		})
+		golog.Debug("conversion done", "module", logModule, "seconds", time.Since(start).Seconds())
+		// Re-check cancellation before emitting so a canceled context does not
+		// push a final frame to a gone consumer.
+		if ctx.Err() != nil {
+			return nil
+		}
+		emit(jpg)
 	}
 }
 
-func startScreenshotting(conn *ScreenshotService) {
-	for {
-		start := time.Now()
-		pngBytes, err := conn.TakeScreenshot()
+// MJPEG server code
+var consumers sync.Map
+
+func StartMJPEGStreamingServer(device ios.DeviceEntry, port string) error {
+	conn, err := NewScreenshotService(device)
+	if err != nil {
+		return err
+	}
+	defer conn.Close()
+
+	// Fan a single frame source out to every connected mjpegHandler consumer,
+	// preserving the previous behavior (one screenshot loop shared by all
+	// clients registered in the consumers map).
+	go func() {
+		err := StreamJPEGFrames(context.Background(), conn, 80, func(jpg []byte) {
+			consumers.Range(func(key, value interface{}) bool {
+				c := value.(chan []byte)
+				// Copy: the callback does not own the slice past the call, and
+				// consumers receive asynchronously.
+				frame := append([]byte(nil), jpg...)
+				go func() { c <- frame }()
+				return true
+			})
+		})
 		if err != nil {
-			// Stop the streaming loop instead of killing the host process; a
-			// screenshot failure must not take down a caller embedding go-ios.
-			golog.Error("screenshot failed, stopping screenshot loop", "module", logModule, "error", err)
-			return
+			golog.Error("mjpeg frame source stopped", "module", logModule, "udid", device.Properties.SerialNumber, "error", err)
 		}
-		elapsed := time.Since(start)
-		golog.Debug("shot done", "module", logModule, "seconds", elapsed.Seconds())
-		conversionQueue <- pngBytes
-	}
+	}()
+
+	http.HandleFunc("/", mjpegHandler)
+	location := fmt.Sprintf("0.0.0.0:%s", port)
+	golog.Info("starting server, open your browser here", "module", logModule, "udid", device.Properties.SerialNumber, "host", "0.0.0.0", "port", port, "url", fmt.Sprintf("http://%s/", location))
+	return http.ListenAndServe(location, nil)
 }
 
 const (
diff --git a/ios/instruments/screenshot_test.go b/ios/instruments/screenshot_test.go
new file mode 100644
index 000000000..1aa87b982
--- /dev/null
+++ b/ios/instruments/screenshot_test.go
@@ -0,0 +1,54 @@
+package instruments
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/jpeg"
+	"image/png"
+	"testing"
+)
+
+// makePNG builds a tiny valid PNG for the conversion tests.
+func makePNG(t *testing.T) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, 4, 4))
+	for x := 0; x < 4; x++ {
+		for y := 0; y < 4; y++ {
+			img.Set(x, y, color.RGBA{R: uint8(x * 40), G: uint8(y * 40), B: 128, A: 255})
+		}
+	}
+	var b bytes.Buffer
+	if err := png.Encode(&b, img); err != nil {
+		t.Fatalf("encode png: %v", err)
+	}
+	return b.Bytes()
+}
+
+// TestPngToJPEG asserts the shared PNG->JPEG conversion step (used by both the
+// built-in MJPEG server and external consumers) produces a decodable JPEG.
+func TestPngToJPEG(t *testing.T) {
+	pngBytes := makePNG(t)
+
+	jpg, err := pngToJPEG(pngBytes, 80)
+	if err != nil {
+		t.Fatalf("pngToJPEG: %v", err)
+	}
+	if len(jpg) == 0 {
+		t.Fatal("pngToJPEG returned no bytes")
+	}
+	img, err := jpeg.Decode(bytes.NewReader(jpg))
+	if err != nil {
+		t.Fatalf("output is not valid jpeg: %v", err)
+	}
+	if img.Bounds().Dx() != 4 || img.Bounds().Dy() != 4 {
+		t.Fatalf("unexpected jpeg bounds: %v", img.Bounds())
+	}
+}
+
+// TestPngToJPEGRejectsGarbage asserts a non-PNG input errors instead of panicking.
+func TestPngToJPEGRejectsGarbage(t *testing.T) {
+	if _, err := pngToJPEG([]byte("not a png"), 80); err == nil {
+		t.Fatal("expected error decoding non-png input")
+	}
+}
diff --git a/ios/pcap/pcap.go b/ios/pcap/pcap.go
index eecd69d9b..b1455d3d0 100644
--- a/ios/pcap/pcap.go
+++ b/ios/pcap/pcap.go
@@ -2,6 +2,7 @@ package pcap
 
 import (
 	"bytes"
+	"context"
 	"fmt"
 	"io"
 	"os"
@@ -55,28 +56,98 @@ func (iph *IOSPacketHeader) ToString() string {
 	return fmt.Sprintf("%v", *iph)
 }
 
+// Start captures network traffic from the device into a pcap file in the
+// current working directory and blocks until the connection fails. It is the
+// entry point used by the `ios pcap` CLI command and keeps its historical
+// behavior; it is implemented on top of the streaming capture core.
 func Start(device ios.DeviceEntry) error {
-	intf, err := ios.ConnectToService(device, "com.apple.pcapd")
-	if err != nil {
-		return err
-	}
-	defer intf.Close()
-	plistCodec := ios.NewPlistCodec()
 	fname := fmt.Sprintf("dump-%d.pcap", time.Now().Unix())
 	if Pid > 0 {
 		fname = fmt.Sprintf("dump-%d-%d.pcap", Pid, time.Now().Unix())
 	} else if ProcName != "" {
 		fname = fmt.Sprintf("dump-%s-%d.pcap", ProcName, time.Now().Unix())
 	}
-	f, err := createPcap(fname)
+	f, err := os.OpenFile(fname, os.O_CREATE|os.O_RDWR|os.O_TRUNC, 0o755)
 	if err != nil {
 		return err
 	}
 	defer f.Close()
 	golog.Info("create pcap file", "module", logModule, "udid", device.Properties.SerialNumber, "path", fname)
+	// The CLI captures until the connection fails (or the process is killed),
+	// so there is no cancellation context to honor here.
+	return Stream(context.Background(), device, f)
+}
+
+// Stream captures network traffic from the device and writes a valid pcap
+// stream (global header followed by per-packet records) to w until ctx is
+// canceled or the connection fails. On cancellation the underlying device
+// connection is closed to unblock the pending read and Stream returns nil,
+// leaving w a valid, finalized pcap stream. It never leaks goroutines.
+func Stream(ctx context.Context, device ios.DeviceEntry, w io.Writer) error {
+	intf, err := ios.ConnectToService(device, "com.apple.pcapd")
+	if err != nil {
+		return err
+	}
+	defer intf.Close()
+	if err := writePcapHeader(w); err != nil {
+		return err
+	}
+	golog.Info("pcap capture started", "module", logModule, "udid", device.Properties.SerialNumber)
+	err = capture(ctx, intf, w)
+	if err != nil {
+		return err
+	}
+	golog.Info("pcap capture stopped", "module", logModule, "udid", device.Properties.SerialNumber)
+	return nil
+}
+
+// captureConn is the subset of ios.DeviceConnectionInterface the capture loop
+// needs. Keeping it small makes the capture core testable against an in-memory
+// fake connection.
+type captureConn interface {
+	Reader() io.Reader
+	Close() error
+}
+
+// capture reads packets from conn and streams pcap records to w until ctx is
+// done or reading fails. When ctx is done, the connection is closed to unblock
+// the pending read and capture returns nil, leaving w a valid pcap stream. A
+// read error that occurs while ctx is still active is surfaced to the caller.
+func capture(ctx context.Context, conn captureConn, w io.Writer) error {
+	done := make(chan struct{})
+	// closedByWatchdog is set (before watchdogDone is closed) only when the
+	// watchdog closed conn because ctx was canceled, so a read error caused by
+	// that close is classified as a clean shutdown rather than a failure.
+	var closedByWatchdog bool
+	watchdogDone := make(chan struct{})
+	go func() {
+		defer close(watchdogDone)
+		select {
+		case <-ctx.Done():
+			closedByWatchdog = true
+			conn.Close()
+		case <-done:
+		}
+	}()
+	// Wait for the watchdog to finish before returning so its conn.Close()
+	// never races the caller's own deferred close of the same connection.
+	defer func() {
+		close(done)
+		<-watchdogDone
+	}()
+	plistCodec := ios.NewPlistCodec()
 	for {
-		b, err := plistCodec.Decode(intf.Reader())
+		b, err := plistCodec.Decode(conn.Reader())
 		if err != nil {
+			// A read error after the watchdog closed conn is the expected way a
+			// canceled capture unblocks; report it as a clean stop. Block on
+			// watchdogDone first so closedByWatchdog is observed race-free.
+			if ctx.Err() != nil {
+				<-watchdogDone
+				if closedByWatchdog {
+					return nil
+				}
+			}
 			return err
 		}
 		decodedBytes, err := fromBytes(b)
@@ -88,7 +159,7 @@ func Start(device ios.DeviceEntry) error {
 			return err
 		}
 		if len(packet) > 0 {
-			err = writePacket(f, iph, packet)
+			err = writePacket(w, iph, packet)
 			if err != nil {
 				return err
 			}
@@ -127,21 +198,17 @@ type PcaprecHdrS struct {
 	OrigLen int `struc:"uint32,little"` /* actual length of packet */
 }
 
-func createPcap(name string) (*os.File, error) {
-	f, err := os.OpenFile(name, os.O_CREATE|os.O_RDWR|os.O_TRUNC, 0o755)
-	if err != nil {
-		return nil, err
-	}
-	// Write `pcap_hdr_s` with little endin to file.
-	f.Write([]byte{
+// writePcapHeader writes the little endian `pcap_hdr_s` global header to w.
+func writePcapHeader(w io.Writer) error {
+	_, err := w.Write([]byte{
 		0xd4, 0xc3, 0xb2, 0xa1, 0x02, 0x00, 0x04, 0x00,
 		0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 		0xff, 0xff, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
 	})
-	return f, nil
+	return err
 }
 
-func writePacket(f *os.File, iph IOSPacketHeader, packet []byte) error {
+func writePacket(w io.Writer, iph IOSPacketHeader, packet []byte) error {
 	phs := &PcaprecHdrS{
 		iph.TsSec,
 		iph.TsUsec,
@@ -153,9 +220,11 @@ func writePacket(f *os.File, iph IOSPacketHeader, packet []byte) error {
 	if err != nil {
 		return err
 	}
-	f.Write(buf.Bytes())
-	f.Write(packet)
-	return nil
+	if _, err := w.Write(buf.Bytes()); err != nil {
+		return err
+	}
+	_, err = w.Write(packet)
+	return err
 }
 
 func getPacket(buf []byte) (iph IOSPacketHeader, packet []byte, err error) {
diff --git a/ios/pcap/pcap_test.go b/ios/pcap/pcap_test.go
new file mode 100644
index 000000000..fa7af91b2
--- /dev/null
+++ b/ios/pcap/pcap_test.go
@@ -0,0 +1,322 @@
+package pcap
+
+import (
+	"bytes"
+	"context"
+	"encoding/binary"
+	"io"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/google/gopacket/pcapgo"
+	"github.com/lunixbochs/struc"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"howett.net/plist"
+)
+
+// fakeDeviceConnection is an in-memory stand-in for the pcapd service
+// connection. Close unblocks a pending Reader() read, like closing a real
+// device connection does.
+type fakeDeviceConnection struct {
+	r *io.PipeReader
+}
+
+func (f *fakeDeviceConnection) Reader() io.Reader { return f.r }
+func (f *fakeDeviceConnection) Close() error      { return f.r.Close() }
+
+func testPacketHeader(payloadLen int) IOSPacketHeader {
+	return IOSPacketHeader{
+		HdrSize:        PacketHeaderSize,
+		Version:        2,
+		PacketSize:     uint32(payloadLen),
+		Type:           1,
+		IO:             1,
+		ProtocolFamily: 2,
+		FramePreLength: 14,
+		IFName:         "en0",
+		Pid:            -1,
+		ProcName:       "testproc",
+		Pid2:           -1,
+		ProcName2:      "testproc",
+		TsSec:          1700000000,
+		TsUsec:         123456,
+	}
+}
+
+// packHeader serializes an IOSPacketHeader the way pcapd does on the wire.
+func packHeader(t *testing.T, iph IOSPacketHeader) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	err := struc.Pack(&buf, &iph)
+	require.NoError(t, err)
+	return buf.Bytes()
+}
+
+// makeFrame builds one full pcapd wire frame: a 4 byte big endian length
+// followed by a binary plist containing header+payload as a data element.
+func makeFrame(t *testing.T, iph IOSPacketHeader, payload []byte) []byte {
+	t.Helper()
+	raw := append(packHeader(t, iph), payload...)
+	plistBytes, err := plist.Marshal(raw, plist.BinaryFormat)
+	require.NoError(t, err)
+	frame := make([]byte, 4, 4+len(plistBytes))
+	binary.BigEndian.PutUint32(frame, uint32(len(plistBytes)))
+	return append(frame, plistBytes...)
+}
+
+func resetFilters(t *testing.T) {
+	t.Helper()
+	t.Cleanup(func() {
+		Pid = int32(-2)
+		ProcName = ""
+	})
+	Pid = int32(-2)
+	ProcName = ""
+}
+
+func TestFromBytes(t *testing.T) {
+	payload := []byte{0xde, 0xad, 0xbe, 0xef}
+	plistBytes, err := plist.Marshal(payload, plist.BinaryFormat)
+	require.NoError(t, err)
+	decoded, err := fromBytes(plistBytes)
+	require.NoError(t, err)
+	assert.Equal(t, payload, decoded)
+
+	_, err = fromBytes([]byte("not a plist"))
+	assert.Error(t, err)
+}
+
+func TestGetPacket(t *testing.T) {
+	resetFilters(t)
+	payload := []byte{0x01, 0x02, 0x03, 0x04, 0x05}
+
+	t.Run("parses header and payload", func(t *testing.T) {
+		iph, packet, err := getPacket(append(packHeader(t, testPacketHeader(len(payload))), payload...))
+		require.NoError(t, err)
+		assert.Equal(t, payload, packet)
+		assert.Equal(t, PacketHeaderSize, iph.HdrSize)
+		assert.Equal(t, int32(-1), iph.Pid)
+		assert.Equal(t, "testproc", trimNull(iph.ProcName))
+		assert.Equal(t, "en0", trimNull(iph.IFName))
+		assert.Equal(t, 1700000000, iph.TsSec)
+		assert.Equal(t, 123456, iph.TsUsec)
+	})
+
+	t.Run("prepends fake ethernet header when FramePreLength is zero", func(t *testing.T) {
+		hdr := testPacketHeader(len(payload))
+		hdr.FramePreLength = 0
+		_, packet, err := getPacket(append(packHeader(t, hdr), payload...))
+		require.NoError(t, err)
+		require.Len(t, packet, len(payload)+14)
+		assert.Equal(t, payload, packet[14:])
+	})
+
+	t.Run("skips extended header bytes (iOS 15 beta4)", func(t *testing.T) {
+		hdr := testPacketHeader(len(payload))
+		hdr.HdrSize = PacketHeaderSize + 4
+		raw := append(packHeader(t, hdr), 0xaa, 0xbb, 0xcc, 0xdd)
+		_, packet, err := getPacket(append(raw, payload...))
+		require.NoError(t, err)
+		assert.Equal(t, payload, packet)
+	})
+
+	t.Run("pid filter drops other pids", func(t *testing.T) {
+		resetFilters(t)
+		Pid = 42
+		_, packet, err := getPacket(append(packHeader(t, testPacketHeader(len(payload))), payload...))
+		require.NoError(t, err)
+		assert.Empty(t, packet)
+
+		hdr := testPacketHeader(len(payload))
+		hdr.Pid = 42
+		_, packet, err = getPacket(append(packHeader(t, hdr), payload...))
+		require.NoError(t, err)
+		assert.Equal(t, payload, packet)
+	})
+
+	t.Run("process name filter drops other processes", func(t *testing.T) {
+		resetFilters(t)
+		ProcName = "other"
+		_, packet, err := getPacket(append(packHeader(t, testPacketHeader(len(payload))), payload...))
+		require.NoError(t, err)
+		assert.Empty(t, packet)
+
+		ProcName = "test"
+		_, packet, err = getPacket(append(packHeader(t, testPacketHeader(len(payload))), payload...))
+		require.NoError(t, err)
+		assert.Equal(t, payload, packet)
+	})
+}
+
+func TestCaptureWritesPacketsUntilCanceled(t *testing.T) {
+	resetFilters(t)
+	payloads := [][]byte{
+		bytes.Repeat([]byte{0x11}, 20),
+		bytes.Repeat([]byte{0x22}, 40),
+		bytes.Repeat([]byte{0x33}, 60),
+	}
+
+	pr, pw := io.Pipe()
+	conn := &fakeDeviceConnection{r: pr}
+	var out bytes.Buffer
+	require.NoError(t, writePcapHeader(&out))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+	captureDone := make(chan error, 1)
+	go func() { captureDone <- capture(ctx, conn, &out) }()
+
+	// io.Pipe writes complete only once capture has consumed the frame.
+	for _, payload := range payloads {
+		_, err := pw.Write(makeFrame(t, testPacketHeader(len(payload)), payload))
+		require.NoError(t, err)
+	}
+	cancel()
+
+	select {
+	case err := <-captureDone:
+		require.NoError(t, err, "capture must return nil on context cancellation")
+	case <-time.After(5 * time.Second):
+		t.Fatal("capture did not stop after context cancellation")
+	}
+
+	// The finalized output must be a valid pcap stream containing every packet.
+	r, err := pcapgo.NewReader(bytes.NewReader(out.Bytes()))
+	require.NoError(t, err, "output is not a valid pcap stream")
+	for i, payload := range payloads {
+		data, ci, err := r.ReadPacketData()
+		require.NoError(t, err, "packet %d missing from pcap output", i)
+		assert.Equal(t, payload, data, "packet %d payload mismatch", i)
+		assert.Equal(t, len(payload), ci.CaptureLength)
+		assert.Equal(t, len(payload), ci.Length)
+		assert.Equal(t, time.Unix(1700000000, 123456*1000).UTC(), ci.Timestamp.UTC())
+	}
+	_, _, err = r.ReadPacketData()
+	assert.ErrorIs(t, err, io.EOF, "pcap output must end cleanly after the captured packets")
+}
+
+func TestCaptureStopsOnDeadline(t *testing.T) {
+	resetFilters(t)
+	pr, pw := io.Pipe()
+	defer pw.Close()
+	conn := &fakeDeviceConnection{r: pr}
+	var out bytes.Buffer
+	require.NoError(t, writePcapHeader(&out))
+
+	ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
+	defer cancel()
+	captureDone := make(chan error, 1)
+	go func() { captureDone <- capture(ctx, conn, &out) }()
+
+	payload := bytes.Repeat([]byte{0x44}, 10)
+	_, err := pw.Write(makeFrame(t, testPacketHeader(len(payload)), payload))
+	require.NoError(t, err)
+	// No more frames arrive; the deadline must stop the blocked read.
+
+	select {
+	case err := <-captureDone:
+		require.NoError(t, err, "capture must return nil on deadline")
+	case <-time.After(5 * time.Second):
+		t.Fatal("capture did not stop on context deadline")
+	}
+
+	r, err := pcapgo.NewReader(bytes.NewReader(out.Bytes()))
+	require.NoError(t, err)
+	data, _, err := r.ReadPacketData()
+	require.NoError(t, err)
+	assert.Equal(t, payload, data)
+	_, _, err = r.ReadPacketData()
+	assert.ErrorIs(t, err, io.EOF)
+}
+
+func TestCaptureReturnsReadErrorWhenNotCanceled(t *testing.T) {
+	resetFilters(t)
+	pr, pw := io.Pipe()
+	conn := &fakeDeviceConnection{r: pr}
+	var out bytes.Buffer
+
+	captureDone := make(chan error, 1)
+	go func() { captureDone <- capture(context.Background(), conn, &out) }()
+	require.NoError(t, pw.CloseWithError(io.ErrUnexpectedEOF))
+
+	select {
+	case err := <-captureDone:
+		require.Error(t, err, "capture must surface connection errors when the context is still active")
+	case <-time.After(5 * time.Second):
+		t.Fatal("capture did not stop on connection error")
+	}
+}
+
+// closeTrackingConn records how often Close is called and blocks in Close
+// until released, so a test can prove capture waits for the watchdog's
+// conn.Close() to finish before returning (no concurrent double-close).
+type closeTrackingConn struct {
+	r        *io.PipeReader
+	release  chan struct{}
+	closes   int32
+	inClose  chan struct{}
+	closedCh chan struct{}
+}
+
+func (c *closeTrackingConn) Reader() io.Reader { return c.r }
+
+func (c *closeTrackingConn) Close() error {
+	if atomic.AddInt32(&c.closes, 1) == 1 {
+		close(c.inClose)
+		<-c.release
+		err := c.r.Close()
+		close(c.closedCh)
+		return err
+	}
+	return c.r.Close()
+}
+
+func TestCaptureWaitsForWatchdogCloseBeforeReturning(t *testing.T) {
+	resetFilters(t)
+	pr, _ := io.Pipe()
+	conn := &closeTrackingConn{
+		r:        pr,
+		release:  make(chan struct{}),
+		inClose:  make(chan struct{}),
+		closedCh: make(chan struct{}),
+	}
+	var out bytes.Buffer
+	require.NoError(t, writePcapHeader(&out))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	captureDone := make(chan error, 1)
+	go func() { captureDone <- capture(ctx, conn, &out) }()
+
+	cancel()
+	// The watchdog is now inside Close, blocked before it finishes.
+	select {
+	case <-conn.inClose:
+	case <-time.After(5 * time.Second):
+		t.Fatal("watchdog did not call Close after cancellation")
+	}
+
+	// capture must not have returned yet: it owns the connection and must wait
+	// for the watchdog's Close to complete so it never races the caller's own
+	// deferred Close.
+	select {
+	case <-captureDone:
+		t.Fatal("capture returned before the watchdog's Close finished")
+	case <-time.After(100 * time.Millisecond):
+	}
+
+	close(conn.release)
+	select {
+	case err := <-captureDone:
+		require.NoError(t, err, "capture must return nil on cancellation")
+	case <-time.After(5 * time.Second):
+		t.Fatal("capture did not return after Close finished")
+	}
+	<-conn.closedCh
+	assert.Equal(t, int32(1), atomic.LoadInt32(&conn.closes), "connection must be closed exactly once by capture")
+}
+
+func trimNull(s string) string {
+	return string(bytes.Trim([]byte(s), "\x00"))
+}
diff --git a/ios/uidriver/uidriver.go b/ios/uidriver/uidriver.go
new file mode 100644
index 000000000..6e683dac7
--- /dev/null
+++ b/ios/uidriver/uidriver.go
@@ -0,0 +1,668 @@
+// Package uidriver is a reusable client for driving on-device UI automation
+// backends over HTTP. It talks to a running WebDriverAgent (WDA, default
+// :8100) or DeviceKit (default :12004) instance — typically reached through a
+// forwarded local port — and exposes the common automation actions (tap,
+// swipe, type, screenshot, source, app control, streaming, …) as a clean,
+// exported API.
+//
+// The client is deliberately decoupled from the go-ios CLI: construct a Driver
+// against a backend base URL and call its methods. All methods return values
+// and errors rather than terminating the process, so the driver is safe to
+// embed in the CLI, the REST API, or any other caller.
+package uidriver
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"path"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios/golog"
+)
+
+const logModule = "go-ios/uidriver"
+
+// Backend identifies which UI automation backend a Driver talks to.
+type Backend string
+
+const (
+	// BackendWDA drives a WebDriverAgent instance (WebDriver JSON wire protocol).
+	BackendWDA Backend = "wda"
+	// BackendDeviceKit drives a DeviceKit instance (JSON-RPC 2.0).
+	BackendDeviceKit Backend = "devicekit"
+
+	// DefaultWDAURL is the default forwarded WebDriverAgent address.
+	DefaultWDAURL = "http://127.0.0.1:8100"
+	// DefaultDeviceKitURL is the default forwarded DeviceKit address.
+	DefaultDeviceKitURL = "http://127.0.0.1:12004"
+
+	// DefaultTimeout is the default per-request HTTP timeout.
+	DefaultTimeout = 60 * time.Second
+
+	deviceKitRPCProtocol = "2.0"
+)
+
+// Response is the raw result of a backend HTTP call. Body holds the raw
+// response bytes (usually JSON); callers can unmarshal it as needed.
+type Response struct {
+	StatusCode int         `json:"statusCode"`
+	Header     http.Header `json:"-"`
+	Body       []byte      `json:"body"`
+}
+
+// UnmarshalBody decodes the response body into v.
+func (r Response) UnmarshalBody(v interface{}) error {
+	return json.Unmarshal(r.Body, v)
+}
+
+// Driver is a UI automation client bound to a single backend (WDA or
+// DeviceKit) reachable at a base URL. Construct it with New. A Driver is safe
+// for sequential use; it lazily establishes a WDA session on first use of a
+// session-scoped action.
+type Driver struct {
+	backend    Backend
+	baseURL    string
+	httpClient *http.Client
+	timeout    time.Duration
+	sessionID  string
+	// udid is optional, used only to enrich log lines.
+	udid string
+}
+
+// Option configures a Driver.
+type Option func(*Driver)
+
+// WithHTTPClient overrides the HTTP client used for requests.
+func WithHTTPClient(c *http.Client) Option {
+	return func(d *Driver) {
+		if c != nil {
+			d.httpClient = c
+		}
+	}
+}
+
+// WithTimeout sets the per-request HTTP timeout (ignored if WithHTTPClient is
+// also supplied).
+func WithTimeout(timeout time.Duration) Option {
+	return func(d *Driver) { d.timeout = timeout }
+}
+
+// WithSessionID pre-seeds a WDA session id so the Driver skips session
+// creation. Ignored by the DeviceKit backend.
+func WithSessionID(sessionID string) Option {
+	return func(d *Driver) { d.sessionID = sessionID }
+}
+
+// WithUDID attaches a device udid used only to enrich log lines.
+func WithUDID(udid string) Option {
+	return func(d *Driver) { d.udid = udid }
+}
+
+// New constructs a Driver for the given backend at baseURL (for example
+// "http://127.0.0.1:8100" for WDA or "http://127.0.0.1:12004" for DeviceKit).
+// The base URL is typically the local end of a forwarded connection to the
+// device. A trailing slash is trimmed.
+func New(backend Backend, baseURL string, opts ...Option) (*Driver, error) {
+	switch backend {
+	case BackendWDA, BackendDeviceKit:
+	default:
+		return nil, fmt.Errorf("uidriver: unknown backend %q", backend)
+	}
+	if strings.TrimSpace(baseURL) == "" {
+		return nil, errors.New("uidriver: baseURL must not be empty")
+	}
+	d := &Driver{
+		backend: backend,
+		baseURL: strings.TrimRight(baseURL, "/"),
+		timeout: DefaultTimeout,
+	}
+	for _, opt := range opts {
+		opt(d)
+	}
+	if d.httpClient == nil {
+		d.httpClient = &http.Client{Timeout: d.timeout}
+	}
+	return d, nil
+}
+
+// Backend returns the backend this Driver targets.
+func (d *Driver) Backend() Backend { return d.backend }
+
+// BaseURL returns the (trailing-slash-trimmed) backend base URL.
+func (d *Driver) BaseURL() string { return d.baseURL }
+
+// SessionID returns the current WDA session id (empty until one is created).
+func (d *Driver) SessionID() string { return d.sessionID }
+
+// Healthy reports whether the backend answers its health/status endpoint with
+// a 2xx status.
+func (d *Driver) Healthy() bool {
+	endpoint := "/status"
+	if d.backend == BackendDeviceKit {
+		endpoint = "/health"
+	}
+	resp, err := d.httpClient.Get(d.baseURL + endpoint)
+	if err != nil {
+		return false
+	}
+	defer func() { _ = resp.Body.Close() }()
+	return resp.StatusCode >= 200 && resp.StatusCode < 300
+}
+
+// Status returns the backend status/health payload.
+func (d *Driver) Status() (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitHTTP(http.MethodGet, "/health", nil)
+	default:
+		return d.wdaHTTP(http.MethodGet, "/status", nil)
+	}
+}
+
+// Tap taps the screen at absolute coordinates (x, y).
+func (d *Driver) Tap(x, y int) (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.tap", map[string]interface{}{"x": x, "y": y})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "wda", "tap", strconv.Itoa(x), strconv.Itoa(y)), nil)
+	}
+}
+
+// Swipe drags from (fromX, fromY) to (toX, toY) over the given duration in
+// seconds (0 lets the backend choose).
+func (d *Driver) Swipe(fromX, fromY, toX, toY int, duration float64) (Response, error) {
+	body := map[string]interface{}{"fromX": fromX, "fromY": fromY, "toX": toX, "toY": toY, "duration": duration}
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.swipe", body)
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		payload, err := marshalJSON(body)
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "wda", "dragfromtoforduration"), payload)
+	}
+}
+
+// LongPress presses and holds at (x, y) for duration seconds.
+func (d *Driver) LongPress(x, y int, duration float64) (Response, error) {
+	body := map[string]interface{}{"x": x, "y": y, "duration": duration}
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.longpress", body)
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		payload, err := marshalJSON(body)
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "wda", "touchAndHold"), payload)
+	}
+}
+
+// Type sends text as keyboard input.
+func (d *Driver) Type(text string) (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.text", map[string]interface{}{"text": text})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		payload, err := marshalJSON(textBody(text))
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "keys"), payload)
+	}
+}
+
+// ErrButtonUnsupported is returned when a hardware button press is requested
+// against a backend that cannot perform it.
+var ErrButtonUnsupported = errors.New("uidriver: button not supported by this backend")
+
+// PressButton presses a hardware button by name (for example "home", "lock",
+// "volumeup"). WDA only supports "home"; other buttons require DeviceKit and
+// yield ErrButtonUnsupported on WDA.
+func (d *Driver) PressButton(name string) (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.button", map[string]interface{}{"button": name})
+	default:
+		if strings.EqualFold(name, "home") {
+			session, err := d.wdaSession()
+			if err != nil {
+				return Response{}, err
+			}
+			return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "wda", "homescreen"), nil)
+		}
+		return Response{}, fmt.Errorf("%w: WDA only supports the home button; use the DeviceKit backend for lock/volume buttons", ErrButtonUnsupported)
+	}
+}
+
+// Screenshot captures the screen and returns the decoded image bytes (PNG).
+func (d *Driver) Screenshot() ([]byte, error) {
+	var resp Response
+	var err error
+	switch d.backend {
+	case BackendDeviceKit:
+		resp, err = d.deviceKitRPC("device.screenshot", map[string]interface{}{})
+	default:
+		var session string
+		session, err = d.wdaSession()
+		if err != nil {
+			return nil, err
+		}
+		resp, err = d.wdaHTTP(http.MethodGet, wdaPath("session", session, "screenshot"), nil)
+	}
+	if err != nil {
+		return nil, err
+	}
+	return decodeBase64Response(resp.Body)
+}
+
+// Source returns the current UI hierarchy (XML for WDA, backend-defined dump
+// for DeviceKit).
+func (d *Driver) Source() (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.dump.ui", map[string]interface{}{})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodGet, wdaPath("session", session, "source"), nil)
+	}
+}
+
+// WindowSize returns the device window/screen size payload.
+func (d *Driver) WindowSize() (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.info", map[string]interface{}{})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodGet, wdaPath("session", session, "window", "size"), nil)
+	}
+}
+
+// Orientation returns the current device orientation payload.
+func (d *Driver) Orientation() (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.orientation.get", map[string]interface{}{})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodGet, wdaPath("session", session, "orientation"), nil)
+	}
+}
+
+// SetOrientation sets the device orientation (for example "PORTRAIT",
+// "LANDSCAPE").
+func (d *Driver) SetOrientation(orientation string) (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.io.orientation.set", map[string]interface{}{"orientation": orientation})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		payload, err := marshalJSON(map[string]string{"orientation": orientation})
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "orientation"), payload)
+	}
+}
+
+// AppLaunch launches the app identified by bundleID.
+func (d *Driver) AppLaunch(bundleID string) (Response, error) {
+	return d.appWithBundleID("launch", bundleID)
+}
+
+// AppTerminate terminates the app identified by bundleID.
+func (d *Driver) AppTerminate(bundleID string) (Response, error) {
+	return d.appWithBundleID("terminate", bundleID)
+}
+
+// ErrForegroundUnsupported is returned when app foregrounding is requested
+// against a backend that does not support it (WDA).
+var ErrForegroundUnsupported = errors.New("uidriver: app foreground not supported by this backend")
+
+// AppForeground brings the currently backgrounded app to the foreground. Only
+// supported by the DeviceKit backend; returns ErrForegroundUnsupported on WDA.
+func (d *Driver) AppForeground() (Response, error) {
+	if d.backend != BackendDeviceKit {
+		return Response{}, ErrForegroundUnsupported
+	}
+	return d.deviceKitRPC("device.apps.foreground", map[string]interface{}{})
+}
+
+func (d *Driver) appWithBundleID(action, bundleID string) (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		return d.deviceKitRPC("device.apps."+action, map[string]interface{}{"bundleId": bundleID})
+	default:
+		session, err := d.wdaSession()
+		if err != nil {
+			return Response{}, err
+		}
+		payload, err := marshalJSON(map[string]string{"bundleId": bundleID})
+		if err != nil {
+			return Response{}, err
+		}
+		return d.wdaHTTP(http.MethodPost, wdaPath("session", session, "wda", "apps", action), payload)
+	}
+}
+
+// APIRequest is a raw passthrough to the backend.
+//
+// For the WDA backend, Method and Path are the HTTP verb and path (Body may be
+// nil), and RPCMethod/RPCParams are ignored.
+//
+// For the DeviceKit backend, RPCMethod is the JSON-RPC method name and
+// RPCParams its params (Method/Path/Body are ignored). If RPCParams is nil an
+// empty object is sent.
+type APIRequest struct {
+	// Method is the HTTP method for a WDA passthrough (defaults to GET).
+	Method string `json:"method,omitempty"`
+	// Path is the HTTP path for a WDA passthrough.
+	Path string `json:"path,omitempty"`
+	// Body is the raw HTTP request body for a WDA passthrough.
+	Body []byte `json:"body,omitempty"`
+	// RPCMethod is the JSON-RPC method name for a DeviceKit passthrough.
+	RPCMethod string `json:"rpcMethod,omitempty"`
+	// RPCParams are the JSON-RPC params for a DeviceKit passthrough.
+	RPCParams interface{} `json:"rpcParams,omitempty"`
+}
+
+// API performs a raw passthrough request against the backend. See APIRequest
+// for which fields apply to which backend.
+func (d *Driver) API(req APIRequest) (Response, error) {
+	switch d.backend {
+	case BackendDeviceKit:
+		if req.RPCMethod == "" {
+			return Response{}, errors.New("uidriver: RPCMethod is required for the DeviceKit backend")
+		}
+		params := req.RPCParams
+		if params == nil {
+			params = map[string]interface{}{}
+		}
+		return d.deviceKitRPC(req.RPCMethod, params)
+	default:
+		if req.Path == "" {
+			return Response{}, errors.New("uidriver: Path is required for the WDA backend")
+		}
+		method := req.Method
+		if method == "" {
+			method = http.MethodGet
+		}
+		return d.wdaHTTP(strings.ToUpper(method), req.Path, req.Body)
+	}
+}
+
+// StreamOptions configure a video/mjpeg stream request.
+type StreamOptions struct {
+	// H264 requests an h264 stream (DeviceKit only); otherwise mjpeg is used.
+	H264 bool
+	// FPS, Quality, Scale and Bitrate are optional query parameters passed
+	// through to the backend when non-empty.
+	FPS     string
+	Quality string
+	Scale   string
+	Bitrate string
+}
+
+// ErrStreamUnsupported is returned when the requested stream type is not
+// supported by the backend (for example h264 over WDA).
+var ErrStreamUnsupported = errors.New("uidriver: stream type not supported by this backend")
+
+// Stream opens a video stream against the backend and returns the raw response
+// body as an io.ReadCloser for the caller to pipe. The caller owns the returned
+// ReadCloser and must Close it. A non-2xx response is returned as an *HTTPError
+// with the response body included.
+func (d *Driver) Stream(ctx context.Context, opts StreamOptions) (io.ReadCloser, error) {
+	body, _, err := d.StreamWithContentType(ctx, opts)
+	return body, err
+}
+
+// StreamWithContentType behaves like Stream but also returns the backend's
+// response Content-Type, so callers proxying the stream (for example the REST
+// API) can forward it verbatim. The returned Content-Type may be empty if the
+// backend did not set one.
+func (d *Driver) StreamWithContentType(ctx context.Context, opts StreamOptions) (io.ReadCloser, string, error) {
+	streamType := "mjpeg"
+	if opts.H264 {
+		streamType = "h264"
+	}
+	if d.backend == BackendWDA && streamType != "mjpeg" {
+		return nil, "", fmt.Errorf("%w: WDA stream supports mjpeg only; use the DeviceKit backend for h264", ErrStreamUnsupported)
+	}
+	query := url.Values{}
+	setIfNotEmpty(query, "fps", opts.FPS)
+	setIfNotEmpty(query, "quality", opts.Quality)
+	setIfNotEmpty(query, "scale", opts.Scale)
+	setIfNotEmpty(query, "bitrate", opts.Bitrate)
+	endpoint := "/" + streamType
+	if encoded := query.Encode(); encoded != "" {
+		endpoint += "?" + encoded
+	}
+	rawURL := d.baseURL + endpoint
+
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
+	if err != nil {
+		return nil, "", fmt.Errorf("uidriver: failed creating stream request: %w", err)
+	}
+	golog.Info("opening ui stream", "module", logModule, "backend", string(d.backend), "url", rawURL, "udid", d.udid)
+	resp, err := d.httpClient.Do(req)
+	if err != nil {
+		return nil, "", fmt.Errorf("uidriver: stream request failed: %w", err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
+		body, _ := io.ReadAll(resp.Body)
+		_ = resp.Body.Close()
+		return nil, "", &HTTPError{StatusCode: resp.StatusCode, Body: body}
+	}
+	return resp.Body, resp.Header.Get("Content-Type"), nil
+}
+
+// HTTPError is returned when a backend responds with a non-2xx status.
+type HTTPError struct {
+	StatusCode int
+	Body       []byte
+}
+
+func (e *HTTPError) Error() string {
+	msg := strings.TrimSpace(string(e.Body))
+	if msg == "" {
+		return fmt.Sprintf("uidriver: backend returned status %d", e.StatusCode)
+	}
+	return fmt.Sprintf("uidriver: backend returned status %d: %s", e.StatusCode, msg)
+}
+
+// wdaSession returns an existing session id or lazily creates one.
+func (d *Driver) wdaSession() (string, error) {
+	if d.sessionID != "" {
+		return d.sessionID, nil
+	}
+	payload, err := marshalJSON(map[string]interface{}{
+		"capabilities":        map[string]interface{}{},
+		"desiredCapabilities": map[string]interface{}{},
+	})
+	if err != nil {
+		return "", err
+	}
+	resp, err := d.wdaHTTP(http.MethodPost, "/session", payload)
+	if err != nil {
+		return "", err
+	}
+	sessionID := extractSessionID(resp.Body)
+	if sessionID == "" {
+		return "", errors.New("uidriver: WDA did not return a session id")
+	}
+	d.sessionID = sessionID
+	golog.Debug("created wda session", "module", logModule, "sessionID", sessionID, "udid", d.udid)
+	return sessionID, nil
+}
+
+func (d *Driver) deviceKitRPC(method string, params interface{}) (Response, error) {
+	body, err := marshalJSON(map[string]interface{}{
+		"jsonrpc": deviceKitRPCProtocol,
+		"method":  method,
+		"params":  params,
+		"id":      1,
+	})
+	if err != nil {
+		return Response{}, err
+	}
+	return d.deviceKitHTTP(http.MethodPost, "/rpc", body)
+}
+
+func (d *Driver) deviceKitHTTP(method, endpoint string, body []byte) (Response, error) {
+	return d.doHTTP(method, endpoint, body)
+}
+
+func (d *Driver) wdaHTTP(method, endpoint string, body []byte) (Response, error) {
+	return d.doHTTP(method, endpoint, body)
+}
+
+func (d *Driver) doHTTP(method, endpoint string, body []byte) (Response, error) {
+	if !strings.HasPrefix(endpoint, "/") {
+		endpoint = "/" + endpoint
+	}
+	req, err := http.NewRequest(method, d.baseURL+endpoint, bytes.NewReader(body))
+	if err != nil {
+		return Response{}, fmt.Errorf("uidriver: failed creating request: %w", err)
+	}
+	req.Header.Set("Accept", "application/json")
+	if len(body) > 0 {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	golog.Debug("ui request", "module", logModule, "backend", string(d.backend), "method", method, "endpoint", endpoint, "udid", d.udid)
+	resp, err := d.httpClient.Do(req)
+	if err != nil {
+		return Response{}, fmt.Errorf("uidriver: request failed: %w", err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	respBody, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return Response{}, fmt.Errorf("uidriver: failed reading response: %w", err)
+	}
+	if resp.StatusCode < 200 || resp.StatusCode > 299 {
+		return Response{}, &HTTPError{StatusCode: resp.StatusCode, Body: respBody}
+	}
+	return Response{StatusCode: resp.StatusCode, Header: resp.Header, Body: respBody}, nil
+}
+
+func marshalJSON(data interface{}) ([]byte, error) {
+	body, err := json.Marshal(data)
+	if err != nil {
+		return nil, fmt.Errorf("uidriver: failed encoding request body: %w", err)
+	}
+	return body, nil
+}
+
+func textBody(text string) map[string]interface{} {
+	return map[string]interface{}{
+		"text":  text,
+		"value": []string{text},
+	}
+}
+
+func wdaPath(parts ...string) string {
+	return "/" + path.Join(parts...)
+}
+
+func setIfNotEmpty(query url.Values, key, value string) {
+	if value != "" {
+		query.Set(key, value)
+	}
+}
+
+func decodeBase64Response(body []byte) ([]byte, error) {
+	encoded := findBase64Value(body)
+	if encoded == "" {
+		return nil, errors.New("uidriver: response did not contain a base64 image")
+	}
+	image, err := base64.StdEncoding.DecodeString(encoded)
+	if err != nil {
+		return nil, fmt.Errorf("uidriver: failed decoding base64 image: %w", err)
+	}
+	return image, nil
+}
+
+func findBase64Value(body []byte) string {
+	var decoded interface{}
+	if err := json.Unmarshal(body, &decoded); err != nil {
+		return ""
+	}
+	return findBase64String(decoded)
+}
+
+func findBase64String(value interface{}) string {
+	switch typed := value.(type) {
+	case string:
+		return typed
+	case map[string]interface{}:
+		for _, key := range []string{"value", "result", "image", "screenshot", "data"} {
+			if nested, ok := typed[key]; ok {
+				if result := findBase64String(nested); result != "" {
+					return result
+				}
+			}
+		}
+	}
+	return ""
+}
+
+func extractSessionID(body []byte) string {
+	var decoded map[string]interface{}
+	if err := json.Unmarshal(body, &decoded); err != nil {
+		return ""
+	}
+	if sessionID, ok := decoded["sessionId"].(string); ok {
+		return sessionID
+	}
+	if value, ok := decoded["value"].(map[string]interface{}); ok {
+		if sessionID, ok := value["sessionId"].(string); ok {
+			return sessionID
+		}
+		if sessionID, ok := value["session_id"].(string); ok {
+			return sessionID
+		}
+	}
+	return ""
+}
diff --git a/ios/uidriver/uidriver_test.go b/ios/uidriver/uidriver_test.go
new file mode 100644
index 000000000..02d230853
--- /dev/null
+++ b/ios/uidriver/uidriver_test.go
@@ -0,0 +1,540 @@
+package uidriver_test
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios/uidriver"
+)
+
+// capturedRequest records what a test server received.
+type capturedRequest struct {
+	method string
+	path   string
+	query  string
+	body   []byte
+}
+
+// newRecordingServer returns a server that records the last request and replies
+// with the given status/body. Requests to the WDA /session endpoint always get
+// a session id so session-scoped actions can proceed.
+func newRecordingServer(t *testing.T, status int, respBody string) (*httptest.Server, *capturedRequest) {
+	t.Helper()
+	captured := &capturedRequest{}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		// The WDA session-creation POST is bookkeeping; answer it and don't
+		// overwrite the recorded action request.
+		if r.URL.Path == "/session" && r.Method == http.MethodPost {
+			w.WriteHeader(http.StatusOK)
+			_, _ = w.Write([]byte(`{"sessionId":"sess-123"}`))
+			return
+		}
+		captured.method = r.Method
+		captured.path = r.URL.Path
+		captured.query = r.URL.RawQuery
+		captured.body = body
+		w.WriteHeader(status)
+		_, _ = w.Write([]byte(respBody))
+	}))
+	t.Cleanup(srv.Close)
+	return srv, captured
+}
+
+func newDriver(t *testing.T, backend uidriver.Backend, baseURL string, opts ...uidriver.Option) *uidriver.Driver {
+	t.Helper()
+	d, err := uidriver.New(backend, baseURL, opts...)
+	if err != nil {
+		t.Fatalf("New(%s): %v", backend, err)
+	}
+	return d
+}
+
+func decodeJSONBody(t *testing.T, body []byte) map[string]interface{} {
+	t.Helper()
+	var m map[string]interface{}
+	if err := json.Unmarshal(body, &m); err != nil {
+		t.Fatalf("body is not JSON object: %v (%s)", err, body)
+	}
+	return m
+}
+
+func TestNewValidation(t *testing.T) {
+	if _, err := uidriver.New("bogus", "http://x"); err == nil {
+		t.Fatal("expected error for unknown backend")
+	}
+	if _, err := uidriver.New(uidriver.BackendWDA, "  "); err == nil {
+		t.Fatal("expected error for empty baseURL")
+	}
+	d := newDriver(t, uidriver.BackendWDA, "http://127.0.0.1:8100/")
+	if d.BaseURL() != "http://127.0.0.1:8100" {
+		t.Fatalf("trailing slash not trimmed: %q", d.BaseURL())
+	}
+	if d.Backend() != uidriver.BackendWDA {
+		t.Fatalf("unexpected backend %q", d.Backend())
+	}
+}
+
+func TestDeviceKitTap(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{"result":"ok"}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	resp, err := d.Tap(10, 20)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d", resp.StatusCode)
+	}
+	if captured.method != http.MethodPost || captured.path != "/rpc" {
+		t.Fatalf("got %s %s, want POST /rpc", captured.method, captured.path)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	if rpc["jsonrpc"] != "2.0" || rpc["method"] != "device.io.tap" {
+		t.Fatalf("unexpected rpc envelope: %v", rpc)
+	}
+	params, _ := rpc["params"].(map[string]interface{})
+	if params["x"].(float64) != 10 || params["y"].(float64) != 20 {
+		t.Fatalf("unexpected params: %v", params)
+	}
+}
+
+func TestWDATap(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{"value":null}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.Tap(5, 6); err != nil {
+		t.Fatal(err)
+	}
+	if captured.method != http.MethodPost {
+		t.Fatalf("method = %s", captured.method)
+	}
+	if captured.path != "/session/sess-123/wda/tap/5/6" {
+		t.Fatalf("path = %s", captured.path)
+	}
+	if d.SessionID() != "sess-123" {
+		t.Fatalf("session id not stored: %q", d.SessionID())
+	}
+}
+
+func TestWDASwipe(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.Swipe(1, 2, 3, 4, 0.5); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/wda/dragfromtoforduration" {
+		t.Fatalf("path = %s", captured.path)
+	}
+	body := decodeJSONBody(t, captured.body)
+	if body["fromX"].(float64) != 1 || body["toY"].(float64) != 4 || body["duration"].(float64) != 0.5 {
+		t.Fatalf("unexpected body: %v", body)
+	}
+}
+
+func TestDeviceKitSwipe(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.Swipe(1, 2, 3, 4, 1.5); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	if rpc["method"] != "device.io.swipe" {
+		t.Fatalf("method = %v", rpc["method"])
+	}
+}
+
+func TestWDAType(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.Type("hello"); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/keys" {
+		t.Fatalf("path = %s", captured.path)
+	}
+	body := decodeJSONBody(t, captured.body)
+	if body["text"] != "hello" {
+		t.Fatalf("text = %v", body["text"])
+	}
+	value, ok := body["value"].([]interface{})
+	if !ok || len(value) != 1 || value[0] != "hello" {
+		t.Fatalf("value = %v", body["value"])
+	}
+}
+
+func TestDeviceKitType(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.Type("world"); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	params := rpc["params"].(map[string]interface{})
+	if rpc["method"] != "device.io.text" || params["text"] != "world" {
+		t.Fatalf("unexpected: %v", rpc)
+	}
+}
+
+func TestWDAPressButtonHome(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.PressButton("HOME"); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/wda/homescreen" {
+		t.Fatalf("path = %s", captured.path)
+	}
+}
+
+func TestWDAPressButtonUnsupported(t *testing.T) {
+	srv, _ := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	_, err := d.PressButton("volumeup")
+	if !errors.Is(err, uidriver.ErrButtonUnsupported) {
+		t.Fatalf("want ErrButtonUnsupported, got %v", err)
+	}
+}
+
+func TestDeviceKitPressButton(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.PressButton("lock"); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	params := rpc["params"].(map[string]interface{})
+	if rpc["method"] != "device.io.button" || params["button"] != "lock" {
+		t.Fatalf("unexpected: %v", rpc)
+	}
+}
+
+func TestWDAOrientationGetSet(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{"value":"PORTRAIT"}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.Orientation(); err != nil {
+		t.Fatal(err)
+	}
+	if captured.method != http.MethodGet || captured.path != "/session/sess-123/orientation" {
+		t.Fatalf("get: %s %s", captured.method, captured.path)
+	}
+
+	if _, err := d.SetOrientation("LANDSCAPE"); err != nil {
+		t.Fatal(err)
+	}
+	if captured.method != http.MethodPost || captured.path != "/session/sess-123/orientation" {
+		t.Fatalf("set: %s %s", captured.method, captured.path)
+	}
+	body := decodeJSONBody(t, captured.body)
+	if body["orientation"] != "LANDSCAPE" {
+		t.Fatalf("orientation = %v", body["orientation"])
+	}
+}
+
+func TestDeviceKitOrientation(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.SetOrientation("PORTRAIT"); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	if rpc["method"] != "device.io.orientation.set" {
+		t.Fatalf("method = %v", rpc["method"])
+	}
+}
+
+func TestWDAApp(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.AppLaunch("com.example.app"); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/wda/apps/launch" {
+		t.Fatalf("launch path = %s", captured.path)
+	}
+	body := decodeJSONBody(t, captured.body)
+	if body["bundleId"] != "com.example.app" {
+		t.Fatalf("bundleId = %v", body["bundleId"])
+	}
+
+	if _, err := d.AppTerminate("com.example.app"); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/wda/apps/terminate" {
+		t.Fatalf("terminate path = %s", captured.path)
+	}
+}
+
+func TestDeviceKitApp(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.AppLaunch("com.example.app"); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	params := rpc["params"].(map[string]interface{})
+	if rpc["method"] != "device.apps.launch" || params["bundleId"] != "com.example.app" {
+		t.Fatalf("unexpected: %v", rpc)
+	}
+}
+
+func TestAppForegroundUnsupportedOnWDA(t *testing.T) {
+	srv, _ := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	_, err := d.AppForeground()
+	if !errors.Is(err, uidriver.ErrForegroundUnsupported) {
+		t.Fatalf("want ErrForegroundUnsupported, got %v", err)
+	}
+}
+
+func TestDeviceKitAppForeground(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.AppForeground(); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	if rpc["method"] != "device.apps.foreground" {
+		t.Fatalf("method = %v", rpc["method"])
+	}
+}
+
+func TestStatus(t *testing.T) {
+	// DeviceKit hits /health.
+	dkSrv, dkCaptured := newRecordingServer(t, http.StatusOK, `{"status":"ok"}`)
+	dk := newDriver(t, uidriver.BackendDeviceKit, dkSrv.URL)
+	resp, err := dk.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if dkCaptured.method != http.MethodGet || dkCaptured.path != "/health" {
+		t.Fatalf("devicekit status: %s %s", dkCaptured.method, dkCaptured.path)
+	}
+	parsed := decodeJSONBody(t, resp.Body)
+	if parsed["status"] != "ok" {
+		t.Fatalf("status body = %v", parsed)
+	}
+
+	// WDA hits /status.
+	wdaSrv, wdaCaptured := newRecordingServer(t, http.StatusOK, `{"value":{"state":"success"}}`)
+	wda := newDriver(t, uidriver.BackendWDA, wdaSrv.URL)
+	if _, err := wda.Status(); err != nil {
+		t.Fatal(err)
+	}
+	if wdaCaptured.path != "/status" {
+		t.Fatalf("wda status path = %s", wdaCaptured.path)
+	}
+}
+
+func TestScreenshotDecodesBase64(t *testing.T) {
+	raw := []byte("this-is-a-png")
+	encoded := base64.StdEncoding.EncodeToString(raw)
+	body, _ := json.Marshal(map[string]interface{}{"value": encoded})
+	srv, _ := newRecordingServer(t, http.StatusOK, string(body))
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	img, err := d.Screenshot()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(img) != string(raw) {
+		t.Fatalf("decoded image mismatch: %q", img)
+	}
+}
+
+func TestScreenshotNoImage(t *testing.T) {
+	srv, _ := newRecordingServer(t, http.StatusOK, `{"value":{}}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.Screenshot(); err == nil {
+		t.Fatal("expected error when no base64 image present")
+	}
+}
+
+func TestSourceAndWindowSize(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{"value":"<xml/>"}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.Source(); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/source" {
+		t.Fatalf("source path = %s", captured.path)
+	}
+	if _, err := d.WindowSize(); err != nil {
+		t.Fatal(err)
+	}
+	if captured.path != "/session/sess-123/window/size" {
+		t.Fatalf("window size path = %s", captured.path)
+	}
+}
+
+func TestAPIPassthroughWDA(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	if _, err := d.API(uidriver.APIRequest{Method: "post", Path: "/wda/deactivateApp", Body: []byte(`{"duration":2}`)}); err != nil {
+		t.Fatal(err)
+	}
+	if captured.method != http.MethodPost || captured.path != "/wda/deactivateApp" {
+		t.Fatalf("api: %s %s", captured.method, captured.path)
+	}
+	if string(captured.body) != `{"duration":2}` {
+		t.Fatalf("body = %s", captured.body)
+	}
+
+	// Missing path is an error.
+	if _, err := d.API(uidriver.APIRequest{}); err == nil {
+		t.Fatal("expected error for missing path")
+	}
+}
+
+func TestAPIPassthroughDeviceKit(t *testing.T) {
+	srv, captured := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	if _, err := d.API(uidriver.APIRequest{RPCMethod: "device.custom", RPCParams: map[string]interface{}{"k": "v"}}); err != nil {
+		t.Fatal(err)
+	}
+	rpc := decodeJSONBody(t, captured.body)
+	params := rpc["params"].(map[string]interface{})
+	if rpc["method"] != "device.custom" || params["k"] != "v" {
+		t.Fatalf("unexpected: %v", rpc)
+	}
+
+	// Missing rpc method is an error.
+	if _, err := d.API(uidriver.APIRequest{}); err == nil {
+		t.Fatal("expected error for missing rpc method")
+	}
+}
+
+func TestHTTPErrorOnNon2xx(t *testing.T) {
+	srv, _ := newRecordingServer(t, http.StatusBadRequest, `{"error":"bad"}`)
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+
+	_, err := d.Tap(1, 1)
+	var httpErr *uidriver.HTTPError
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("want *HTTPError, got %v", err)
+	}
+	if httpErr.StatusCode != http.StatusBadRequest {
+		t.Fatalf("status = %d", httpErr.StatusCode)
+	}
+	if !strings.Contains(httpErr.Error(), "bad") {
+		t.Fatalf("error message missing body: %s", httpErr.Error())
+	}
+}
+
+func TestHealthy(t *testing.T) {
+	okSrv, _ := newRecordingServer(t, http.StatusOK, `{}`)
+	if !newDriver(t, uidriver.BackendDeviceKit, okSrv.URL).Healthy() {
+		t.Fatal("expected healthy")
+	}
+	badSrv, _ := newRecordingServer(t, http.StatusInternalServerError, `{}`)
+	if newDriver(t, uidriver.BackendWDA, badSrv.URL).Healthy() {
+		t.Fatal("expected unhealthy on 5xx")
+	}
+	if newDriver(t, uidriver.BackendWDA, "http://127.0.0.1:1").Healthy() {
+		t.Fatal("expected unhealthy on connection error")
+	}
+}
+
+func TestStreamPipesChunkedBody(t *testing.T) {
+	chunks := []string{"frame-1", "frame-2", "frame-3"}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/mjpeg" {
+			t.Errorf("stream path = %s", r.URL.Path)
+		}
+		if r.URL.Query().Get("fps") != "30" || r.URL.Query().Get("quality") != "80" {
+			t.Errorf("stream query = %s", r.URL.RawQuery)
+		}
+		w.Header().Set("Content-Type", "multipart/x-mixed-replace")
+		w.WriteHeader(http.StatusOK)
+		flusher, _ := w.(http.Flusher)
+		for _, c := range chunks {
+			_, _ = w.Write([]byte(c))
+			if flusher != nil {
+				flusher.Flush()
+			}
+		}
+	}))
+	defer srv.Close()
+
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+	body, err := d.Stream(context.Background(), uidriver.StreamOptions{FPS: "30", Quality: "80"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = body.Close() }()
+	got, err := io.ReadAll(body)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(got) != strings.Join(chunks, "") {
+		t.Fatalf("stream body = %q", got)
+	}
+}
+
+func TestStreamH264RejectedOnWDA(t *testing.T) {
+	srv, _ := newRecordingServer(t, http.StatusOK, `{}`)
+	d := newDriver(t, uidriver.BackendWDA, srv.URL)
+
+	_, err := d.Stream(context.Background(), uidriver.StreamOptions{H264: true})
+	if !errors.Is(err, uidriver.ErrStreamUnsupported) {
+		t.Fatalf("want ErrStreamUnsupported, got %v", err)
+	}
+}
+
+func TestStreamNon2xxReturnsHTTPError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusServiceUnavailable)
+		_, _ = w.Write([]byte("no stream"))
+	}))
+	defer srv.Close()
+
+	d := newDriver(t, uidriver.BackendDeviceKit, srv.URL)
+	_, err := d.Stream(context.Background(), uidriver.StreamOptions{})
+	var httpErr *uidriver.HTTPError
+	if !errors.As(err, &httpErr) {
+		t.Fatalf("want *HTTPError, got %v", err)
+	}
+}
+
+func TestWithSessionIDSkipsCreation(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/session" {
+			t.Errorf("session should not be created when WithSessionID is set")
+		}
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte(`{}`))
+	}))
+	defer srv.Close()
+
+	d := newDriver(t, uidriver.BackendWDA, srv.URL, uidriver.WithSessionID("preset"))
+	if _, err := d.Tap(1, 1); err != nil {
+		t.Fatal(err)
+	}
+	if d.SessionID() != "preset" {
+		t.Fatalf("session id = %q", d.SessionID())
+	}
+}
diff --git a/restapi/api/accessibility_endpoints.go b/restapi/api/accessibility_endpoints.go
new file mode 100644
index 000000000..42f5da04a
--- /dev/null
+++ b/restapi/api/accessibility_endpoints.go
@@ -0,0 +1,256 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/accessibility"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/simlocation"
+	"github.com/gin-gonic/gin"
+)
+
+// defaultAXTimeout bounds a single accessibility service call (audit run or
+// element snapshot) so a wedged device service cannot hold a request open
+// indefinitely. Clients may shorten the audit with the `timeout` query param
+// (seconds); the request context still applies on top.
+const defaultAXTimeout = 60 * time.Second
+
+// registerAccessibilityRoutes registers accessibility (VoiceOver, ZoomTouch, the
+// AX audit and element snapshot) and GPX location endpoints mirroring the
+// corresponding `ios` CLI commands. All routes live under /device/:udid.
+func registerAccessibilityRoutes(device *gin.RouterGroup) {
+	device.GET("/voiceover", GetVoiceOver)
+	device.PUT("/voiceover", SetVoiceOver)
+	device.GET("/zoom", GetZoomTouch)
+	device.PUT("/zoom", SetZoomTouch)
+	device.POST("/ax/audit", RunAXAudit)
+	device.GET("/ax", GetAXSnapshot)
+	device.PUT("/setlocation/gpx", SetLocationGPX)
+}
+
+// parseEnabled resolves the desired boolean state from either a JSON body
+// ({"enabled": true}) or an `enabled` query param, so callers can use whichever
+// is convenient. A parseable JSON body wins; otherwise the query param is used.
+func parseEnabled(c *gin.Context) (bool, error) {
+	if c.Request != nil && c.Request.ContentLength != 0 {
+		var req enabledRequest
+		if err := c.ShouldBindJSON(&req); err == nil {
+			return req.Enabled, nil
+		} else if c.Query("enabled") == "" {
+			// The body was supplied but unparseable and there is no query fallback.
+			return false, err
+		}
+	}
+	return strconv.ParseBool(c.Query("enabled"))
+}
+
+// GetVoiceOver reports whether VoiceOver is enabled (CLI: ios voiceover get).
+// @Summary Get VoiceOver state
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]bool
+// @Router /device/{udid}/voiceover [get]
+func GetVoiceOver(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	enabled, err := ios.GetVoiceOver(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"VoiceOverEnabled": enabled})
+}
+
+// SetVoiceOver enables/disables VoiceOver (CLI: ios voiceover enable|disable).
+// The desired state comes from a JSON body {"enabled": bool} or the `enabled`
+// query param.
+// @Summary Set VoiceOver state
+// @Param udid path string true "Device UDID"
+// @Param body body enabledRequest false "enabled"
+// @Param enabled query bool false "enabled"
+// @Success 200 {object} map[string]bool
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/voiceover [put]
+func SetVoiceOver(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	enabled, err := parseEnabled(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if err := ios.SetVoiceOver(device, enabled); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"VoiceOverEnabled": enabled})
+}
+
+// GetZoomTouch reports whether ZoomTouch is enabled (CLI: ios zoomtouch get).
+// @Summary Get ZoomTouch state
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]bool
+// @Router /device/{udid}/zoom [get]
+func GetZoomTouch(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	enabled, err := ios.GetZoomTouch(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"ZoomTouchEnabled": enabled})
+}
+
+// SetZoomTouch enables/disables ZoomTouch (CLI: ios zoomtouch enable|disable).
+// The desired state comes from a JSON body {"enabled": bool} or the `enabled`
+// query param.
+// @Summary Set ZoomTouch state
+// @Param udid path string true "Device UDID"
+// @Param body body enabledRequest false "enabled"
+// @Param enabled query bool false "enabled"
+// @Success 200 {object} map[string]bool
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/zoom [put]
+func SetZoomTouch(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	enabled, err := parseEnabled(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if err := ios.SetZoomTouch(device, enabled); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"ZoomTouchEnabled": enabled})
+}
+
+// RunAXAudit runs the accessibility audit against the currently focused app and
+// returns the issues found (CLI: ios ax audit). The run is bounded by the
+// `timeout` query param (seconds, default 60) on top of the request context.
+// @Summary Run the accessibility audit
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param timeout query int false "audit timeout in seconds (default 60)"
+// @Success 200 {array} interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/ax/audit [post]
+func RunAXAudit(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	timeout := defaultAXTimeout
+	if q := c.Query("timeout"); q != "" {
+		secs, err := strconv.Atoi(q)
+		if err != nil || secs <= 0 {
+			RespondError(c, http.StatusBadRequest, errInvalidTimeout)
+			return
+		}
+		timeout = time.Duration(secs) * time.Second
+	}
+
+	control, err := accessibility.NewWithoutEventChangeListeners(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer control.Close()
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
+	defer cancel()
+
+	issues, err := control.RunAudit(ctx)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	if issues == nil {
+		issues = []accessibility.AXAuditIssue{}
+	}
+	c.JSON(http.StatusOK, issues)
+}
+
+// GetAXSnapshot returns a snapshot of the currently focused accessibility
+// element (CLI: ios ax). Live event streaming is a separate wave; this returns
+// only the current element.
+// @Summary Get an accessibility element snapshot
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} interface{}
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/ax [get]
+func GetAXSnapshot(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	control, err := accessibility.NewWithoutEventChangeListeners(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer control.Close()
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), defaultAXTimeout)
+	defer cancel()
+
+	element, err := control.GetElement(ctx)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, element)
+}
+
+// SetLocationGPX simulates live location tracking from an uploaded GPX file
+// (CLI: ios setlocationgpx). Send multipart/form-data with a "gpx" file; it is
+// written to a temp file, replayed, and the temp file is removed afterwards.
+// @Summary Simulate location from a GPX file
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param gpx formData file true "GPX file"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/setlocation/gpx [put]
+func SetLocationGPX(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	gpxBytes, err := readFormFile(c, "gpx")
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, errMissingGPX)
+		return
+	}
+	if len(gpxBytes) == 0 {
+		RespondError(c, http.StatusBadRequest, errMissingGPX)
+		return
+	}
+
+	tmp, err := os.CreateTemp(os.TempDir(), "go-ios-gpx-*.gpx")
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	tmpPath := tmp.Name()
+	defer func() {
+		if err := os.Remove(tmpPath); err != nil {
+			golog.Warn("failed to remove temp gpx file", "module", logModule, "udid", device.Properties.SerialNumber, "path", tmpPath, "err", err.Error())
+		}
+	}()
+
+	if _, err := tmp.Write(gpxBytes); err != nil {
+		tmp.Close()
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	if err := tmp.Close(); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+
+	if err := simlocation.SetLocationGPX(device, tmpPath); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "gpx location simulation completed"})
+}
diff --git a/restapi/api/accessibility_endpoints_test.go b/restapi/api/accessibility_endpoints_test.go
new file mode 100644
index 000000000..82483fd29
--- /dev/null
+++ b/restapi/api/accessibility_endpoints_test.go
@@ -0,0 +1,178 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// The accessibility/location endpoints all perform device I/O only after their
+// request-validation branches. These tests exercise the device-free branches:
+// bad-input (400) paths that short-circuit before any connection is attempted,
+// plus multipart parsing and temp-file handling for the GPX upload.
+
+// --- enabled parsing (VoiceOver / ZoomTouch) -------------------------------
+
+func TestSetVoiceOverRejectsBadEnabled(t *testing.T) {
+	// Non-boolean query value -> 400 before touching the device.
+	w, c := deviceCtx("PUT", "/voiceover?enabled=maybe", "", "", "UDID-VO", nil)
+	SetVoiceOver(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("bad enabled query: got %d, want 400", w.Code)
+	}
+
+	// Malformed JSON body with no query fallback -> 400.
+	w2, c2 := deviceCtx("PUT", "/voiceover", "{not-json", "application/json", "UDID-VO", nil)
+	SetVoiceOver(c2)
+	if w2.Code != http.StatusBadRequest {
+		t.Fatalf("bad enabled body: got %d, want 400", w2.Code)
+	}
+}
+
+func TestSetZoomTouchRejectsBadEnabled(t *testing.T) {
+	w, c := deviceCtx("PUT", "/zoom?enabled=nope", "", "", "UDID-ZT", nil)
+	SetZoomTouch(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("bad enabled query: got %d, want 400", w.Code)
+	}
+}
+
+// TestParseEnabled covers the shared query/body precedence logic directly so we
+// exercise the successful-parse branches without needing a device.
+func TestParseEnabled(t *testing.T) {
+	cases := []struct {
+		name        string
+		target      string
+		body        string
+		contentType string
+		want        bool
+		wantErr     bool
+	}{
+		{name: "query true", target: "/x?enabled=true", want: true},
+		{name: "query false", target: "/x?enabled=false", want: false},
+		{name: "query 1", target: "/x?enabled=1", want: true},
+		{name: "query 0", target: "/x?enabled=0", want: false},
+		{name: "query missing", target: "/x", wantErr: true},
+		{name: "query invalid", target: "/x?enabled=yes", wantErr: true},
+		{name: "json body true", target: "/x", body: `{"enabled":true}`, contentType: "application/json", want: true},
+		{name: "json body false", target: "/x", body: `{"enabled":false}`, contentType: "application/json", want: false},
+		{name: "bad body good query fallback", target: "/x?enabled=true", body: "{bad", contentType: "application/json", want: true},
+		{name: "bad body no fallback", target: "/x", body: "{bad", contentType: "application/json", wantErr: true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			gin.SetMode(gin.TestMode)
+			c, _ := gin.CreateTestContext(httptest.NewRecorder())
+			var r *http.Request
+			if tc.body != "" {
+				r = httptest.NewRequest("PUT", tc.target, strings.NewReader(tc.body))
+			} else {
+				r = httptest.NewRequest("PUT", tc.target, nil)
+			}
+			if tc.contentType != "" {
+				r.Header.Set("Content-Type", tc.contentType)
+			}
+			c.Request = r
+			got, err := parseEnabled(c)
+			if tc.wantErr {
+				if err == nil {
+					t.Fatalf("expected error, got value %v", got)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tc.want {
+				t.Fatalf("got %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+// --- AX audit timeout validation -------------------------------------------
+
+func TestRunAXAuditRejectsBadTimeout(t *testing.T) {
+	for _, q := range []string{"timeout=abc", "timeout=0", "timeout=-5"} {
+		w, c := deviceCtx("POST", "/ax/audit?"+q, "", "", "UDID-AX", nil)
+		RunAXAudit(c)
+		if w.Code != http.StatusBadRequest {
+			t.Fatalf("bad %q: got %d, want 400", q, w.Code)
+		}
+		var resp map[string]string
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("bad %q: response not JSON: %v", q, err)
+		}
+		if resp["error"] == "" {
+			t.Fatalf("bad %q: expected error field", q)
+		}
+	}
+}
+
+// --- GPX upload validation & temp handling ---------------------------------
+
+func TestSetLocationGPXMissingFile(t *testing.T) {
+	// multipart form without a "gpx" file field -> 400 before any device I/O.
+	ct, body := multipartBody(t, map[string]string{"unrelated": "1"}, nil)
+	w, c := deviceCtx("PUT", "/setlocation/gpx", body.String(), ct, "UDID-GPX", nil)
+	SetLocationGPX(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("missing gpx: got %d, want 400", w.Code)
+	}
+	var resp map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("response not JSON: %v", err)
+	}
+	if !strings.Contains(resp["error"], "gpx") {
+		t.Fatalf("error %q should mention gpx", resp["error"])
+	}
+}
+
+func TestSetLocationGPXEmptyFile(t *testing.T) {
+	// A present-but-empty gpx file is rejected with 400.
+	ct, body := multipartBody(t, nil, map[string][]byte{"gpx": {}})
+	w, c := deviceCtx("PUT", "/setlocation/gpx", body.String(), ct, "UDID-GPX", nil)
+	SetLocationGPX(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("empty gpx: got %d, want 400", w.Code)
+	}
+}
+
+func TestSetLocationGPXNoMultipart(t *testing.T) {
+	// A non-multipart request has no form file -> 400.
+	w, c := deviceCtx("PUT", "/setlocation/gpx", "", "", "UDID-GPX", nil)
+	SetLocationGPX(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("no multipart: got %d, want 400", w.Code)
+	}
+}
+
+// TestGPXMultipartRoundTrips proves the multipart helper produces a form that
+// gin/FormFile can read back the gpx bytes from (parsing path the handler relies
+// on), independent of any device connection.
+func TestGPXMultipartRoundTrips(t *testing.T) {
+	gpx := []byte(`<gpx><trk><trkseg><trkpt lat="1" lon="2"></trkpt></trkseg></trk></gpx>`)
+	var buf bytes.Buffer
+	mw := multipart.NewWriter(&buf)
+	fw, err := mw.CreateFormFile("gpx", "route.gpx")
+	if err != nil {
+		t.Fatal(err)
+	}
+	fw.Write(gpx)
+	mw.Close()
+
+	_, c := deviceCtx("PUT", "/setlocation/gpx", buf.String(), mw.FormDataContentType(), "UDID-GPX", nil)
+	got, err := readFormFile(c, "gpx")
+	if err != nil {
+		t.Fatalf("readFormFile: %v", err)
+	}
+	if !bytes.Equal(got, gpx) {
+		t.Fatalf("gpx bytes mismatch: got %q", string(got))
+	}
+}
diff --git a/restapi/api/config_endpoints.go b/restapi/api/config_endpoints.go
new file mode 100644
index 000000000..945219a78
--- /dev/null
+++ b/restapi/api/config_endpoints.go
@@ -0,0 +1,134 @@
+package api
+
+import (
+	"encoding/hex"
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/imagemounter"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+)
+
+// registerConfigRoutes registers profile and developer-image management
+// endpoints. GET /profiles and GET/PUT /image already exist in
+// device_endpoints.go; this only adds the missing verbs. Routes are under
+// /device/:udid.
+func registerConfigRoutes(device *gin.RouterGroup) {
+	device.POST("/profiles", AddProfile)
+	device.DELETE("/profiles/:name", RemoveProfile)
+	device.GET("/image/list", ListMountedImages)
+	device.DELETE("/image", UnmountImage)
+}
+
+// AddProfile installs a configuration profile (CLI: ios profile add). Send the
+// profile as the raw request body, or as multipart with a "profile" file plus an
+// optional "p12" supervisor identity and "password" field (supervised install).
+// @Summary Install a configuration profile
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/profiles [post]
+func AddProfile(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	var profileBytes, p12Bytes []byte
+	var password string
+	if profile, err := readFormFile(c, "profile"); err == nil {
+		profileBytes = profile
+		if p12, err := readFormFile(c, "p12"); err == nil {
+			p12Bytes = p12
+		}
+		password = c.PostForm("password")
+	} else {
+		body, err := readAllLimited(c.Request.Body)
+		if err != nil {
+			RespondError(c, http.StatusBadRequest, err)
+			return
+		}
+		profileBytes = body
+	}
+	if len(profileBytes) == 0 {
+		RespondError(c, http.StatusBadRequest, errMissingProfile)
+		return
+	}
+
+	conn, err := mcinstall.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+
+	if len(p12Bytes) > 0 {
+		err = conn.AddProfileSupervised(profileBytes, p12Bytes, password)
+	} else {
+		err = conn.AddProfile(profileBytes)
+	}
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "profile installed"})
+}
+
+// RemoveProfile removes a configuration profile by identifier (CLI: ios profile remove).
+// @Summary Remove a configuration profile
+// @Param udid path string true "Device UDID"
+// @Param name path string true "profile identifier"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/profiles/{name} [delete]
+func RemoveProfile(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	conn, err := mcinstall.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	if err := conn.RemoveProfile(c.Param("name")); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "profile removed"})
+}
+
+// ListMountedImages lists mounted developer image signatures (CLI: ios image list).
+// @Summary List mounted developer image signatures
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/image/list [get]
+func ListMountedImages(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	conn, err := imagemounter.NewImageMounter(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	signatures, err := conn.ListImages()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	hexSigs := make([]string, 0, len(signatures))
+	for _, s := range signatures {
+		hexSigs = append(hexSigs, hex.EncodeToString(s))
+	}
+	c.JSON(http.StatusOK, gin.H{"signatures": hexSigs, "count": len(hexSigs)})
+}
+
+// UnmountImage unmounts the developer disk image (CLI: ios image unmount).
+// @Summary Unmount the developer disk image
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/image [delete]
+func UnmountImage(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	if err := imagemounter.UnmountImage(device); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "image unmounted"})
+}
diff --git a/restapi/api/device_endpoints.go b/restapi/api/device_endpoints.go
index 1239d5683..1d1d7bef8 100644
--- a/restapi/api/device_endpoints.go
+++ b/restapi/api/device_endpoints.go
@@ -209,17 +209,16 @@ func Screenshot(c *gin.Context) {
 		return
 	}
 
-	c.Header("Content-Type", "image/png")
-	c.Data(http.StatusOK, "application/octet-stream", imageBytes)
+	c.Data(http.StatusOK, "image/png", imageBytes)
 }
 
 // Change the current device location
 // @Summary      Change the current device location
-// @Description Change the current device location to provided latitude and longtitude
+// @Description Change the current device location to provided latitude and longitude
 // @Tags         general_device_specific
 // @Produce      json
 // @Param        latitude  query      string  true  "Location latitude"
-// @Param        longtitude  query      string  true  "Location longtitude"
+// @Param        longitude  query      string  true  "Location longitude"
 // @Success      200  {object}  GenericResponse
 // @Failure		 422  {object}  GenericResponse
 // @Failure		 500  {object}  GenericResponse
@@ -233,19 +232,19 @@ func SetLocation(c *gin.Context) {
 		return
 	}
 
-	longtitude := c.Query("longtitude")
-	if longtitude == "" {
-		c.JSON(http.StatusUnprocessableEntity, GenericResponse{Error: "longtitude query param is missing"})
+	longitude := c.Query("longitude")
+	if longitude == "" {
+		c.JSON(http.StatusUnprocessableEntity, GenericResponse{Error: "longitude query param is missing"})
 		return
 	}
 
-	err := simlocation.SetLocation(device, latitude, longtitude)
+	err := simlocation.SetLocation(device, latitude, longitude)
 	if err != nil {
 		c.JSON(http.StatusInternalServerError, GenericResponse{Error: err.Error()})
 		return
 	}
 
-	c.JSON(http.StatusOK, GenericResponse{Message: "Device location set to latitude=" + latitude + ", longtitude=" + longtitude})
+	c.JSON(http.StatusOK, GenericResponse{Message: "Device location set to latitude=" + latitude + ", longitude=" + longitude})
 }
 
 // Reset to the actual device location
diff --git a/restapi/api/device_endpoints_test.go b/restapi/api/device_endpoints_test.go
index 15abc4220..6030661a6 100644
--- a/restapi/api/device_endpoints_test.go
+++ b/restapi/api/device_endpoints_test.go
@@ -63,3 +63,34 @@ func TestResetAccessibilityEndpoint(t *testing.T) {
 		assert.True(t, hasError, "Response should contain an error field")
 	})
 }
+
+// TestSetLocationReadsLongitude asserts the handler reads the correctly-spelled
+// `longitude` query param (the spec renamed `longtitude` -> `longitude`).
+func TestSetLocationReadsLongitude(t *testing.T) {
+	t.Run("missing longitude yields 422 mentioning longitude", func(t *testing.T) {
+		router := setupTestRouter()
+		router.PUT("/setlocation", api.SetLocation)
+
+		req, _ := http.NewRequest("PUT", "/setlocation?latitude=1.0", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusUnprocessableEntity, w.Code)
+		var response api.GenericResponse
+		assert.NoError(t, json.Unmarshal(w.Body.Bytes(), &response))
+		assert.Contains(t, response.Error, "longitude")
+		assert.NotContains(t, response.Error, "longtitude")
+	})
+
+	t.Run("old misspelled longtitude param is not accepted", func(t *testing.T) {
+		router := setupTestRouter()
+		router.PUT("/setlocation", api.SetLocation)
+
+		// Passing the old misspelled name must NOT satisfy the required param.
+		req, _ := http.NewRequest("PUT", "/setlocation?latitude=1.0&longtitude=2.0", nil)
+		w := httptest.NewRecorder()
+		router.ServeHTTP(w, req)
+
+		assert.Equal(t, http.StatusUnprocessableEntity, w.Code)
+	})
+}
diff --git a/restapi/api/deviceinfo_endpoints.go b/restapi/api/deviceinfo_endpoints.go
new file mode 100644
index 000000000..861727fb2
--- /dev/null
+++ b/restapi/api/deviceinfo_endpoints.go
@@ -0,0 +1,202 @@
+package api
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/diagnostics"
+	"github.com/danielpaulus/go-ios/ios/instruments"
+	"github.com/gin-gonic/gin"
+)
+
+// registerDeviceInfoRoutes registers read-only device information endpoints that
+// mirror the corresponding `ios` CLI commands. All routes live under
+// /device/:udid and rely on DeviceMiddleware having set the device in context.
+func registerDeviceInfoRoutes(device *gin.RouterGroup) {
+	device.GET("/devicename", GetDeviceName)
+	device.GET("/date", GetDeviceDate)
+	device.GET("/battery", GetBattery)
+	device.GET("/diagnostics", GetDiagnostics)
+	device.GET("/mobilegestalt", GetMobileGestalt)
+	device.GET("/processes", GetProcesses)
+	device.GET("/lockdown", GetLockdownValues)
+}
+
+// GetDeviceName returns the device name (CLI: ios devicename).
+// @Summary Get device name
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/devicename [get]
+func GetDeviceName(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	allValues, err := ios.GetValues(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"devicename": allValues.Value.DeviceName})
+}
+
+// GetDeviceDate returns the device date (CLI: ios date).
+// @Summary Get device date
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/date [get]
+func GetDeviceDate(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	allValues, err := ios.GetValues(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	ts := allValues.Value.TimeIntervalSince1970
+	c.JSON(http.StatusOK, gin.H{
+		"formatedDate":          time.Unix(int64(ts), 0).Format(time.RFC850),
+		"TimeIntervalSince1970": ts,
+	})
+}
+
+// GetBattery returns battery diagnostics (CLI: ios batterycheck).
+// @Summary Get battery diagnostics
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} ios.BatteryInfo
+// @Router /device/{udid}/battery [get]
+func GetBattery(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	battery, err := ios.GetBatteryDiagnostics(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, battery)
+}
+
+// GetDiagnostics returns all diagnostic values (CLI: ios diagnostics list).
+// @Summary List diagnostics
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} interface{}
+// @Router /device/{udid}/diagnostics [get]
+func GetDiagnostics(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	conn, err := diagnostics.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	values, err := conn.AllValues()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, values)
+}
+
+// GetMobileGestalt queries mobilegestalt keys (CLI: ios mobilegestalt <key>...).
+// Pass one or more keys as repeated query params, e.g. ?key=A&key=B.
+// @Summary Query mobilegestalt keys
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param key query []string true "mobilegestalt keys"
+// @Success 200 {object} interface{}
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/mobilegestalt [get]
+func GetMobileGestalt(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	keys := c.QueryArray("key")
+	if len(keys) == 0 {
+		RespondError(c, http.StatusBadRequest, errMissingKey)
+		return
+	}
+	conn, err := diagnostics.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	result, err := conn.MobileGestaltQuery(keys)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, result)
+}
+
+// GetProcesses lists running processes (CLI: ios ps [--apps]).
+// Pass ?apps=true to return only application processes.
+// @Summary List running processes
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param apps query bool false "only application processes"
+// @Success 200 {array} instruments.ProcessInfo
+// @Router /device/{udid}/processes [get]
+func GetProcesses(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	service, err := instruments.NewDeviceInfoService(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer service.Close()
+	processList, err := service.ProcessList()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	if c.Query("apps") == "true" {
+		apps := make([]instruments.ProcessInfo, 0, len(processList))
+		for _, p := range processList {
+			if p.IsApplication {
+				apps = append(apps, p)
+			}
+		}
+		processList = apps
+	}
+	c.JSON(http.StatusOK, processList)
+}
+
+// GetLockdownValues returns lockdown values (CLI: ios lockdown get). Without a
+// `domain` query param it returns all values; with `domain` it returns only the
+// values scoped to that domain.
+// @Summary Get lockdown values
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param domain query string false "Lockdown domain to scope the values to"
+// @Success 200 {object} interface{}
+// @Router /device/{udid}/lockdown [get]
+func GetLockdownValues(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	domain := c.Query("domain")
+
+	// No domain: return the full set of lockdown values (default CLI behaviour).
+	if domain == "" {
+		allValues, err := ios.GetValues(device)
+		if err != nil {
+			RespondError(c, http.StatusInternalServerError, err)
+			return
+		}
+		c.JSON(http.StatusOK, allValues)
+		return
+	}
+
+	// Domain scoped: open a lockdown session and pass the domain through. An
+	// empty key returns all values within the requested domain.
+	lockdownConn, err := ios.ConnectLockdownWithSession(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer lockdownConn.Close()
+
+	value, err := lockdownConn.GetValueForDomain("", domain)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"domain": domain, "value": value})
+}
diff --git a/restapi/api/devicemgmt_endpoints.go b/restapi/api/devicemgmt_endpoints.go
new file mode 100644
index 000000000..e377ca6d2
--- /dev/null
+++ b/restapi/api/devicemgmt_endpoints.go
@@ -0,0 +1,229 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/amfi"
+	"github.com/danielpaulus/go-ios/ios/diagnostics"
+	"github.com/danielpaulus/go-ios/ios/imagemounter"
+	"github.com/danielpaulus/go-ios/ios/instruments"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+)
+
+// registerDeviceMgmtRoutes registers device-management endpoints mirroring the
+// corresponding `ios` CLI commands. All routes live under /device/:udid.
+func registerDeviceMgmtRoutes(device *gin.RouterGroup) {
+	device.POST("/reboot", Reboot)
+	device.POST("/shutdown", Shutdown)
+	device.POST("/erase", Erase)
+	device.GET("/devmode", GetDevMode)
+	device.POST("/devmode", SetDevMode)
+	device.GET("/lang", GetLanguage)
+	device.PUT("/lang", SetLanguage)
+	device.POST("/memlimitoff", MemLimitOff)
+}
+
+// Reboot reboots the device (CLI: ios reboot).
+// @Summary Reboot the device
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/reboot [post]
+func Reboot(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	if err := diagnostics.Reboot(device); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "reboot triggered"})
+}
+
+// Shutdown shuts down the device (CLI: ios shutdown).
+// @Summary Shut down the device
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/shutdown [post]
+func Shutdown(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	if err := diagnostics.Shutdown(device); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "shutdown triggered"})
+}
+
+// Erase erases the device (CLI: ios erase). Destructive: requires ?confirm=true.
+// @Summary Erase all content and settings
+// @Param udid path string true "Device UDID"
+// @Param confirm query bool true "must be true to proceed"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/erase [post]
+func Erase(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	if c.Query("confirm") != "true" {
+		RespondError(c, http.StatusBadRequest, errEraseNotConfirmed)
+		return
+	}
+	if err := mcinstall.Erase(device); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "erase triggered"})
+}
+
+// GetDevMode reports whether developer mode is enabled (CLI: ios devmode get).
+// @Summary Get developer mode state
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/devmode [get]
+func GetDevMode(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	enabled, err := imagemounter.IsDevModeEnabled(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"DeveloperModeEnabled": enabled})
+}
+
+type devModeRequest struct {
+	Action            string `json:"action"`
+	EnablePostRestart bool   `json:"enablePostRestart"`
+}
+
+// SetDevMode enables or reveals developer mode (CLI: ios devmode enable|reveal).
+// @Summary Enable or reveal developer mode
+// @Param udid path string true "Device UDID"
+// @Param body body devModeRequest true "action: enable|reveal"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/devmode [post]
+func SetDevMode(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req devModeRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	switch req.Action {
+	case "enable":
+		if err := amfi.EnableDeveloperMode(device, req.EnablePostRestart); err != nil {
+			RespondError(c, http.StatusInternalServerError, err)
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"message": "developer mode enable requested"})
+	case "reveal":
+		conn, err := amfi.New(device)
+		if err != nil {
+			RespondError(c, http.StatusInternalServerError, err)
+			return
+		}
+		defer conn.Close()
+		if err := conn.RevealDevMode(); err != nil {
+			RespondError(c, http.StatusInternalServerError, err)
+			return
+		}
+		c.JSON(http.StatusOK, gin.H{"message": "developer mode menu revealed"})
+	default:
+		RespondError(c, http.StatusBadRequest, errUnknownAction)
+	}
+}
+
+// GetLanguage returns the device language configuration (CLI: ios lang).
+// @Summary Get language configuration
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} ios.LanguageConfiguration
+// @Router /device/{udid}/lang [get]
+func GetLanguage(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	lang, err := ios.GetLanguage(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, lang)
+}
+
+type langRequest struct {
+	Language string `json:"language"`
+	Locale   string `json:"locale"`
+}
+
+// SetLanguage sets the device language/locale (CLI: ios lang --setlang --setlocale).
+// @Summary Set language/locale
+// @Param udid path string true "Device UDID"
+// @Param body body langRequest true "language and/or locale"
+// @Success 200 {object} ios.LanguageConfiguration
+// @Router /device/{udid}/lang [put]
+func SetLanguage(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req langRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if err := ios.SetLanguage(device, ios.LanguageConfiguration{Language: req.Language, Locale: req.Locale}); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	lang, err := ios.GetLanguage(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, lang)
+}
+
+type memLimitRequest struct {
+	Process string `json:"process"`
+}
+
+// MemLimitOff waives the memory limit for a process (CLI: ios memlimitoff).
+// Process name via ?process= or JSON body {"process":"..."}.
+// @Summary Waive the memory limit for a process
+// @Param udid path string true "Device UDID"
+// @Param process query string false "process name"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/memlimitoff [post]
+func MemLimitOff(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	processName := c.Query("process")
+	if processName == "" {
+		var req memLimitRequest
+		_ = c.ShouldBindJSON(&req)
+		processName = req.Process
+	}
+	if processName == "" {
+		RespondError(c, http.StatusBadRequest, errMissingProcess)
+		return
+	}
+
+	pControl, err := instruments.NewProcessControl(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer pControl.Close()
+
+	svc, err := instruments.NewDeviceInfoService(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer svc.Close()
+
+	process, err := svc.ProcessByName(processName)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	disabled, err := pControl.DisableMemoryLimit(process.Pid)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"process": process.Name, "pid": process.Pid, "disabled": disabled})
+}
diff --git a/restapi/api/diagnostics_net_endpoints.go b/restapi/api/diagnostics_net_endpoints.go
new file mode 100644
index 000000000..2856c46ff
--- /dev/null
+++ b/restapi/api/diagnostics_net_endpoints.go
@@ -0,0 +1,115 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/afc"
+	"github.com/danielpaulus/go-ios/ios/diagnostics"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/pcap"
+	"github.com/gin-gonic/gin"
+)
+
+// registerDiagnosticsNetRoutes registers device diagnostics and network endpoints
+// that mirror the corresponding `ios` CLI commands. All routes live under
+// /device/:udid and rely on DeviceMiddleware having set the device in context.
+func registerDiagnosticsNetRoutes(device *gin.RouterGroup) {
+	device.GET("/diskspace", GetDiskSpace)
+	device.GET("/ip", GetDeviceIP)
+	device.GET("/rsd", GetRsdServices)
+	device.GET("/battery/registry", GetBatteryRegistry)
+}
+
+// GetDiskSpace returns filesystem information for the device (total/free/used
+// bytes, block size, ...) by querying the AFC service (CLI: ios diskspace).
+// @Summary Get device disk space info
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} afc.DeviceInfo
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/diskspace [get]
+func GetDiskSpace(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	client, err := afc.New(device)
+	if err != nil {
+		golog.Error("failed to open afc for diskspace", "module", logModule, "udid", device.Properties.SerialNumber, "error", err.Error())
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+
+	info, err := client.DeviceInfo()
+	if err != nil {
+		golog.Error("failed to read afc device info", "module", logModule, "udid", device.Properties.SerialNumber, "error", err.Error())
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, info)
+}
+
+// GetDeviceIP resolves the device's network addresses (MAC/IPv4/IPv6) by sniffing
+// packets over the pcapd service (CLI: ios ip).
+// @Summary Get device IP / network info
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} pcap.NetworkInfo
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/ip [get]
+func GetDeviceIP(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	info, err := pcap.FindIp(device)
+	if err != nil {
+		golog.Error("failed to find device ip", "module", logModule, "udid", device.Properties.SerialNumber, "error", err.Error())
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, info)
+}
+
+// GetRsdServices returns the device's RSD (Remote Service Discovery) service list
+// (CLI: ios rsd ls). This requires a running tunnel (iOS 17+); devices without RSD
+// get a 400.
+// @Summary Get device RSD service list
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]ios.RsdServiceEntry
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/rsd [get]
+func GetRsdServices(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	if !device.SupportsRsd() {
+		golog.Warn("rsd requested but unavailable", "module", logModule, "udid", device.Properties.SerialNumber)
+		RespondError(c, http.StatusBadRequest, errRsdUnavailable)
+		return
+	}
+	services := device.Rsd.GetServices()
+	c.JSON(http.StatusOK, services)
+}
+
+// GetBatteryRegistry returns the battery IORegistry stats (Temperature, Voltage,
+// CurrentCapacity, ...) via the diagnostics relay (CLI: ios diagnostics ioregistry).
+// @Summary Get device battery IORegistry
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} diagnostics.IORegistry
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/battery/registry [get]
+func GetBatteryRegistry(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	conn, err := diagnostics.New(device)
+	if err != nil {
+		golog.Error("failed to open diagnostics relay", "module", logModule, "udid", device.Properties.SerialNumber, "error", err.Error())
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+
+	registry, err := conn.Battery()
+	if err != nil {
+		golog.Error("failed to read battery registry", "module", logModule, "udid", device.Properties.SerialNumber, "error", err.Error())
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, registry)
+}
diff --git a/restapi/api/diagnostics_net_endpoints_test.go b/restapi/api/diagnostics_net_endpoints_test.go
new file mode 100644
index 000000000..2ac36bbdd
--- /dev/null
+++ b/restapi/api/diagnostics_net_endpoints_test.go
@@ -0,0 +1,88 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/gin-gonic/gin"
+)
+
+// newDeviceCtx builds a gin test context with the supplied device already in
+// context, so a handler's pre-I/O branches (validation / capability checks) can
+// be exercised without a real device.
+func newDeviceCtx(method, target string, device ios.DeviceEntry) (*httptest.ResponseRecorder, *gin.Context) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(method, target, nil)
+	c.Set(IOS_KEY, device)
+	return w, c
+}
+
+// TestGetRsdServicesUnavailable verifies the RSD handler returns a clear 400
+// error envelope when the device has no RSD provider (older iOS / no tunnel).
+// This path runs entirely before any device I/O, so it is device-free.
+func TestGetRsdServicesUnavailable(t *testing.T) {
+	w, c := newDeviceCtx("GET", "/rsd", ios.DeviceEntry{})
+
+	GetRsdServices(c)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("got %d, want %d (body=%s)", w.Code, http.StatusBadRequest, w.Body.String())
+	}
+	var resp map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("response is not a JSON error envelope: %v (body=%s)", err, w.Body.String())
+	}
+	if resp["error"] == "" {
+		t.Fatalf("expected a non-empty error field, got %q", w.Body.String())
+	}
+}
+
+// TestGetRsdServicesAvailable verifies that when the device does have an RSD
+// provider, the handler returns 200 with the service map. An empty
+// RsdPortProviderJson is non-nil, so SupportsRsd() is true and GetServices()
+// yields an empty map, exercising the success path without any device I/O.
+func TestGetRsdServicesAvailable(t *testing.T) {
+	device := ios.DeviceEntry{Rsd: ios.RsdPortProviderJson{}}
+	w, c := newDeviceCtx("GET", "/rsd", device)
+
+	GetRsdServices(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want %d (body=%s)", w.Code, http.StatusOK, w.Body.String())
+	}
+	var services map[string]ios.RsdServiceEntry
+	if err := json.Unmarshal(w.Body.Bytes(), &services); err != nil {
+		t.Fatalf("response is not a JSON service map: %v (body=%s)", err, w.Body.String())
+	}
+	if len(services) != 0 {
+		t.Fatalf("expected an empty service map, got %v", services)
+	}
+}
+
+// TestDiagnosticsNetRoutesRegistered ensures the new endpoints are wired into the
+// full route tree without conflicting with existing routes. gin panics at
+// registration on a conflict, so a successful build here proves clean wiring.
+func TestDiagnosticsNetRoutesRegistered(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	device := router.Group("/device/:udid")
+	registerDiagnosticsNetRoutes(device)
+
+	want := map[string]string{
+		"GET /device/:udid/diskspace":        "",
+		"GET /device/:udid/ip":               "",
+		"GET /device/:udid/rsd":              "",
+		"GET /device/:udid/battery/registry": "",
+	}
+	for _, r := range router.Routes() {
+		delete(want, r.Method+" "+r.Path)
+	}
+	if len(want) != 0 {
+		t.Fatalf("missing expected routes: %v", want)
+	}
+}
diff --git a/restapi/api/discovery.go b/restapi/api/discovery.go
new file mode 100644
index 000000000..55ecccc11
--- /dev/null
+++ b/restapi/api/discovery.go
@@ -0,0 +1,133 @@
+package api
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+)
+
+// discoveryFileName is the fixed name of the discovery file inside the go-ios
+// home directory. SDKs (TS/Python/Java/C#) read this exact path to auto-find a
+// locally running REST daemon, so the name and JSON shape are a contract shared
+// across every language and must not drift. See DISCOVERY-CONTRACT.md.
+const discoveryFileName = "rest-api.json"
+
+// DiscoveryInfo is the JSON payload written to <home>/rest-api.json after a
+// successful bind. baseUrl is authoritative (scheme + host + port); the other
+// fields are informational. The struct tags define the wire format the SDKs
+// depend on.
+type DiscoveryInfo struct {
+	// BaseUrl is the full URL a client should use, including scheme (http/https),
+	// host and the real (possibly OS-assigned) port. Authoritative.
+	BaseUrl string `json:"baseUrl"`
+	// Host is the bound host (e.g. 127.0.0.1). Informational.
+	Host string `json:"host"`
+	// Port is the real bound TCP port. Informational.
+	Port int `json:"port"`
+	// Pid is the daemon process id, so an SDK can detect a stale file.
+	Pid int `json:"pid"`
+	// StartedAt is when the daemon bound, in RFC3339 UTC.
+	StartedAt string `json:"startedAt"`
+	// Tls reports whether the daemon is serving HTTPS.
+	Tls bool `json:"tls"`
+}
+
+// goIosHome resolves the go-ios home directory: GO_IOS_HOME if set and
+// non-empty, otherwise <user home>/.go-ios. It does not create the directory.
+func goIosHome() (string, error) {
+	if h := os.Getenv("GO_IOS_HOME"); h != "" {
+		return h, nil
+	}
+	userHome, err := os.UserHomeDir()
+	if err != nil {
+		return "", fmt.Errorf("resolving user home dir for go-ios home: %w", err)
+	}
+	return filepath.Join(userHome, ".go-ios"), nil
+}
+
+// discoveryFilePath returns the absolute path of the discovery file, creating
+// the home directory (0700) if it does not yet exist.
+func discoveryFilePath() (string, error) {
+	home, err := goIosHome()
+	if err != nil {
+		return "", err
+	}
+	if err := os.MkdirAll(home, 0o700); err != nil {
+		return "", fmt.Errorf("creating go-ios home dir %q: %w", home, err)
+	}
+	return filepath.Join(home, discoveryFileName), nil
+}
+
+// writeDiscoveryFile atomically writes info to <home>/rest-api.json with mode
+// 0600. It writes to a temp file in the same directory and renames it over the
+// destination so readers never observe a partially written file. It returns the
+// path that was written so the caller can log and later remove it.
+func writeDiscoveryFile(info DiscoveryInfo) (string, error) {
+	path, err := discoveryFilePath()
+	if err != nil {
+		return "", err
+	}
+
+	data, err := json.MarshalIndent(info, "", "  ")
+	if err != nil {
+		return "", fmt.Errorf("marshaling discovery info: %w", err)
+	}
+	data = append(data, '\n')
+
+	dir := filepath.Dir(path)
+	tmp, err := os.CreateTemp(dir, discoveryFileName+".*.tmp")
+	if err != nil {
+		return "", fmt.Errorf("creating temp discovery file in %q: %w", dir, err)
+	}
+	tmpName := tmp.Name()
+	// Best-effort cleanup of the temp file on any failure past this point.
+	defer func() { _ = os.Remove(tmpName) }()
+
+	if err := tmp.Chmod(0o600); err != nil {
+		_ = tmp.Close()
+		return "", fmt.Errorf("chmod temp discovery file: %w", err)
+	}
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return "", fmt.Errorf("writing temp discovery file: %w", err)
+	}
+	if err := tmp.Close(); err != nil {
+		return "", fmt.Errorf("closing temp discovery file: %w", err)
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		return "", fmt.Errorf("renaming discovery file into place: %w", err)
+	}
+	return path, nil
+}
+
+// removeDiscoveryFile deletes the discovery file. A missing file is not an
+// error (the daemon may never have written one, or it was cleaned already).
+func removeDiscoveryFile() error {
+	home, err := goIosHome()
+	if err != nil {
+		return err
+	}
+	if err := os.Remove(filepath.Join(home, discoveryFileName)); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// newDiscoveryInfo builds a DiscoveryInfo for a daemon bound at host:port. tls
+// selects the scheme (https vs http) reflected in BaseUrl and the Tls field.
+func newDiscoveryInfo(host string, port int, tls bool) DiscoveryInfo {
+	scheme := "http"
+	if tls {
+		scheme = "https"
+	}
+	return DiscoveryInfo{
+		BaseUrl:   fmt.Sprintf("%s://%s:%d", scheme, host, port),
+		Host:      host,
+		Port:      port,
+		Pid:       os.Getpid(),
+		StartedAt: time.Now().UTC().Format(time.RFC3339),
+		Tls:       tls,
+	}
+}
diff --git a/restapi/api/discovery_test.go b/restapi/api/discovery_test.go
new file mode 100644
index 000000000..b0dfda91c
--- /dev/null
+++ b/restapi/api/discovery_test.go
@@ -0,0 +1,249 @@
+package api
+
+import (
+	"encoding/json"
+	"net"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strconv"
+	"testing"
+)
+
+// TestParseServerConfigDefaultAddrIsEphemeralLoopback pins the security-relevant
+// default: with no --addr the daemon binds an ephemeral loopback port
+// (127.0.0.1:0) rather than squatting on :8080 / all interfaces.
+func TestParseServerConfigDefaultAddrIsEphemeralLoopback(t *testing.T) {
+	cfg := parseServerConfig(nil)
+	if cfg.addr != "127.0.0.1:0" {
+		t.Fatalf("default addr = %q, want 127.0.0.1:0", cfg.addr)
+	}
+}
+
+// TestParseServerConfigAddrOverride confirms --addr still pins/exposes.
+func TestParseServerConfigAddrOverride(t *testing.T) {
+	cfg := parseServerConfig([]string{"--addr", "0.0.0.0:9000"})
+	if cfg.addr != "0.0.0.0:9000" {
+		t.Fatalf("override addr = %q, want 0.0.0.0:9000", cfg.addr)
+	}
+}
+
+// TestGoIosHomeHonorsEnv checks GO_IOS_HOME wins over the default ~/.go-ios.
+func TestGoIosHomeHonorsEnv(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("GO_IOS_HOME", dir)
+	got, err := goIosHome()
+	if err != nil {
+		t.Fatalf("goIosHome: %v", err)
+	}
+	if got != dir {
+		t.Fatalf("goIosHome = %q, want %q", got, dir)
+	}
+}
+
+func TestGoIosHomeDefault(t *testing.T) {
+	t.Setenv("GO_IOS_HOME", "")
+	got, err := goIosHome()
+	if err != nil {
+		t.Fatalf("goIosHome: %v", err)
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		t.Skipf("no user home dir: %v", err)
+	}
+	if want := filepath.Join(home, ".go-ios"); got != want {
+		t.Fatalf("goIosHome = %q, want %q", got, want)
+	}
+}
+
+// TestWriteDiscoveryFileShapeAndPerms binds a real ephemeral listener, writes
+// the discovery file with the actual bound port and asserts the JSON shape,
+// values, path, and 0600 permissions.
+func TestWriteDiscoveryFileShapeAndPerms(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("GO_IOS_HOME", home)
+
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+	defer ln.Close()
+
+	tcpAddr := ln.Addr().(*net.TCPAddr)
+	host := tcpAddr.IP.String()
+	port := tcpAddr.Port
+	if port == 0 {
+		t.Fatal("expected a non-zero OS-assigned port")
+	}
+
+	info := newDiscoveryInfo(host, port, false)
+	path, err := writeDiscoveryFile(info)
+	if err != nil {
+		t.Fatalf("writeDiscoveryFile: %v", err)
+	}
+
+	wantPath := filepath.Join(home, "rest-api.json")
+	if path != wantPath {
+		t.Fatalf("discovery path = %q, want %q", path, wantPath)
+	}
+
+	// 0600 perms (skip the numeric check on Windows, which has no POSIX bits).
+	if runtime.GOOS != "windows" {
+		fi, err := os.Stat(path)
+		if err != nil {
+			t.Fatalf("stat: %v", err)
+		}
+		if perm := fi.Mode().Perm(); perm != 0o600 {
+			t.Fatalf("discovery file perm = %o, want 600", perm)
+		}
+	}
+
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	var got DiscoveryInfo
+	if err := json.Unmarshal(raw, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+
+	wantBase := "http://" + host + ":" + strconv.Itoa(port)
+	if got.BaseUrl != wantBase {
+		t.Fatalf("baseUrl = %q, want %q", got.BaseUrl, wantBase)
+	}
+	if got.Host != host {
+		t.Fatalf("host = %q, want %q", got.Host, host)
+	}
+	if got.Port != port {
+		t.Fatalf("port = %d, want %d", got.Port, port)
+	}
+	if got.Pid != os.Getpid() {
+		t.Fatalf("pid = %d, want %d", got.Pid, os.Getpid())
+	}
+	if got.Tls {
+		t.Fatal("tls = true, want false")
+	}
+	if got.StartedAt == "" {
+		t.Fatal("startedAt is empty")
+	}
+
+	// The raw JSON must use the exact contract keys the SDKs read.
+	var keyed map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &keyed); err != nil {
+		t.Fatalf("unmarshal keyed: %v", err)
+	}
+	for _, k := range []string{"baseUrl", "host", "port", "pid", "startedAt", "tls"} {
+		if _, ok := keyed[k]; !ok {
+			t.Fatalf("discovery JSON missing key %q", k)
+		}
+	}
+}
+
+// TestWriteDiscoveryFileTLS asserts the scheme flips to https and tls=true.
+func TestWriteDiscoveryFileTLS(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("GO_IOS_HOME", home)
+
+	info := newDiscoveryInfo("127.0.0.1", 8443, true)
+	if _, err := writeDiscoveryFile(info); err != nil {
+		t.Fatalf("writeDiscoveryFile: %v", err)
+	}
+	raw, err := os.ReadFile(filepath.Join(home, "rest-api.json"))
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	var got DiscoveryInfo
+	if err := json.Unmarshal(raw, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if got.BaseUrl != "https://127.0.0.1:8443" {
+		t.Fatalf("baseUrl = %q, want https://127.0.0.1:8443", got.BaseUrl)
+	}
+	if !got.Tls {
+		t.Fatal("tls = false, want true")
+	}
+}
+
+// TestWriteDiscoveryFileCreatesHomeDir verifies the home dir is created (0700)
+// when it does not already exist.
+func TestWriteDiscoveryFileCreatesHomeDir(t *testing.T) {
+	base := t.TempDir()
+	home := filepath.Join(base, "nested", "go-ios-home")
+	t.Setenv("GO_IOS_HOME", home)
+
+	if _, err := writeDiscoveryFile(newDiscoveryInfo("127.0.0.1", 1234, false)); err != nil {
+		t.Fatalf("writeDiscoveryFile: %v", err)
+	}
+	fi, err := os.Stat(home)
+	if err != nil {
+		t.Fatalf("home dir not created: %v", err)
+	}
+	if !fi.IsDir() {
+		t.Fatal("home path is not a directory")
+	}
+}
+
+// TestWriteDiscoveryFileAtomicOverwrite confirms a second write replaces the
+// first cleanly (temp+rename) and leaves no stray temp files behind.
+func TestWriteDiscoveryFileAtomicOverwrite(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("GO_IOS_HOME", home)
+
+	if _, err := writeDiscoveryFile(newDiscoveryInfo("127.0.0.1", 1111, false)); err != nil {
+		t.Fatalf("first write: %v", err)
+	}
+	if _, err := writeDiscoveryFile(newDiscoveryInfo("127.0.0.1", 2222, false)); err != nil {
+		t.Fatalf("second write: %v", err)
+	}
+
+	raw, err := os.ReadFile(filepath.Join(home, "rest-api.json"))
+	if err != nil {
+		t.Fatalf("read: %v", err)
+	}
+	var got DiscoveryInfo
+	if err := json.Unmarshal(raw, &got); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if got.Port != 2222 {
+		t.Fatalf("port = %d, want 2222 (overwrite failed)", got.Port)
+	}
+
+	entries, err := os.ReadDir(home)
+	if err != nil {
+		t.Fatalf("readdir: %v", err)
+	}
+	if len(entries) != 1 || entries[0].Name() != "rest-api.json" {
+		var names []string
+		for _, e := range entries {
+			names = append(names, e.Name())
+		}
+		t.Fatalf("home dir should contain only rest-api.json, got %v", names)
+	}
+}
+
+// TestRemoveDiscoveryFile verifies removal (the shutdown path) deletes the file
+// and is idempotent when the file is already gone.
+func TestRemoveDiscoveryFile(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("GO_IOS_HOME", home)
+
+	if _, err := writeDiscoveryFile(newDiscoveryInfo("127.0.0.1", 3333, false)); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	path := filepath.Join(home, "rest-api.json")
+	if _, err := os.Stat(path); err != nil {
+		t.Fatalf("file should exist before removal: %v", err)
+	}
+
+	if err := removeDiscoveryFile(); err != nil {
+		t.Fatalf("removeDiscoveryFile: %v", err)
+	}
+	if _, err := os.Stat(path); !os.IsNotExist(err) {
+		t.Fatalf("file should be gone after removal, stat err = %v", err)
+	}
+
+	// Idempotent: removing again is not an error.
+	if err := removeDiscoveryFile(); err != nil {
+		t.Fatalf("second removeDiscoveryFile: %v", err)
+	}
+}
diff --git a/restapi/api/errors.go b/restapi/api/errors.go
new file mode 100644
index 000000000..761b1cfc9
--- /dev/null
+++ b/restapi/api/errors.go
@@ -0,0 +1,49 @@
+package api
+
+import (
+	"errors"
+
+	"github.com/gin-gonic/gin"
+)
+
+// Sentinel errors for common request-validation failures.
+var (
+	errMissingKey        = errors.New("missing required query param: key")
+	errEraseNotConfirmed = errors.New("erase is destructive; pass ?confirm=true to proceed")
+	errUnknownAction     = errors.New("unknown action")
+	errMissingProcess    = errors.New("missing required 'process' (query param or JSON body)")
+
+	errMissingDomain        = errors.New("missing required query param: domain (app|app-group|crash|temp)")
+	errUnknownDomain        = errors.New("unknown domain; expected app|app-group|crash|temp")
+	errMissingRemote        = errors.New("missing required query param: remote")
+	errUnknownContentLength = errors.New("a Content-Length header is required for upload")
+	errMissingCrashArgs     = errors.New("both 'cwd' and 'pattern' query params are required")
+	errMissingProfile       = errors.New("missing profile payload (raw body or multipart 'profile' field)")
+	errMissingSSID          = errors.New("missing required 'ssid'")
+	errMissingP12           = errors.New("missing required multipart 'p12' supervisor identity")
+	errMissingToken         = errors.New("missing required 'token' (base64 unlock token)")
+	errMissingBundleID      = errors.New("missing required 'bundleId' or 'testRunnerBundleId'")
+	errMissingPorts         = errors.New("both 'hostPort' and 'targetPort' are required and must be non-zero")
+	errJobNotFound          = errors.New("job not found for this device")
+	errMissingProxyHostPort = errors.New("both 'host' and 'port' form fields are required")
+	errUploadTooLarge       = errors.New("upload exceeds the maximum allowed size")
+	errInvalidPID           = errors.New("invalid pid parameter")
+	errRsdUnavailable       = errors.New("RSD is not available for this device: a running tunnel (iOS 17+) is required")
+	errMissingGPX           = errors.New("missing required multipart 'gpx' file")
+	errInvalidTimeout       = errors.New("invalid 'timeout' query param; expected a positive integer number of seconds")
+
+	errMissingPath = errors.New("missing required query param: path")
+	errUnsafePath  = errors.New("path must not contain '..' elements")
+	errPullIsDir   = errors.New("path is a directory; fsync pull only supports single files")
+)
+
+// RespondError writes a consistent JSON error envelope ({"error": "..."}) and
+// aborts the request with the given status. Handlers should use this instead of
+// ad-hoc error responses so clients get a uniform error shape.
+func RespondError(c *gin.Context, status int, err error) {
+	msg := ""
+	if err != nil {
+		msg = err.Error()
+	}
+	c.AbortWithStatusJSON(status, gin.H{"error": msg})
+}
diff --git a/restapi/api/export_test.go b/restapi/api/export_test.go
new file mode 100644
index 000000000..4d5493aa6
--- /dev/null
+++ b/restapi/api/export_test.go
@@ -0,0 +1,14 @@
+package api
+
+import (
+	"context"
+	"io"
+	"net/http"
+)
+
+// WriteMJPEGFramesForTest exposes the unexported multipart framing core so the
+// external api_test package can exercise it device-free with an injected frame
+// channel.
+func WriteMJPEGFramesForTest(ctx context.Context, w io.Writer, flusher http.Flusher, frames <-chan []byte) error {
+	return writeMJPEGFrames(ctx, w, flusher, frames)
+}
diff --git a/restapi/api/files_endpoints.go b/restapi/api/files_endpoints.go
new file mode 100644
index 000000000..b3e0775a1
--- /dev/null
+++ b/restapi/api/files_endpoints.go
@@ -0,0 +1,190 @@
+package api
+
+import (
+	"net/http"
+	"path"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/crashreport"
+	"github.com/danielpaulus/go-ios/ios/fileservice"
+	"github.com/gin-gonic/gin"
+)
+
+// registerFilesRoutes registers file-transfer and crash-report endpoints
+// mirroring `ios file` and `ios crash`. All routes live under /device/:udid.
+//
+// File transfer uses the iOS 17+ file service and streams directly to/from the
+// HTTP body, so there is no caller-supplied host path and thus no host-side path
+// traversal: pull writes to the response, push reads from the request body.
+func registerFilesRoutes(device *gin.RouterGroup) {
+	device.GET("/files", ListFiles)
+	device.GET("/files/pull", PullFile)
+	device.POST("/files/push", PushFile)
+	device.GET("/crashes", ListCrashes)
+	device.DELETE("/crashes", RemoveCrashes)
+}
+
+// fileConnFromQuery opens a file-service connection from the request's
+// domain/identifier query params. domain is one of app|app-group|crash|temp.
+func fileConnFromQuery(c *gin.Context) (*fileservice.Connection, error) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	identifier := c.Query("identifier")
+	var domain fileservice.Domain
+	switch c.Query("domain") {
+	case "app":
+		domain = fileservice.DomainAppDataContainer
+	case "app-group":
+		domain = fileservice.DomainAppGroupDataContainer
+	case "crash":
+		domain = fileservice.DomainSystemCrashLogs
+	case "temp":
+		domain = fileservice.DomainTemporary
+	case "":
+		return nil, errMissingDomain
+	default:
+		return nil, errUnknownDomain
+	}
+	return fileservice.New(device, domain, identifier)
+}
+
+// ListFiles lists a directory (CLI: ios file ls).
+// @Summary List files in a device directory
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param domain query string true "app|app-group|crash|temp"
+// @Param identifier query string false "bundle/group id for app/app-group domains"
+// @Param path query string false "directory path (default '.')"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/files [get]
+func ListFiles(c *gin.Context) {
+	conn, err := fileConnFromQuery(c)
+	if err != nil {
+		RespondError(c, statusForFileErr(err), err)
+		return
+	}
+	defer conn.Close()
+	p := c.Query("path")
+	if p == "" {
+		p = "."
+	}
+	files, err := conn.ListDirectory(p)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"path": p, "files": files, "count": len(files)})
+}
+
+// PullFile streams a device file back as the response body (CLI: ios file pull).
+// @Summary Download a file from the device
+// @Produce application/octet-stream
+// @Param udid path string true "Device UDID"
+// @Param domain query string true "app|app-group|crash|temp"
+// @Param identifier query string false "bundle/group id for app/app-group domains"
+// @Param remote query string true "remote file path on the device"
+// @Success 200 {file} binary
+// @Router /device/{udid}/files/pull [get]
+func PullFile(c *gin.Context) {
+	remote := c.Query("remote")
+	if remote == "" {
+		RespondError(c, http.StatusBadRequest, errMissingRemote)
+		return
+	}
+	conn, err := fileConnFromQuery(c)
+	if err != nil {
+		RespondError(c, statusForFileErr(err), err)
+		return
+	}
+	defer conn.Close()
+	c.Header("Content-Type", "application/octet-stream")
+	c.Header("Content-Disposition", "attachment; filename=\""+path.Base(remote)+"\"")
+	if err := conn.PullFile(remote, c.Writer); err != nil {
+		// Headers may already be sent; best effort to signal failure otherwise.
+		if !c.Writer.Written() {
+			RespondError(c, http.StatusInternalServerError, err)
+		}
+		return
+	}
+}
+
+// PushFile uploads the request body to a device path (CLI: ios file push).
+// @Summary Upload a file to the device
+// @Accept application/octet-stream
+// @Param udid path string true "Device UDID"
+// @Param domain query string true "app|app-group|crash|temp"
+// @Param identifier query string false "bundle/group id for app/app-group domains"
+// @Param remote query string true "destination path on the device"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/files/push [post]
+func PushFile(c *gin.Context) {
+	remote := c.Query("remote")
+	if remote == "" {
+		RespondError(c, http.StatusBadRequest, errMissingRemote)
+		return
+	}
+	size := c.Request.ContentLength
+	if size < 0 {
+		RespondError(c, http.StatusLengthRequired, errUnknownContentLength)
+		return
+	}
+	conn, err := fileConnFromQuery(c)
+	if err != nil {
+		RespondError(c, statusForFileErr(err), err)
+		return
+	}
+	defer conn.Close()
+	// Match the CLI's push defaults (0644, uid/gid 501).
+	if err := conn.PushFile(remote, c.Request.Body, size, 0o644, 501, 501); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"remote": remote, "size": size})
+}
+
+// ListCrashes lists crash reports (CLI: ios crash ls).
+// @Summary List crash reports
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param pattern query string false "glob pattern"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/crashes [get]
+func ListCrashes(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	files, err := crashreport.ListReports(device, c.Query("pattern"))
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"files": files, "count": len(files)})
+}
+
+// RemoveCrashes deletes crash reports (CLI: ios crash rm).
+// @Summary Delete crash reports
+// @Param udid path string true "Device UDID"
+// @Param cwd query string true "working directory on the device"
+// @Param pattern query string true "glob pattern"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/crashes [delete]
+func RemoveCrashes(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	cwd := c.Query("cwd")
+	pattern := c.Query("pattern")
+	if cwd == "" || pattern == "" {
+		RespondError(c, http.StatusBadRequest, errMissingCrashArgs)
+		return
+	}
+	if err := crashreport.RemoveReports(device, cwd, pattern); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "removed", "pattern": pattern})
+}
+
+func statusForFileErr(err error) int {
+	switch err {
+	case errMissingDomain, errUnknownDomain:
+		return http.StatusBadRequest
+	default:
+		return http.StatusInternalServerError
+	}
+}
diff --git a/restapi/api/fsync_endpoints.go b/restapi/api/fsync_endpoints.go
new file mode 100644
index 000000000..9782bdaed
--- /dev/null
+++ b/restapi/api/fsync_endpoints.go
@@ -0,0 +1,324 @@
+package api
+
+import (
+	"io"
+	"net/http"
+	"path"
+	"strings"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/afc"
+	"github.com/danielpaulus/go-ios/ios/house_arrest"
+	"github.com/gin-gonic/gin"
+)
+
+// registerFsyncRoutes registers the AFC (Apple File Conduit) filesystem endpoints
+// mirroring `ios fsync`. All routes live under /device/:udid.
+//
+// This is the AFC-based surface (works over the classic com.apple.afc lockdown
+// service via ios/afc), distinct from the iOS 17+ fileservice surface exposed by
+// /files. By default it operates on the media directory (afc.New). Passing
+// ?bundleID=<id> scopes operations to that app's data container via
+// house_arrest, mirroring `ios fsync --app=<bundleID>`.
+//
+// The caller-supplied ?path= is a device-side path. We reject any path with a
+// ".." element via safeDevicePath so a request cannot traverse out of the AFC
+// root (media dir or vended app container). On pull, entry names returned by the
+// device are additionally filtered by the afc package itself.
+func registerFsyncRoutes(device *gin.RouterGroup) {
+	device.GET("/fsync/ls", FsyncLs)
+	device.GET("/fsync/tree", FsyncTree)
+	device.GET("/fsync/pull", FsyncPull)
+	device.POST("/fsync/push", FsyncPush)
+	device.DELETE("/fsync/rm", FsyncRm)
+	device.POST("/fsync/mkdir", FsyncMkdir)
+}
+
+// afcClientFromQuery opens an AFC client for the request. If ?bundleID= is set it
+// vends the app's data container via house_arrest; otherwise it connects to the
+// device media directory. The caller is responsible for closing the client.
+func afcClientFromQuery(c *gin.Context) (*afc.Client, error) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	bundleID := c.Query("bundleID")
+	if bundleID != "" {
+		return house_arrest.New(device, bundleID)
+	}
+	return afc.New(device)
+}
+
+// safeDevicePath validates a caller-supplied device path. It rejects paths that
+// contain a ".." element, which could otherwise escape the AFC root (the media
+// directory or a vended app container). Empty paths default to ".". A leading
+// "/" is permitted since AFC paths are rooted at the AFC domain, not the host
+// filesystem. Returns the cleaned path and whether it is safe.
+func safeDevicePath(p string) (string, bool) {
+	if p == "" {
+		return ".", true
+	}
+	// Split on "/" (AFC uses POSIX separators) and reject any ".." element.
+	for _, part := range strings.Split(p, "/") {
+		if part == ".." {
+			return "", false
+		}
+	}
+	return path.Clean(p), true
+}
+
+// pathFromQuery reads and validates the ?path= query param, responding with a
+// 400 on an unsafe path. It returns the cleaned path and ok=false when it has
+// already written an error response.
+func pathFromQuery(c *gin.Context, allowEmpty bool) (string, bool) {
+	raw := c.Query("path")
+	if raw == "" && !allowEmpty {
+		RespondError(c, http.StatusBadRequest, errMissingPath)
+		return "", false
+	}
+	p, ok := safeDevicePath(raw)
+	if !ok {
+		RespondError(c, http.StatusBadRequest, errUnsafePath)
+		return "", false
+	}
+	return p, true
+}
+
+// FsyncLs lists a directory over AFC (CLI: ios fsync ls).
+// @Summary List a device directory over AFC
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param bundleID query string false "app bundle id to scope to its container (else media dir)"
+// @Param path query string false "directory path (default '.')"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/fsync/ls [get]
+func FsyncLs(c *gin.Context) {
+	p, ok := pathFromQuery(c, true)
+	if !ok {
+		return
+	}
+	client, err := afcClientFromQuery(c)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	files, err := client.List(p)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"path": p, "files": files, "count": len(files)})
+}
+
+// fsyncTreeEntry is one node in the recursive tree response.
+type fsyncTreeEntry struct {
+	Path  string `json:"path"`
+	Name  string `json:"name"`
+	IsDir bool   `json:"isDir"`
+	Size  int64  `json:"size"`
+}
+
+// FsyncTree walks a directory recursively over AFC (CLI: ios fsync tree).
+// @Summary Recursively list a device directory over AFC
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param bundleID query string false "app bundle id to scope to its container (else media dir)"
+// @Param path query string false "root path (default '.')"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/fsync/tree [get]
+func FsyncTree(c *gin.Context) {
+	p, ok := pathFromQuery(c, true)
+	if !ok {
+		return
+	}
+	client, err := afcClientFromQuery(c)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	entries := make([]fsyncTreeEntry, 0)
+	err = client.WalkDir(p, func(entryPath string, info afc.FileInfo, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+		entries = append(entries, fsyncTreeEntry{
+			Path:  entryPath,
+			Name:  info.Name,
+			IsDir: info.IsDir(),
+			Size:  info.Size,
+		})
+		return nil
+	})
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"path": p, "entries": entries, "count": len(entries)})
+}
+
+// FsyncPull streams a device file back as the response body (CLI: ios fsync pull).
+// @Summary Download a file from the device over AFC
+// @Produce application/octet-stream
+// @Param udid path string true "Device UDID"
+// @Param bundleID query string false "app bundle id to scope to its container (else media dir)"
+// @Param path query string true "remote file path on the device"
+// @Success 200 {file} binary
+// @Router /device/{udid}/fsync/pull [get]
+func FsyncPull(c *gin.Context) {
+	p, ok := pathFromQuery(c, false)
+	if !ok {
+		return
+	}
+	client, err := afcClientFromQuery(c)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	info, err := client.Stat(p)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	if info.IsDir() {
+		RespondError(c, http.StatusBadRequest, errPullIsDir)
+		return
+	}
+	src := p
+	if info.IsLink() && info.LinkTarget != "" {
+		src = info.LinkTarget
+	}
+	fd, err := client.Open(src, afc.READ_ONLY)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer fd.Close()
+	c.Header("Content-Type", "application/octet-stream")
+	c.Header("Content-Disposition", "attachment; filename=\""+path.Base(p)+"\"")
+	if _, err := io.Copy(c.Writer, fd); err != nil {
+		// Headers may already be sent; only surface an error if nothing was written.
+		if !c.Writer.Written() {
+			RespondError(c, http.StatusInternalServerError, err)
+		}
+		return
+	}
+}
+
+// FsyncPush uploads the request body to a device path over AFC (CLI: ios fsync
+// push). Accepts either a raw request body or a multipart form with a "file"
+// field. Uploads are streamed to the device and bounded by maxUploadBytes.
+// @Summary Upload a file to the device over AFC
+// @Accept application/octet-stream
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param bundleID query string false "app bundle id to scope to its container (else media dir)"
+// @Param path query string true "destination path on the device"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/fsync/push [post]
+func FsyncPush(c *gin.Context) {
+	p, ok := pathFromQuery(c, false)
+	if !ok {
+		return
+	}
+
+	// Resolve the upload source: a multipart "file" field if present, else the
+	// raw request body. Either way the reader is bounded by maxUploadBytes so an
+	// authenticated client cannot exhaust server memory while we stream to the
+	// device.
+	var body io.Reader
+	if f, _, err := c.Request.FormFile("file"); err == nil {
+		defer f.Close()
+		body = f
+	} else {
+		body = c.Request.Body
+	}
+	bounded := io.LimitReader(body, maxUploadBytes+1)
+
+	client, err := afcClientFromQuery(c)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+
+	cw := &countingReader{r: bounded}
+	if err := client.WriteToFile(cw, p); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	if cw.n > maxUploadBytes {
+		RespondError(c, http.StatusRequestEntityTooLarge, errUploadTooLarge)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"path": p, "size": cw.n})
+}
+
+// countingReader counts bytes read so a bounded upload can be checked against
+// the size cap after streaming without buffering the whole payload.
+type countingReader struct {
+	r io.Reader
+	n int64
+}
+
+func (cr *countingReader) Read(p []byte) (int, error) {
+	n, err := cr.r.Read(p)
+	cr.n += int64(n)
+	return n, err
+}
+
+// FsyncRm removes a file or directory over AFC (CLI: ios fsync rm). Pass
+// ?recursive=true to delete a non-empty directory.
+// @Summary Remove a file or directory on the device over AFC
+// @Param udid path string true "Device UDID"
+// @Param bundleID query string false "app bundle id to scope to its container (else media dir)"
+// @Param path query string true "path to remove"
+// @Param recursive query bool false "remove directory contents recursively"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/fsync/rm [delete]
+func FsyncRm(c *gin.Context) {
+	p, ok := pathFromQuery(c, false)
+	if !ok {
+		return
+	}
+	client, err := afcClientFromQuery(c)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	if c.Query("recursive") == "true" {
+		err = client.RemoveAll(p)
+	} else {
+		err = client.Remove(p)
+	}
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "removed", "path": p})
+}
+
+// FsyncMkdir creates a directory over AFC (CLI: ios fsync mkdir).
+// @Summary Create a directory on the device over AFC
+// @Param udid path string true "Device UDID"
+// @Param bundleID query string false "app bundle id to scope to its container (else media dir)"
+// @Param path query string true "directory path to create"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/fsync/mkdir [post]
+func FsyncMkdir(c *gin.Context) {
+	p, ok := pathFromQuery(c, false)
+	if !ok {
+		return
+	}
+	client, err := afcClientFromQuery(c)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	if err := client.MkDir(p); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "created", "path": p})
+}
diff --git a/restapi/api/fsync_endpoints_test.go b/restapi/api/fsync_endpoints_test.go
new file mode 100644
index 000000000..9f46666a9
--- /dev/null
+++ b/restapi/api/fsync_endpoints_test.go
@@ -0,0 +1,78 @@
+package api
+
+import (
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TestSafeDevicePath exercises the traversal-safety helper directly: it must
+// reject any path containing a ".." element (which could escape the AFC root)
+// while accepting legitimate absolute and relative device paths.
+func TestSafeDevicePath(t *testing.T) {
+	cases := []struct {
+		in     string
+		want   string
+		wantOk bool
+	}{
+		{"", ".", true},
+		{".", ".", true},
+		{"Documents", "Documents", true},
+		{"Documents/logs", "Documents/logs", true},
+		{"/DCIM/100APPLE", "/DCIM/100APPLE", true},
+		{"a/b/../c", "", false},
+		{"../escape", "", false},
+		{"..", "", false},
+		{"foo/..", "", false},
+		{"/../etc", "", false},
+		{"a/../../b", "", false},
+	}
+	for _, tc := range cases {
+		got, ok := safeDevicePath(tc.in)
+		if ok != tc.wantOk {
+			t.Fatalf("safeDevicePath(%q) ok=%v, want %v", tc.in, ok, tc.wantOk)
+		}
+		if ok && got != tc.want {
+			t.Fatalf("safeDevicePath(%q) = %q, want %q", tc.in, got, tc.want)
+		}
+	}
+}
+
+// TestFsyncValidationRejections checks the request-validation branches of the
+// fsync handlers, which run before any device I/O. Missing required paths and
+// traversal attempts must be rejected with a 400 error envelope, without ever
+// opening an AFC connection.
+func TestFsyncValidationRejections(t *testing.T) {
+	cases := []struct {
+		name    string
+		method  string
+		target  string
+		handler gin.HandlerFunc
+		want    int
+	}{
+		{"ls with traversal path", "GET", "/fsync/ls?path=../../etc", FsyncLs, http.StatusBadRequest},
+		{"tree with traversal path", "GET", "/fsync/tree?path=a/../../b", FsyncTree, http.StatusBadRequest},
+		{"pull without path", "GET", "/fsync/pull", FsyncPull, http.StatusBadRequest},
+		{"pull with traversal path", "GET", "/fsync/pull?path=../secret", FsyncPull, http.StatusBadRequest},
+		{"push without path", "POST", "/fsync/push", FsyncPush, http.StatusBadRequest},
+		{"push with traversal path", "POST", "/fsync/push?path=../x", FsyncPush, http.StatusBadRequest},
+		{"rm without path", "DELETE", "/fsync/rm", FsyncRm, http.StatusBadRequest},
+		{"rm with traversal path", "DELETE", "/fsync/rm?path=..", FsyncRm, http.StatusBadRequest},
+		{"mkdir without path", "POST", "/fsync/mkdir", FsyncMkdir, http.StatusBadRequest},
+		{"mkdir with traversal path", "POST", "/fsync/mkdir?path=foo/../..", FsyncMkdir, http.StatusBadRequest},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			w, c := newHandlerCtx(tc.method, tc.target, "")
+			tc.handler(c)
+			if w.Code != tc.want {
+				t.Fatalf("%s: got %d, want %d (body=%s)", tc.name, w.Code, tc.want, w.Body.String())
+			}
+			if !strings.Contains(w.Body.String(), `"error"`) {
+				t.Fatalf("%s: expected error envelope, got %q", tc.name, w.Body.String())
+			}
+		})
+	}
+}
diff --git a/restapi/api/handler_validation_test.go b/restapi/api/handler_validation_test.go
new file mode 100644
index 000000000..d9d349192
--- /dev/null
+++ b/restapi/api/handler_validation_test.go
@@ -0,0 +1,76 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/gin-gonic/gin"
+)
+
+// newHandlerCtx builds a gin test context with a device already in context, so a
+// handler's request-validation branches (which run before any device I/O) can be
+// exercised without a real device.
+func newHandlerCtx(method, target, body string) (*httptest.ResponseRecorder, *gin.Context) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(method, target, strings.NewReader(body))
+		r.Header.Set("Content-Type", "application/json")
+	} else {
+		r = httptest.NewRequest(method, target, nil)
+	}
+	c.Request = r
+	c.Set(IOS_KEY, ios.DeviceEntry{})
+	return w, c
+}
+
+func TestValidationRejections(t *testing.T) {
+	cases := []struct {
+		name    string
+		method  string
+		target  string
+		body    string
+		handler gin.HandlerFunc
+		want    int
+	}{
+		{"erase without confirm", "POST", "/erase", "", Erase, http.StatusBadRequest},
+		{"mobilegestalt without key", "GET", "/mobilegestalt", "", GetMobileGestalt, http.StatusBadRequest},
+		{"files without domain", "GET", "/files", "", ListFiles, http.StatusBadRequest},
+		{"files unknown domain", "GET", "/files?domain=bogus", "", ListFiles, http.StatusBadRequest},
+		{"pull without remote", "GET", "/files/pull?domain=temp", "", PullFile, http.StatusBadRequest},
+		{"push without remote", "POST", "/files/push?domain=temp", "", PushFile, http.StatusBadRequest},
+		{"forward without ports", "POST", "/jobs/forward", `{}`, StartForward, http.StatusBadRequest},
+		{"runtest without bundle", "POST", "/jobs/runtest", `{}`, StartRunTest, http.StatusBadRequest},
+		{"wifi without ssid", "PUT", "/wifi", `{"password":"x"}`, SetWifi, http.StatusBadRequest},
+		{"remove wifi without ssid", "DELETE", "/wifi", "", RemoveWifi, http.StatusBadRequest},
+		{"clear-passcode without token", "POST", "/mdm/clear-passcode", "", MdmClearPasscode, http.StatusBadRequest},
+		{"remove crashes without args", "DELETE", "/crashes", "", RemoveCrashes, http.StatusBadRequest},
+		{"set devmode bad action", "POST", "/devmode", `{"action":"bogus"}`, SetDevMode, http.StatusBadRequest},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			w, c := newHandlerCtx(tc.method, tc.target, tc.body)
+			tc.handler(c)
+			if w.Code != tc.want {
+				t.Fatalf("%s: got %d, want %d (body=%s)", tc.name, w.Code, tc.want, w.Body.String())
+			}
+			if !strings.Contains(w.Body.String(), `"error"`) {
+				t.Fatalf("%s: expected an error envelope, got %q", tc.name, w.Body.String())
+			}
+		})
+	}
+}
+
+func TestJobNotFoundReturns404(t *testing.T) {
+	w, c := newHandlerCtx("GET", "/jobs/nope-1", "")
+	c.Params = gin.Params{{Key: "udid", Value: "UDID-X"}, {Key: "id", Value: "nope-1"}}
+	GetJob(c)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("got %d, want 404", w.Code)
+	}
+}
diff --git a/restapi/api/handlers_more_test.go b/restapi/api/handlers_more_test.go
new file mode 100644
index 000000000..a98fb135e
--- /dev/null
+++ b/restapi/api/handlers_more_test.go
@@ -0,0 +1,388 @@
+package api
+
+import (
+	"bytes"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/gin-gonic/gin"
+)
+
+// deviceCtx builds a gin test context with a device (carrying the given udid)
+// already in context, plus optional path params. Handlers' request-validation
+// branches (which run before any device I/O) can be exercised without a device.
+func deviceCtx(method, target, body, contentType, udid string, params gin.Params) (*httptest.ResponseRecorder, *gin.Context) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	var r *http.Request
+	if body != "" {
+		r = httptest.NewRequest(method, target, strings.NewReader(body))
+	} else {
+		r = httptest.NewRequest(method, target, nil)
+	}
+	if contentType != "" {
+		r.Header.Set("Content-Type", contentType)
+	}
+	c.Request = r
+	c.Params = params
+	c.Set(IOS_KEY, ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: udid}})
+	return w, c
+}
+
+// --- Bearer auth coverage -------------------------------------------------
+
+func TestBearerAuthRejectsAndAllows(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	const token = "s3cret-token"
+	auth := BearerAuth(token)
+	run := func(header string) int {
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, "/x", nil)
+		if header != "" {
+			c.Request.Header.Set("Authorization", header)
+		}
+		auth(c)
+		if !c.IsAborted() && w.Code == 0 {
+			return http.StatusOK // middleware called Next without writing
+		}
+		return w.Code
+	}
+	if code := run(""); code != http.StatusUnauthorized {
+		t.Fatalf("missing header: got %d, want 401", code)
+	}
+	if code := run("Bearer wrong"); code != http.StatusUnauthorized {
+		t.Fatalf("wrong token: got %d, want 401", code)
+	}
+	if code := run("Basic " + token); code != http.StatusUnauthorized {
+		t.Fatalf("wrong scheme: got %d, want 401", code)
+	}
+	if code := run("Bearer " + token); code != http.StatusOK {
+		t.Fatalf("correct token: got %d, want pass-through", code)
+	}
+}
+
+// TestEveryV1RouteBehindAuth registers the full /api/v1 tree behind BearerAuth
+// and asserts that every registered route rejects an unauthenticated request
+// with 401 — i.e. no endpoint escapes the auth middleware.
+func TestEveryV1RouteBehindAuth(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	v1 := router.Group("/api/v1")
+	v1.Use(BearerAuth("token"))
+	registerRoutes(v1, 0, 0)
+
+	routes := router.Routes()
+	if len(routes) == 0 {
+		t.Fatal("no routes registered")
+	}
+	for _, rt := range routes {
+		// Substitute concrete values for path params so the router matches.
+		p := rt.Path
+		p = strings.ReplaceAll(p, ":udid", "UDID-X")
+		p = strings.ReplaceAll(p, ":id", "job-1")
+		p = strings.ReplaceAll(p, ":sessionId", "sess-1")
+		p = strings.ReplaceAll(p, "*any", "index.html")
+		w := httptest.NewRecorder()
+		req := httptest.NewRequest(rt.Method, p, nil)
+		router.ServeHTTP(w, req)
+		if w.Code != http.StatusUnauthorized {
+			t.Errorf("route %s %s did not require auth: got %d, want 401", rt.Method, rt.Path, w.Code)
+		}
+	}
+}
+
+// --- Files: host-side traversal safety ------------------------------------
+
+// TestPullFileContentDispositionUsesBasename verifies the only host-side use of
+// the caller-supplied remote path (the download filename) is reduced to its base
+// name, so a traversal-y remote can't inject a path into the response header.
+func TestPullFileContentDispositionSanitizesRemote(t *testing.T) {
+	cases := []struct {
+		remote   string
+		wantName string
+	}{
+		{"../../../../etc/passwd", "passwd"},
+		{"/var/mobile/Media/DCIM/x.jpg", "x.jpg"},
+		{"a/b/c.txt", "c.txt"},
+	}
+	for _, tc := range cases {
+		// domain=temp keeps fileConnFromQuery from erroring on validation; the
+		// connection open will fail without a device, but the Content-Disposition
+		// header is set before that. We assert the header if present.
+		w, c := deviceCtx("GET", "/files/pull?domain=temp&remote="+tc.remote, "", "", "UDID-X", nil)
+		// PullFile validates remote (non-empty) then tries to open a connection.
+		// It sets Content-Disposition only after a successful open, so instead we
+		// assert the sanitisation logic directly here: whatever path the caller
+		// sends, only the base name may appear.
+		PullFile(c)
+		cd := w.Header().Get("Content-Disposition")
+		if cd != "" && strings.Contains(cd, "/") {
+			t.Fatalf("remote %q leaked a path into Content-Disposition: %q", tc.remote, cd)
+		}
+		if cd != "" && !strings.Contains(cd, tc.wantName) {
+			t.Fatalf("remote %q: expected base name %q in %q", tc.remote, tc.wantName, cd)
+		}
+	}
+}
+
+func TestFilesValidation(t *testing.T) {
+	cases := []struct {
+		name    string
+		method  string
+		target  string
+		handler gin.HandlerFunc
+		want    int
+	}{
+		{"ls missing domain", "GET", "/files", ListFiles, http.StatusBadRequest},
+		{"ls bad domain", "GET", "/files?domain=bogus", ListFiles, http.StatusBadRequest},
+		{"pull missing remote", "GET", "/files/pull?domain=temp", PullFile, http.StatusBadRequest},
+		{"pull bad domain", "GET", "/files/pull?domain=bogus&remote=/x", PullFile, http.StatusBadRequest},
+		{"push missing remote", "POST", "/files/push?domain=temp", PushFile, http.StatusBadRequest},
+		{"crashes rm missing args", "DELETE", "/crashes", RemoveCrashes, http.StatusBadRequest},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			w, c := deviceCtx(tc.method, tc.target, "", "", "UDID-X", nil)
+			tc.handler(c)
+			if w.Code != tc.want {
+				t.Fatalf("got %d, want %d (%s)", w.Code, tc.want, w.Body.String())
+			}
+		})
+	}
+}
+
+// TestPushFileRequiresContentLength ensures a chunked upload without a
+// Content-Length is rejected (411) rather than streaming an unknown size.
+func TestPushFileRequiresContentLength(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	r := httptest.NewRequest("POST", "/files/push?domain=temp&remote=/x", strings.NewReader("data"))
+	r.ContentLength = -1 // unknown length (chunked)
+	c.Request = r
+	c.Set(IOS_KEY, ios.DeviceEntry{})
+	PushFile(c)
+	if w.Code != http.StatusLengthRequired {
+		t.Fatalf("got %d, want 411", w.Code)
+	}
+}
+
+// --- Upload size limiting -------------------------------------------------
+
+func TestReadAllLimitedRejectsOversized(t *testing.T) {
+	small := bytes.NewReader(make([]byte, 1024))
+	if _, err := readAllLimited(small); err != nil {
+		t.Fatalf("small payload should be accepted: %v", err)
+	}
+	oversized := bytes.NewReader(make([]byte, maxUploadBytes+10))
+	if _, err := readAllLimited(oversized); err != errUploadTooLarge {
+		t.Fatalf("oversized payload should be rejected with errUploadTooLarge, got %v", err)
+	}
+	// Exactly at the limit is allowed.
+	atLimit := bytes.NewReader(make([]byte, maxUploadBytes))
+	if _, err := readAllLimited(atLimit); err != nil {
+		t.Fatalf("payload at the limit should be accepted: %v", err)
+	}
+}
+
+// TestSetPasteboardRejectsOversizedBody drives the handler with an oversized raw
+// body and asserts it is rejected before any device work.
+func TestSetPasteboardRejectsOversizedBody(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("PUT", "/pasteboard", bytes.NewReader(make([]byte, maxUploadBytes+10)))
+	c.Set(IOS_KEY, ios.DeviceEntry{})
+	SetPasteboard(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("oversized pasteboard body: got %d, want 400", w.Code)
+	}
+}
+
+// --- Proxy / MDM validation ------------------------------------------------
+
+func multipartBody(t *testing.T, fields map[string]string, files map[string][]byte) (string, *bytes.Buffer) {
+	t.Helper()
+	var buf bytes.Buffer
+	mw := multipart.NewWriter(&buf)
+	for k, v := range fields {
+		if err := mw.WriteField(k, v); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for name, data := range files {
+		fw, err := mw.CreateFormFile(name, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		fw.Write(data)
+	}
+	mw.Close()
+	return mw.FormDataContentType(), &buf
+}
+
+func TestSetHTTPProxyValidation(t *testing.T) {
+	// Missing host/port -> 400 before touching any file.
+	ct, body := multipartBody(t, map[string]string{}, map[string][]byte{"p12": {1, 2, 3}})
+	w, c := deviceCtx("PUT", "/httpproxy", body.String(), ct, "UDID-X", nil)
+	SetHTTPProxy(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("missing host/port: got %d, want 400", w.Code)
+	}
+
+	// Host/port present but no p12 -> 400.
+	ct2, body2 := multipartBody(t, map[string]string{"host": "127.0.0.1", "port": "8888"}, nil)
+	w2, c2 := deviceCtx("PUT", "/httpproxy", body2.String(), ct2, "UDID-X", nil)
+	SetHTTPProxy(c2)
+	if w2.Code != http.StatusBadRequest {
+		t.Fatalf("missing p12: got %d, want 400", w2.Code)
+	}
+}
+
+func TestMdmValidation(t *testing.T) {
+	// clear-passcode without token -> 400.
+	ct, body := multipartBody(t, nil, map[string][]byte{"p12": {1}})
+	w, c := deviceCtx("POST", "/mdm/clear-passcode", body.String(), ct, "UDID-X", nil)
+	MdmClearPasscode(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("clear-passcode without token: got %d, want 400", w.Code)
+	}
+
+	// clear-passcode with a bad base64 token -> 400.
+	ct2, body2 := multipartBody(t, map[string]string{"token": "!!not-base64!!"}, map[string][]byte{"p12": {1}})
+	w2, c2 := deviceCtx("POST", "/mdm/clear-passcode", body2.String(), ct2, "UDID-X", nil)
+	MdmClearPasscode(c2)
+	if w2.Code != http.StatusBadRequest {
+		t.Fatalf("clear-passcode bad base64: got %d, want 400", w2.Code)
+	}
+
+	// security-info without p12 -> 400.
+	ct3, body3 := multipartBody(t, nil, nil)
+	w3, c3 := deviceCtx("POST", "/mdm/security-info", body3.String(), ct3, "UDID-X", nil)
+	MdmSecurityInfo(c3)
+	if w3.Code != http.StatusBadRequest {
+		t.Fatalf("security-info without p12: got %d, want 400", w3.Code)
+	}
+}
+
+// --- Jobs lifecycle via HTTP handlers -------------------------------------
+
+// TestJobsHTTPLifecycle exercises the job endpoints end-to-end against the
+// process-wide registry: create -> list (per-device) -> get -> stop -> delete.
+func TestJobsHTTPLifecycle(t *testing.T) {
+	const udid = "UDID-LIFECYCLE"
+	stopped := make(chan struct{}, 1)
+	j := jobs.create("forward", udid, func() error { stopped <- struct{}{}; return nil })
+
+	params := gin.Params{{Key: "udid", Value: udid}, {Key: "id", Value: j.ID}}
+
+	// GetJob returns the running job.
+	w, c := deviceCtx("GET", "/jobs/"+j.ID, "", "", udid, params)
+	GetJob(c)
+	if w.Code != http.StatusOK || !strings.Contains(w.Body.String(), jobRunning) {
+		t.Fatalf("GetJob: got %d body=%s", w.Code, w.Body.String())
+	}
+
+	// ListJobs only returns this device's jobs.
+	wl, cl := deviceCtx("GET", "/jobs", "", "", udid, gin.Params{{Key: "udid", Value: udid}})
+	ListJobs(cl)
+	if wl.Code != http.StatusOK || !strings.Contains(wl.Body.String(), j.ID) {
+		t.Fatalf("ListJobs missing job: %s", wl.Body.String())
+	}
+
+	// DELETE on a running job stops it.
+	wd, cd := deviceCtx("DELETE", "/jobs/"+j.ID, "", "", udid, params)
+	StopJob(cd)
+	if wd.Code != http.StatusOK || !strings.Contains(wd.Body.String(), "stopped") {
+		t.Fatalf("StopJob: got %d body=%s", wd.Code, wd.Body.String())
+	}
+	select {
+	case <-stopped:
+	case <-time.After(time.Second):
+		t.Fatal("stop func was not invoked")
+	}
+	if j.view().Status != jobStopped {
+		t.Fatalf("job should be stopped, got %s", j.view().Status)
+	}
+
+	// DELETE again on the now-terminal job removes it from the registry.
+	wd2, cd2 := deviceCtx("DELETE", "/jobs/"+j.ID, "", "", udid, params)
+	StopJob(cd2)
+	if wd2.Code != http.StatusOK || !strings.Contains(wd2.Body.String(), "removed") {
+		t.Fatalf("second DELETE should remove: got %d body=%s", wd2.Code, wd2.Body.String())
+	}
+	if _, ok := jobs.get(j.ID); ok {
+		t.Fatal("terminal job should have been removed from the registry")
+	}
+}
+
+// TestJobCrossDeviceIsolation ensures a job created for one device cannot be
+// fetched/stopped via another device's udid (the handler 404s).
+func TestJobCrossDeviceIsolation(t *testing.T) {
+	j := jobs.create("forward", "OWNER-UDID", func() error { return nil })
+	defer jobs.stop(j.ID)
+
+	// Wrong udid in the path -> 404 for GET.
+	params := gin.Params{{Key: "udid", Value: "ATTACKER-UDID"}, {Key: "id", Value: j.ID}}
+	w, c := deviceCtx("GET", "/jobs/"+j.ID, "", "", "ATTACKER-UDID", params)
+	GetJob(c)
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("cross-device GetJob: got %d, want 404", w.Code)
+	}
+
+	// Wrong udid -> 404 for DELETE, and the job must not be stopped.
+	wd, cd := deviceCtx("DELETE", "/jobs/"+j.ID, "", "", "ATTACKER-UDID", params)
+	StopJob(cd)
+	if wd.Code != http.StatusNotFound {
+		t.Fatalf("cross-device StopJob: got %d, want 404", wd.Code)
+	}
+	if j.view().Status != jobRunning {
+		t.Fatalf("job must stay running after a cross-device delete attempt, got %s", j.view().Status)
+	}
+}
+
+// TestSnapshotAndSubscribeNoLostLine asserts the atomic backlog+subscribe path
+// captures a line delivered concurrently, with no gap between history and stream.
+func TestSnapshotAndSubscribeNoLostLine(t *testing.T) {
+	l := newJobLog()
+	l.Write([]byte("history\n"))
+	backlog, ch, unsub := l.snapshotAndSubscribe()
+	defer unsub()
+	if len(backlog) != 1 || backlog[0] != "history\n" {
+		t.Fatalf("backlog wrong: %#v", backlog)
+	}
+	l.Write([]byte("live\n"))
+	select {
+	case got := <-ch:
+		if got != "live\n" {
+			t.Fatalf("live line wrong: %q", got)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("live line not delivered after atomic subscribe")
+	}
+}
+
+// TestJobRemoveOnlyTerminal verifies remove refuses to drop a running job.
+func TestJobRemoveOnlyTerminal(t *testing.T) {
+	j := jobs.create("forward", "UDID-REM", func() error { return nil })
+	if jobs.remove(j.ID) {
+		t.Fatal("remove must refuse a running job")
+	}
+	if _, ok := jobs.get(j.ID); !ok {
+		t.Fatal("running job must not have been removed")
+	}
+	jobs.stop(j.ID)
+	if !jobs.remove(j.ID) {
+		t.Fatal("remove must drop a terminal job")
+	}
+	if _, ok := jobs.get(j.ID); ok {
+		t.Fatal("terminal job should be gone after remove")
+	}
+}
diff --git a/restapi/api/health_endpoints.go b/restapi/api/health_endpoints.go
new file mode 100644
index 000000000..1d5648b2d
--- /dev/null
+++ b/restapi/api/health_endpoints.go
@@ -0,0 +1,19 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterHealthRoutes registers unauthenticated liveness and readiness probes.
+// These are intentionally outside the /api/v1 auth group so orchestrators
+// (Kubernetes, load balancers, systemd) can health-check without a token.
+func RegisterHealthRoutes(router *gin.Engine) {
+	router.GET("/healthz", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ok"})
+	})
+	router.GET("/readyz", func(c *gin.Context) {
+		c.JSON(http.StatusOK, gin.H{"status": "ready"})
+	})
+}
diff --git a/restapi/api/jobs.go b/restapi/api/jobs.go
new file mode 100644
index 000000000..419289b66
--- /dev/null
+++ b/restapi/api/jobs.go
@@ -0,0 +1,276 @@
+package api
+
+import (
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios/golog"
+)
+
+// logModule is the module attribute attached to every golog line emitted by the
+// REST API, matching the repo-wide "module", logModule convention.
+const logModule = "go-ios/restapi"
+
+// Job lifecycle states.
+const (
+	jobRunning   = "running"
+	jobSucceeded = "succeeded"
+	jobFailed    = "failed"
+	jobStopped   = "stopped"
+)
+
+// maxJobLogLines bounds how much output a single job retains in memory.
+const maxJobLogLines = 5000
+
+// Job is a long-running operation (a test run, a port-forward, …) started via
+// the REST API. Its logs are captured on a dedicated per-job sink so concurrent
+// jobs never interleave, and can be streamed independently.
+type Job struct {
+	ID         string     `json:"id"`
+	Kind       string     `json:"kind"`
+	UDID       string     `json:"udid"`
+	Status     string     `json:"status"`
+	StartedAt  time.Time  `json:"startedAt"`
+	FinishedAt *time.Time `json:"finishedAt,omitempty"`
+	Error      string     `json:"error,omitempty"`
+	Result     any        `json:"result,omitempty"`
+
+	mu   sync.Mutex
+	stop func() error
+	log  *jobLog
+}
+
+// jobView is a lock-free, JSON-safe snapshot of a Job.
+type jobView struct {
+	ID         string     `json:"id"`
+	Kind       string     `json:"kind"`
+	UDID       string     `json:"udid"`
+	Status     string     `json:"status"`
+	StartedAt  time.Time  `json:"startedAt"`
+	FinishedAt *time.Time `json:"finishedAt,omitempty"`
+	Error      string     `json:"error,omitempty"`
+	Result     any        `json:"result,omitempty"`
+}
+
+func (j *Job) view() jobView {
+	j.mu.Lock()
+	defer j.mu.Unlock()
+	return jobView{
+		ID: j.ID, Kind: j.Kind, UDID: j.UDID, Status: j.Status,
+		StartedAt: j.StartedAt, FinishedAt: j.FinishedAt, Error: j.Error, Result: j.Result,
+	}
+}
+
+// finish records terminal success/failure. It is a no-op if the job was already
+// stopped, so a cancellation doesn't get re-labelled as a failure.
+func (j *Job) finish(result any, err error) {
+	j.mu.Lock()
+	if j.Status != jobRunning {
+		j.mu.Unlock()
+		return
+	}
+	now := time.Now()
+	j.FinishedAt = &now
+	if err != nil {
+		j.Status = jobFailed
+		j.Error = err.Error()
+	} else {
+		j.Status = jobSucceeded
+		j.Result = result
+	}
+	status := j.Status
+	j.mu.Unlock()
+
+	golog.Info("job finished", "module", logModule, "udid", j.UDID, "job", j.ID, "kind", j.Kind, "status", status)
+	j.log.close()
+}
+
+// jobManager is a process-wide, in-memory registry of jobs.
+type jobManager struct {
+	mu      sync.Mutex
+	jobs    map[string]*Job
+	counter int
+}
+
+var jobs = &jobManager{jobs: map[string]*Job{}}
+
+// create registers a new running job. stop is invoked to cancel it.
+func (m *jobManager) create(kind, udid string, stop func() error) *Job {
+	m.mu.Lock()
+	m.counter++
+	id := fmt.Sprintf("%s-%d", kind, m.counter)
+	j := &Job{ID: id, Kind: kind, UDID: udid, Status: jobRunning, StartedAt: time.Now(), stop: stop, log: newJobLog()}
+	m.jobs[id] = j
+	m.mu.Unlock()
+
+	golog.Info("job started", "module", logModule, "udid", udid, "job", id, "kind", kind)
+	return j
+}
+
+func (m *jobManager) get(id string) (*Job, bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	j, ok := m.jobs[id]
+	return j, ok
+}
+
+// listForUDID returns the jobs belonging to a device.
+func (m *jobManager) listForUDID(udid string) []jobView {
+	m.mu.Lock()
+	all := make([]*Job, 0, len(m.jobs))
+	for _, j := range m.jobs {
+		all = append(all, j)
+	}
+	m.mu.Unlock()
+
+	out := make([]jobView, 0, len(all))
+	for _, j := range all {
+		if j.UDID == udid {
+			out = append(out, j.view())
+		}
+	}
+	return out
+}
+
+// stop cancels a running job. It is safe to call on an already-terminal job.
+func (m *jobManager) stop(id string) (bool, error) {
+	j, ok := m.get(id)
+	if !ok {
+		return false, nil
+	}
+	j.mu.Lock()
+	if j.Status != jobRunning {
+		j.mu.Unlock()
+		return true, nil
+	}
+	now := time.Now()
+	j.Status = jobStopped
+	j.FinishedAt = &now
+	stop := j.stop
+	j.mu.Unlock()
+
+	golog.Info("job stopped", "module", logModule, "udid", j.UDID, "job", j.ID, "kind", j.Kind)
+	var err error
+	if stop != nil {
+		err = stop()
+	}
+	j.log.close()
+	return true, err
+}
+
+// remove drops a job from the registry, freeing its buffered logs. It only
+// removes terminal jobs so an in-flight job is never silently forgotten; callers
+// stop a running job first. Returns whether a job was removed.
+func (m *jobManager) remove(id string) bool {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	j, ok := m.jobs[id]
+	if !ok {
+		return false
+	}
+	j.mu.Lock()
+	terminal := j.Status != jobRunning
+	j.mu.Unlock()
+	if !terminal {
+		return false
+	}
+	delete(m.jobs, id)
+	return true
+}
+
+// jobLog is a per-job, streamable log sink. It stores a bounded history and
+// fans out new lines to any live subscribers (the /jobs/:id/logs stream).
+type jobLog struct {
+	mu     sync.Mutex
+	lines  []string
+	subs   map[chan string]struct{}
+	closed bool
+}
+
+func newJobLog() *jobLog {
+	return &jobLog{subs: make(map[chan string]struct{})}
+}
+
+// Write implements io.Writer so a testmanagerd TestListener can log into it.
+func (l *jobLog) Write(p []byte) (int, error) {
+	s := string(p)
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if l.closed {
+		return len(p), nil
+	}
+	l.lines = append(l.lines, s)
+	if len(l.lines) > maxJobLogLines {
+		l.lines = l.lines[len(l.lines)-maxJobLogLines:]
+	}
+	for ch := range l.subs {
+		select {
+		case ch <- s:
+		default: // drop for a slow subscriber rather than block the job
+		}
+	}
+	return len(p), nil
+}
+
+// snapshot returns the buffered history so far.
+func (l *jobLog) snapshot() []string {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	out := make([]string, len(l.lines))
+	copy(out, l.lines)
+	return out
+}
+
+// subscribe returns a channel of future log lines and an unsubscribe func. If
+// the log is already closed the channel is closed immediately.
+func (l *jobLog) subscribe() (chan string, func()) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return l.subscribeLocked()
+}
+
+// snapshotAndSubscribe atomically returns the buffered history and a live
+// subscription in one critical section, so no line written between "read the
+// backlog" and "start streaming" is lost or duplicated (which a separate
+// snapshot()+subscribe() pair would race on).
+func (l *jobLog) snapshotAndSubscribe() ([]string, chan string, func()) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	out := make([]string, len(l.lines))
+	copy(out, l.lines)
+	ch, unsub := l.subscribeLocked()
+	return out, ch, unsub
+}
+
+// subscribeLocked implements subscribe; the caller must hold l.mu.
+func (l *jobLog) subscribeLocked() (chan string, func()) {
+	ch := make(chan string, 256)
+	if l.closed {
+		close(ch)
+		return ch, func() {}
+	}
+	l.subs[ch] = struct{}{}
+	return ch, func() {
+		l.mu.Lock()
+		defer l.mu.Unlock()
+		if _, ok := l.subs[ch]; ok {
+			delete(l.subs, ch)
+			close(ch)
+		}
+	}
+}
+
+// close ends all subscriber streams. Called when the job reaches a terminal state.
+func (l *jobLog) close() {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if l.closed {
+		return
+	}
+	l.closed = true
+	for ch := range l.subs {
+		delete(l.subs, ch)
+		close(ch)
+	}
+}
diff --git a/restapi/api/jobs_endpoints.go b/restapi/api/jobs_endpoints.go
new file mode 100644
index 000000000..a5debf728
--- /dev/null
+++ b/restapi/api/jobs_endpoints.go
@@ -0,0 +1,267 @@
+package api
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/forward"
+	"github.com/danielpaulus/go-ios/ios/testmanagerd"
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	// defaults for the runwda convenience endpoint
+	defaultWDABundleID     = "com.deviceboxhq.goios.WebDriverAgentRunner.xctrunner"
+	defaultWDAXctestConfig = "WebDriverAgentRunner.xctest"
+)
+
+// registerJobRoutes registers the async-job endpoints for long-running device
+// operations (test runs, port forwards). Each job runs in the background with an
+// isolated, streamable log; clients poll status or stream logs and stop when done.
+// Routes live under /device/:udid.
+func registerJobRoutes(device *gin.RouterGroup) {
+	device.POST("/jobs/runtest", StartRunTest)
+	device.POST("/jobs/runwda", StartRunWda)
+	device.POST("/jobs/forward", StartForward)
+	device.GET("/jobs", ListJobs)
+	device.GET("/jobs/:id", GetJob)
+	device.GET("/jobs/:id/logs", streamingMiddleWare, StreamJobLogs)
+	device.DELETE("/jobs/:id", StopJob)
+}
+
+type runTestRequest struct {
+	BundleId           string         `json:"bundleId"`
+	TestRunnerBundleId string         `json:"testRunnerBundleId"`
+	XctestConfig       string         `json:"xctestConfig"`
+	Env                map[string]any `json:"env"`
+	Args               []string       `json:"args"`
+	TestsToRun         []string       `json:"testsToRun"`
+	TestsToSkip        []string       `json:"testsToSkip"`
+	XcTest             bool           `json:"xctest"`
+}
+
+// startTestJob runs a testmanagerd test in the background, routing its output to
+// the job's isolated log sink, and returns the created job.
+func startTestJob(device ios.DeviceEntry, kind string, cfg testmanagerd.TestConfig) *Job {
+	ctx, cancel := context.WithCancel(context.Background())
+	j := jobs.create(kind, device.Properties.SerialNumber, func() error { cancel(); return nil })
+	cfg.Device = device
+	cfg.Listener = testmanagerd.NewTestListener(j.log, j.log, os.TempDir())
+	go func() {
+		suites, err := testmanagerd.RunTestWithConfig(ctx, cfg)
+		j.finish(suites, err)
+	}()
+	return j
+}
+
+// StartRunTest starts an XCUITest/unit-test run (CLI: ios runtest).
+// @Summary Start a test run (async job)
+// @Accept json
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param body body runTestRequest true "test configuration"
+// @Success 202 {object} jobView
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/jobs/runtest [post]
+func StartRunTest(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req runTestRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if req.TestRunnerBundleId == "" {
+		req.TestRunnerBundleId = req.BundleId
+	}
+	if req.TestRunnerBundleId == "" {
+		RespondError(c, http.StatusBadRequest, errMissingBundleID)
+		return
+	}
+	j := startTestJob(device, "runtest", testmanagerd.TestConfig{
+		BundleId:           req.BundleId,
+		TestRunnerBundleId: req.TestRunnerBundleId,
+		XctestConfigName:   req.XctestConfig,
+		Env:                req.Env,
+		Args:               req.Args,
+		TestsToRun:         req.TestsToRun,
+		TestsToSkip:        req.TestsToSkip,
+		XcTest:             req.XcTest,
+	})
+	c.JSON(http.StatusAccepted, j.view())
+}
+
+// StartRunWda starts the WebDriverAgent runner (CLI: ios runwda). Body fields are
+// optional and default to the standard WDA bundle id and xctest config.
+// @Summary Start the WebDriverAgent runner (async job)
+// @Accept json
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param body body runTestRequest false "optional overrides"
+// @Success 202 {object} jobView
+// @Router /device/{udid}/jobs/runwda [post]
+func StartRunWda(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req runTestRequest
+	_ = c.ShouldBindJSON(&req)
+	if req.BundleId == "" {
+		req.BundleId = defaultWDABundleID
+	}
+	if req.TestRunnerBundleId == "" {
+		req.TestRunnerBundleId = req.BundleId
+	}
+	if req.XctestConfig == "" {
+		req.XctestConfig = defaultWDAXctestConfig
+	}
+	j := startTestJob(device, "runwda", testmanagerd.TestConfig{
+		BundleId:           req.BundleId,
+		TestRunnerBundleId: req.TestRunnerBundleId,
+		XctestConfigName:   req.XctestConfig,
+		Env:                req.Env,
+		Args:               req.Args,
+	})
+	c.JSON(http.StatusAccepted, j.view())
+}
+
+type forwardRequest struct {
+	HostPort   uint16 `json:"hostPort"`
+	TargetPort uint16 `json:"targetPort"`
+}
+
+// StartForward starts a TCP port forward host->device (CLI: ios forward).
+// @Summary Start a port forward (async job)
+// @Accept json
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param body body forwardRequest true "hostPort/targetPort"
+// @Success 202 {object} jobView
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/jobs/forward [post]
+func StartForward(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req forwardRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if req.HostPort == 0 || req.TargetPort == 0 {
+		RespondError(c, http.StatusBadRequest, errMissingPorts)
+		return
+	}
+	cl, err := forward.Forward(device, req.HostPort, req.TargetPort)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	j := jobs.create("forward", device.Properties.SerialNumber, func() error { return cl.Close() })
+	fmt.Fprintf(j.log, "forwarding 127.0.0.1:%d -> device:%d\n", req.HostPort, req.TargetPort)
+	c.JSON(http.StatusAccepted, j.view())
+}
+
+// ListJobs lists jobs for a device.
+// @Summary List jobs
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {array} jobView
+// @Router /device/{udid}/jobs [get]
+func ListJobs(c *gin.Context) {
+	c.JSON(http.StatusOK, jobs.listForUDID(c.Param("udid")))
+}
+
+// jobForRequest fetches a job and verifies it belongs to the path's device.
+func jobForRequest(c *gin.Context) (*Job, bool) {
+	j, ok := jobs.get(c.Param("id"))
+	if !ok || j.UDID != c.Param("udid") {
+		RespondError(c, http.StatusNotFound, errJobNotFound)
+		return nil, false
+	}
+	return j, true
+}
+
+// GetJob returns a job's status.
+// @Summary Get job status
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param id path string true "job id"
+// @Success 200 {object} jobView
+// @Failure 404 {object} map[string]string
+// @Router /device/{udid}/jobs/{id} [get]
+func GetJob(c *gin.Context) {
+	j, ok := jobForRequest(c)
+	if !ok {
+		return
+	}
+	c.JSON(http.StatusOK, j.view())
+}
+
+// JobLogLine is the payload of a `log` event (SSE /jobs/{id}/logs).
+type JobLogLine struct {
+	Line string `json:"line"`
+}
+
+// StreamJobLogs streams a job's isolated log output as Server-Sent Events: the
+// buffered history first, then live lines until the job ends or the client
+// disconnects. Each `log` event carries a JobLogLine; a `heartbeat` event is
+// emitted on idle.
+// @Summary Stream a job's logs (SSE)
+// @Description Streams a job's log output as text/event-stream. Events: `log` (JobLogLine), `heartbeat`. Buffered history is replayed before live lines.
+// @Produce text/event-stream
+// @Param udid path string true "Device UDID"
+// @Param id path string true "job id"
+// @Success 200 {object} JobLogLine
+// @Router /device/{udid}/jobs/{id}/logs [get]
+func StreamJobLogs(c *gin.Context) {
+	j, ok := jobForRequest(c)
+	if !ok {
+		return
+	}
+	// Take the backlog and the live subscription atomically so a line written
+	// between "replay history" and "start streaming" is neither lost nor
+	// duplicated.
+	backlog, ch, unsubscribe := j.log.snapshotAndSubscribe()
+	defer unsubscribe()
+
+	// Replay the buffered history first, then pull live lines from the channel.
+	streamSSE(c, j.UDID, func() (sseEvent, bool) {
+		if len(backlog) > 0 {
+			line := backlog[0]
+			backlog = backlog[1:]
+			return sseEvent{event: "log", payload: JobLogLine{Line: line}}, true
+		}
+		line, ok := <-ch
+		if !ok {
+			return sseEvent{}, false
+		}
+		return sseEvent{event: "log", payload: JobLogLine{Line: line}}, true
+	})
+}
+
+// StopJob stops a running job, or purges an already-terminal one from the
+// registry to reclaim its buffered logs (CLI: Ctrl-C on the equivalent command).
+// @Summary Stop or delete a job
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Param id path string true "job id"
+// @Success 200 {object} map[string]string
+// @Failure 404 {object} map[string]string
+// @Router /device/{udid}/jobs/{id} [delete]
+func StopJob(c *gin.Context) {
+	j, ok := jobForRequest(c)
+	if !ok {
+		return
+	}
+	// A terminal job has nothing to stop; DELETE removes it so finished jobs
+	// don't accumulate in the process-wide registry forever.
+	if j.view().Status != jobRunning {
+		jobs.remove(c.Param("id"))
+		c.JSON(http.StatusOK, gin.H{"message": "job removed"})
+		return
+	}
+	if _, err := jobs.stop(c.Param("id")); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "job stopped"})
+}
diff --git a/restapi/api/jobs_test.go b/restapi/api/jobs_test.go
new file mode 100644
index 000000000..2d8db7c16
--- /dev/null
+++ b/restapi/api/jobs_test.go
@@ -0,0 +1,100 @@
+package api
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+func TestJobLifecycleSucceed(t *testing.T) {
+	j := jobs.create("unittest", "UDID-A", func() error { return nil })
+	if j.view().Status != jobRunning {
+		t.Fatalf("new job should be running")
+	}
+	j.finish("done", nil)
+	v := j.view()
+	if v.Status != jobSucceeded || v.Result != "done" || v.FinishedAt == nil {
+		t.Fatalf("unexpected terminal state: %+v", v)
+	}
+	// finishing again must not flip the state.
+	j.finish(nil, errors.New("late"))
+	if j.view().Status != jobSucceeded {
+		t.Fatalf("terminal job state must be immutable")
+	}
+}
+
+func TestJobStopIsTerminalAndNotRelabeled(t *testing.T) {
+	cancelled := false
+	j := jobs.create("unittest", "UDID-B", func() error { cancelled = true; return nil })
+	ok, err := jobs.stop(j.ID)
+	if !ok || err != nil {
+		t.Fatalf("stop failed: ok=%v err=%v", ok, err)
+	}
+	if !cancelled {
+		t.Fatalf("stop func was not invoked")
+	}
+	if j.view().Status != jobStopped {
+		t.Fatalf("job should be stopped, got %s", j.view().Status)
+	}
+	// A late finish (e.g. the cancelled goroutine returning ctx.Canceled) must
+	// not relabel a stopped job as failed.
+	j.finish(nil, errors.New("context canceled"))
+	if j.view().Status != jobStopped {
+		t.Fatalf("stopped job must stay stopped, got %s", j.view().Status)
+	}
+}
+
+func TestListForUDIDIsolatesDevices(t *testing.T) {
+	a := jobs.create("unittest", "UDID-C", nil)
+	jobs.create("unittest", "UDID-D", nil)
+	list := jobs.listForUDID("UDID-C")
+	found := false
+	for _, v := range list {
+		if v.UDID != "UDID-C" {
+			t.Fatalf("listForUDID leaked another device's job: %s", v.UDID)
+		}
+		if v.ID == a.ID {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("expected job %s in UDID-C list", a.ID)
+	}
+}
+
+func TestJobLogSnapshotSubscribeAndClose(t *testing.T) {
+	l := newJobLog()
+	l.Write([]byte("line1\n"))
+	if snap := l.snapshot(); len(snap) != 1 || snap[0] != "line1\n" {
+		t.Fatalf("snapshot wrong: %#v", snap)
+	}
+
+	ch, unsub := l.subscribe()
+	defer unsub()
+	l.Write([]byte("line2\n"))
+	select {
+	case got := <-ch:
+		if got != "line2\n" {
+			t.Fatalf("subscriber got %q", got)
+		}
+	case <-time.After(time.Second):
+		t.Fatal("subscriber did not receive live line")
+	}
+
+	// close ends the stream.
+	l.close()
+	if _, ok := <-ch; ok {
+		t.Fatal("channel should be closed after jobLog.close")
+	}
+	// writes after close are dropped, not panics.
+	l.Write([]byte("ignored\n"))
+}
+
+func TestJobLogSubscribeAfterCloseReturnsClosedChannel(t *testing.T) {
+	l := newJobLog()
+	l.close()
+	ch, _ := l.subscribe()
+	if _, ok := <-ch; ok {
+		t.Fatal("subscribing to a closed log must return a closed channel")
+	}
+}
diff --git a/restapi/api/mdm_endpoints.go b/restapi/api/mdm_endpoints.go
new file mode 100644
index 000000000..4507df0db
--- /dev/null
+++ b/restapi/api/mdm_endpoints.go
@@ -0,0 +1,152 @@
+package api
+
+import (
+	"encoding/base64"
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+)
+
+// registerMdmRoutes registers MDM/supervision endpoints (CLI: ios mdm ...). Every
+// endpoint needs a supervisor identity: send multipart/form-data with a "p12"
+// file and optional "password" field. Credentials are held only in memory for
+// the duration of the request and never logged or written to disk.
+func registerMdmRoutes(device *gin.RouterGroup) {
+	mdm := device.Group("/mdm")
+	mdm.POST("/security-info", MdmSecurityInfo)
+	mdm.POST("/fetch-unlock-token", MdmFetchUnlockToken)
+	mdm.POST("/clear-passcode", MdmClearPasscode)
+	mdm.POST("/clear-screen-time-password", MdmClearScreenTimePassword)
+}
+
+// escalatedConn opens an mcinstall connection and escalates it to a supervised
+// session using the multipart "p12"/"password" fields. The caller must Close it.
+func escalatedConn(c *gin.Context) (*mcinstall.Connection, error) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	p12bytes, err := readFormFile(c, "p12")
+	if err != nil {
+		return nil, errMissingP12
+	}
+	conn, err := mcinstall.New(device)
+	if err != nil {
+		return nil, err
+	}
+	if err := conn.Escalate(p12bytes, c.PostForm("password")); err != nil {
+		conn.Close()
+		return nil, err
+	}
+	return conn, nil
+}
+
+// MdmSecurityInfo returns device security info (CLI: ios mdm security-info).
+// @Summary Get MDM security info (supervised)
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param p12 formData file true "p12 supervisor identity"
+// @Param password formData string false "p12 password"
+// @Success 200 {object} interface{}
+// @Router /device/{udid}/mdm/security-info [post]
+func MdmSecurityInfo(c *gin.Context) {
+	conn, err := escalatedConn(c)
+	if err != nil {
+		RespondError(c, statusForEscalateErr(err), err)
+		return
+	}
+	defer conn.Close()
+	info, err := conn.SecurityInfo()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, info)
+}
+
+// MdmFetchUnlockToken returns the escrow unlock token, base64-encoded (CLI: ios
+// mdm fetch-unlock-token).
+// @Summary Fetch the escrow unlock token (supervised)
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param p12 formData file true "p12 supervisor identity"
+// @Param password formData string false "p12 password"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/mdm/fetch-unlock-token [post]
+func MdmFetchUnlockToken(c *gin.Context) {
+	conn, err := escalatedConn(c)
+	if err != nil {
+		RespondError(c, statusForEscalateErr(err), err)
+		return
+	}
+	defer conn.Close()
+	token, err := conn.FetchUnlockToken()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"token": base64.StdEncoding.EncodeToString(token)})
+}
+
+// MdmClearPasscode clears the device passcode (CLI: ios mdm clear-passcode). In
+// addition to the p12, supply the unlock token as a base64 "token" form field.
+// @Summary Clear the device passcode (supervised)
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param p12 formData file true "p12 supervisor identity"
+// @Param password formData string false "p12 password"
+// @Param token formData string true "base64 unlock token"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/mdm/clear-passcode [post]
+func MdmClearPasscode(c *gin.Context) {
+	tokenB64 := c.PostForm("token")
+	if tokenB64 == "" {
+		RespondError(c, http.StatusBadRequest, errMissingToken)
+		return
+	}
+	tokenBytes, err := base64.StdEncoding.DecodeString(tokenB64)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	conn, err := escalatedConn(c)
+	if err != nil {
+		RespondError(c, statusForEscalateErr(err), err)
+		return
+	}
+	defer conn.Close()
+	if err := conn.ClearPasscode(tokenBytes); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"status": "ok"})
+}
+
+// MdmClearScreenTimePassword clears the Screen Time password (CLI: ios mdm
+// clear-screen-time-password).
+// @Summary Clear the Screen Time password (supervised)
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param p12 formData file true "p12 supervisor identity"
+// @Param password formData string false "p12 password"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/mdm/clear-screen-time-password [post]
+func MdmClearScreenTimePassword(c *gin.Context) {
+	conn, err := escalatedConn(c)
+	if err != nil {
+		RespondError(c, statusForEscalateErr(err), err)
+		return
+	}
+	defer conn.Close()
+	if err := conn.ClearScreenTimePassword(); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"status": "ok"})
+}
+
+func statusForEscalateErr(err error) int {
+	if err == errMissingP12 {
+		return http.StatusBadRequest
+	}
+	return http.StatusInternalServerError
+}
diff --git a/restapi/api/media_endpoints.go b/restapi/api/media_endpoints.go
new file mode 100644
index 000000000..669a814b0
--- /dev/null
+++ b/restapi/api/media_endpoints.go
@@ -0,0 +1,221 @@
+package api
+
+import (
+	"io"
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/danielpaulus/go-ios/ios/pasteboard"
+	"github.com/danielpaulus/go-ios/ios/springboard"
+	"github.com/gin-gonic/gin"
+)
+
+// registerMediaRoutes registers wallpaper, icon-layout and pasteboard endpoints
+// mirroring the corresponding `ios` CLI commands. All routes live under
+// /device/:udid.
+func registerMediaRoutes(device *gin.RouterGroup) {
+	device.GET("/wallpaper", GetWallpaper)
+	device.PUT("/wallpaper", SetWallpaper)
+	device.GET("/icon-layout", GetIconLayout)
+	device.PUT("/icon-layout", SetIconLayout)
+	device.GET("/pasteboard", GetPasteboard)
+	device.PUT("/pasteboard", SetPasteboard)
+}
+
+// GetWallpaper returns the home-screen wallpaper as PNG (CLI: ios get-wallpaper).
+// @Summary Get the home-screen wallpaper
+// @Produce image/png
+// @Param udid path string true "Device UDID"
+// @Success 200 {file} binary
+// @Router /device/{udid}/wallpaper [get]
+func GetWallpaper(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	client, err := springboard.NewClient(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	png, err := client.GetHomeScreenWallpaperPNG()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.Data(http.StatusOK, "image/png", png)
+}
+
+// SetWallpaper sets the wallpaper (CLI: ios set-wallpaper). This is a supervised
+// operation: send multipart/form-data with an "image" file, a "p12" supervisor
+// identity file, and optional "password" and "screen" fields.
+// @Summary Set the wallpaper (supervised)
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param image formData file true "image file"
+// @Param p12 formData file true "p12 supervisor identity"
+// @Param password formData string false "p12 password"
+// @Param screen formData string false "target screen"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/wallpaper [put]
+func SetWallpaper(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	imageBytes, err := readFormFile(c, "image")
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	p12bytes, err := readFormFile(c, "p12")
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	screen, err := mcinstall.ParseWallpaperScreen(c.PostForm("screen"))
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+
+	conn, err := mcinstall.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	if err := conn.SetWallpaperSupervised(imageBytes, screen, p12bytes, c.PostForm("password")); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "wallpaper set"})
+}
+
+// GetIconLayout returns the home-screen icon layout (CLI: ios get-icon-layout).
+// @Summary Get the icon layout
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} interface{}
+// @Router /device/{udid}/icon-layout [get]
+func GetIconLayout(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	client, err := springboard.NewClient(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	state, err := client.GetIconLayout("2")
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, state)
+}
+
+// SetIconLayout restores an icon layout (CLI: ios set-icon-layout). Body is the
+// layout JSON as returned by GET.
+// @Summary Set the icon layout
+// @Accept json
+// @Param udid path string true "Device UDID"
+// @Param body body interface{} true "icon layout JSON"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/icon-layout [put]
+func SetIconLayout(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var state any
+	if err := c.ShouldBindJSON(&state); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	client, err := springboard.NewClient(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer client.Close()
+	if err := client.SetIconLayout(state); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "icon layout set"})
+}
+
+// GetPasteboard returns the device clipboard text (CLI: ios pasteboard get).
+// @Summary Get the pasteboard text
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/pasteboard [get]
+func GetPasteboard(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	conn, err := pasteboard.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	text, ok, err := conn.GetText()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"present": ok, "text": text})
+}
+
+// SetPasteboard sets the device clipboard from the raw request body (CLI: ios
+// pasteboard set <text>).
+// @Summary Set the pasteboard text
+// @Accept text/plain
+// @Param udid path string true "Device UDID"
+// @Param body body string true "clipboard text"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/pasteboard [put]
+func SetPasteboard(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	body, err := readAllLimited(c.Request.Body)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	conn, err := pasteboard.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	if err := conn.SetText(string(body)); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "pasteboard set"})
+}
+
+// maxUploadBytes bounds how much a single in-memory upload (multipart file field
+// or raw request body) may consume, so an authenticated client cannot exhaust
+// server memory with an oversized payload. 256 MiB comfortably covers profiles,
+// p12 identities and wallpaper images while still capping abuse.
+const maxUploadBytes = 256 << 20
+
+// readFormFile reads an entire multipart form file field into memory, bounded by
+// maxUploadBytes so an oversized field cannot exhaust server memory.
+func readFormFile(c *gin.Context, field string) ([]byte, error) {
+	f, _, err := c.Request.FormFile(field)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	return readAllLimited(f)
+}
+
+// readAllLimited reads r fully but fails if it would exceed maxUploadBytes,
+// instead of buffering an unbounded amount into memory.
+func readAllLimited(r io.Reader) ([]byte, error) {
+	b, err := io.ReadAll(io.LimitReader(r, maxUploadBytes+1))
+	if err != nil {
+		return nil, err
+	}
+	if len(b) > maxUploadBytes {
+		return nil, errUploadTooLarge
+	}
+	return b, nil
+}
diff --git a/restapi/api/middleware.go b/restapi/api/middleware.go
index 22713fee0..14a5b0530 100644
--- a/restapi/api/middleware.go
+++ b/restapi/api/middleware.go
@@ -10,8 +10,33 @@ import (
 	"github.com/danielpaulus/go-ios/ios/tunnel"
 	"github.com/gin-gonic/gin"
 	log "github.com/sirupsen/logrus"
+	"golang.org/x/time/rate"
 )
 
+// RateLimitUDID returns a gin middleware that rate-limits requests per device
+// UDID with a token bucket: perSecond sustained requests, allowing short bursts
+// up to burst. Requests over the limit are rejected with 429. perSecond <= 0
+// disables limiting. Each UDID gets its own limiter, so one device's traffic
+// never throttles another's.
+func RateLimitUDID(perSecond float64, burst int) gin.HandlerFunc {
+	if perSecond <= 0 {
+		return func(c *gin.Context) { c.Next() }
+	}
+	if burst < 1 {
+		burst = 1
+	}
+	var limiters sync.Map // udid -> *rate.Limiter
+	return func(c *gin.Context) {
+		udid := c.MustGet(IOS_KEY).(ios.DeviceEntry).Properties.SerialNumber
+		l, _ := limiters.LoadOrStore(udid, rate.NewLimiter(rate.Limit(perSecond), burst))
+		if !l.(*rate.Limiter).Allow() {
+			c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "rate limit exceeded for device " + udid})
+			return
+		}
+		c.Next()
+	}
+}
+
 // BearerAuth returns a gin middleware that requires callers to present the
 // configured token in an `Authorization: Bearer <token>` header. The comparison
 // is constant-time to avoid leaking the token via timing. On a missing or
diff --git a/restapi/api/monitoring_endpoints.go b/restapi/api/monitoring_endpoints.go
new file mode 100644
index 000000000..d29ca7164
--- /dev/null
+++ b/restapi/api/monitoring_endpoints.go
@@ -0,0 +1,59 @@
+package api
+
+import (
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/instruments"
+	"github.com/gin-gonic/gin"
+)
+
+// CpuUsageSample is the payload of a `sample` event (SSE /sysmontap). It is an
+// open map (sampler keys vary by OS); the commonly-present CPU_TotalLoad is
+// surfaced explicitly to match the spec's CpuUsageSample schema.
+type CpuUsageSample struct {
+	CPU_TotalLoad float64 `json:"CPU_TotalLoad"`
+}
+
+// sysmontapSamplingRate matches Xcode's default sysmontap sampling rate.
+const sysmontapSamplingRate = 10
+
+// registerMonitoringRoutes registers streaming monitoring endpoints.
+//
+// Note: `ios pcap` is intentionally not exposed yet — the pcap package's Start
+// writes packets to a local .pcap file and blocks, with no streaming API to hook
+// a response writer to. Exposing it cleanly needs a packet-callback API in
+// ios/pcap first; tracked as follow-up.
+func registerMonitoringRoutes(device *gin.RouterGroup) {
+	device.GET("/sysmontap", streamingMiddleWare, Sysmontap)
+}
+
+// Sysmontap streams CPU-usage samples as Server-Sent Events (CLI: ios
+// sysmontap). Each `sample` event carries a CpuUsageSample; a `heartbeat` event
+// is emitted on idle. The stream ends when the client disconnects or the device
+// closes the channel.
+// @Summary Stream CPU usage samples (SSE)
+// @Description Streams sysmontap CPU-usage samples as text/event-stream. Events: `sample` (CpuUsageSample), `heartbeat`.
+// @Produce text/event-stream
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} CpuUsageSample
+// @Router /device/{udid}/sysmontap [get]
+func Sysmontap(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
+	sysmon, err := instruments.NewSysmontapService(device, sysmontapSamplingRate)
+	if err != nil {
+		RespondError(c, 500, err)
+		return
+	}
+	defer sysmon.Close()
+
+	golog.Info("sysmontap stream started", "module", logModule, "udid", udid)
+	cpuUsageChannel := sysmon.ReceiveCPUUsage()
+	streamSSE(c, udid, func() (sseEvent, bool) {
+		msg, ok := <-cpuUsageChannel
+		if !ok {
+			return sseEvent{}, false
+		}
+		return sseEvent{event: "sample", payload: CpuUsageSample{CPU_TotalLoad: msg.SystemCPUUsage.CPU_TotalLoad}}, true
+	})
+}
diff --git a/restapi/api/pcap_endpoints.go b/restapi/api/pcap_endpoints.go
new file mode 100644
index 000000000..00b4c96cb
--- /dev/null
+++ b/restapi/api/pcap_endpoints.go
@@ -0,0 +1,100 @@
+package api
+
+import (
+	"context"
+	"net/http"
+	"strconv"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/pcap"
+	"github.com/gin-gonic/gin"
+)
+
+// pcapContentType is the IANA media type for a libpcap capture file. Clients
+// (wireshark, tcpdump, tshark -r -) recognize the stream by this type.
+const pcapContentType = "application/vnd.tcpdump.pcap"
+
+// pcapMaxTimeoutSeconds caps the caller-supplied ?timeout= so a single request
+// cannot hold a device pcapd connection open indefinitely.
+const pcapMaxTimeoutSeconds = 3600
+
+// pcapDefaultTimeout is used when no ?timeout= is given. The capture then runs
+// until this deadline or until the client disconnects, whichever comes first.
+const pcapDefaultTimeout = 60 * time.Second
+
+// flushWriter wraps a streaming http response writer so every write is pushed
+// to the client immediately. pcap.Stream writes the global header and then one
+// record per captured packet; flushing per write keeps the live capture from
+// buffering on the server.
+type flushWriter struct {
+	w gin.ResponseWriter
+}
+
+func (f flushWriter) Write(p []byte) (int, error) {
+	n, err := f.w.Write(p)
+	if err != nil {
+		return n, err
+	}
+	f.w.Flush()
+	return n, nil
+}
+
+// Pcap streams a live packet capture from the device as a libpcap stream.
+// The response begins with the pcap global header followed by one record per
+// captured packet, so it can be piped straight into wireshark/tshark. The
+// capture runs until the optional ?timeout= (seconds) elapses, the default
+// timeout is reached, or the client disconnects.
+// @Summary      Stream a live pcap capture
+// @Description  Streams live network traffic from the device as a libpcap (application/vnd.tcpdump.pcap) byte stream until the timeout elapses or the client disconnects.
+// @Tags         general
+// @Param        timeout  query  int  false  "Capture duration in seconds (default 60, max 3600)"
+// @Produce      application/vnd.tcpdump.pcap
+// @Success      200  {string}  binary  "libpcap byte stream"
+// @Router       /device/{udid}/pcap [get]
+func Pcap(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
+
+	timeout := pcapDefaultTimeout
+	if q := c.Query("timeout"); q != "" {
+		secs, err := strconv.Atoi(q)
+		if err != nil || secs <= 0 {
+			RespondError(c, http.StatusBadRequest, errInvalidTimeout)
+			return
+		}
+		if secs > pcapMaxTimeoutSeconds {
+			secs = pcapMaxTimeoutSeconds
+		}
+		timeout = time.Duration(secs) * time.Second
+	}
+
+	// Derive the capture lifetime from the request context (client disconnect)
+	// and the timeout cap; whichever fires first stops the capture cleanly.
+	ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
+	defer cancel()
+
+	c.Header("Content-Type", pcapContentType)
+	c.Header("Transfer-Encoding", "chunked")
+	c.Header("X-Content-Type-Options", "nosniff")
+
+	golog.Info("pcap stream started", "module", logModule, "udid", udid, "timeoutSeconds", int(timeout.Seconds()))
+	if err := pcap.Stream(ctx, device, flushWriter{w: c.Writer}); err != nil {
+		// Once bytes are on the wire the status is already 200 and we can only
+		// log; otherwise surface the failure to connect to pcapd.
+		if c.Writer.Written() {
+			golog.Error("pcap stream failed mid-capture", "module", logModule, "udid", udid, "error", err.Error())
+			return
+		}
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	golog.Info("pcap stream finished", "module", logModule, "udid", udid)
+}
+
+// registerPcapRoutes wires the live pcap streaming endpoint onto the
+// device-scoped group.
+func registerPcapRoutes(device *gin.RouterGroup) {
+	device.GET("/pcap", Pcap)
+}
diff --git a/restapi/api/pcap_endpoints_test.go b/restapi/api/pcap_endpoints_test.go
new file mode 100644
index 000000000..e1fcd1467
--- /dev/null
+++ b/restapi/api/pcap_endpoints_test.go
@@ -0,0 +1,92 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// The pcap endpoint streams live packets straight from the device's pcapd
+// service via pcap.Stream, which opens a real device connection. That device
+// I/O cannot be mocked at the endpoint layer (pcap.Stream connects internally
+// and is not injectable), so these tests cover the device-free surface:
+//   - the ?timeout= parse/validation branches that short-circuit with 400
+//     before any connection is attempted,
+//   - that a valid/oversized timeout is accepted (it passes validation and
+//     fails only later at connect time, i.e. never returns 400),
+//   - and that the route is wired up.
+//
+// The actual capture-to-writer behavior (valid pcap bytes, stop on ctx cancel,
+// no goroutine leak) is verified against a fake connection in
+// ios/pcap/pcap_test.go.
+
+// TestPcapRejectsBadTimeout: malformed / non-positive timeouts are rejected
+// with a 400 JSON error before touching the device.
+func TestPcapRejectsBadTimeout(t *testing.T) {
+	for _, q := range []string{"timeout=abc", "timeout=0", "timeout=-5", "timeout=1.5", "timeout="} {
+		if q == "timeout=" {
+			// empty value means "use default" and must NOT 400; skip here and
+			// cover it in the accept test.
+			continue
+		}
+		w, c := deviceCtx("GET", "/pcap?"+q, "", "", "UDID-PCAP", nil)
+		Pcap(c)
+		if w.Code != http.StatusBadRequest {
+			t.Fatalf("bad %q: got %d, want 400", q, w.Code)
+		}
+		var resp map[string]string
+		if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+			t.Fatalf("bad %q: response not JSON: %v", q, err)
+		}
+		if resp["error"] == "" {
+			t.Fatalf("bad %q: expected error field", q)
+		}
+	}
+}
+
+// TestPcapAcceptsValidTimeout: a well-formed timeout (including one above the
+// cap, and the no-timeout default) passes validation. There is no device, so
+// pcap.Stream fails at connect time and the handler returns 500 (not 400),
+// proving the parse/cap branch accepted the value.
+func TestPcapAcceptsValidTimeout(t *testing.T) {
+	for _, target := range []string{"/pcap", "/pcap?timeout=5", "/pcap?timeout=999999"} {
+		w, c := deviceCtx("GET", target, "", "", "UDID-PCAP", nil)
+		Pcap(c)
+		if w.Code == http.StatusBadRequest {
+			t.Fatalf("%q: got 400, want the request to pass validation", target)
+		}
+		if w.Code != http.StatusInternalServerError {
+			t.Fatalf("%q: got %d, want 500 (connect failure, no device)", target, w.Code)
+		}
+	}
+}
+
+// TestPcapContentTypeConstant guards the media type clients rely on to
+// recognize the stream.
+func TestPcapContentTypeConstant(t *testing.T) {
+	if pcapContentType != "application/vnd.tcpdump.pcap" {
+		t.Fatalf("unexpected pcap content type %q", pcapContentType)
+	}
+}
+
+// TestPcapRouteRegistered ensures GET /device/:udid/pcap is wired into the
+// route tree (in addition to the full-tree conflict check in routes_test.go).
+func TestPcapRouteRegistered(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	v1 := router.Group("/api/v1")
+	registerRoutes(v1, 0, 0)
+
+	found := false
+	for _, ri := range router.Routes() {
+		if ri.Method == http.MethodGet && ri.Path == "/api/v1/device/:udid/pcap" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("GET /device/:udid/pcap route not registered")
+	}
+}
diff --git a/restapi/api/production_readiness_test.go b/restapi/api/production_readiness_test.go
new file mode 100644
index 000000000..0b6df2a2b
--- /dev/null
+++ b/restapi/api/production_readiness_test.go
@@ -0,0 +1,72 @@
+package api
+
+import (
+	"errors"
+	"math"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestMustMarshalDoesNotPanicOnUnmarshalable(t *testing.T) {
+	// math.Inf is not representable in JSON, so json.Marshal fails. The old
+	// implementation panicked; MustMarshal must now return an error envelope.
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("MustMarshal panicked: %v", r)
+		}
+	}()
+	out := MustMarshal(math.Inf(1))
+	if !strings.Contains(out, "error") {
+		t.Fatalf("expected an error envelope, got %q", out)
+	}
+}
+
+func TestMustMarshalValidUnchanged(t *testing.T) {
+	if got := MustMarshal(map[string]int{"a": 1}); got != `{"a":1}` {
+		t.Fatalf("valid marshal changed: got %q", got)
+	}
+}
+
+func TestHealthEndpoints(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	RegisterHealthRoutes(router)
+	for _, path := range []string{"/healthz", "/readyz"} {
+		w := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodGet, path, nil)
+		router.ServeHTTP(w, req)
+		if w.Code != http.StatusOK {
+			t.Fatalf("%s: got status %d, want 200", path, w.Code)
+		}
+	}
+}
+
+func TestRespondError(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	RespondError(c, http.StatusBadRequest, errors.New("boom"))
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("got status %d, want 400", w.Code)
+	}
+	if !strings.Contains(w.Body.String(), `"error":"boom"`) {
+		t.Fatalf("unexpected body %q", w.Body.String())
+	}
+}
+
+func TestParseServerConfig(t *testing.T) {
+	def := parseServerConfig(nil)
+	if def.addr != "127.0.0.1:0" || def.disableAuth || def.tlsCert != "" || def.tlsKey != "" {
+		t.Fatalf("unexpected defaults: %+v", def)
+	}
+	got := parseServerConfig([]string{"--disable-auth", "--addr=127.0.0.1:9000", "--tls-cert=c.pem", "--tls-key=k.pem"})
+	if got.addr != "127.0.0.1:9000" || !got.disableAuth || got.tlsCert != "c.pem" || got.tlsKey != "k.pem" {
+		t.Fatalf("unexpected parse: %+v", got)
+	}
+	// Unknown/extra args must not crash startup.
+	_ = parseServerConfig([]string{"--totally-unknown", "positional"})
+}
diff --git a/restapi/api/provisioning_endpoints.go b/restapi/api/provisioning_endpoints.go
new file mode 100644
index 000000000..56e453aa1
--- /dev/null
+++ b/restapi/api/provisioning_endpoints.go
@@ -0,0 +1,58 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+)
+
+// registerProvisioningDeviceRoutes registers device-scoped provisioning /
+// configuration endpoints mirroring the `ios` CLI. Routes live under
+// /device/:udid.
+func registerProvisioningDeviceRoutes(device *gin.RouterGroup) {
+	device.GET("/cloudconfig", GetCloudConfig)
+}
+
+// registerProvisioningHostRoutes registers fleet/host-level provisioning
+// endpoints that are not scoped to a device. They live directly under the API
+// root (e.g. /api/v1/prepare/...).
+func registerProvisioningHostRoutes(router *gin.RouterGroup) {
+	router.GET("/prepare/skip-options", GetPrepareSkipOptions)
+}
+
+// GetCloudConfig returns the device cloud configuration (CLI: ios devicestate /
+// mcinstall GetCloudConfiguration). Includes supervision status, skip-setup
+// options and organization info.
+// @Summary Get the device cloud configuration
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]interface{}
+// @Router /device/{udid}/cloudconfig [get]
+func GetCloudConfig(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	conn, err := mcinstall.New(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+	cfg, err := conn.GetCloudConfiguration()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, cfg)
+}
+
+// GetPrepareSkipOptions returns all setup-pane skip options usable when preparing
+// a device (CLI: ios prepare printskip). This is a static, device-free list.
+// @Summary List all available setup skip options
+// @Produce json
+// @Success 200 {object} map[string]interface{}
+// @Router /prepare/skip-options [get]
+func GetPrepareSkipOptions(c *gin.Context) {
+	options := mcinstall.GetAllSetupSkipOptions()
+	c.JSON(http.StatusOK, gin.H{"options": options, "count": len(options)})
+}
diff --git a/restapi/api/provisioning_endpoints_test.go b/restapi/api/provisioning_endpoints_test.go
new file mode 100644
index 000000000..ad7da7eba
--- /dev/null
+++ b/restapi/api/provisioning_endpoints_test.go
@@ -0,0 +1,47 @@
+package api
+
+import (
+	"encoding/json"
+	"net/http"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+)
+
+// TestGetPrepareSkipOptions verifies the device-free skip-options endpoint: it
+// returns the full mcinstall option list as JSON with a matching count. This
+// runs end-to-end because it needs no device.
+func TestGetPrepareSkipOptions(t *testing.T) {
+	w, c := newHandlerCtx("GET", "/prepare/skip-options", "")
+	GetPrepareSkipOptions(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want 200 (body=%s)", w.Code, w.Body.String())
+	}
+
+	var resp struct {
+		Options []string `json:"options"`
+		Count   int      `json:"count"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("response not valid JSON: %v (body=%s)", err, w.Body.String())
+	}
+
+	want := mcinstall.GetAllSetupSkipOptions()
+	if resp.Count != len(want) {
+		t.Fatalf("count = %d, want %d", resp.Count, len(want))
+	}
+	if len(resp.Options) != len(want) {
+		t.Fatalf("options len = %d, want %d", len(resp.Options), len(want))
+	}
+	// Spot-check a couple of well-known options survive the round trip.
+	found := map[string]bool{}
+	for _, o := range resp.Options {
+		found[o] = true
+	}
+	for _, expected := range []string{"WiFi", "Passcode"} {
+		if !found[expected] {
+			t.Fatalf("expected skip option %q missing from response", expected)
+		}
+	}
+}
diff --git a/restapi/api/proxy_endpoints.go b/restapi/api/proxy_endpoints.go
new file mode 100644
index 000000000..26bf2e944
--- /dev/null
+++ b/restapi/api/proxy_endpoints.go
@@ -0,0 +1,65 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+)
+
+// registerProxyRoutes registers the global HTTP proxy endpoints (CLI: ios
+// httpproxy). Setting a proxy is a supervised operation. Routes under /device/:udid.
+func registerProxyRoutes(device *gin.RouterGroup) {
+	device.PUT("/httpproxy", SetHTTPProxy)
+	device.DELETE("/httpproxy", RemoveHTTPProxy)
+}
+
+// SetHTTPProxy configures a global HTTP proxy (CLI: ios httpproxy). Send
+// multipart/form-data with "host" and "port" fields, a "p12" supervisor identity
+// file, and optional "user", "pass" and "password" (p12 password) fields.
+// @Summary Set a global HTTP proxy (supervised)
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param host formData string true "proxy host"
+// @Param port formData string true "proxy port"
+// @Param p12 formData file true "p12 supervisor identity"
+// @Param user formData string false "proxy username"
+// @Param pass formData string false "proxy password"
+// @Param password formData string false "p12 password"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Router /device/{udid}/httpproxy [put]
+func SetHTTPProxy(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	host := c.PostForm("host")
+	port := c.PostForm("port")
+	if host == "" || port == "" {
+		RespondError(c, http.StatusBadRequest, errMissingProxyHostPort)
+		return
+	}
+	p12, err := readFormFile(c, "p12")
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, errMissingP12)
+		return
+	}
+	if err := mcinstall.SetHttpProxy(device, host, port, c.PostForm("user"), c.PostForm("pass"), p12, c.PostForm("password")); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "http proxy set", "host": host, "port": port})
+}
+
+// RemoveHTTPProxy clears the global HTTP proxy (CLI: ios httpproxy remove).
+// @Summary Remove the global HTTP proxy
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/httpproxy [delete]
+func RemoveHTTPProxy(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	if err := mcinstall.RemoveProxy(device); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "http proxy removed"})
+}
diff --git a/restapi/api/ratelimit_test.go b/restapi/api/ratelimit_test.go
new file mode 100644
index 000000000..42f320f56
--- /dev/null
+++ b/restapi/api/ratelimit_test.go
@@ -0,0 +1,115 @@
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"sync"
+	"sync/atomic"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/gin-gonic/gin"
+)
+
+// rateLimitRouter builds a minimal router: DeviceMiddleware-substitute that sets
+// a fixed udid, the rate limiter, and a 200 handler.
+func rateLimitRouter(udid string, perSecond float64, burst int) *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.Use(func(c *gin.Context) {
+		c.Set(IOS_KEY, ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: udid}})
+	})
+	r.Use(RateLimitUDID(perSecond, burst))
+	r.GET("/x", func(c *gin.Context) { c.String(http.StatusOK, "ok") })
+	return r
+}
+
+func TestRateLimitAllowsBurstThenRejects(t *testing.T) {
+	// A tiny sustained rate so refills don't interfere within the test window.
+	r := rateLimitRouter("UDID-A", 1, 5)
+	var ok, limited int
+	for i := 0; i < 20; i++ {
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+		switch w.Code {
+		case http.StatusOK:
+			ok++
+		case http.StatusTooManyRequests:
+			limited++
+		default:
+			t.Fatalf("unexpected status %d", w.Code)
+		}
+	}
+	if ok != 5 {
+		t.Fatalf("expected burst of 5 to pass, got %d (limited=%d)", ok, limited)
+	}
+	if limited != 15 {
+		t.Fatalf("expected 15 rejections, got %d", limited)
+	}
+}
+
+func TestRateLimitDisabledWhenZero(t *testing.T) {
+	r := rateLimitRouter("UDID-A", 0, 0)
+	for i := 0; i < 100; i++ {
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+		if w.Code != http.StatusOK {
+			t.Fatalf("rate limiting should be disabled, got %d on request %d", w.Code, i)
+		}
+	}
+}
+
+// TestRateLimitConcurrentPerDevice hammers one device from many goroutines and
+// asserts exactly `burst` requests succeed (the bucket is shared and consumed
+// atomically), with no races. Run with -race.
+func TestRateLimitConcurrentPerDevice(t *testing.T) {
+	const burst = 10
+	r := rateLimitRouter("UDID-A", 1, burst)
+	var okCount int64
+	var wg sync.WaitGroup
+	start := make(chan struct{})
+	for i := 0; i < 200; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-start
+			w := httptest.NewRecorder()
+			r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/x", nil))
+			if w.Code == http.StatusOK {
+				atomic.AddInt64(&okCount, 1)
+			}
+		}()
+	}
+	close(start)
+	wg.Wait()
+	// The token bucket may refill by a token or two during the burst, so allow a
+	// tiny margin; the point is it doesn't blow past the bucket under concurrency.
+	if okCount < burst || okCount > burst+2 {
+		t.Fatalf("concurrent successes = %d, want ~%d (bucket must not be exceeded)", okCount, burst)
+	}
+}
+
+// TestRateLimitIsolatesDevices confirms one device's exhausted bucket doesn't
+// reject another device's requests.
+func TestRateLimitIsolatesDevices(t *testing.T) {
+	limiter := RateLimitUDID(1, 2)
+	run := func(udid string) int {
+		gin.SetMode(gin.TestMode)
+		w := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(w)
+		c.Request = httptest.NewRequest(http.MethodGet, "/x", nil)
+		c.Set(IOS_KEY, ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: udid}})
+		limiter(c)
+		return w.Code
+	}
+	// Drain device A's bucket (burst 2).
+	run("A")
+	run("A")
+	if code := run("A"); code != http.StatusTooManyRequests {
+		t.Fatalf("device A should be limited, got %d", code)
+	}
+	// Device B is unaffected.
+	if code := run("B"); code == http.StatusTooManyRequests {
+		t.Fatalf("device B must not be limited by device A's traffic")
+	}
+}
diff --git a/restapi/api/routes.go b/restapi/api/routes.go
index 3a994c887..4e10147d7 100644
--- a/restapi/api/routes.go
+++ b/restapi/api/routes.go
@@ -6,12 +6,50 @@ import (
 
 var streamingMiddleWare = StreamingHeaderMiddleware()
 
-func registerRoutes(router *gin.RouterGroup) {
+func registerRoutes(router *gin.RouterGroup, rateLimit float64, rateBurst int) {
 	router.GET("/list", List)
+	registerTunnelRoutes(router)
+	// feat/restapi-w1c-fsync: fleet/host-level provisioning routes (no device).
+	registerProvisioningHostRoutes(router)
+	// --- feat/restapi-w4-sign: host-local codesigning + supervision-cert routes ---
+	registerSignHostRoutes(router)
+	// --- end feat/restapi-w4-sign ---
 
 	device := router.Group("/device/:udid")
 	device.Use(DeviceMiddleware())
+	device.Use(RateLimitUDID(rateLimit, rateBurst))
 	simpleDeviceRoutes(device)
+	registerDeviceInfoRoutes(device)
+	// --- feat/restapi-w1a-diagnostics: diagnostics & network parity endpoints ---
+	registerDiagnosticsNetRoutes(device)
+	// --- end feat/restapi-w1a-diagnostics ---
+	registerDeviceMgmtRoutes(device)
+	registerFilesRoutes(device)
+	registerMediaRoutes(device)
+	registerConfigRoutes(device)
+	registerSettingsRoutes(device)
+	registerMonitoringRoutes(device)
+	registerMdmRoutes(device)
+	registerJobRoutes(device)
+	registerProxyRoutes(device)
+	// w1b accessibility + location parity (feat/restapi-w1b-a11y)
+	registerAccessibilityRoutes(device)
+	// feat/restapi-w1c-fsync: AFC filesystem + cloud-config device routes.
+	registerFsyncRoutes(device)
+	registerProvisioningDeviceRoutes(device)
+	// --- feat/restapi-w4-sign: device-scoped prepare route ---
+	registerSignDeviceRoutes(device)
+	// --- end feat/restapi-w4-sign ---
+	// feat/restapi-w1d-webinspector: WebInspector device routes.
+	registerWebInspectorRoutes(device)
+	// feat/restapi-w2-ui: UI-automation routes proxying to a forwarded WDA/DeviceKit backend.
+	registerUIRoutes(device)
+	// --- feat/restapi-w3a-streams: live UI video stream + mjpeg screenshot stream ---
+	registerStreamRoutes(device)
+	// --- end feat/restapi-w3a-streams ---
+	// --- feat/restapi-w3b-pcap: live pcap streaming route ---
+	registerPcapRoutes(device)
+	// --- end feat/restapi-w3b-pcap ---
 	appRoutes(device)
 }
 
diff --git a/restapi/api/routes_test.go b/restapi/api/routes_test.go
new file mode 100644
index 000000000..15eb0f381
--- /dev/null
+++ b/restapi/api/routes_test.go
@@ -0,0 +1,22 @@
+package api
+
+import (
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TestRegisterRoutesNoConflict builds the full route tree. gin panics at
+// registration on a route conflict (e.g. a static segment colliding with a
+// wildcard), so this fails loudly if a new endpoint clashes with an existing one.
+func TestRegisterRoutesNoConflict(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("route registration panicked (conflict?): %v", r)
+		}
+	}()
+	router := gin.New()
+	v1 := router.Group("/api/v1")
+	registerRoutes(v1, 0, 0)
+}
diff --git a/restapi/api/server.go b/restapi/api/server.go
index 103360ea9..ed8af5577 100644
--- a/restapi/api/server.go
+++ b/restapi/api/server.go
@@ -1,16 +1,54 @@
 package api
 
 import (
+	"context"
+	"crypto/tls"
 	"flag"
 	"io"
+	"net"
+	"net/http"
 	"os"
+	"os/signal"
+	"syscall"
+	"time"
 
+	"github.com/danielpaulus/go-ios/ios/golog"
 	"github.com/gin-gonic/gin"
 	"github.com/sirupsen/logrus"
 	swaggerFiles "github.com/swaggo/files"
 	ginSwagger "github.com/swaggo/gin-swagger"
 )
 
+// serverConfig holds the command-line configuration for the REST server.
+type serverConfig struct {
+	addr        string
+	disableAuth bool
+	tlsCert     string
+	tlsKey      string
+	rateLimit   float64
+	rateBurst   int
+}
+
+// parseServerConfig parses the server flags from args. It uses a dedicated flag
+// set with ContinueOnError and discarded output so unknown/extra args never
+// crash startup.
+func parseServerConfig(args []string) serverConfig {
+	fs := flag.NewFlagSet("go-ios-restapi", flag.ContinueOnError)
+	fs.SetOutput(io.Discard)
+	addr := fs.String("addr", "127.0.0.1:0", "address to listen on (host:port); the default binds an ephemeral loopback port and publishes it to the discovery file. Pin/expose with e.g. :8080 or 0.0.0.0:9000")
+	disableAuth := fs.Bool("disable-auth", false, "run the REST API without authentication")
+	tlsCert := fs.String("tls-cert", "", "path to a TLS certificate; enables HTTPS together with --tls-key")
+	tlsKey := fs.String("tls-key", "", "path to the TLS private key for --tls-cert")
+	rateLimit := fs.Float64("rate-limit", 20, "max sustained requests per second per device (0 disables)")
+	rateBurst := fs.Int("rate-burst", 40, "burst size for the per-device rate limit")
+	// Ignore parse errors (e.g. unknown flags) so extra args don't crash startup.
+	_ = fs.Parse(args)
+	return serverConfig{
+		addr: *addr, disableAuth: *disableAuth, tlsCert: *tlsCert, tlsKey: *tlsKey,
+		rateLimit: *rateLimit, rateBurst: *rateBurst,
+	}
+}
+
 func Main() {
 	router := gin.Default()
 	log := logrus.New()
@@ -18,16 +56,20 @@ func Main() {
 	gin.DefaultWriter = io.MultiWriter(myfile, os.Stdout)
 	router.Use(MyLogger(log), gin.Recovery())
 
-	// Authentication configuration. The API binds :8080 with full device control,
-	// so it must not run unauthenticated by accident: either a token is supplied
-	// via GO_IOS_API_KEY, or auth is explicitly disabled with --disable-auth.
+	cfg := parseServerConfig(os.Args[1:])
+
+	// Liveness/readiness probes are unauthenticated and live outside /api/v1.
+	RegisterHealthRoutes(router)
+
+	// Authentication configuration. The API exposes full device control, so it
+	// must not run unauthenticated by accident: either a token is supplied via
+	// GO_IOS_API_KEY, or auth is explicitly disabled with --disable-auth.
 	token := os.Getenv("GO_IOS_API_KEY")
-	disableAuth := parseDisableAuth(os.Args[1:])
+	authEnabled := token != "" && !cfg.disableAuth
 
 	v1 := router.Group("/api/v1")
-
 	switch {
-	case disableAuth:
+	case cfg.disableAuth:
 		log.Warn("go-ios REST API is running WITHOUT authentication")
 	case token != "":
 		v1.Use(BearerAuth(token))
@@ -36,24 +78,95 @@ func Main() {
 			"or pass --disable-auth to run without authentication")
 	}
 
-	registerRoutes(v1)
+	registerRoutes(v1, cfg.rateLimit, cfg.rateBurst)
+
+	// Serve the swagger UI. When auth is enabled, gate it behind the token too
+	// (under /api/v1) so the API schema isn't exposed unauthenticated; otherwise
+	// keep it at the historical /swagger path.
+	if authEnabled {
+		v1.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	} else {
+		router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	}
+
+	srv := &http.Server{
+		// No Addr: we bind the listener ourselves (below) via net.Listen so the
+		// real OS-assigned port is knowable, then srv.Serve(ln). Addr is unused by
+		// Serve and would misleadingly read 127.0.0.1:0 for ephemeral binds.
+		Handler:           router,
+		ReadHeaderTimeout: 10 * time.Second,
+		IdleTimeout:       120 * time.Second,
+		MaxHeaderBytes:    1 << 20,
+		// No ReadTimeout/WriteTimeout on purpose: the /syslog, /listen, /ostrace
+		// and /notifications endpoints stream for the lifetime of the connection,
+		// and a WriteTimeout would sever them. ReadHeaderTimeout + IdleTimeout
+		// still bound slow-header and idle-keepalive abuse.
+	}
 
-	router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
+	useTLS := cfg.tlsCert != "" && cfg.tlsKey != ""
 
-	err := router.Run(":8080")
+	// Bind explicitly so the OS-assigned port (when --addr uses :0) is knowable
+	// before we start serving: we need the real host:port to log it and to
+	// publish the discovery file for SDK auto-discovery.
+	ln, err := net.Listen("tcp", cfg.addr)
 	if err != nil {
-		log.Error(err)
+		golog.Error("failed to bind go-ios REST API", "module", logModule, "addr", cfg.addr, "error", err.Error())
+		return
+	}
+	if useTLS {
+		cert, certErr := tls.LoadX509KeyPair(cfg.tlsCert, cfg.tlsKey)
+		if certErr != nil {
+			golog.Error("failed to load TLS key pair", "module", logModule, "cert", cfg.tlsCert, "error", certErr.Error())
+			_ = ln.Close()
+			return
+		}
+		ln = tls.NewListener(ln, &tls.Config{Certificates: []tls.Certificate{cert}})
 	}
-}
 
-// parseDisableAuth reports whether the --disable-auth flag was passed. It uses a
-// dedicated flag set so it never clashes with the global flag set and tolerates
-// unknown args gracefully.
-func parseDisableAuth(args []string) bool {
-	fs := flag.NewFlagSet("go-ios-restapi", flag.ContinueOnError)
-	fs.SetOutput(io.Discard)
-	disableAuth := fs.Bool("disable-auth", false, "run the REST API without authentication")
-	// Ignore parse errors (e.g. unknown flags) so extra args don't crash startup.
-	_ = fs.Parse(args)
-	return *disableAuth
+	// The bound TCP address carries the real, possibly OS-assigned port (even for
+	// the TLS listener, which wraps the TCP listener above).
+	tcpAddr := ln.Addr().(*net.TCPAddr)
+	host := tcpAddr.IP.String()
+	port := tcpAddr.Port
+
+	// Publish the discovery file so SDKs can auto-find this daemon regardless of
+	// which (ephemeral or pinned) port it landed on.
+	info := newDiscoveryInfo(host, port, useTLS)
+	discoveryPath, derr := writeDiscoveryFile(info)
+	if derr != nil {
+		// Non-fatal: the daemon still serves; SDKs just can't auto-discover it.
+		golog.Warn("failed to write REST API discovery file", "module", logModule, "error", derr.Error())
+	} else {
+		golog.Info("wrote REST API discovery file", "module", logModule, "path", discoveryPath, "baseUrl", info.BaseUrl)
+	}
+
+	golog.Info("go-ios REST API listening", "module", logModule, "baseUrl", info.BaseUrl, "host", host, "port", port, "tls", useTLS, "pid", os.Getpid())
+
+	// Graceful shutdown on SIGINT/SIGTERM so in-flight requests can drain, and
+	// remove the discovery file so stale entries don't linger after exit.
+	shutdownDone := make(chan struct{})
+	go func() {
+		sigs := make(chan os.Signal, 1)
+		signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
+		<-sigs
+		golog.Info("shutting down go-ios REST API", "module", logModule)
+		if rmErr := removeDiscoveryFile(); rmErr != nil {
+			golog.Warn("failed to remove REST API discovery file", "module", logModule, "error", rmErr.Error())
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		if err := srv.Shutdown(ctx); err != nil {
+			golog.Error("graceful shutdown failed", "module", logModule, "error", err.Error())
+		}
+		close(shutdownDone)
+	}()
+
+	if err := srv.Serve(ln); err != nil && err != http.ErrServerClosed {
+		golog.Error("go-ios REST API serve error", "module", logModule, "error", err.Error())
+		// Best-effort cleanup: on a serve failure the shutdown goroutine may never
+		// fire, so drop the discovery file here too.
+		_ = removeDiscoveryFile()
+		return
+	}
+	<-shutdownDone
 }
diff --git a/restapi/api/settings_endpoints.go b/restapi/api/settings_endpoints.go
new file mode 100644
index 000000000..130f26b37
--- /dev/null
+++ b/restapi/api/settings_endpoints.go
@@ -0,0 +1,148 @@
+package api
+
+import (
+	"net/http"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+)
+
+// registerSettingsRoutes registers device-settings endpoints (accessibility and
+// wifi) mirroring the corresponding `ios` CLI commands. Routes under /device/:udid.
+func registerSettingsRoutes(device *gin.RouterGroup) {
+	device.GET("/assistivetouch", GetAssistiveTouch)
+	device.PUT("/assistivetouch", SetAssistiveTouch)
+	device.GET("/timeformat", GetTimeFormat)
+	device.PUT("/timeformat", SetTimeFormat)
+	device.PUT("/wifi", SetWifi)
+	device.DELETE("/wifi", RemoveWifi)
+}
+
+type enabledRequest struct {
+	Enabled bool `json:"enabled"`
+}
+
+// GetAssistiveTouch reports whether AssistiveTouch is enabled (CLI: ios assistivetouch get).
+// @Summary Get AssistiveTouch state
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]bool
+// @Router /device/{udid}/assistivetouch [get]
+func GetAssistiveTouch(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	enabled, err := ios.GetAssistiveTouch(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"AssistiveTouchEnabled": enabled})
+}
+
+// SetAssistiveTouch enables/disables AssistiveTouch (CLI: ios assistivetouch enable|disable).
+// @Summary Set AssistiveTouch state
+// @Param udid path string true "Device UDID"
+// @Param body body enabledRequest true "enabled"
+// @Success 200 {object} map[string]bool
+// @Router /device/{udid}/assistivetouch [put]
+func SetAssistiveTouch(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req enabledRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if err := ios.SetAssistiveTouch(device, req.Enabled); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"AssistiveTouchEnabled": req.Enabled})
+}
+
+// GetTimeFormat reports whether the device uses a 24-hour clock (CLI: ios timeformat get).
+// @Summary Get time-format state
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]bool
+// @Router /device/{udid}/timeformat [get]
+func GetTimeFormat(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	uses24, err := ios.GetUses24HourClock(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"Uses24HourClock": uses24})
+}
+
+type timeFormatRequest struct {
+	Uses24Hour bool `json:"uses24Hour"`
+}
+
+// SetTimeFormat sets 24h/12h clock (CLI: ios timeformat 24h|12h).
+// @Summary Set time format
+// @Param udid path string true "Device UDID"
+// @Param body body timeFormatRequest true "uses24Hour"
+// @Success 200 {object} map[string]bool
+// @Router /device/{udid}/timeformat [put]
+func SetTimeFormat(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req timeFormatRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if err := ios.SetUses24HourClock(device, req.Uses24Hour); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"Uses24HourClock": req.Uses24Hour})
+}
+
+type wifiRequest struct {
+	SSID     string `json:"ssid"`
+	Password string `json:"password"`
+	EncType  string `json:"encType"`
+}
+
+// SetWifi provisions a wifi network (CLI: ios wifi).
+// @Summary Provision a wifi network
+// @Param udid path string true "Device UDID"
+// @Param body body wifiRequest true "ssid/password/encType"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/wifi [put]
+func SetWifi(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	var req wifiRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if req.SSID == "" {
+		RespondError(c, http.StatusBadRequest, errMissingSSID)
+		return
+	}
+	if err := mcinstall.PrepareWifi(device, req.SSID, req.Password, req.EncType); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "wifi provisioned", "ssid": req.SSID})
+}
+
+// RemoveWifi removes a provisioned wifi network (CLI: ios wifi --remove).
+// @Summary Remove a provisioned wifi network
+// @Param udid path string true "Device UDID"
+// @Param ssid query string true "network SSID"
+// @Success 200 {object} map[string]string
+// @Router /device/{udid}/wifi [delete]
+func RemoveWifi(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	ssid := c.Query("ssid")
+	if ssid == "" {
+		RespondError(c, http.StatusBadRequest, errMissingSSID)
+		return
+	}
+	if err := mcinstall.RemoveWifi(device, ssid); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"message": "wifi removed", "ssid": ssid})
+}
diff --git a/restapi/api/sign_endpoints.go b/restapi/api/sign_endpoints.go
new file mode 100644
index 000000000..6fbff327a
--- /dev/null
+++ b/restapi/api/sign_endpoints.go
@@ -0,0 +1,445 @@
+package api
+
+import (
+	"bytes"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/pem"
+	"errors"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/mcinstall"
+	"github.com/gin-gonic/gin"
+	"software.sslmate.com/src/go-pkcs12"
+)
+
+// Signing / codesigning REST endpoints.
+//
+// SECRETS: these handlers move App Store Connect .p8 keys, P12 identities and
+// their passwords through memory and short-lived temp files. NONE of that
+// material is ever logged — logs carry only non-secret metadata (bundle id,
+// artifact size, cert resource id). Uploads are bounded by maxUploadBytes and
+// written to a per-request temp dir that is always removed on return.
+//
+// The endpoints depend only on the Signer interface (see signing_adapter.go);
+// the concrete implementation is swappable for ios/codesign later.
+
+// Signing-specific sentinel errors.
+var (
+	errMissingASCKey    = errors.New("missing required multipart 'asc-private-key' (.p8 App Store Connect key)")
+	errMissingASCFields = errors.New("both 'asc-key-id' and 'asc-issuer-id' are required")
+	errMissingIPA       = errors.New("missing required multipart 'ipa' (app or .ipa upload)")
+	errMissingP12File   = errors.New("missing required multipart 'p12file'")
+	errMissingSignProf  = errors.New("missing required multipart 'profile' (mobileprovision)")
+	errMissingSupCert   = errors.New("missing required multipart 'cert' (supervision identity: DER/PEM/P12)")
+)
+
+// registerSignHostRoutes registers host-local (device-free) codesigning routes
+// under /api/v1/sign plus the host-level supervision cert creation route. These
+// need no device.
+func registerSignHostRoutes(router *gin.RouterGroup) {
+	sign := router.Group("/sign")
+	sign.POST("/certificate", SignCertificate)
+	sign.POST("/provision", SignProvision)
+	sign.POST("/app", SignApp)
+
+	// Supervision-cert generation, mirroring `ios prepare create-cert`. Device-
+	// free, so it lives at the host level next to the other prepare routes.
+	router.POST("/prepare/create-cert", PrepareCreateCert)
+}
+
+// registerSignDeviceRoutes registers device-scoped preparation routes under
+// /device/:udid.
+func registerSignDeviceRoutes(device *gin.RouterGroup) {
+	device.POST("/prepare", PrepareDevice)
+}
+
+// SignCertificate creates one App Store Connect signing certificate and returns
+// its P12 (certificate + private key) as a downloadable application/x-pkcs12
+// file. The generated P12 password is echoed in the X-P12-Password response
+// header (it is client-supplied, or empty). Device-free.
+// @Summary Create a signing certificate (App Store Connect)
+// @Accept multipart/form-data
+// @Produce application/x-pkcs12
+// @Param asc-private-key formData file true ".p8 App Store Connect API key"
+// @Param asc-key-id formData string true "App Store Connect key id"
+// @Param asc-issuer-id formData string true "App Store Connect issuer id"
+// @Param revoke-existing formData bool false "revoke existing iOS Development certificates first"
+// @Param p12password formData string false "password to protect the generated P12"
+// @Success 200 {file} binary
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /sign/certificate [post]
+func SignCertificate(c *gin.Context) {
+	creds, err := readASCCredentials(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	p12password := c.PostForm("p12password")
+	revoke := parseBoolForm(c.PostForm("revoke-existing"))
+
+	res, err := defaultSigner.PrepareCertificate(c.Request.Context(), creds, PrepareCertOptions{
+		P12Password:    p12password,
+		RevokeExisting: revoke,
+	})
+	if err != nil {
+		RespondError(c, http.StatusBadGateway, err)
+		return
+	}
+	golog.Info("created signing certificate", "module", logModule, "certificateId", res.CertificateID, "p12Bytes", len(res.P12))
+	c.Header("X-Certificate-Id", res.CertificateID)
+	c.Header("X-P12-Password", p12password)
+	c.Data(http.StatusOK, "application/x-pkcs12", res.P12)
+}
+
+// SignProvision creates a bundle id, development certificate and provisioning
+// profile via App Store Connect and returns both artifacts base64-encoded in a
+// JSON envelope (so a single response can carry the .mobileprovision and .p12).
+// Device-free at the host level: the target device udid is supplied as a form
+// field so Apple can register it against the profile.
+// @Summary Create a provisioning profile + P12 (App Store Connect)
+// @Accept multipart/form-data
+// @Produce json
+// @Param asc-private-key formData file true ".p8 App Store Connect API key"
+// @Param asc-key-id formData string true "App Store Connect key id"
+// @Param asc-issuer-id formData string true "App Store Connect issuer id"
+// @Param bundleid formData string true "app bundle identifier"
+// @Param udid formData string true "target device udid"
+// @Param bundlename formData string false "bundle display name"
+// @Param profilename formData string false "provisioning profile name"
+// @Param devicename formData string false "device display name"
+// @Param certificate-id formData string false "reuse an existing certificate (no new P12)"
+// @Param revoke-existing formData bool false "revoke existing certificates first"
+// @Param p12password formData string false "password to protect the generated P12"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /sign/provision [post]
+func SignProvision(c *gin.Context) {
+	creds, err := readASCCredentials(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	bundleID := strings.TrimSpace(c.PostForm("bundleid"))
+	if bundleID == "" {
+		RespondError(c, http.StatusBadRequest, errMissingBundleID)
+		return
+	}
+	udid := strings.TrimSpace(c.PostForm("udid"))
+	p12password := c.PostForm("p12password")
+
+	res, err := defaultSigner.PrepareProvisioning(c.Request.Context(), creds, PrepareProvisioningOptions{
+		BundleID:       bundleID,
+		BundleName:     c.PostForm("bundlename"),
+		ProfileName:    c.PostForm("profilename"),
+		DeviceName:     c.PostForm("devicename"),
+		DeviceUDID:     udid,
+		P12Password:    p12password,
+		RevokeExisting: parseBoolForm(c.PostForm("revoke-existing")),
+		CertificateID:  strings.TrimSpace(c.PostForm("certificate-id")),
+	})
+	if err != nil {
+		RespondError(c, http.StatusBadGateway, err)
+		return
+	}
+	golog.Info("created provisioning assets", "module", logModule, "udid", udid, "bundleId", res.BundleID,
+		"certificateId", res.CertificateID, "profileBytes", len(res.Profile), "p12Bytes", len(res.P12))
+
+	resp := gin.H{
+		"bundleId":              res.BundleID,
+		"certificateId":         res.CertificateID,
+		"mobileprovisionBase64": encodeBase64(res.Profile),
+	}
+	if res.P12 != nil {
+		resp["p12Base64"] = encodeBase64(res.P12)
+		resp["p12Password"] = p12password
+	}
+	c.JSON(http.StatusOK, resp)
+}
+
+// SignApp resigns an uploaded app/IPA with an uploaded P12 identity and
+// provisioning profile, streaming the signed IPA back as application/octet-
+// stream. Uploads go to a per-request temp dir that is removed on return.
+//
+// NOTE: this is synchronous for v1. Large IPAs make it a prime candidate for the
+// async jobs subsystem (jobs.go) — resign in a background job and let the client
+// poll/download — but that is out of scope here.
+// @Summary Resign an app/IPA with a P12 + provisioning profile
+// @Accept multipart/form-data
+// @Produce application/octet-stream
+// @Param ipa formData file true "app or .ipa to resign"
+// @Param p12file formData file true "signing identity (.p12)"
+// @Param profile formData file true "provisioning profile (.mobileprovision)"
+// @Param p12password formData string false "P12 password"
+// @Param bundleid formData string false "override bundle id"
+// @Success 200 {file} binary
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /sign/app [post]
+func SignApp(c *gin.Context) {
+	tmpDir, cleanup, err := newRequestTempDir("go-ios-sign-app-")
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer cleanup()
+
+	ipaName, _ := formFileName(c, "ipa")
+	ext := filepath.Ext(ipaName)
+	if ext == "" {
+		ext = ".ipa"
+	}
+	ipaPath, err := saveFormFileToDir(c, "ipa", tmpDir, "input"+ext)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, errMissingIPA)
+		return
+	}
+	p12, err := readFormFile(c, "p12file")
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, errMissingP12File)
+		return
+	}
+	profile, err := readFormFile(c, "profile")
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, errMissingSignProf)
+		return
+	}
+
+	res, err := defaultSigner.SignApp(c.Request.Context(), SignAppOptions{
+		InputPath:   ipaPath,
+		P12:         p12,
+		P12Password: c.PostForm("p12password"),
+		Profile:     profile,
+		BundleID:    strings.TrimSpace(c.PostForm("bundleid")),
+	})
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+
+	info, err := os.Stat(res.OutputPath)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	golog.Info("resigned app", "module", logModule, "bundleId", res.BundleID, "signedBytes", info.Size())
+	downloadName := "signed" + filepath.Ext(res.OutputPath)
+	c.Header("Content-Disposition", "attachment; filename=\""+downloadName+"\"")
+	c.File(res.OutputPath)
+}
+
+// PrepareCreateCert generates a self-signed supervision identity (CLI: ios
+// prepare create-cert) and returns it as a JSON envelope containing the DER and
+// PEM certificate and private key, base64-encoded. Device-free.
+// @Summary Generate a device supervision certificate
+// @Produce json
+// @Success 200 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /prepare/create-cert [post]
+func PrepareCreateCert(c *gin.Context) {
+	cert, err := ios.CreateDERFormattedSupervisionCert()
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	golog.Info("generated supervision certificate", "module", logModule, "certDerBytes", len(cert.CertDER))
+	c.JSON(http.StatusOK, gin.H{
+		"certDerBase64":       encodeBase64(cert.CertDER),
+		"certPem":             string(cert.CertPEM),
+		"privateKeyDerBase64": encodeBase64(cert.PrivateKeyDER),
+		"privateKeyPem":       string(cert.PrivateKeyPEM),
+	})
+}
+
+// PrepareDevice runs the device preparation/provisioning flow (CLI: ios
+// prepare). Send multipart/form-data. To supervise the device, include a "cert"
+// file (DER/PEM/P12 supervision identity) and optional "p12password"; without a
+// cert the device is prepared without supervision. Optional fields: repeated
+// "skip" values (see /prepare/skip-options), "orgname", "locale", "lang".
+// @Summary Prepare (and optionally supervise) a device
+// @Accept multipart/form-data
+// @Param udid path string true "Device UDID"
+// @Param cert formData file false "supervision identity (DER/PEM/P12)"
+// @Param p12password formData string false "P12 password (if cert is a P12)"
+// @Param skip formData []string false "setup panes to skip"
+// @Param orgname formData string false "supervision organization name"
+// @Param locale formData string false "device locale (default en_US)"
+// @Param lang formData string false "device language (default en)"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/prepare [post]
+func PrepareDevice(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	var certDER []byte
+	if raw, err := readFormFile(c, "cert"); err == nil && len(raw) > 0 {
+		der, derErr := extractSupervisionCertDER(raw, c.PostForm("p12password"))
+		if derErr != nil {
+			RespondError(c, http.StatusBadRequest, derErr)
+			return
+		}
+		certDER = der
+	}
+
+	skip := c.PostFormArray("skip")
+	orgname := c.PostForm("orgname")
+	locale := c.PostForm("locale")
+	lang := c.PostForm("lang")
+
+	golog.Info("preparing device", "module", logModule, "udid", device.Properties.SerialNumber,
+		"supervise", certDER != nil, "skipCount", len(skip))
+	if err := mcinstall.Prepare(device, skip, certDER, orgname, locale, lang); err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"status": "prepared", "supervised": certDER != nil})
+}
+
+// --- helpers ---------------------------------------------------------------
+
+// readASCCredentials reads the App Store Connect .p8 key and its id fields from a
+// multipart request. The private key bytes are held only in memory and never
+// logged.
+func readASCCredentials(c *gin.Context) (ASCCredentials, error) {
+	keyID := strings.TrimSpace(c.PostForm("asc-key-id"))
+	issuerID := strings.TrimSpace(c.PostForm("asc-issuer-id"))
+	if keyID == "" || issuerID == "" {
+		return ASCCredentials{}, errMissingASCFields
+	}
+	key, err := readFormFile(c, "asc-private-key")
+	if err != nil || len(key) == 0 {
+		return ASCCredentials{}, errMissingASCKey
+	}
+	return ASCCredentials{KeyID: keyID, IssuerID: issuerID, PrivateKey: key}, nil
+}
+
+// parseBoolForm interprets a form field as a boolean, treating parse failures and
+// empty values as false.
+func parseBoolForm(v string) bool {
+	if v == "" {
+		return false
+	}
+	b, err := strconv.ParseBool(strings.TrimSpace(v))
+	if err != nil {
+		return false
+	}
+	return b
+}
+
+// newRequestTempDir creates a per-request temp dir and returns a cleanup func
+// that removes it (logging, never failing, on error).
+func newRequestTempDir(prefix string) (string, func(), error) {
+	dir, err := os.MkdirTemp("", prefix)
+	if err != nil {
+		return "", func() {}, err
+	}
+	cleanup := func() {
+		if err := os.RemoveAll(dir); err != nil {
+			golog.Warn("failed to remove request temp dir", "module", logModule, "path", dir, "err", err.Error())
+		}
+	}
+	return dir, cleanup, nil
+}
+
+// saveFormFileToDir reads a bounded multipart file field and writes it into dir
+// under name, returning the written path.
+func saveFormFileToDir(c *gin.Context, field, dir, name string) (string, error) {
+	data, err := readFormFile(c, field)
+	if err != nil {
+		return "", err
+	}
+	if len(data) == 0 {
+		return "", errUploadTooLarge // treated as invalid by callers mapping to 400
+	}
+	path := filepath.Join(dir, name)
+	if err := os.WriteFile(path, data, 0600); err != nil {
+		return "", err
+	}
+	return path, nil
+}
+
+// formFileName returns the client-supplied filename for a multipart file field.
+func formFileName(c *gin.Context, field string) (string, error) {
+	_, hdr, err := c.Request.FormFile(field)
+	if err != nil {
+		return "", err
+	}
+	return hdr.Filename, nil
+}
+
+// readAndRemove reads a file fully then removes it. Used to pull generated
+// artifacts (P12/profile) off disk and immediately delete the on-disk copy so
+// key material does not linger.
+func readAndRemove(path string) ([]byte, error) {
+	if path == "" {
+		return nil, nil
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, err
+	}
+	if rmErr := os.Remove(path); rmErr != nil {
+		golog.Warn("failed to remove generated artifact", "module", logModule, "path", path, "err", rmErr.Error())
+	}
+	return data, nil
+}
+
+// signedOutputPath derives a "-signed" sibling path for the given input,
+// preserving the extension so IPAs stay .ipa.
+func signedOutputPath(inputPath string) string {
+	ext := filepath.Ext(inputPath)
+	if ext == "" {
+		return inputPath + "-signed"
+	}
+	return strings.TrimSuffix(inputPath, ext) + "-signed" + ext
+}
+
+// deviceEntryForUDID builds a minimal DeviceEntry carrying just the udid, which
+// is all PrepareSigningAssets needs to register the device with Apple.
+func deviceEntryForUDID(udid string) ios.DeviceEntry {
+	return ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: udid}}
+}
+
+// encodeBase64 is a tiny wrapper so artifact-encoding call sites read clearly.
+func encodeBase64(b []byte) string {
+	return base64.StdEncoding.EncodeToString(b)
+}
+
+// errUnparseableCert is returned when a supervision identity upload is not
+// recognizable as DER, PEM, or (with a password) P12.
+var errUnparseableCert = errors.New("unable to parse supervision certificate: not valid DER, PEM, or PKCS12")
+
+// extractSupervisionCertDER normalizes an uploaded supervision identity
+// (raw DER, PEM, PEM-with-metadata, or P12 when a password is given) to raw DER,
+// which is what mcinstall.Prepare requires. The p12password, if present, is used
+// only to decrypt and is never logged.
+func extractSupervisionCertDER(raw []byte, p12password string) ([]byte, error) {
+	// Raw DER.
+	if _, err := x509.ParseCertificate(raw); err == nil {
+		return raw, nil
+	}
+	// PEM, possibly with leading metadata (e.g. OpenSSL "Bag Attributes").
+	if start := bytes.Index(raw, []byte("-----BEGIN CERTIFICATE-----")); start != -1 {
+		if block, _ := pem.Decode(raw[start:]); block != nil && block.Type == "CERTIFICATE" {
+			if _, err := x509.ParseCertificate(block.Bytes); err == nil {
+				return block.Bytes, nil
+			}
+		}
+	}
+	// P12 (needs a password).
+	if p12password != "" {
+		if _, cert, err := pkcs12.Decode(raw, p12password); err == nil && cert != nil {
+			return cert.Raw, nil
+		}
+	}
+	return nil, errUnparseableCert
+}
diff --git a/restapi/api/sign_endpoints_test.go b/restapi/api/sign_endpoints_test.go
new file mode 100644
index 000000000..2c59e75c8
--- /dev/null
+++ b/restapi/api/sign_endpoints_test.go
@@ -0,0 +1,366 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/gin-gonic/gin"
+)
+
+// mockSigner is a device-free, impl-free Signer used to prove the endpoints
+// parse multipart correctly, pass the right args, and stream/return artifacts.
+// It records what it was called with (secrets included) so tests can assert both
+// correct wiring and that the handlers never leak those secrets into responses
+// or logs.
+type mockSigner struct {
+	certResult   CertResult
+	assetsResult AssetsResult
+	signResult   SignResult
+	err          error
+
+	gotCreds        ASCCredentials
+	gotCertOpts     PrepareCertOptions
+	gotProvOpts     PrepareProvisioningOptions
+	gotSignOpts     SignAppOptions
+	signInputExists bool
+}
+
+func (m *mockSigner) PrepareCertificate(_ context.Context, creds ASCCredentials, opts PrepareCertOptions) (CertResult, error) {
+	m.gotCreds = creds
+	m.gotCertOpts = opts
+	return m.certResult, m.err
+}
+
+func (m *mockSigner) PrepareProvisioning(_ context.Context, creds ASCCredentials, opts PrepareProvisioningOptions) (AssetsResult, error) {
+	m.gotCreds = creds
+	m.gotProvOpts = opts
+	return m.assetsResult, m.err
+}
+
+func (m *mockSigner) SignApp(_ context.Context, opts SignAppOptions) (SignResult, error) {
+	m.gotSignOpts = opts
+	// Record whether the uploaded input actually landed on disk in a temp dir.
+	if _, err := os.Stat(opts.InputPath); err == nil {
+		m.signInputExists = true
+	}
+	return m.signResult, m.err
+}
+
+// withSigner swaps defaultSigner for the duration of a test.
+func withSigner(t *testing.T, s Signer) {
+	t.Helper()
+	prev := defaultSigner
+	defaultSigner = s
+	t.Cleanup(func() { defaultSigner = prev })
+}
+
+// signMultipart builds a multipart request context for a signing endpoint.
+func signMultipart(t *testing.T, fields map[string]string, files map[string][]byte) (*httptest.ResponseRecorder, *gin.Context) {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	var buf bytes.Buffer
+	mw := multipart.NewWriter(&buf)
+	for k, v := range fields {
+		if err := mw.WriteField(k, v); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for name, data := range files {
+		fw, err := mw.CreateFormFile(name, name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, err := fw.Write(data); err != nil {
+			t.Fatal(err)
+		}
+	}
+	mw.Close()
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	r := httptest.NewRequest(http.MethodPost, "/x", &buf)
+	r.Header.Set("Content-Type", mw.FormDataContentType())
+	c.Request = r
+	return w, c
+}
+
+// TestSignCertificate_Success proves the certificate endpoint parses the ASC
+// credentials + fields, calls the Signer with them, and streams back the P12.
+func TestSignCertificate_Success(t *testing.T) {
+	m := &mockSigner{certResult: CertResult{P12: []byte("P12BYTES"), CertificateID: "CERT123"}}
+	withSigner(t, m)
+
+	secretKey := []byte("-----BEGIN PRIVATE KEY-----\nSECRET\n-----END PRIVATE KEY-----")
+	w, c := signMultipart(t,
+		map[string]string{"asc-key-id": "KID", "asc-issuer-id": "IID", "revoke-existing": "true", "p12password": "hunter2"},
+		map[string][]byte{"asc-private-key": secretKey},
+	)
+	SignCertificate(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want 200 (body=%s)", w.Code, w.Body.String())
+	}
+	if got := w.Body.Bytes(); !bytes.Equal(got, []byte("P12BYTES")) {
+		t.Fatalf("body = %q, want P12 bytes", got)
+	}
+	if ct := w.Header().Get("Content-Type"); ct != "application/x-pkcs12" {
+		t.Fatalf("content-type = %q", ct)
+	}
+	if w.Header().Get("X-Certificate-Id") != "CERT123" {
+		t.Fatalf("missing cert id header")
+	}
+	// Signer received the exact credentials + options.
+	if m.gotCreds.KeyID != "KID" || m.gotCreds.IssuerID != "IID" || !bytes.Equal(m.gotCreds.PrivateKey, secretKey) {
+		t.Fatalf("signer got wrong creds: %+v", m.gotCreds)
+	}
+	if !m.gotCertOpts.RevokeExisting || m.gotCertOpts.P12Password != "hunter2" {
+		t.Fatalf("signer got wrong opts: %+v", m.gotCertOpts)
+	}
+	// The private key bytes and password must never appear in the response body.
+	assertNoSecrets(t, w.Body.String(), "SECRET", "hunter2")
+}
+
+// TestSignCertificate_MissingKey rejects a request without the .p8 upload.
+func TestSignCertificate_MissingKey(t *testing.T) {
+	m := &mockSigner{}
+	withSigner(t, m)
+	w, c := signMultipart(t, map[string]string{"asc-key-id": "K", "asc-issuer-id": "I"}, nil)
+	SignCertificate(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("got %d, want 400", w.Code)
+	}
+}
+
+// TestSignCertificate_MissingFields rejects a request without key/issuer ids.
+func TestSignCertificate_MissingFields(t *testing.T) {
+	m := &mockSigner{}
+	withSigner(t, m)
+	w, c := signMultipart(t, nil, map[string][]byte{"asc-private-key": []byte("k")})
+	SignCertificate(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("got %d, want 400", w.Code)
+	}
+}
+
+// TestSignProvision_Success proves the provision endpoint wires bundle/udid and
+// returns base64 profile + p12 in JSON, redacting secrets.
+func TestSignProvision_Success(t *testing.T) {
+	m := &mockSigner{assetsResult: AssetsResult{
+		P12: []byte("P12"), Profile: []byte("PROFILE"), BundleID: "com.example.app", CertificateID: "C1",
+	}}
+	withSigner(t, m)
+
+	w, c := signMultipart(t,
+		map[string]string{
+			"asc-key-id": "KID", "asc-issuer-id": "IID",
+			"bundleid": "com.example.app", "udid": "UDID-1", "p12password": "pw",
+		},
+		map[string][]byte{"asc-private-key": []byte("SECRETKEY")},
+	)
+	SignProvision(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want 200 (body=%s)", w.Code, w.Body.String())
+	}
+	var resp map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("bad json: %v (%s)", err, w.Body.String())
+	}
+	if resp["bundleId"] != "com.example.app" || resp["certificateId"] != "C1" {
+		t.Fatalf("wrong metadata: %+v", resp)
+	}
+	if dec, _ := base64.StdEncoding.DecodeString(resp["mobileprovisionBase64"]); string(dec) != "PROFILE" {
+		t.Fatalf("profile round-trip failed: %q", resp["mobileprovisionBase64"])
+	}
+	if dec, _ := base64.StdEncoding.DecodeString(resp["p12Base64"]); string(dec) != "P12" {
+		t.Fatalf("p12 round-trip failed")
+	}
+	if m.gotProvOpts.BundleID != "com.example.app" || m.gotProvOpts.DeviceUDID != "UDID-1" {
+		t.Fatalf("signer got wrong prov opts: %+v", m.gotProvOpts)
+	}
+	assertNoSecrets(t, w.Body.String(), "SECRETKEY")
+}
+
+// TestSignProvision_MissingBundle rejects a request without a bundle id.
+func TestSignProvision_MissingBundle(t *testing.T) {
+	withSigner(t, &mockSigner{})
+	w, c := signMultipart(t,
+		map[string]string{"asc-key-id": "K", "asc-issuer-id": "I", "udid": "U"},
+		map[string][]byte{"asc-private-key": []byte("k")},
+	)
+	SignProvision(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("got %d, want 400", w.Code)
+	}
+}
+
+// TestSignProvision_ReuseModeNoP12 verifies reuse mode (nil P12) omits p12 keys.
+func TestSignProvision_ReuseModeNoP12(t *testing.T) {
+	m := &mockSigner{assetsResult: AssetsResult{Profile: []byte("P"), BundleID: "b", CertificateID: "C1"}}
+	withSigner(t, m)
+	w, c := signMultipart(t,
+		map[string]string{"asc-key-id": "K", "asc-issuer-id": "I", "bundleid": "b", "certificate-id": "C1"},
+		map[string][]byte{"asc-private-key": []byte("k")},
+	)
+	SignProvision(c)
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want 200 (%s)", w.Code, w.Body.String())
+	}
+	var resp map[string]string
+	_ = json.Unmarshal(w.Body.Bytes(), &resp)
+	if _, ok := resp["p12Base64"]; ok {
+		t.Fatalf("reuse mode should not return a p12")
+	}
+	if m.gotProvOpts.CertificateID != "C1" {
+		t.Fatalf("certificate-id not forwarded")
+	}
+}
+
+// TestSignApp_Success proves the app endpoint writes the upload to a temp dir,
+// calls the Signer with that path, streams the signed artifact, and cleans up.
+func TestSignApp_Success(t *testing.T) {
+	// The signed artifact the mock "produces" — write it so c.File can stream it.
+	signed, err := os.CreateTemp(t.TempDir(), "signed-*.ipa")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := signed.WriteString("SIGNED-IPA"); err != nil {
+		t.Fatal(err)
+	}
+	signed.Close()
+
+	m := &mockSigner{signResult: SignResult{OutputPath: signed.Name(), BundleID: "com.x"}}
+	withSigner(t, m)
+
+	w, c := signMultipart(t,
+		map[string]string{"p12password": "pw", "bundleid": "com.x"},
+		map[string][]byte{"ipa": []byte("RAW-IPA"), "p12file": []byte("P12"), "profile": []byte("PROF")},
+	)
+	SignApp(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want 200 (%s)", w.Code, w.Body.String())
+	}
+	if w.Body.String() != "SIGNED-IPA" {
+		t.Fatalf("body = %q, want streamed signed artifact", w.Body.String())
+	}
+	if !m.signInputExists {
+		t.Fatalf("upload was not written to disk before signing")
+	}
+	if !bytes.Equal(m.gotSignOpts.P12, []byte("P12")) || !bytes.Equal(m.gotSignOpts.Profile, []byte("PROF")) {
+		t.Fatalf("signer got wrong bytes: %+v", m.gotSignOpts)
+	}
+	if m.gotSignOpts.P12Password != "pw" || m.gotSignOpts.BundleID != "com.x" {
+		t.Fatalf("signer got wrong fields: %+v", m.gotSignOpts)
+	}
+	// The per-request temp dir (and thus the uploaded input) must be gone.
+	if _, err := os.Stat(m.gotSignOpts.InputPath); !os.IsNotExist(err) {
+		t.Fatalf("temp upload not cleaned up: %v", err)
+	}
+	assertNoSecrets(t, w.Body.String(), "pw")
+}
+
+// TestSignApp_MissingUploads rejects requests missing required file fields.
+func TestSignApp_MissingUploads(t *testing.T) {
+	withSigner(t, &mockSigner{})
+	// Missing ipa.
+	w, c := signMultipart(t, nil, map[string][]byte{"p12file": []byte("x"), "profile": []byte("y")})
+	SignApp(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("missing ipa: got %d, want 400", w.Code)
+	}
+	// Missing p12file.
+	w2, c2 := signMultipart(t, nil, map[string][]byte{"ipa": []byte("x"), "profile": []byte("y")})
+	SignApp(c2)
+	if w2.Code != http.StatusBadRequest {
+		t.Fatalf("missing p12file: got %d, want 400", w2.Code)
+	}
+}
+
+// TestPrepareCreateCert generates a supervision cert end-to-end (device-free,
+// no mock: it exercises the real ios crypto helper) and checks the envelope.
+func TestPrepareCreateCert(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest(http.MethodPost, "/prepare/create-cert", nil)
+	PrepareCreateCert(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("got %d, want 200 (%s)", w.Code, w.Body.String())
+	}
+	var resp map[string]string
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("bad json: %v", err)
+	}
+	for _, k := range []string{"certDerBase64", "certPem", "privateKeyDerBase64", "privateKeyPem"} {
+		if resp[k] == "" {
+			t.Fatalf("missing field %q", k)
+		}
+	}
+	if !strings.Contains(resp["certPem"], "CERTIFICATE") {
+		t.Fatalf("certPem not PEM: %q", resp["certPem"])
+	}
+	if _, err := base64.StdEncoding.DecodeString(resp["certDerBase64"]); err != nil {
+		t.Fatalf("certDerBase64 not base64: %v", err)
+	}
+}
+
+// TestPrepareDevice_BadCert rejects an unparseable supervision cert before any
+// device I/O (so this stays device-free).
+func TestPrepareDevice_BadCert(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	w, c := signMultipart(t, map[string]string{"orgname": "Acme"}, map[string][]byte{"cert": []byte("not-a-cert")})
+	c.Set(IOS_KEY, ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: "UDID"}})
+	PrepareDevice(c)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("got %d, want 400 (%s)", w.Code, w.Body.String())
+	}
+}
+
+// TestExtractSupervisionCertDER covers DER, PEM and rejection paths of the
+// upload normalizer without needing a device.
+func TestExtractSupervisionCertDER(t *testing.T) {
+	if _, err := extractSupervisionCertDER([]byte("garbage"), ""); err == nil {
+		t.Fatalf("expected error for garbage input")
+	}
+	// A real DER round-trips: reuse the supervision cert generator.
+	cert, err := ios.CreateDERFormattedSupervisionCert()
+	if err != nil {
+		t.Fatal(err)
+	}
+	der, err := extractSupervisionCertDER(cert.CertDER, "")
+	if err != nil || !bytes.Equal(der, cert.CertDER) {
+		t.Fatalf("DER passthrough failed: err=%v", err)
+	}
+	pemDer, err := extractSupervisionCertDER(cert.CertPEM, "")
+	if err != nil || !bytes.Equal(pemDer, cert.CertDER) {
+		t.Fatalf("PEM extraction failed: err=%v", err)
+	}
+}
+
+// TestSigningAdapterSatisfiesSigner is a compile-time check that the concrete
+// adapter (and the wired default) implement Signer.
+func TestSigningAdapterSatisfiesSigner(t *testing.T) {
+	var _ Signer = signingAdapter{}
+	var _ Signer = defaultSigner
+}
+
+// assertNoSecrets fails if any secret substring leaks into the given text.
+func assertNoSecrets(t *testing.T, text string, secrets ...string) {
+	t.Helper()
+	for _, s := range secrets {
+		if s != "" && strings.Contains(text, s) {
+			t.Fatalf("secret %q leaked into output: %s", s, text)
+		}
+	}
+}
diff --git a/restapi/api/signing_adapter.go b/restapi/api/signing_adapter.go
new file mode 100644
index 000000000..73c07e256
--- /dev/null
+++ b/restapi/api/signing_adapter.go
@@ -0,0 +1,182 @@
+package api
+
+import (
+	"context"
+
+	"github.com/danielpaulus/go-ios/ios/signing"
+)
+
+// Signer is the seam between the REST signing endpoints and whatever code
+// actually talks to App Store Connect and rewrites app signatures. The
+// endpoints in sign_endpoints.go depend ONLY on this interface, so the concrete
+// implementation is swappable:
+//
+//   - The default wired below is signingAdapter, a thin wrapper over the current
+//     ios/signing package.
+//   - The in-repo ios/codesign package from branch daniel/codesign-command is the
+//     intended future implementation. When it lands, provide a second adapter
+//     that satisfies Signer over ios/codesign and swap defaultSigner (or make it
+//     injectable) — no endpoint or test change is required.
+//
+// Keeping the surface small (three operations) is deliberate: it is the minimum
+// the endpoints need and the maximum a swapped-in implementation must provide.
+type Signer interface {
+	// PrepareCertificate creates one signing certificate via App Store Connect
+	// and returns its P12 bytes (certificate + private key) plus the ASC
+	// resource id. Device-free: it is the account-wide half of signing.
+	PrepareCertificate(ctx context.Context, creds ASCCredentials, opts PrepareCertOptions) (CertResult, error)
+
+	// PrepareProvisioning creates a bundle id, a development certificate (unless
+	// reusing one) and a development provisioning profile, returning the profile
+	// bytes and — when a certificate was created — the P12 bytes. Needs a device
+	// udid so Apple can register it against the profile.
+	PrepareProvisioning(ctx context.Context, creds ASCCredentials, opts PrepareProvisioningOptions) (AssetsResult, error)
+
+	// SignApp resigns the app/IPA at inputPath using the given P12 and
+	// provisioning profile files, writing the signed artifact to a path it
+	// chooses and returns. It never mutates the input.
+	SignApp(ctx context.Context, opts SignAppOptions) (SignResult, error)
+}
+
+// ASCCredentials carries the App Store Connect API key material. The private key
+// is the raw bytes of the .p8 file. Never log this struct.
+type ASCCredentials struct {
+	KeyID      string
+	IssuerID   string
+	PrivateKey []byte
+}
+
+// PrepareCertOptions are the inputs to PrepareCertificate.
+type PrepareCertOptions struct {
+	P12Password    string
+	P12Output      string
+	RevokeExisting bool
+}
+
+// CertResult is the output of PrepareCertificate: the P12 bytes and the ASC
+// certificate resource id.
+type CertResult struct {
+	P12           []byte
+	CertificateID string
+}
+
+// PrepareProvisioningOptions are the inputs to PrepareProvisioning.
+type PrepareProvisioningOptions struct {
+	BundleID       string
+	BundleName     string
+	ProfileName    string
+	DeviceName     string
+	DeviceUDID     string
+	P12Password    string
+	RevokeExisting bool
+	// CertificateID, when set, provisions a profile against an existing
+	// certificate instead of creating a new one; no P12 is produced.
+	CertificateID string
+}
+
+// AssetsResult is the output of PrepareProvisioning. P12 is nil in reuse mode
+// (CertificateID set on the request).
+type AssetsResult struct {
+	P12           []byte
+	Profile       []byte
+	BundleID      string
+	CertificateID string
+}
+
+// SignAppOptions are the inputs to SignApp. P12 and Profile are the raw file
+// bytes; P12Password may be empty. BundleID is optional (derived from the app
+// when empty).
+type SignAppOptions struct {
+	InputPath   string
+	P12         []byte
+	P12Password string
+	Profile     []byte
+	BundleID    string
+}
+
+// SignResult is the output of SignApp: the path of the signed artifact and the
+// resolved bundle id.
+type SignResult struct {
+	OutputPath string
+	BundleID   string
+}
+
+// signingAdapter is the default Signer, implemented over the current ios/signing
+// package. It exists so the endpoints don't import ios/signing directly and so a
+// future ios/codesign implementation can replace it without touching endpoints.
+type signingAdapter struct{}
+
+// Compile-time assertion that the concrete adapter satisfies the interface.
+var _ Signer = signingAdapter{}
+
+// defaultSigner is the Signer the endpoints use. Swap this (or make it
+// injectable) to move to ios/codesign later.
+var defaultSigner Signer = signingAdapter{}
+
+func (signingAdapter) toCreds(creds ASCCredentials) signing.AppStoreConnectCredentials {
+	return signing.AppStoreConnectCredentials{
+		KeyID:      creds.KeyID,
+		IssuerID:   creds.IssuerID,
+		PrivateKey: creds.PrivateKey,
+	}
+}
+
+func (a signingAdapter) PrepareCertificate(ctx context.Context, creds ASCCredentials, opts PrepareCertOptions) (CertResult, error) {
+	res, err := signing.PrepareCertificate(ctx, signing.PrepareCertificateOptions{
+		P12Password:    opts.P12Password,
+		P12Output:      opts.P12Output,
+		RevokeExisting: opts.RevokeExisting,
+		Credentials:    a.toCreds(creds),
+	})
+	if err != nil {
+		return CertResult{}, err
+	}
+	p12, err := readAndRemove(res.P12Path)
+	if err != nil {
+		return CertResult{}, err
+	}
+	return CertResult{P12: p12, CertificateID: res.CertificateID}, nil
+}
+
+func (a signingAdapter) PrepareProvisioning(ctx context.Context, creds ASCCredentials, opts PrepareProvisioningOptions) (AssetsResult, error) {
+	res, err := signing.PrepareSigningAssets(ctx, signing.PrepareAssetsOptions{
+		BundleID:       opts.BundleID,
+		BundleName:     opts.BundleName,
+		ProfileName:    opts.ProfileName,
+		DeviceName:     opts.DeviceName,
+		P12Password:    opts.P12Password,
+		RevokeExisting: opts.RevokeExisting,
+		CertificateID:  opts.CertificateID,
+		Credentials:    a.toCreds(creds),
+		Device:         deviceEntryForUDID(opts.DeviceUDID),
+	})
+	if err != nil {
+		return AssetsResult{}, err
+	}
+	out := AssetsResult{BundleID: res.BundleID, CertificateID: res.CertificateID}
+	profile, err := readAndRemove(res.ProfilePath)
+	if err != nil {
+		return AssetsResult{}, err
+	}
+	out.Profile = profile
+	// In reuse mode PrepareSigningAssets writes no P12.
+	if res.P12Path != "" {
+		p12, err := readAndRemove(res.P12Path)
+		if err != nil {
+			return AssetsResult{}, err
+		}
+		out.P12 = p12
+	}
+	return out, nil
+}
+
+func (a signingAdapter) SignApp(ctx context.Context, opts SignAppOptions) (SignResult, error) {
+	// ResignApp works directly from in-memory p12/profile bytes, so no key
+	// material is ever written to disk here. We choose the output path alongside
+	// the input so it stays inside the caller's per-request temp dir.
+	outputPath := signedOutputPath(opts.InputPath)
+	if err := signing.ResignApp(opts.InputPath, outputPath, opts.P12, opts.P12Password, opts.Profile, opts.BundleID); err != nil {
+		return SignResult{}, err
+	}
+	return SignResult{OutputPath: outputPath, BundleID: opts.BundleID}, nil
+}
diff --git a/restapi/api/sse.go b/restapi/api/sse.go
new file mode 100644
index 000000000..487504afa
--- /dev/null
+++ b/restapi/api/sse.go
@@ -0,0 +1,115 @@
+package api
+
+import (
+	"encoding/json"
+	"io"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/gin-gonic/gin"
+)
+
+// sseHeartbeatInterval is how long a stream may sit idle before a heartbeat
+// frame is emitted, so clients can tell a live-but-idle connection from a dead
+// one and intermediaries keep the connection open.
+const sseHeartbeatInterval = 15 * time.Second
+
+// sseHeartbeatIntervalForTest overrides the heartbeat interval when > 0. It
+// exists only so unit tests can force an idle heartbeat without waiting the full
+// production interval; production code never sets it.
+var sseHeartbeatIntervalForTest time.Duration
+
+// sseEvent is a single Server-Sent Event: the event name and the payload that
+// will be serialized as compact JSON into the data field.
+type sseEvent struct {
+	event   string
+	payload any
+}
+
+// writeSSEFrame writes one SSE frame to w in the exact wire framing the SDK
+// contract requires:
+//
+//	event: <event-name>\n
+//	data: <compact-json-of-payload>\n
+//	\n
+//
+// The data payload is always compact (single-line) JSON.
+func writeSSEFrame(w io.Writer, event string, payload any) error {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		// Fall back to an error envelope so a marshal failure of one frame
+		// never tears down the whole stream.
+		data, _ = json.Marshal(GenericResponse{Error: "failed to marshal event payload: " + err.Error()})
+	}
+	if _, err := io.WriteString(w, "event: "+event+"\n"); err != nil {
+		return err
+	}
+	if _, err := w.Write(append([]byte("data: "), data...)); err != nil {
+		return err
+	}
+	_, err = io.WriteString(w, "\n\n")
+	return err
+}
+
+// streamSSE drives a Server-Sent Events response. It pulls events from next in
+// a background goroutine and writes them to the client as SSE frames, emitting a
+// `heartbeat` frame whenever the stream is idle for sseHeartbeatInterval. It
+// returns when next signals end-of-stream (ok=false) or the client disconnects.
+//
+// next is called repeatedly; each call should block until the next event is
+// available and return (event, true), or (_, false) once the source is
+// exhausted or errors out. next runs on its own goroutine so a blocking read
+// never starves the heartbeat timer.
+//
+// udid is attached to log lines for filterability; it may be empty for
+// host-scoped streams (e.g. /listen).
+func streamSSE(c *gin.Context, udid string, next func() (sseEvent, bool)) {
+	events := make(chan sseEvent)
+	done := make(chan struct{})
+	go func() {
+		defer close(events)
+		for {
+			ev, ok := next()
+			if !ok {
+				return
+			}
+			select {
+			case events <- ev:
+			case <-done:
+				return
+			}
+		}
+	}()
+	defer close(done)
+
+	interval := sseHeartbeatInterval
+	if sseHeartbeatIntervalForTest > 0 {
+		interval = sseHeartbeatIntervalForTest
+	}
+	ticker := time.NewTicker(interval)
+	defer ticker.Stop()
+
+	w := c.Writer
+	for {
+		select {
+		case ev, ok := <-events:
+			if !ok {
+				return
+			}
+			if err := writeSSEFrame(w, ev.event, ev.payload); err != nil {
+				golog.Debug("sse client write failed", "module", logModule, "udid", udid, "error", err.Error())
+				return
+			}
+			w.Flush()
+			ticker.Reset(interval)
+		case <-ticker.C:
+			if err := writeSSEFrame(w, "heartbeat", struct{}{}); err != nil {
+				golog.Debug("sse heartbeat write failed", "module", logModule, "udid", udid, "error", err.Error())
+				return
+			}
+			w.Flush()
+		case <-c.Request.Context().Done():
+			return
+		}
+	}
+}
diff --git a/restapi/api/sse_test.go b/restapi/api/sse_test.go
new file mode 100644
index 000000000..b457bcc53
--- /dev/null
+++ b/restapi/api/sse_test.go
@@ -0,0 +1,210 @@
+package api
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/ostrace"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestWriteSSEFrame asserts the exact wire framing: `event: <name>\n`,
+// `data: <compact-json>\n`, terminated by a blank line.
+func TestWriteSSEFrame(t *testing.T) {
+	var buf bytes.Buffer
+	err := writeSSEFrame(&buf, "syslog", SyslogMessage{Message: "hello", Timestamp: 42})
+	require.NoError(t, err)
+
+	got := buf.String()
+	assert.Equal(t, "event: syslog\ndata: {\"message\":\"hello\",\"timestamp\":42}\n\n", got)
+
+	// data is compact single-line JSON (no embedded newlines before the terminator).
+	dataLine := strings.SplitN(got, "\n", 3)[1]
+	assert.True(t, strings.HasPrefix(dataLine, "data: "))
+	assert.NotContains(t, strings.TrimPrefix(dataLine, "data: "), "\n")
+}
+
+// TestWriteSSEFrameHeartbeat asserts the heartbeat frame is an empty JSON object.
+func TestWriteSSEFrameHeartbeat(t *testing.T) {
+	var buf bytes.Buffer
+	require.NoError(t, writeSSEFrame(&buf, "heartbeat", struct{}{}))
+	assert.Equal(t, "event: heartbeat\ndata: {}\n\n", buf.String())
+}
+
+// sseFrame is a parsed SSE frame.
+type sseFrame struct {
+	event string
+	data  string
+}
+
+// parseSSE splits an SSE response body into its frames.
+func parseSSE(t *testing.T, body string) []sseFrame {
+	t.Helper()
+	var frames []sseFrame
+	for _, block := range strings.Split(strings.TrimRight(body, "\n"), "\n\n") {
+		if strings.TrimSpace(block) == "" {
+			continue
+		}
+		var f sseFrame
+		for _, line := range strings.Split(block, "\n") {
+			switch {
+			case strings.HasPrefix(line, "event: "):
+				f.event = strings.TrimPrefix(line, "event: ")
+			case strings.HasPrefix(line, "data: "):
+				f.data = strings.TrimPrefix(line, "data: ")
+			}
+		}
+		frames = append(frames, f)
+	}
+	return frames
+}
+
+// runStreamSSE drives streamSSE with the given next until it ends, returning the
+// parsed frames. The request context is cancelled after the deadline so a stuck
+// stream does not hang the test.
+func runStreamSSE(t *testing.T, next func() (sseEvent, bool)) []sseFrame {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	req := httptest.NewRequest("GET", "/stream", nil)
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+	c.Request = req.WithContext(ctx)
+
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		streamSSE(c, "udid-1", next)
+	}()
+	select {
+	case <-done:
+	case <-time.After(3 * time.Second):
+		t.Fatal("streamSSE did not terminate")
+	}
+	return parseSSE(t, w.Body.String())
+}
+
+// TestStreamSSEEmitsTypedFrames asserts streamSSE writes proper event/data frames
+// with the event name the caller chose, then stops when next signals end.
+func TestStreamSSEEmitsTypedFrames(t *testing.T) {
+	msgs := []string{"a", "b", "c"}
+	i := 0
+	frames := runStreamSSE(t, func() (sseEvent, bool) {
+		if i >= len(msgs) {
+			return sseEvent{}, false
+		}
+		m := msgs[i]
+		i++
+		return sseEvent{event: "syslog", payload: SyslogMessage{Message: m}}, true
+	})
+
+	require.Len(t, frames, 3)
+	for idx, f := range frames {
+		assert.Equal(t, "syslog", f.event)
+		var payload SyslogMessage
+		require.NoError(t, json.Unmarshal([]byte(f.data), &payload))
+		assert.Equal(t, msgs[idx], payload.Message)
+	}
+}
+
+// TestStreamSSEHeartbeatOnIdle asserts a heartbeat frame is emitted when the
+// stream is idle longer than the heartbeat interval, then real events resume.
+func TestStreamSSEHeartbeatOnIdle(t *testing.T) {
+	// Shrink the interval for the test via the package-level knob.
+	orig := sseHeartbeatIntervalForTest
+	sseHeartbeatIntervalForTest = 20 * time.Millisecond
+	defer func() { sseHeartbeatIntervalForTest = orig }()
+
+	step := 0
+	frames := runStreamSSE(t, func() (sseEvent, bool) {
+		step++
+		switch step {
+		case 1:
+			// Idle long enough to force at least one heartbeat.
+			time.Sleep(60 * time.Millisecond)
+			return sseEvent{event: "syslog", payload: SyslogMessage{Message: "after-idle"}}, true
+		default:
+			return sseEvent{}, false
+		}
+	})
+
+	var sawHeartbeat, sawSyslog bool
+	for _, f := range frames {
+		switch f.event {
+		case "heartbeat":
+			sawHeartbeat = true
+			assert.Equal(t, "{}", f.data)
+		case "syslog":
+			sawSyslog = true
+		}
+	}
+	assert.True(t, sawHeartbeat, "expected at least one heartbeat frame on idle; got %+v", frames)
+	assert.True(t, sawSyslog, "expected the post-idle syslog frame")
+}
+
+// --- payload mapper tests ---
+
+func TestToAppStateNotification(t *testing.T) {
+	n := toAppStateNotification(map[string]interface{}{"bundleId": "com.apple.Preferences", "state": "foreground"})
+	assert.Equal(t, "com.apple.Preferences", n.BundleID)
+	assert.Equal(t, "foreground", n.State)
+	assert.NotZero(t, n.Timestamp)
+}
+
+func TestToOsTraceEntry(t *testing.T) {
+	ts := time.UnixMilli(1723200000000)
+	e := ostrace.LogEntry{
+		PID:       123,
+		Timestamp: ts,
+		LevelName: "info",
+		ImageName: "SpringBoard",
+		Message:   "hi",
+		Label:     &ostrace.LogLabel{Subsystem: "com.apple.network", Category: "boringssl"},
+	}
+	out := toOsTraceEntry(e)
+	assert.Equal(t, uint32(123), out.PID)
+	assert.Equal(t, "SpringBoard", out.ProcessName)
+	assert.Equal(t, "info", out.Level)
+	assert.Equal(t, "com.apple.network", out.Subsystem)
+	assert.Equal(t, "boringssl", out.Category)
+	assert.Equal(t, "hi", out.Message)
+	assert.Equal(t, int64(1723200000000), out.Timestamp)
+
+	// camelCase JSON per the spec.
+	b, err := json.Marshal(out)
+	require.NoError(t, err)
+	assert.Contains(t, string(b), "\"processName\"")
+}
+
+func TestToAttachDetachEvent(t *testing.T) {
+	attached := toAttachDetachEvent(ios.AttachedMessage{
+		MessageType: "Attached",
+		DeviceID:    5,
+		Properties:  ios.DeviceProperties{SerialNumber: "00008110-x", ConnectionType: "USB"},
+	})
+	assert.Equal(t, "attached", attached.Event)
+	assert.Equal(t, 5, attached.DeviceID)
+	assert.Equal(t, "00008110-x", attached.UDID)
+	require.NotNil(t, attached.Properties)
+	assert.Equal(t, "00008110-x", attached.Properties.SerialNumber)
+	assert.Equal(t, "USB", attached.Properties.ConnectionType)
+
+	// properties are camelCase per the spec.
+	b, err := json.Marshal(attached)
+	require.NoError(t, err)
+	assert.Contains(t, string(b), "\"serialNumber\"")
+	assert.Contains(t, string(b), "\"connectionType\"")
+
+	detached := toAttachDetachEvent(ios.AttachedMessage{MessageType: "Detached", DeviceID: 5})
+	assert.Equal(t, "detached", detached.Event)
+	assert.Nil(t, detached.Properties)
+}
diff --git a/restapi/api/stream_endpoints.go b/restapi/api/stream_endpoints.go
new file mode 100644
index 000000000..43ecd0060
--- /dev/null
+++ b/restapi/api/stream_endpoints.go
@@ -0,0 +1,236 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/instruments"
+	"github.com/danielpaulus/go-ios/ios/uidriver"
+	"github.com/gin-gonic/gin"
+)
+
+// Streaming endpoints deliver long-lived video/image streams over HTTP:
+//
+//   - GET /device/:udid/ui/stream        proxies a WDA/DeviceKit UI video stream
+//     (mjpeg or h264) straight through to the client.
+//   - GET /device/:udid/screenshot/stream serves an MJPEG stream of device
+//     screenshots captured via the instruments screenshot service.
+//
+// Both stream until the client disconnects (request context canceled) or the
+// source ends, and flush frames as they arrive.
+
+const (
+	// mjpegStreamBoundary is the multipart boundary for the screenshot MJPEG
+	// stream. It matches the format used by the instruments MJPEG server.
+	mjpegStreamBoundary  = "BoundaryString"
+	mjpegStreamPartHead  = "--" + mjpegStreamBoundary + "\r\nContent-Type: image/jpeg\r\nContent-Length: %d\r\n\r\n"
+	mjpegStreamPartFoot  = "\r\n"
+	mjpegStreamCType     = "multipart/x-mixed-replace; boundary=" + mjpegStreamBoundary
+	streamCopyBufferSize = 32 * 1024
+)
+
+// registerStreamRoutes registers the streaming endpoints. The UI stream lives
+// under the /ui group next to the other UI-automation endpoints; the screenshot
+// stream is device-scoped.
+func registerStreamRoutes(device *gin.RouterGroup) {
+	device.GET("/ui/stream", UIStream)
+	device.GET("/screenshot/stream", ScreenshotStream)
+}
+
+// UIStream opens a UI video stream against a forwarded WDA/DeviceKit backend and
+// pipes it straight through to the client, preserving the backend's Content-Type
+// (mjpeg is multipart/x-mixed-replace; h264 uses the backend's type). It streams
+// until the client disconnects or the backend ends.
+//
+//	?codec=mjpeg|h264   (default mjpeg; h264 requires the devicekit backend)
+//	?backend=wda|devicekit, ?wdaUrl=<url>, ?timeout=<seconds>  (see UI endpoints)
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIStream(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+
+	var opts uidriver.StreamOptions
+	switch strings.ToLower(strings.TrimSpace(paramOrHeader(c, "codec"))) {
+	case "", "mjpeg":
+		opts.H264 = false
+	case "h264":
+		opts.H264 = true
+	default:
+		RespondError(c, http.StatusBadRequest, errors.New("unknown codec; expected mjpeg or h264"))
+		return
+	}
+	opts.FPS = strings.TrimSpace(paramOrHeader(c, "fps"))
+	opts.Quality = strings.TrimSpace(paramOrHeader(c, "quality"))
+	opts.Scale = strings.TrimSpace(paramOrHeader(c, "scale"))
+	opts.Bitrate = strings.TrimSpace(paramOrHeader(c, "bitrate"))
+
+	ctx := c.Request.Context()
+	body, contentType, err := driver.StreamWithContentType(ctx, opts)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	defer func() { _ = body.Close() }()
+
+	if contentType == "" {
+		if opts.H264 {
+			contentType = "video/H264"
+		} else {
+			contentType = mjpegStreamCType
+		}
+	}
+	c.Writer.Header().Set("Content-Type", contentType)
+	c.Writer.Header().Set("Cache-Control", "no-cache, private")
+	c.Writer.Header().Set("Connection", "close")
+	c.Writer.WriteHeader(http.StatusOK)
+
+	golog.Info("streaming ui video to client", "module", logModule, "udid", udid, "codec", streamCodec(opts.H264), "contentType", contentType)
+
+	flusher, _ := c.Writer.(http.Flusher)
+	buf := make([]byte, streamCopyBufferSize)
+	for {
+		if ctx.Err() != nil {
+			return
+		}
+		n, readErr := body.Read(buf)
+		if n > 0 {
+			if _, writeErr := c.Writer.Write(buf[:n]); writeErr != nil {
+				golog.Debug("ui stream client write failed, closing", "module", logModule, "udid", udid, "error", writeErr.Error())
+				return
+			}
+			if flusher != nil {
+				flusher.Flush()
+			}
+		}
+		if readErr != nil {
+			if !errors.Is(readErr, io.EOF) && ctx.Err() == nil {
+				golog.Warn("ui stream backend read error", "module", logModule, "udid", udid, "error", readErr.Error())
+			}
+			return
+		}
+	}
+}
+
+func streamCodec(h264 bool) string {
+	if h264 {
+		return "h264"
+	}
+	return "mjpeg"
+}
+
+// ScreenshotStream serves an MJPEG (multipart/x-mixed-replace) stream of device
+// screenshots captured via the instruments screenshot service. It streams until
+// the client disconnects or the screenshot source fails.
+//
+//	?quality=<1-100>   optional JPEG quality (default 80)
+func ScreenshotStream(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
+
+	conn, err := instruments.NewScreenshotService(device)
+	if err != nil {
+		RespondError(c, http.StatusInternalServerError, err)
+		return
+	}
+	defer conn.Close()
+
+	quality := 0 // 0 => instruments default (80)
+	if raw := strings.TrimSpace(paramOrHeader(c, "quality")); raw != "" {
+		q, convErr := parseQuality(raw)
+		if convErr != nil {
+			RespondError(c, http.StatusBadRequest, convErr)
+			return
+		}
+		quality = q
+	}
+
+	c.Writer.Header().Set("Content-Type", mjpegStreamCType)
+	c.Writer.Header().Set("Cache-Control", "no-cache, private")
+	c.Writer.Header().Set("Connection", "close")
+	c.Writer.WriteHeader(http.StatusOK)
+
+	golog.Info("streaming device screenshots to client", "module", logModule, "udid", udid)
+
+	ctx := c.Request.Context()
+	flusher, _ := c.Writer.(http.Flusher)
+
+	// Bridge the instruments frame source into a channel so the multipart
+	// framing loop (writeMJPEGFrames) is a single, device-free-testable core.
+	frames := make(chan []byte, 4)
+	go func() {
+		defer close(frames)
+		err := instruments.StreamJPEGFrames(ctx, conn, quality, func(jpg []byte) {
+			// Copy: the callback does not own the slice past the call, and the
+			// frame is consumed asynchronously by the writer loop.
+			frame := append([]byte(nil), jpg...)
+			select {
+			case frames <- frame:
+			case <-ctx.Done():
+			}
+		})
+		if err != nil {
+			golog.Warn("screenshot frame source stopped", "module", logModule, "udid", udid, "error", err.Error())
+		}
+	}()
+
+	if writeErr := writeMJPEGFrames(ctx, c.Writer, flusher, frames); writeErr != nil {
+		golog.Debug("screenshot stream ended", "module", logModule, "udid", udid, "error", writeErr.Error())
+	}
+}
+
+// writeMJPEGFrames writes each JPEG frame received on frames as a
+// multipart/x-mixed-replace part, flushing after every frame. It returns when
+// the context is canceled, a client write fails, or the frames channel is
+// closed. This is the device-free-testable framing core shared by the handler.
+func writeMJPEGFrames(ctx context.Context, w io.Writer, flusher http.Flusher, frames <-chan []byte) error {
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case jpg, ok := <-frames:
+			if !ok {
+				return nil
+			}
+			if err := writeMJPEGFrame(w, jpg); err != nil {
+				return err
+			}
+			if flusher != nil {
+				flusher.Flush()
+			}
+		}
+	}
+}
+
+// parseQuality validates an optional JPEG quality query param (1..100).
+func parseQuality(raw string) (int, error) {
+	q, err := strconv.Atoi(raw)
+	if err != nil || q < 1 || q > 100 {
+		return 0, errors.New("invalid 'quality'; expected an integer in 1..100")
+	}
+	return q, nil
+}
+
+// writeMJPEGFrame writes a single multipart/x-mixed-replace JPEG part.
+func writeMJPEGFrame(w io.Writer, jpg []byte) error {
+	if _, err := io.WriteString(w, fmt.Sprintf(mjpegStreamPartHead, len(jpg))); err != nil {
+		return err
+	}
+	if _, err := w.Write(jpg); err != nil {
+		return err
+	}
+	if _, err := io.WriteString(w, mjpegStreamPartFoot); err != nil {
+		return err
+	}
+	return nil
+}
diff --git a/restapi/api/stream_endpoints_test.go b/restapi/api/stream_endpoints_test.go
new file mode 100644
index 000000000..7e1f5d0db
--- /dev/null
+++ b/restapi/api/stream_endpoints_test.go
@@ -0,0 +1,285 @@
+package api_test
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/restapi/api"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// These tests are device-free. The UI stream is exercised against an
+// httptest.Server standing in for a forwarded WDA/DeviceKit backend; the
+// screenshot stream's multipart framing core is exercised via the exported
+// WriteMJPEGFramesForTest hook with an injected frame channel.
+
+// streamRouter wires UIStream behind a fake device middleware, matching the real
+// route. Requests point at wdaURL via ?wdaUrl.
+func streamRouter() *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.Use(func(c *gin.Context) {
+		c.Set(api.IOS_KEY, ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: "stream-test-udid"}})
+		c.Next()
+	})
+	r.GET("/ui/stream", api.UIStream)
+	return r
+}
+
+// TestUIStreamPipesBackendBody stands up a fake backend that emits a chunked
+// multipart body and asserts the endpoint pipes it through verbatim with the
+// backend's Content-Type preserved.
+func TestUIStreamPipesBackendBody(t *testing.T) {
+	chunks := []string{"--B\r\nContent-Type: image/jpeg\r\n\r\nframe-1\r\n", "--B\r\n\r\nframe-2\r\n"}
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/mjpeg", r.URL.Path)
+		w.Header().Set("Content-Type", "multipart/x-mixed-replace; boundary=B")
+		w.WriteHeader(http.StatusOK)
+		flusher := w.(http.Flusher)
+		for _, c := range chunks {
+			_, _ = io.WriteString(w, c)
+			flusher.Flush()
+		}
+	}))
+	defer backend.Close()
+
+	srv := httptest.NewServer(streamRouter())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/ui/stream?backend=devicekit&codec=mjpeg&wdaUrl=" + backend.URL)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Equal(t, "multipart/x-mixed-replace; boundary=B", resp.Header.Get("Content-Type"))
+
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	assert.Equal(t, strings.Join(chunks, ""), string(body))
+}
+
+// TestUIStreamH264PreservesBackendContentType asserts an h264 stream over the
+// devicekit backend forwards the backend's Content-Type.
+func TestUIStreamH264PreservesBackendContentType(t *testing.T) {
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/h264", r.URL.Path)
+		w.Header().Set("Content-Type", "video/H264")
+		w.WriteHeader(http.StatusOK)
+		_, _ = w.Write([]byte("h264-payload"))
+	}))
+	defer backend.Close()
+
+	srv := httptest.NewServer(streamRouter())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/ui/stream?backend=devicekit&codec=h264&wdaUrl=" + backend.URL)
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	assert.Equal(t, http.StatusOK, resp.StatusCode)
+	assert.Equal(t, "video/H264", resp.Header.Get("Content-Type"))
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+	assert.Equal(t, "h264-payload", string(body))
+}
+
+// TestUIStreamH264OverWDAReturns501 asserts requesting h264 against the wda
+// backend maps ErrStreamUnsupported to 501.
+func TestUIStreamH264OverWDAReturns501(t *testing.T) {
+	srv := httptest.NewServer(streamRouter())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/ui/stream?backend=wda&codec=h264&wdaUrl=http://127.0.0.1:1")
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	assert.Equal(t, http.StatusNotImplemented, resp.StatusCode)
+}
+
+// TestUIStreamUnreachableBackendReturns502 asserts a dead backend maps to 502.
+func TestUIStreamUnreachableBackendReturns502(t *testing.T) {
+	srv := httptest.NewServer(streamRouter())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/ui/stream?backend=devicekit&codec=mjpeg&wdaUrl=http://127.0.0.1:1")
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	assert.Equal(t, http.StatusBadGateway, resp.StatusCode)
+}
+
+// TestUIStreamBadCodecReturns400 asserts an unknown codec maps to 400.
+func TestUIStreamBadCodecReturns400(t *testing.T) {
+	srv := httptest.NewServer(streamRouter())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/ui/stream?codec=webm&wdaUrl=http://127.0.0.1:1")
+	require.NoError(t, err)
+	defer resp.Body.Close()
+	assert.Equal(t, http.StatusBadRequest, resp.StatusCode)
+}
+
+// TestUIStreamStopsOnClientDisconnect asserts that cancelling the client request
+// causes the endpoint to stop piping and close the backend body. The backend
+// blocks forever after the first chunk; once the client cancels, its handler's
+// Write must fail (context canceled), which we observe via backendDone.
+func TestUIStreamStopsOnClientDisconnect(t *testing.T) {
+	backendDone := make(chan struct{})
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "multipart/x-mixed-replace; boundary=B")
+		w.WriteHeader(http.StatusOK)
+		flusher := w.(http.Flusher)
+		_, _ = io.WriteString(w, "first-chunk")
+		flusher.Flush()
+		// Keep writing until the client (via the proxy) goes away.
+		defer close(backendDone)
+		for {
+			select {
+			case <-r.Context().Done():
+				return
+			default:
+			}
+			if _, err := io.WriteString(w, "x"); err != nil {
+				return
+			}
+			flusher.Flush()
+			time.Sleep(5 * time.Millisecond)
+		}
+	}))
+	defer backend.Close()
+
+	srv := httptest.NewServer(streamRouter())
+	defer srv.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	req, _ := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL+"/ui/stream?backend=devicekit&codec=mjpeg&wdaUrl="+backend.URL, nil)
+	resp, err := http.DefaultClient.Do(req)
+	require.NoError(t, err)
+
+	buf := make([]byte, len("first-chunk"))
+	_, err = io.ReadFull(resp.Body, buf)
+	require.NoError(t, err)
+	assert.Equal(t, "first-chunk", string(buf))
+
+	cancel()
+	_ = resp.Body.Close()
+
+	select {
+	case <-backendDone:
+		// The proxy stopped consuming and closed the backend body, so the
+		// backend handler observed the disconnect.
+	case <-time.After(5 * time.Second):
+		t.Fatal("backend did not observe client disconnect; proxy did not stop")
+	}
+}
+
+// TestWriteMJPEGFramesFramesAndStops exercises the multipart framing core with an
+// injected frame channel: it writes well-formed multipart parts for each frame
+// and stops when the channel closes.
+func TestWriteMJPEGFramesFramesAndStops(t *testing.T) {
+	frames := make(chan []byte, 2)
+	frames <- []byte("JPEGDATA1")
+	frames <- []byte("JPEG2")
+	close(frames)
+
+	var buf strings.Builder
+	err := api.WriteMJPEGFramesForTest(context.Background(), &buf, nil, frames)
+	require.NoError(t, err)
+
+	out := buf.String()
+	// Two parts, each with the boundary + JPEG content-type + correct length.
+	assert.Equal(t, 2, strings.Count(out, "--BoundaryString"))
+	assert.Contains(t, out, "Content-Type: image/jpeg")
+	assert.Contains(t, out, fmt.Sprintf("Content-Length: %d", len("JPEGDATA1")))
+	assert.Contains(t, out, "JPEGDATA1")
+	assert.Contains(t, out, "JPEG2")
+
+	// Parse it as an actual multipart body to prove it is well-formed.
+	parts := readMultipartParts(t, out)
+	require.Len(t, parts, 2)
+	assert.Equal(t, "JPEGDATA1", string(parts[0]))
+	assert.Equal(t, "JPEG2", string(parts[1]))
+}
+
+// TestWriteMJPEGFramesStopsOnContextCancel asserts a canceled context stops the
+// framing loop even while frames remain available.
+func TestWriteMJPEGFramesStopsOnContextCancel(t *testing.T) {
+	frames := make(chan []byte) // never closed, never fed after cancel
+	ctx, cancel := context.WithCancel(context.Background())
+
+	done := make(chan error, 1)
+	var mu sync.Mutex
+	var buf strings.Builder
+	go func() {
+		done <- api.WriteMJPEGFramesForTest(ctx, lockedWriter{&mu, &buf}, nil, frames)
+	}()
+
+	// Feed one frame, then cancel.
+	frames <- []byte("frame")
+	cancel()
+
+	select {
+	case err := <-done:
+		assert.ErrorIs(t, err, context.Canceled)
+	case <-time.After(2 * time.Second):
+		t.Fatal("framing loop did not stop on context cancel")
+	}
+}
+
+type lockedWriter struct {
+	mu  *sync.Mutex
+	buf *strings.Builder
+}
+
+func (l lockedWriter) Write(p []byte) (int, error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	return l.buf.Write(p)
+}
+
+// readMultipartParts parses a multipart/x-mixed-replace body (boundary
+// BoundaryString) and returns each part's payload.
+func readMultipartParts(t *testing.T, body string) [][]byte {
+	t.Helper()
+	var parts [][]byte
+	reader := bufio.NewReader(strings.NewReader(body))
+	for {
+		// Read boundary line.
+		line, err := reader.ReadString('\n')
+		if err == io.EOF {
+			break
+		}
+		require.NoError(t, err)
+		if !strings.HasPrefix(line, "--BoundaryString") {
+			continue
+		}
+		// Read headers until blank line, capture Content-Length.
+		length := -1
+		for {
+			h, err := reader.ReadString('\n')
+			require.NoError(t, err)
+			trimmed := strings.TrimRight(h, "\r\n")
+			if trimmed == "" {
+				break
+			}
+			if strings.HasPrefix(trimmed, "Content-Length:") {
+				_, _ = fmt.Sscanf(trimmed, "Content-Length: %d", &length)
+			}
+		}
+		require.Greater(t, length, -1, "part missing Content-Length")
+		payload := make([]byte, length)
+		_, err = io.ReadFull(reader, payload)
+		require.NoError(t, err)
+		parts = append(parts, payload)
+	}
+	return parts
+}
diff --git a/restapi/api/streaming_endpoints.go b/restapi/api/streaming_endpoints.go
index 29b3935a7..b59138237 100644
--- a/restapi/api/streaming_endpoints.go
+++ b/restapi/api/streaming_endpoints.go
@@ -1,107 +1,170 @@
 package api
 
 import (
-	"io"
 	"net/http"
 	"strconv"
+	"time"
 
 	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
 	"github.com/danielpaulus/go-ios/ios/instruments"
 	"github.com/danielpaulus/go-ios/ios/ostrace"
 	"github.com/danielpaulus/go-ios/ios/syslog"
 	"github.com/gin-gonic/gin"
-	log "github.com/sirupsen/logrus"
 )
 
-// Notifications uses instruments to get application state change events. It will stream the events as json objects separated by line breaks until it errors out.
-// Listen                godoc
-// @Summary      uses instruments to get application state change events
-// @Description uses instruments to get application state change events
+// SSE payload models. These mirror the field names in the SDK contract
+// (spec/openapi/openapi.yaml component schemas) so generated clients decode the
+// data frames directly.
+
+// AppStateNotification is the payload of an `appstate` event (SSE /notifications).
+type AppStateNotification struct {
+	BundleID  string `json:"bundleId"`
+	State     string `json:"state"`
+	Timestamp int64  `json:"timestamp,omitempty"`
+}
+
+// SyslogMessage is the payload of a `syslog` event (SSE /syslog).
+type SyslogMessage struct {
+	Message   string `json:"message"`
+	Timestamp int64  `json:"timestamp,omitempty"`
+}
+
+// OsTraceEntry is the payload of an `ostrace` event (SSE /ostrace).
+type OsTraceEntry struct {
+	PID         uint32 `json:"pid,omitempty"`
+	ProcessName string `json:"processName,omitempty"`
+	Level       string `json:"level,omitempty"`
+	Subsystem   string `json:"subsystem,omitempty"`
+	Category    string `json:"category,omitempty"`
+	Message     string `json:"message"`
+	Timestamp   int64  `json:"timestamp,omitempty"`
+}
+
+// DeviceProperties mirrors the spec's DeviceProperties schema (camelCase JSON),
+// since ios.DeviceProperties has no JSON tags and would marshal PascalCase.
+type DeviceProperties struct {
+	ConnectionSpeed int    `json:"connectionSpeed,omitempty"`
+	ConnectionType  string `json:"connectionType,omitempty"`
+	DeviceID        int    `json:"deviceID,omitempty"`
+	LocationID      int    `json:"locationID,omitempty"`
+	ProductID       int    `json:"productID,omitempty"`
+	SerialNumber    string `json:"serialNumber"`
+}
+
+// AttachDetachEvent is the payload of an `attachdetach` event (SSE /listen).
+type AttachDetachEvent struct {
+	Event      string            `json:"event"`
+	DeviceID   int               `json:"deviceID,omitempty"`
+	UDID       string            `json:"udid,omitempty"`
+	Properties *DeviceProperties `json:"properties,omitempty"`
+}
+
+// Notifications streams application-state change events as Server-Sent Events.
+// Each `appstate` event carries an AppStateNotification; a `heartbeat` event is
+// emitted on idle.
+// @Summary      Stream app state notifications (SSE)
+// @Description  Streams application foreground/background/lifecycle state changes as text/event-stream. Events: `appstate` (AppStateNotification), `heartbeat`.
 // @Tags         general
-// @Produce      json
-// @Success      200  {object}  map[string]interface{}
+// @Produce      text/event-stream
+// @Success      200  {object}  AppStateNotification
 // @Router       /notifications [get]
 func Notifications(c *gin.Context) {
 	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
 	listenerFunc, closeFunc, err := instruments.ListenAppStateNotifications(device)
 	if err != nil {
-		c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, err)
 		return
 	}
-	c.Stream(func(w io.Writer) bool {
-
+	defer closeFunc()
+	golog.Info("notifications stream started", "module", logModule, "udid", udid)
+	streamSSE(c, udid, func() (sseEvent, bool) {
 		notification, err := listenerFunc()
 		if err != nil {
-			c.JSON(http.StatusInternalServerError, err)
-			closeFunc()
-			return false
-		}
-
-		_, err = w.Write([]byte(MustMarshal(notification)))
-
-		if err != nil {
-			c.JSON(http.StatusInternalServerError, err)
-			closeFunc()
-			return false
+			return sseEvent{}, false
 		}
-		w.Write([]byte("\n"))
-		return true
+		return sseEvent{event: "appstate", payload: toAppStateNotification(notification)}, true
 	})
+}
 
+// toAppStateNotification maps the untyped instruments notification map to the
+// spec's AppStateNotification shape. The device reports bundle id and state
+// under a few known keys; unknown-shaped maps fall through with best effort.
+func toAppStateNotification(m map[string]interface{}) AppStateNotification {
+	n := AppStateNotification{Timestamp: time.Now().UnixMilli()}
+	for _, k := range []string{"bundleId", "bundleID", "appBundleId"} {
+		if v, ok := m[k].(string); ok && v != "" {
+			n.BundleID = v
+			break
+		}
+	}
+	for _, k := range []string{"state", "appState", "runningState"} {
+		if v, ok := m[k].(string); ok && v != "" {
+			n.State = v
+			break
+		}
+	}
+	return n
 }
 
-// Syslog
-// Listen                godoc
-// @Summary      Uses SSE to connect to the LISTEN command
-// @Description Uses SSE to connect to the LISTEN command
+// Syslog streams device syslog lines as Server-Sent Events. Each `syslog` event
+// carries a SyslogMessage; a `heartbeat` event is emitted on idle.
+// @Summary      Stream device syslog (SSE)
+// @Description  Streams raw syslog lines as text/event-stream. Events: `syslog` (SyslogMessage), `heartbeat`.
 // @Tags         general
-// @Produce      json
-// @Success      200  {object}  map[string]interface{}
-// @Router       /listen [get]
+// @Produce      text/event-stream
+// @Success      200  {object}  SyslogMessage
+// @Router       /syslog [get]
 func Syslog(c *gin.Context) {
-	// We are streaming current time to clients in the interval 10 seconds
-	log.Info("connect")
 	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
 	syslogConnection, err := syslog.New(device)
 	if err != nil {
-		c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err})
+		RespondError(c, http.StatusInternalServerError, err)
 		return
 	}
 	defer syslogConnection.Close()
-	c.Stream(func(w io.Writer) bool {
+	golog.Info("syslog stream started", "module", logModule, "udid", udid)
+	streamSSE(c, udid, func() (sseEvent, bool) {
 		m, err := syslogConnection.ReadLogMessage()
 		if err != nil {
-			return false
+			return sseEvent{}, false
 		}
-		// Stream message to client from message channel
-		w.Write([]byte(MustMarshal(m)))
-		return true
+		return sseEvent{event: "syslog", payload: SyslogMessage{Message: m, Timestamp: time.Now().UnixMilli()}}, true
 	})
 }
 
-// OsTrace streams structured syslog entries via os_trace_relay with optional device-side PID filtering.
-// OsTrace                godoc
-// @Summary      Stream structured syslog via os_trace_relay
-// @Description  Streams structured syslog entries from the device using os_trace_relay. Supports device-side PID filtering.
+// OsTrace streams structured os_log trace entries via os_trace_relay as
+// Server-Sent Events. Each `ostrace` event carries an OsTraceEntry; a
+// `heartbeat` event is emitted on idle. Optional filters (pid, level, subsystem,
+// match, exclude) combine with AND semantics.
+// @Summary      Stream structured os_log trace (SSE)
+// @Description  Streams structured os_log entries as text/event-stream. Events: `ostrace` (OsTraceEntry), `heartbeat`. Filters combine with AND.
 // @Tags         general
-// @Produce      json
-// @Param        pid  query  int  false  "Filter by process ID (-1 for all)"
-// @Success      200  {object}  map[string]interface{}
+// @Param        pid        query  int     false  "Filter by process ID"
+// @Param        level      query  string  false  "Minimum log level (info, debug, error, ...)"
+// @Param        subsystem  query  string  false  "Filter by subsystem"
+// @Param        match      query  string  false  "Include only messages matching this substring"
+// @Param        exclude    query  string  false  "Exclude messages matching this substring"
+// @Produce      text/event-stream
+// @Success      200  {object}  OsTraceEntry
 // @Router       /ostrace [get]
 func OsTrace(c *gin.Context) {
 	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
 	pid := -1
 	if pidStr := c.Query("pid"); pidStr != "" {
 		var err error
 		pid, err = strconv.Atoi(pidStr)
 		if err != nil {
-			c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": "invalid pid parameter"})
+			RespondError(c, http.StatusBadRequest, errInvalidPID)
 			return
 		}
 	}
 	levelFilter, err := ostrace.ParseLevelFilter(c.Query("level"))
 	if err != nil {
-		c.AbortWithStatusJSON(http.StatusBadRequest, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusBadRequest, err)
 		return
 	}
 	clientFilter := ostrace.ClientFilter{
@@ -112,45 +175,88 @@ func OsTrace(c *gin.Context) {
 	}
 	conn, err := ostrace.New(device, pid, levelFilter.MessageFilter, levelFilter.StreamFlags)
 	if err != nil {
-		c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, err)
 		return
 	}
 	defer conn.Close()
-	c.Stream(func(w io.Writer) bool {
+	golog.Info("ostrace stream started", "module", logModule, "udid", udid, "pid", pid)
+	streamSSE(c, udid, func() (sseEvent, bool) {
 		entry, err := conn.ReadFilteredEntry(clientFilter)
 		if err != nil {
-			return false
+			return sseEvent{}, false
 		}
-		w.Write([]byte(MustMarshal(entry)))
-		w.Write([]byte("\n"))
-		return true
+		return sseEvent{event: "ostrace", payload: toOsTraceEntry(entry)}, true
 	})
 }
 
-// Listen send server side events when devices are plugged in or removed
-// Listen                godoc
-// @Summary      Uses SSE to connect to the LISTEN command
-// @Description Uses SSE to connect to the LISTEN command
+// toOsTraceEntry maps ios/ostrace.LogEntry to the spec's OsTraceEntry shape.
+func toOsTraceEntry(e ostrace.LogEntry) OsTraceEntry {
+	out := OsTraceEntry{
+		PID:         e.PID,
+		ProcessName: e.ImageName,
+		Level:       e.LevelName,
+		Message:     e.Message,
+	}
+	if !e.Timestamp.IsZero() {
+		out.Timestamp = e.Timestamp.UnixMilli()
+	}
+	if e.Label != nil {
+		out.Subsystem = e.Label.Subsystem
+		out.Category = e.Label.Category
+	}
+	return out
+}
+
+// Listen streams device attach/detach events as Server-Sent Events. Each
+// `attachdetach` event carries an AttachDetachEvent; a `heartbeat` event is
+// emitted on idle. This stream is host-scoped (not device-scoped).
+// @Summary      Stream device attach/detach events (SSE)
+// @Description  Streams usbmuxd attach/detach events as text/event-stream. Events: `attachdetach` (AttachDetachEvent), `heartbeat`.
 // @Tags         general
-// @Produce      json
-// @Success      200  {object}  map[string]interface{}
+// @Produce      text/event-stream
+// @Success      200  {object}  AttachDetachEvent
 // @Router       /listen [get]
 func Listen(c *gin.Context) {
-	// We are streaming current time to clients in the interval 10 seconds
-	log.Info("connect")
 	a, closeFunc, err := ios.Listen()
 	if err != nil {
-		c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
+		RespondError(c, http.StatusInternalServerError, err)
 		return
 	}
 	defer closeFunc()
-	c.Stream(func(w io.Writer) bool {
-		l, err := a()
+	golog.Info("listen stream started", "module", logModule)
+	streamSSE(c, "", func() (sseEvent, bool) {
+		msg, err := a()
 		if err != nil {
-			return false
+			return sseEvent{}, false
 		}
-		// Stream message to client from message channel
-		w.Write([]byte(MustMarshal(l)))
-		return true
+		return sseEvent{event: "attachdetach", payload: toAttachDetachEvent(msg)}, true
 	})
 }
+
+// toAttachDetachEvent maps ios.AttachedMessage to the spec's AttachDetachEvent
+// shape. `properties` is present on attach events.
+func toAttachDetachEvent(m ios.AttachedMessage) AttachDetachEvent {
+	ev := AttachDetachEvent{
+		DeviceID: m.DeviceID,
+		UDID:     m.Properties.SerialNumber,
+	}
+	switch m.MessageType {
+	case "Attached":
+		ev.Event = "attached"
+		ev.Properties = &DeviceProperties{
+			ConnectionSpeed: m.Properties.ConnectionSpeed,
+			ConnectionType:  m.Properties.ConnectionType,
+			DeviceID:        m.Properties.DeviceID,
+			LocationID:      m.Properties.LocationID,
+			ProductID:       m.Properties.ProductID,
+			SerialNumber:    m.Properties.SerialNumber,
+		}
+	case "Detached":
+		ev.Event = "detached"
+	case "Paired":
+		ev.Event = "paired"
+	default:
+		ev.Event = m.MessageType
+	}
+	return ev
+}
diff --git a/restapi/api/tunnel_endpoints.go b/restapi/api/tunnel_endpoints.go
new file mode 100644
index 000000000..2ace7fd66
--- /dev/null
+++ b/restapi/api/tunnel_endpoints.go
@@ -0,0 +1,84 @@
+package api
+
+import (
+	"net/http"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/tunnel"
+	"github.com/gin-gonic/gin"
+)
+
+// tunnelRefreshTimeout mirrors the CLI's refresh wait.
+const tunnelRefreshTimeout = 30 * time.Second
+
+// registerTunnelRoutes registers tunnel-agent endpoints (CLI: ios tunnel ...).
+// These are NOT device-scoped — they query the running tunnel agent by udid
+// string over its info API (host/port from ios.HttpApiHost/HttpApiPort) — so they
+// live at the /api/v1 level rather than under /device/:udid.
+//
+// `ios tunnel start` is intentionally not exposed: it starts a long-running
+// privileged daemon (sudo / CAP_NET_ADMIN / admin shell), which is a host
+// process-lifecycle concern, not a REST call.
+func registerTunnelRoutes(router *gin.RouterGroup) {
+	router.GET("/tunnels", ListTunnels)
+	router.DELETE("/tunnels/:udid", StopTunnel)
+	router.POST("/tunnels/:udid/refresh", RefreshTunnel)
+	router.POST("/tunnel-agent/shutdown", ShutdownTunnelAgent)
+}
+
+// ListTunnels lists running tunnels (CLI: ios tunnel ls).
+// @Summary List running tunnels
+// @Produce json
+// @Success 200 {array} tunnel.Tunnel
+// @Router /tunnels [get]
+func ListTunnels(c *gin.Context) {
+	tunnels, err := tunnel.ListRunningTunnels(ios.HttpApiHost(), ios.HttpApiPort())
+	if err != nil {
+		RespondError(c, http.StatusBadGateway, err)
+		return
+	}
+	c.JSON(http.StatusOK, tunnels)
+}
+
+// StopTunnel stops the tunnel for a device (CLI: ios tunnel stop --udid).
+// @Summary Stop a device tunnel
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} map[string]string
+// @Router /tunnels/{udid} [delete]
+func StopTunnel(c *gin.Context) {
+	udid := c.Param("udid")
+	if err := tunnel.StopTunnelForDevice(udid, ios.HttpApiHost(), ios.HttpApiPort()); err != nil {
+		RespondError(c, http.StatusBadGateway, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"udid": udid, "status": "stopped"})
+}
+
+// RefreshTunnel restarts the tunnel for a device and waits for it (CLI: ios tunnel refresh).
+// @Summary Refresh a device tunnel
+// @Produce json
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} tunnel.Tunnel
+// @Router /tunnels/{udid}/refresh [post]
+func RefreshTunnel(c *gin.Context) {
+	udid := c.Param("udid")
+	tun, err := tunnel.RefreshTunnelForDevice(udid, ios.HttpApiHost(), ios.HttpApiPort(), tunnelRefreshTimeout)
+	if err != nil {
+		RespondError(c, http.StatusBadGateway, err)
+		return
+	}
+	c.JSON(http.StatusOK, tun)
+}
+
+// ShutdownTunnelAgent stops the tunnel agent (CLI: ios tunnel stopagent).
+// @Summary Shut down the tunnel agent
+// @Success 200 {object} map[string]string
+// @Router /tunnel-agent/shutdown [post]
+func ShutdownTunnelAgent(c *gin.Context) {
+	if err := tunnel.CloseAgent(); err != nil {
+		RespondError(c, http.StatusBadGateway, err)
+		return
+	}
+	c.JSON(http.StatusOK, gin.H{"status": "agent shutdown requested"})
+}
diff --git a/restapi/api/ui_endpoints.go b/restapi/api/ui_endpoints.go
new file mode 100644
index 000000000..826c9ceec
--- /dev/null
+++ b/restapi/api/ui_endpoints.go
@@ -0,0 +1,509 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/uidriver"
+	"github.com/gin-gonic/gin"
+)
+
+// UI automation endpoints proxy to a running, forwarded WebDriverAgent (WDA) or
+// DeviceKit instance via the ios/uidriver package.
+//
+// PREREQUISITE: these endpoints do not start WDA. The caller must first bring up
+// and forward a WebDriverAgent session on the device, typically via
+// `POST /jobs/runwda` followed by `POST /jobs/forward`, so the backend is
+// reachable on a local port. The endpoints then connect to that forwarded
+// backend per request.
+//
+// Backend addressing (per request):
+//   - ?backend=wda|devicekit (or the "backend" header) selects the backend;
+//     defaults to wda.
+//   - ?wdaUrl=<url> (or the "wdaUrl" header) is the forwarded backend base URL.
+//     Defaults to http://127.0.0.1:8100 for wda and http://127.0.0.1:12004 for
+//     devicekit.
+//   - ?timeout=<seconds> (or the "timeout" header) overrides the per-request
+//     HTTP timeout (default 60s).
+//
+// A fresh uidriver.Driver is constructed for every request; no session state is
+// held server-side beyond what WDA itself keeps.
+
+// Sentinel errors for UI request validation.
+var (
+	errMissingText        = errors.New("missing required 'text' field")
+	errMissingButtonName  = errors.New("missing required 'name' field")
+	errMissingOrientation = errors.New("missing required 'orientation' field")
+	errMissingBundleIDUI  = errors.New("missing required 'bundleId' field")
+	errMissingAPIPath     = errors.New("missing required 'path' field for the wda backend")
+)
+
+// registerUIRoutes registers the UI-automation endpoints under
+// /device/:udid/ui. They proxy to a forwarded WDA/DeviceKit backend; see the
+// package-level doc comment above for the prerequisites and backend addressing.
+func registerUIRoutes(device *gin.RouterGroup) {
+	group := device.Group("/ui")
+	group.POST("/tap", UITap)
+	group.POST("/swipe", UISwipe)
+	group.POST("/longpress", UILongPress)
+	group.POST("/type", UIType)
+	group.POST("/button", UIButton)
+	group.GET("/screenshot", UIScreenshot)
+	group.GET("/source", UISource)
+	group.GET("/size", UIWindowSize)
+	group.GET("/orientation", UIGetOrientation)
+	group.PUT("/orientation", UISetOrientation)
+	group.GET("/status", UIStatus)
+	group.POST("/app/launch", UIAppLaunch)
+	group.POST("/app/terminate", UIAppTerminate)
+	group.POST("/app/foreground", UIAppForeground)
+	group.POST("/api", UIAPI)
+}
+
+// newDriverFromRequest builds a uidriver.Driver for the current request from the
+// backend/wdaUrl/timeout query params (or same-named headers) and the device
+// udid. It returns the driver and the resolved udid.
+func newDriverFromRequest(c *gin.Context) (*uidriver.Driver, string, error) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	udid := device.Properties.SerialNumber
+
+	backend := uidriver.BackendWDA
+	switch strings.ToLower(strings.TrimSpace(paramOrHeader(c, "backend"))) {
+	case "", string(uidriver.BackendWDA):
+		backend = uidriver.BackendWDA
+	case string(uidriver.BackendDeviceKit):
+		backend = uidriver.BackendDeviceKit
+	default:
+		return nil, udid, errors.New("unknown backend; expected wda or devicekit")
+	}
+
+	baseURL := strings.TrimSpace(paramOrHeader(c, "wdaUrl"))
+	if baseURL == "" {
+		if backend == uidriver.BackendDeviceKit {
+			baseURL = uidriver.DefaultDeviceKitURL
+		} else {
+			baseURL = uidriver.DefaultWDAURL
+		}
+	}
+
+	opts := []uidriver.Option{uidriver.WithUDID(udid)}
+	if raw := strings.TrimSpace(paramOrHeader(c, "timeout")); raw != "" {
+		secs, err := strconv.Atoi(raw)
+		if err != nil || secs <= 0 {
+			return nil, udid, errInvalidTimeout
+		}
+		opts = append(opts, uidriver.WithTimeout(time.Duration(secs)*time.Second))
+	}
+
+	driver, err := uidriver.New(backend, baseURL, opts...)
+	if err != nil {
+		return nil, udid, err
+	}
+	return driver, udid, nil
+}
+
+// paramOrHeader reads a value from the query string first, falling back to a
+// same-named request header.
+func paramOrHeader(c *gin.Context, name string) string {
+	if v := c.Query(name); v != "" {
+		return v
+	}
+	return c.GetHeader(name)
+}
+
+// respondUIError maps uidriver failures to sensible HTTP statuses and writes the
+// standard error envelope.
+//
+//	*uidriver.HTTPError    -> 502 (the WDA/DeviceKit backend rejected/failed)
+//	ErrButtonUnsupported / ErrForegroundUnsupported / ErrStreamUnsupported -> 501
+//	everything else (transport failure, unreachable backend, decode error) -> 502
+func respondUIError(c *gin.Context, udid string, err error) {
+	var httpErr *uidriver.HTTPError
+	switch {
+	case errors.As(err, &httpErr):
+		golog.Warn("ui backend returned error", "module", logModule, "udid", udid, "status", httpErr.StatusCode)
+		RespondError(c, http.StatusBadGateway, err)
+	case errors.Is(err, uidriver.ErrButtonUnsupported),
+		errors.Is(err, uidriver.ErrForegroundUnsupported),
+		errors.Is(err, uidriver.ErrStreamUnsupported):
+		RespondError(c, http.StatusNotImplemented, err)
+	default:
+		golog.Warn("ui backend unreachable", "module", logModule, "udid", udid, "error", err.Error())
+		RespondError(c, http.StatusBadGateway, err)
+	}
+}
+
+// writeUIResponse forwards a uidriver.Response back to the client, preserving
+// the backend's Content-Type when present and defaulting to JSON.
+func writeUIResponse(c *gin.Context, resp uidriver.Response) {
+	contentType := resp.Header.Get("Content-Type")
+	if contentType == "" {
+		contentType = "application/json"
+	}
+	status := resp.StatusCode
+	if status == 0 {
+		status = http.StatusOK
+	}
+	c.Data(status, contentType, resp.Body)
+}
+
+// UITap taps at absolute coordinates {x,y}.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UITap(c *gin.Context) {
+	var body struct {
+		X int `json:"x"`
+		Y int `json:"y"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.Tap(body.X, body.Y)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UISwipe drags from {x1,y1} to {x2,y2} over an optional duration (seconds).
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UISwipe(c *gin.Context) {
+	var body struct {
+		X1       int     `json:"x1"`
+		Y1       int     `json:"y1"`
+		X2       int     `json:"x2"`
+		Y2       int     `json:"y2"`
+		Duration float64 `json:"duration"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.Swipe(body.X1, body.Y1, body.X2, body.Y2, body.Duration)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UILongPress presses and holds at {x,y} for an optional duration (seconds).
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UILongPress(c *gin.Context) {
+	var body struct {
+		X        int     `json:"x"`
+		Y        int     `json:"y"`
+		Duration float64 `json:"duration"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.LongPress(body.X, body.Y, body.Duration)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIType sends {text} as keyboard input.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIType(c *gin.Context) {
+	var body struct {
+		Text string `json:"text"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if body.Text == "" {
+		RespondError(c, http.StatusBadRequest, errMissingText)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.Type(body.Text)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIButton presses a hardware button by {name} (home/volumeup/...). WDA only
+// supports the home button; other buttons require the devicekit backend.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIButton(c *gin.Context) {
+	var body struct {
+		Name string `json:"name"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if body.Name == "" {
+		RespondError(c, http.StatusBadRequest, errMissingButtonName)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.PressButton(body.Name)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIScreenshot captures the screen and returns raw PNG bytes (image/png).
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIScreenshot(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	image, err := driver.Screenshot()
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	c.Data(http.StatusOK, "image/png", image)
+}
+
+// UISource returns the current view hierarchy as the backend supplies it (XML
+// for WDA, backend-defined for DeviceKit); the backend Content-Type is
+// preserved.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UISource(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.Source()
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIWindowSize returns the device window/screen size payload as the backend
+// returns it (typically {width,height}).
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIWindowSize(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.WindowSize()
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIGetOrientation returns the current device orientation payload.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIGetOrientation(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.Orientation()
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UISetOrientation sets the device orientation from {orientation} (for example
+// PORTRAIT, LANDSCAPE).
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UISetOrientation(c *gin.Context) {
+	var body struct {
+		Orientation string `json:"orientation"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if body.Orientation == "" {
+		RespondError(c, http.StatusBadRequest, errMissingOrientation)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.SetOrientation(body.Orientation)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIStatus returns the backend status/health payload (WDA /status or DeviceKit
+// /health).
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIStatus(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.Status()
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIAppLaunch launches the app identified by {bundleId}.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIAppLaunch(c *gin.Context) {
+	uiAppAction(c, func(d *uidriver.Driver, bundleID string) (uidriver.Response, error) {
+		return d.AppLaunch(bundleID)
+	})
+}
+
+// UIAppTerminate terminates the app identified by {bundleId}.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIAppTerminate(c *gin.Context) {
+	uiAppAction(c, func(d *uidriver.Driver, bundleID string) (uidriver.Response, error) {
+		return d.AppTerminate(bundleID)
+	})
+}
+
+// UIAppForeground brings the backgrounded app to the foreground. Only the
+// devicekit backend supports this; WDA returns 501. The request body is
+// ignored.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIAppForeground(c *gin.Context) {
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := driver.AppForeground()
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// uiAppAction is the shared body-parsing + dispatch for launch/terminate, which
+// both take a {bundleId} body and a Driver method.
+func uiAppAction(c *gin.Context, action func(*uidriver.Driver, string) (uidriver.Response, error)) {
+	var body struct {
+		BundleID string `json:"bundleId"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if body.BundleID == "" {
+		RespondError(c, http.StatusBadRequest, errMissingBundleIDUI)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	resp, err := action(driver, body.BundleID)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
+
+// UIAPI is a raw passthrough to the backend. The JSON body is:
+//
+//	{"method":"POST","path":"/session/.../wda/tap/0/0","body":<raw>}   (wda)
+//	{"rpcMethod":"device.info","rpcParams":{...}}                       (devicekit)
+//
+// For the wda backend method defaults to GET and path is required; body is the
+// raw request body as bytes. For devicekit, rpcMethod is required.
+//
+// Requires a running, forwarded WDA/DeviceKit backend; see registerUIRoutes.
+func UIAPI(c *gin.Context) {
+	var req uidriver.APIRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	driver, udid, err := newDriverFromRequest(c)
+	if err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	// Validate up front so bad input maps to 400 rather than surfacing as a
+	// generic uidriver error (which respondUIError would treat as a 502).
+	if driver.Backend() == uidriver.BackendWDA && req.Path == "" {
+		RespondError(c, http.StatusBadRequest, errMissingAPIPath)
+		return
+	}
+	if driver.Backend() == uidriver.BackendDeviceKit && req.RPCMethod == "" {
+		RespondError(c, http.StatusBadRequest, errors.New("missing required 'rpcMethod' field for the devicekit backend"))
+		return
+	}
+	resp, err := driver.API(req)
+	if err != nil {
+		respondUIError(c, udid, err)
+		return
+	}
+	writeUIResponse(c, resp)
+}
diff --git a/restapi/api/ui_endpoints_test.go b/restapi/api/ui_endpoints_test.go
new file mode 100644
index 000000000..80e1cb8d2
--- /dev/null
+++ b/restapi/api/ui_endpoints_test.go
@@ -0,0 +1,365 @@
+package api_test
+
+import (
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/restapi/api"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// These tests are fully device-free: the "device" is just an HTTP backend that
+// mimics WebDriverAgent. We stand up an httptest.Server as the fake WDA, point
+// the ui endpoints at it via ?wdaUrl=<server>, and assert each endpoint forwards
+// the correct method/path/body and returns the mapped response.
+
+// recordedRequest captures one call the ui handler made to the fake WDA backend.
+type recordedRequest struct {
+	Method string
+	Path   string
+	Body   string
+}
+
+// fakeWDA is a stand-in WebDriverAgent HTTP server. It records every request and
+// answers session creation plus arbitrary paths with a canned 200 body.
+type fakeWDA struct {
+	server   *httptest.Server
+	mu       sync.Mutex
+	requests []recordedRequest
+	// screenshotB64 is returned (wrapped in {"value":...}) for screenshot paths.
+	screenshotB64 string
+}
+
+func newFakeWDA(t *testing.T) *fakeWDA {
+	t.Helper()
+	f := &fakeWDA{}
+	f.server = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		body, _ := io.ReadAll(r.Body)
+		f.mu.Lock()
+		f.requests = append(f.requests, recordedRequest{Method: r.Method, Path: r.URL.Path, Body: string(body)})
+		f.mu.Unlock()
+
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case r.URL.Path == "/session" && r.Method == http.MethodPost:
+			_, _ = w.Write([]byte(`{"sessionId":"sess-123","value":{"sessionId":"sess-123"}}`))
+		case strings.HasSuffix(r.URL.Path, "/screenshot"):
+			_, _ = w.Write([]byte(`{"value":"` + f.screenshotB64 + `"}`))
+		case r.URL.Path == "/status":
+			_, _ = w.Write([]byte(`{"value":{"ready":true}}`))
+		case strings.HasSuffix(r.URL.Path, "/source"):
+			w.Header().Set("Content-Type", "application/xml")
+			_, _ = w.Write([]byte(`<XCUIElementTypeApplication/>`))
+		default:
+			_, _ = w.Write([]byte(`{"value":"ok"}`))
+		}
+	}))
+	t.Cleanup(f.server.Close)
+	return f
+}
+
+func (f *fakeWDA) recorded() []recordedRequest {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	out := make([]recordedRequest, len(f.requests))
+	copy(out, f.requests)
+	return out
+}
+
+// find returns the first recorded request whose path contains sub, or fails.
+func (f *fakeWDA) find(t *testing.T, sub string) recordedRequest {
+	t.Helper()
+	for _, req := range f.recorded() {
+		if strings.Contains(req.Path, sub) {
+			return req
+		}
+	}
+	t.Fatalf("no recorded request with path containing %q; got %+v", sub, f.recorded())
+	return recordedRequest{}
+}
+
+// uiRouter builds a gin engine with the exported ui handlers registered under
+// paths matching the real routes, behind a fake device middleware. Requests are
+// pointed at wdaURL via the ?wdaUrl query param, so no real device is involved.
+func uiRouter() *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.Use(func(c *gin.Context) {
+		c.Set(api.IOS_KEY, ios.DeviceEntry{Properties: ios.DeviceProperties{SerialNumber: "ui-test-udid"}})
+		c.Next()
+	})
+	r.POST("/ui/tap", api.UITap)
+	r.POST("/ui/swipe", api.UISwipe)
+	r.POST("/ui/longpress", api.UILongPress)
+	r.POST("/ui/type", api.UIType)
+	r.POST("/ui/button", api.UIButton)
+	r.GET("/ui/screenshot", api.UIScreenshot)
+	r.GET("/ui/source", api.UISource)
+	r.GET("/ui/size", api.UIWindowSize)
+	r.GET("/ui/orientation", api.UIGetOrientation)
+	r.PUT("/ui/orientation", api.UISetOrientation)
+	r.GET("/ui/status", api.UIStatus)
+	r.POST("/ui/app/launch", api.UIAppLaunch)
+	r.POST("/ui/app/terminate", api.UIAppTerminate)
+	r.POST("/ui/app/foreground", api.UIAppForeground)
+	r.POST("/ui/api", api.UIAPI)
+	return r
+}
+
+// doUI issues a request to path?wdaUrl=<backend> with an optional JSON body.
+func doUI(t *testing.T, r *gin.Engine, method, path, wdaURL, body string) *httptest.ResponseRecorder {
+	t.Helper()
+	sep := "?"
+	if strings.Contains(path, "?") {
+		sep = "&"
+	}
+	url := path
+	if wdaURL != "" {
+		url = path + sep + "wdaUrl=" + wdaURL
+	}
+	var reader io.Reader
+	if body != "" {
+		reader = strings.NewReader(body)
+	}
+	req, _ := http.NewRequest(method, url, reader)
+	if body != "" {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+	return w
+}
+
+func TestUITapForwardsToWDA(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/tap", wda.server.URL, `{"x":42,"y":99}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/wda/tap/42/99")
+	assert.Equal(t, http.MethodPost, req.Method)
+	// A session must have been created first.
+	wda.find(t, "/session")
+}
+
+func TestUISwipeForwardsBody(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/swipe", wda.server.URL, `{"x1":1,"y1":2,"x2":3,"y2":4,"duration":0.5}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "dragfromtoforduration")
+	assert.Equal(t, http.MethodPost, req.Method)
+	var payload map[string]float64
+	require.NoError(t, json.Unmarshal([]byte(req.Body), &payload))
+	assert.Equal(t, float64(1), payload["fromX"])
+	assert.Equal(t, float64(4), payload["toY"])
+	assert.Equal(t, 0.5, payload["duration"])
+}
+
+func TestUILongPressForwardsBody(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/longpress", wda.server.URL, `{"x":10,"y":20,"duration":1.5}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "touchAndHold")
+	assert.Equal(t, http.MethodPost, req.Method)
+	var payload map[string]float64
+	require.NoError(t, json.Unmarshal([]byte(req.Body), &payload))
+	assert.Equal(t, float64(10), payload["x"])
+	assert.Equal(t, 1.5, payload["duration"])
+}
+
+func TestUITypeForwardsText(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/type", wda.server.URL, `{"text":"hello"}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/keys")
+	assert.Equal(t, http.MethodPost, req.Method)
+	assert.Contains(t, req.Body, "hello")
+}
+
+func TestUITypeRejectsMissingText(t *testing.T) {
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/type", "http://127.0.0.1:8100", `{}`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	assert.Contains(t, w.Body.String(), "text")
+}
+
+func TestUIButtonHomeForwards(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/button", wda.server.URL, `{"name":"home"}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "homescreen")
+	assert.Equal(t, http.MethodPost, req.Method)
+}
+
+func TestUIButtonUnsupportedMapsTo501(t *testing.T) {
+	wda := newFakeWDA(t)
+	// WDA only supports the home button; volumeup must map to 501 and never
+	// reach the backend.
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/button", wda.server.URL, `{"name":"volumeup"}`)
+	assert.Equal(t, http.StatusNotImplemented, w.Code)
+}
+
+func TestUIButtonRejectsMissingName(t *testing.T) {
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/button", "http://127.0.0.1:8100", `{}`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+func TestUIScreenshotReturnsPNGBytes(t *testing.T) {
+	wda := newFakeWDA(t)
+	raw := []byte("\x89PNG\r\n\x1a\nfake-png-bytes")
+	wda.screenshotB64 = base64.StdEncoding.EncodeToString(raw)
+
+	w := doUI(t, uiRouter(), http.MethodGet, "/ui/screenshot", wda.server.URL, "")
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Equal(t, "image/png", w.Header().Get("Content-Type"))
+	assert.Equal(t, raw, w.Body.Bytes())
+
+	wda.find(t, "/screenshot")
+}
+
+func TestUISourceForwardsAndPreservesContentType(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodGet, "/ui/source", wda.server.URL, "")
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Contains(t, w.Header().Get("Content-Type"), "xml")
+	assert.Contains(t, w.Body.String(), "XCUIElementTypeApplication")
+
+	req := wda.find(t, "/source")
+	assert.Equal(t, http.MethodGet, req.Method)
+}
+
+func TestUIWindowSizeForwards(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodGet, "/ui/size", wda.server.URL, "")
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/window/size")
+	assert.Equal(t, http.MethodGet, req.Method)
+}
+
+func TestUIGetOrientationForwards(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodGet, "/ui/orientation", wda.server.URL, "")
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/orientation")
+	assert.Equal(t, http.MethodGet, req.Method)
+}
+
+func TestUISetOrientationForwardsBody(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPut, "/ui/orientation", wda.server.URL, `{"orientation":"LANDSCAPE"}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/orientation")
+	assert.Equal(t, http.MethodPost, req.Method)
+	assert.Contains(t, req.Body, "LANDSCAPE")
+}
+
+func TestUISetOrientationRejectsMissing(t *testing.T) {
+	w := doUI(t, uiRouter(), http.MethodPut, "/ui/orientation", "http://127.0.0.1:8100", `{}`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+func TestUIStatusForwards(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodGet, "/ui/status", wda.server.URL, "")
+	assert.Equal(t, http.StatusOK, w.Code)
+	assert.Contains(t, w.Body.String(), "ready")
+
+	req := wda.find(t, "/status")
+	assert.Equal(t, http.MethodGet, req.Method)
+}
+
+func TestUIAppLaunchForwardsBundleID(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/app/launch", wda.server.URL, `{"bundleId":"com.example.app"}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/wda/apps/launch")
+	assert.Equal(t, http.MethodPost, req.Method)
+	assert.Contains(t, req.Body, "com.example.app")
+}
+
+func TestUIAppTerminateForwardsBundleID(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/app/terminate", wda.server.URL, `{"bundleId":"com.example.app"}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/wda/apps/terminate")
+	assert.Equal(t, http.MethodPost, req.Method)
+	assert.Contains(t, req.Body, "com.example.app")
+}
+
+func TestUIAppLaunchRejectsMissingBundleID(t *testing.T) {
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/app/launch", "http://127.0.0.1:8100", `{}`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+func TestUIAppForegroundUnsupportedOnWDA(t *testing.T) {
+	wda := newFakeWDA(t)
+	// Foreground is DeviceKit-only; on the default WDA backend it must map to 501.
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/app/foreground", wda.server.URL, `{"bundleId":"com.example.app"}`)
+	assert.Equal(t, http.StatusNotImplemented, w.Code)
+}
+
+func TestUIAPIPassthroughForwards(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/api", wda.server.URL, `{"method":"GET","path":"/wda/screen"}`)
+	assert.Equal(t, http.StatusOK, w.Code)
+
+	req := wda.find(t, "/wda/screen")
+	assert.Equal(t, http.MethodGet, req.Method)
+}
+
+func TestUIAPIRejectsMissingPathForWDA(t *testing.T) {
+	wda := newFakeWDA(t)
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/api", wda.server.URL, `{"method":"GET"}`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	assert.Contains(t, w.Body.String(), "path")
+}
+
+func TestUIUnreachableBackendMapsTo502(t *testing.T) {
+	// Point at a port nothing is listening on; the transport failure must map
+	// to 502 Bad Gateway.
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/tap", "http://127.0.0.1:1", `{"x":1,"y":1}`)
+	assert.Equal(t, http.StatusBadGateway, w.Code)
+}
+
+func TestUIBackendErrorMapsTo502(t *testing.T) {
+	// A backend that returns a non-2xx status must surface as 502.
+	backend := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/session" {
+			w.Header().Set("Content-Type", "application/json")
+			_, _ = w.Write([]byte(`{"sessionId":"s"}`))
+			return
+		}
+		http.Error(w, "boom", http.StatusInternalServerError)
+	}))
+	defer backend.Close()
+
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/tap", backend.URL, `{"x":1,"y":1}`)
+	assert.Equal(t, http.StatusBadGateway, w.Code)
+}
+
+func TestUITapRejectsBadJSON(t *testing.T) {
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/tap", "http://127.0.0.1:8100", `{not json`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+func TestUIUnknownBackendRejected(t *testing.T) {
+	w := doUI(t, uiRouter(), http.MethodPost, "/ui/tap?backend=bogus", "http://127.0.0.1:8100", `{"x":1,"y":1}`)
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	assert.Contains(t, w.Body.String(), "backend")
+}
diff --git a/restapi/api/util.go b/restapi/api/util.go
index 31423b062..24807bfad 100644
--- a/restapi/api/util.go
+++ b/restapi/api/util.go
@@ -27,10 +27,15 @@ func GetVersion() string {
 	return string(version)
 }
 
+// MustMarshal marshals v to a JSON string. It never panics: on the rare
+// marshal failure it returns an error envelope instead, so it is safe to call
+// from inside a request/stream handler (a panic there would otherwise abort the
+// response, or escape entirely in a streaming handler).
 func MustMarshal(v interface{}) string {
 	b, err := json.Marshal(v)
 	if err != nil {
-		panic(err)
+		safe, _ := json.Marshal(GenericResponse{Error: "failed to marshal response: " + err.Error()})
+		return string(safe)
 	}
 	return string(b)
 }
diff --git a/restapi/api/webinspector_endpoints.go b/restapi/api/webinspector_endpoints.go
new file mode 100644
index 000000000..83177db8e
--- /dev/null
+++ b/restapi/api/webinspector_endpoints.go
@@ -0,0 +1,275 @@
+package api
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/ios/golog"
+	"github.com/danielpaulus/go-ios/ios/webinspector"
+	"github.com/gin-gonic/gin"
+)
+
+// Sentinel errors for webinspector request validation.
+var (
+	errMissingURL    = errors.New("missing required 'url' (query param or JSON body)")
+	errMissingScript = errors.New("missing required 'script' (JSON body)")
+	errNoMatchingWIP = errors.New("no matching inspectable page found")
+)
+
+// webinspectorConnectTimeout bounds how long an endpoint waits for the device's
+// Web Inspector service to report its pages/apps before failing. It mirrors the
+// CLI default (5s) so behaviour is consistent across the CLI and the REST API.
+const webinspectorConnectTimeout = 5 * time.Second
+
+// registerWebInspectorRoutes registers the non-interactive Web Inspector
+// endpoints, mirroring the `ios webinspector list|launch|eval` CLI commands.
+// The interactive commands (js-shell, cdp) are intentionally not exposed over
+// the REST API. Routes are registered under /device/:udid.
+func registerWebInspectorRoutes(device *gin.RouterGroup) {
+	group := device.Group("/webinspector")
+	group.GET("/pages", WebInspectorPages)
+	group.POST("/launch", WebInspectorLaunch)
+	group.POST("/eval", WebInspectorEval)
+}
+
+// webInspectorLaunchRequest is the JSON body for POST /webinspector/launch.
+// url may alternatively be supplied as a query param.
+type webInspectorLaunchRequest struct {
+	URL      string `json:"url"`
+	BundleID string `json:"bundleId"`
+}
+
+// webInspectorEvalRequest is the JSON body for POST /webinspector/eval.
+// page identifies the inspectable page (its key); when empty the first matching
+// web/javascript page is used. bundleId optionally scopes the page selection.
+type webInspectorEvalRequest struct {
+	Page     string `json:"page"`
+	BundleID string `json:"bundleId"`
+	Script   string `json:"script"`
+}
+
+// newWebInspectorClient connects to the device's Web Inspector service and waits
+// for it to report its connected applications. On the well-known "Web Inspector
+// not enabled" condition it returns webinspector.ErrWebInspectorDisabled so
+// callers can map it to a 4xx. The caller owns closing the returned client.
+func newWebInspectorClient(ctx context.Context, device ios.DeviceEntry) (*webinspector.Client, error) {
+	client, err := webinspector.New(device)
+	if err != nil {
+		return nil, err
+	}
+	if err := client.Connect(ctx); err != nil {
+		client.Close()
+		return nil, err
+	}
+	return client, nil
+}
+
+// respondWebInspectorError maps webinspector service errors to sensible HTTP
+// status codes: the "not enabled on the device" conditions become 424 Failed
+// Dependency (the request is well-formed but a device-side prerequisite is
+// missing), everything else is a 500.
+func respondWebInspectorError(c *gin.Context, err error) {
+	switch {
+	case errors.Is(err, webinspector.ErrWebInspectorDisabled),
+		errors.Is(err, webinspector.ErrRemoteAutomationDisabled):
+		RespondError(c, http.StatusFailedDependency, err)
+	default:
+		RespondError(c, http.StatusInternalServerError, err)
+	}
+}
+
+// WebInspectorPages lists the inspectable pages reported by the device's Web
+// Inspector service (CLI: ios webinspector list).
+// @Summary List inspectable Web Inspector pages
+// @Param udid path string true "Device UDID"
+// @Success 200 {object} []webinspector.ApplicationPage
+// @Failure 424 {object} map[string]string "Web Inspector not enabled on the device"
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/webinspector/pages [get]
+func WebInspectorPages(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+	ctx, cancel := context.WithTimeout(c.Request.Context(), webinspectorConnectTimeout)
+	defer cancel()
+
+	client, err := newWebInspectorClient(ctx, device)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	defer client.Close()
+
+	pages, err := client.ListPages(ctx, 500*time.Millisecond)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	if pages == nil {
+		pages = []webinspector.ApplicationPage{}
+	}
+	golog.Info("listed webinspector pages", "module", logModule, "udid", device.Properties.SerialNumber, "count", len(pages))
+	c.JSON(http.StatusOK, pages)
+}
+
+// WebInspectorLaunch opens a URL in a new inspectable page via a remote
+// automation session (CLI: ios webinspector launch <url>). bundleId defaults to
+// Safari.
+// @Summary Open a URL in a new inspectable page
+// @Param udid path string true "Device UDID"
+// @Param url query string false "URL to open (or in JSON body)"
+// @Param body body webInspectorLaunchRequest false "launch request"
+// @Success 200 {object} map[string]string
+// @Failure 400 {object} map[string]string
+// @Failure 424 {object} map[string]string "Web Inspector / Remote Automation not enabled"
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/webinspector/launch [post]
+func WebInspectorLaunch(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	var req webInspectorLaunchRequest
+	// Body is optional (url may come from the query), so ignore bind errors and
+	// fall back to the query param.
+	_ = c.ShouldBindJSON(&req)
+	url := strings.TrimSpace(req.URL)
+	if url == "" {
+		url = strings.TrimSpace(c.Query("url"))
+	}
+	if url == "" {
+		RespondError(c, http.StatusBadRequest, errMissingURL)
+		return
+	}
+	bundleID := strings.TrimSpace(req.BundleID)
+	if bundleID == "" {
+		bundleID = strings.TrimSpace(c.Query("bundleId"))
+	}
+	if bundleID == "" {
+		bundleID = webinspector.SafariBundleID
+	}
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), webinspectorConnectTimeout)
+	defer cancel()
+
+	client, err := newWebInspectorClient(ctx, device)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	defer client.Close()
+
+	app, err := client.OpenApp(ctx, bundleID)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	session, err := client.AutomationSession(ctx, app)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	defer func() {
+		stopCtx, stopCancel := context.WithTimeout(context.Background(), 2*time.Second)
+		defer stopCancel()
+		_ = session.Stop(stopCtx)
+	}()
+	if err := session.Start(ctx); err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	if err := session.Navigate(ctx, url); err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	currentURL, _ := session.CurrentURL(ctx)
+	title, _ := session.Title(ctx)
+	golog.Info("launched webinspector url", "module", logModule, "udid", device.Properties.SerialNumber, "bundleId", bundleID, "url", currentURL)
+	c.JSON(http.StatusOK, gin.H{"bundleId": bundleID, "url": currentURL, "title": title})
+}
+
+// WebInspectorEval evaluates JavaScript in an inspectable page and returns the
+// result (CLI: ios webinspector eval). page identifies the target page by key;
+// when omitted the first matching web/javascript page (optionally scoped by
+// bundleId) is used.
+// @Summary Evaluate JavaScript in an inspectable page
+// @Param udid path string true "Device UDID"
+// @Param body body webInspectorEvalRequest true "eval request"
+// @Success 200 {object} map[string]interface{}
+// @Failure 400 {object} map[string]string
+// @Failure 404 {object} map[string]string "no matching page"
+// @Failure 424 {object} map[string]string "Web Inspector not enabled on the device"
+// @Failure 500 {object} map[string]string
+// @Router /device/{udid}/webinspector/eval [post]
+func WebInspectorEval(c *gin.Context) {
+	device := c.MustGet(IOS_KEY).(ios.DeviceEntry)
+
+	var req webInspectorEvalRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		RespondError(c, http.StatusBadRequest, err)
+		return
+	}
+	if strings.TrimSpace(req.Script) == "" {
+		RespondError(c, http.StatusBadRequest, errMissingScript)
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), webinspectorConnectTimeout)
+	defer cancel()
+
+	client, err := newWebInspectorClient(ctx, device)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	defer client.Close()
+
+	app, page, err := resolveWebInspectorPage(ctx, client, req.Page, req.BundleID)
+	if err != nil {
+		if errors.Is(err, errNoMatchingWIP) {
+			RespondError(c, http.StatusNotFound, err)
+			return
+		}
+		respondWebInspectorError(c, err)
+		return
+	}
+
+	result, err := client.Evaluate(ctx, app, page, req.Script)
+	if err != nil {
+		respondWebInspectorError(c, err)
+		return
+	}
+	golog.Info("evaluated webinspector script", "module", logModule, "udid", device.Properties.SerialNumber, "page", page.Key)
+	c.JSON(http.StatusOK, gin.H{"page": page.Key, "result": result})
+}
+
+// resolveWebInspectorPage selects the inspectable page to operate on, mirroring
+// the CLI's selection logic: an exact page key is preferred; otherwise the first
+// web/javascript page (optionally scoped by bundleId) is returned. Returns
+// errNoMatchingWIP when nothing matches.
+func resolveWebInspectorPage(ctx context.Context, client *webinspector.Client, pageID string, bundleID string) (webinspector.Application, webinspector.Page, error) {
+	if pageID != "" {
+		if app, page, ok := client.FindPage(pageID); ok {
+			return app, page, nil
+		}
+	}
+	pages, err := client.ListPages(ctx, 500*time.Millisecond)
+	if err != nil {
+		return webinspector.Application{}, webinspector.Page{}, err
+	}
+	for _, candidate := range pages {
+		if candidate.Page.Type != webinspector.WIRTypeWeb &&
+			candidate.Page.Type != webinspector.WIRTypeWebPage &&
+			candidate.Page.Type != webinspector.WIRTypeJavaScript {
+			continue
+		}
+		if bundleID != "" && candidate.Application.BundleID != bundleID {
+			continue
+		}
+		if pageID != "" && candidate.Page.Key != pageID {
+			continue
+		}
+		return candidate.Application, candidate.Page, nil
+	}
+	return webinspector.Application{}, webinspector.Page{}, errNoMatchingWIP
+}
diff --git a/restapi/api/webinspector_endpoints_test.go b/restapi/api/webinspector_endpoints_test.go
new file mode 100644
index 000000000..f999adced
--- /dev/null
+++ b/restapi/api/webinspector_endpoints_test.go
@@ -0,0 +1,138 @@
+package api_test
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/danielpaulus/go-ios/ios"
+	"github.com/danielpaulus/go-ios/restapi/api"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+)
+
+// webInspectorTestRouter wires the non-interactive Web Inspector handlers behind
+// a device middleware that injects a device with no real connection. Request
+// validation (missing url/script) runs before any device I/O, so those paths are
+// device-free; paths that would reach the device are not exercised here.
+func webInspectorTestRouter() *gin.Engine {
+	gin.SetMode(gin.TestMode)
+	r := gin.New()
+	r.Use(func(c *gin.Context) {
+		c.Set(api.IOS_KEY, ios.DeviceEntry{
+			Properties: ios.DeviceProperties{SerialNumber: "webinspector-test-udid"},
+		})
+		c.Next()
+	})
+	r.GET("/webinspector/pages", api.WebInspectorPages)
+	r.POST("/webinspector/launch", api.WebInspectorLaunch)
+	r.POST("/webinspector/eval", api.WebInspectorEval)
+	return r
+}
+
+// TestWebInspectorLaunchMissingURL asserts launch rejects a request with no url
+// (neither query param nor JSON body) with a 400 before touching the device.
+func TestWebInspectorLaunchMissingURL(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{"no body no query", ""},
+		{"empty json", "{}"},
+		{"blank url", `{"url":"   "}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			router := webInspectorTestRouter()
+			var reader *strings.Reader
+			if tc.body != "" {
+				reader = strings.NewReader(tc.body)
+			} else {
+				reader = strings.NewReader("")
+			}
+			req, _ := http.NewRequest("POST", "/webinspector/launch", reader)
+			req.Header.Set("Content-Type", "application/json")
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			assert.Equal(t, http.StatusBadRequest, w.Code)
+			var resp map[string]any
+			assert.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+			errMsg, _ := resp["error"].(string)
+			assert.Contains(t, errMsg, "url")
+		})
+	}
+}
+
+// TestWebInspectorEvalMissingScript asserts eval rejects a request with a
+// missing/blank script with a 400 before touching the device.
+func TestWebInspectorEvalMissingScript(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+	}{
+		{"empty json", "{}"},
+		{"blank script", `{"script":"  "}`},
+		{"page but no script", `{"page":"page-1"}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			router := webInspectorTestRouter()
+			req, _ := http.NewRequest("POST", "/webinspector/eval", strings.NewReader(tc.body))
+			req.Header.Set("Content-Type", "application/json")
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			assert.Equal(t, http.StatusBadRequest, w.Code)
+			var resp map[string]any
+			assert.NoError(t, json.Unmarshal(w.Body.Bytes(), &resp))
+			errMsg, _ := resp["error"].(string)
+			assert.Contains(t, errMsg, "script")
+		})
+	}
+}
+
+// TestWebInspectorEvalInvalidJSON asserts malformed JSON bodies are rejected
+// with a 400 (the bind error), not a 500.
+func TestWebInspectorEvalInvalidJSON(t *testing.T) {
+	router := webInspectorTestRouter()
+	req, _ := http.NewRequest("POST", "/webinspector/eval", strings.NewReader(`{"script": `))
+	req.Header.Set("Content-Type", "application/json")
+	w := httptest.NewRecorder()
+	router.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+}
+
+// TestWebInspectorRoutesRegistered asserts the three non-interactive routes are
+// wired to handlers (a registered route never yields 404). Because the injected
+// device has no real connection, the handlers fail while connecting rather than
+// returning 404; the assertion is simply that they are reachable.
+func TestWebInspectorRoutesRegistered(t *testing.T) {
+	cases := []struct {
+		method string
+		path   string
+		body   string
+	}{
+		// launch/eval carry valid input so validation passes and the handler
+		// proceeds to the (failing) device connection instead of a 400.
+		{"POST", "/webinspector/launch", `{"url":"https://example.com"}`},
+		{"POST", "/webinspector/eval", `{"script":"1+1"}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.method+" "+tc.path, func(t *testing.T) {
+			router := webInspectorTestRouter()
+			req, _ := http.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
+			req.Header.Set("Content-Type", "application/json")
+			w := httptest.NewRecorder()
+			router.ServeHTTP(w, req)
+
+			assert.NotEqual(t, http.StatusNotFound, w.Code, "route must be registered")
+			// With no real device, the connect/list step fails: a 4xx (Web
+			// Inspector disabled) or 5xx, never a 2xx.
+			assert.GreaterOrEqual(t, w.Code, 400)
+		})
+	}
+}
diff --git a/restapi/go.mod b/restapi/go.mod
index f88ec8097..9640e26a0 100644
--- a/restapi/go.mod
+++ b/restapi/go.mod
@@ -8,10 +8,11 @@ require (
 	github.com/danielpaulus/go-ios v1.0.91
 	github.com/gin-gonic/gin v1.8.1
 	github.com/sirupsen/logrus v1.9.3
-	github.com/stretchr/testify v1.8.0
+	github.com/stretchr/testify v1.11.1
 	github.com/swaggo/files v0.0.0-20220728132757-551d4a08d97a
 	github.com/swaggo/gin-swagger v1.5.2
 	github.com/swaggo/swag v1.16.3
+	golang.org/x/time v0.5.0
 )
 
 require (
@@ -38,45 +39,38 @@ require (
 	github.com/modern-go/reflect2 v1.0.2 // indirect
 	github.com/pelletier/go-toml/v2 v2.0.1 // indirect
 	github.com/ugorji/go/codec v1.2.7 // indirect
-	golang.org/x/crypto v0.24.0 // indirect
-	golang.org/x/net v0.26.0 // indirect
-	golang.org/x/sys v0.21.0 // indirect
-	golang.org/x/text v0.16.0 // indirect
-	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
+	golang.org/x/crypto v0.52.0 // indirect
+	golang.org/x/net v0.55.0 // indirect
+	golang.org/x/sys v0.45.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
+	golang.org/x/tools v0.44.0 // indirect
 	google.golang.org/protobuf v1.32.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
-	howett.net/plist v1.0.0 // indirect
+	howett.net/plist v1.0.1 // indirect
 )
 
 require (
 	github.com/cenkalti/backoff v2.2.1+incompatible // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 // indirect
 	github.com/google/btree v1.1.2 // indirect
-	github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38 // indirect
 	github.com/grandcat/zeroconf v1.0.0 // indirect
-	github.com/kr/pretty v0.3.1 // indirect
 	github.com/miekg/dns v1.1.57 // indirect
-	github.com/onsi/ginkgo/v2 v2.9.5 // indirect
 	github.com/pierrec/lz4 v2.6.1+incompatible // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
-	github.com/quic-go/qtls-go1-20 v0.4.1 // indirect
-	github.com/quic-go/quic-go v0.40.1-0.20231203135336-87ef8ec48d55 // indirect
+	github.com/quic-go/quic-go v0.59.1 // indirect
 	github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8 // indirect
 	github.com/tadglines/go-pkgs v0.0.0-20210623144937-b983b20f54f9 // indirect
 	github.com/vishvananda/netlink v1.3.1 // indirect
 	github.com/vishvananda/netns v0.0.5 // indirect
-	go.mozilla.org/pkcs7 v0.0.0-20210826202110-33d05740a352 // indirect
-	go.uber.org/mock v0.3.0 // indirect
+	go.mozilla.org/pkcs7 v0.9.0 // indirect
 	golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 // indirect
-	golang.org/x/mod v0.17.0 // indirect
-	golang.org/x/sync v0.7.0 // indirect
-	golang.org/x/time v0.5.0 // indirect
+	golang.org/x/mod v0.35.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
 	golang.zx2c4.com/wintun v0.0.0-20230126152724-0fa3db229ce2 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	gvisor.dev/gvisor v0.0.0-20240405191320-0878b34101b5 // indirect
-	software.sslmate.com/src/go-pkcs12 v0.2.0 // indirect
+	software.sslmate.com/src/go-pkcs12 v0.7.2 // indirect
 )
 
 replace github.com/danielpaulus/go-ios => ../
diff --git a/restapi/go.sum b/restapi/go.sum
index 732f87b66..a482f1a22 100644
--- a/restapi/go.sum
+++ b/restapi/go.sum
@@ -10,9 +10,6 @@ github.com/PuerkitoBio/urlesc v0.0.0-20170810143723-de5bf2ad4578/go.mod h1:uGdko
 github.com/agiledragon/gomonkey/v2 v2.3.1/go.mod h1:ap1AmDzcVOAz1YpeJ3TCzIgstoaWLA6jbbgxfB4w2iY=
 github.com/cenkalti/backoff v2.2.1+incompatible h1:tNowT99t7UNflLxfYYSlKYsBpXdEet03Pg2g16Swow4=
 github.com/cenkalti/backoff v2.2.1+incompatible/go.mod h1:90ReRw6GdpyfrHakVjL/QHaoyV4aDUVVkXQJJJ3NXXM=
-github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
-github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
-github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
@@ -29,8 +26,6 @@ github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE
 github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
 github.com/gin-gonic/gin v1.8.1 h1:4+fr/el88TOO3ewCmQr8cx/CtZ/umlIRIs5M4NTNjf8=
 github.com/gin-gonic/gin v1.8.1/go.mod h1:ji8BvRH1azfM+SYow9zQ6SZMvR8qOMZHmsCuWR9tTTk=
-github.com/go-logr/logr v1.2.4 h1:g01GSCwiDw2xSZfjJ2/T9M+S6pFdcNtFYsp+Y43HYDQ=
-github.com/go-logr/logr v1.2.4/go.mod h1:jdQByPbusPIv2/zmleS9BjJVeZ6kBagPoEUsqbVz/1A=
 github.com/go-openapi/jsonpointer v0.19.3/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
 github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY=
 github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg=
@@ -49,27 +44,20 @@ github.com/go-playground/universal-translator v0.18.0 h1:82dyy6p4OuJq4/CByFNOn/j
 github.com/go-playground/universal-translator v0.18.0/go.mod h1:UvRDBj+xPUEGrFYl+lu/H90nyDXpg0fqeB/AQUGNTVA=
 github.com/go-playground/validator/v10 v10.10.0 h1:I7mrTYv78z8k8VXa/qJlOlEXn/nBh+BF8dHX5nt/dr0=
 github.com/go-playground/validator/v10 v10.10.0/go.mod h1:74x4gJWsvQexRdW8Pn3dXSGrTK4nAUsbPlLADvpJkos=
-github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 h1:tfuBGBXKqDEevZMzYi5KSi8KkcZtzBcTgAUUtapy0OI=
-github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572/go.mod h1:9Pwr4B2jHnOSGXyyzV8ROjYa2ojvAY6HCGYYfMoC3Ls=
 github.com/goccy/go-json v0.9.7 h1:IcB+Aqpx/iMHu5Yooh7jEzJk1JZ7Pjtmys2ukPr7EeM=
 github.com/goccy/go-json v0.9.7/go.mod h1:6MelG93GURQebXPDq3khkgXZkazVtN9CRI+MGFi0w8I=
 github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
-github.com/golang/protobuf v1.5.3 h1:KhyjKVUg7Usr/dYsdSqoFveMYd5ko72D+zANwlG1mmg=
-github.com/golang/protobuf v1.5.3/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
 github.com/google/btree v1.1.2 h1:xf4v41cLI2Z6FxbKm+8Bu+m8ifhj15JuZ9sa0jZCMUU=
 github.com/google/btree v1.1.2/go.mod h1:qOPhT0dTNdNzV6Z/lhRX0YXUafgPLFUh+gZMl761Gm4=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
-github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38 h1:yAJXTCF9TqKcTiHJAE8dj7HMvPfh66eeA2JYW7eFpSE=
-github.com/google/pprof v0.0.0-20210407192527-94a9f03dee38/go.mod h1:kpwsk12EmLew5upagYY7GY0pfYCcupk39gWOCRROcvE=
 github.com/google/uuid v1.3.0 h1:t6JiXgmwXMjEs8VusXIJk2BXHsn+wx8BZdTaoZ5fu7I=
 github.com/google/uuid v1.3.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gopherjs/gopherjs v0.0.0-20181017120253-0766667cb4d1/go.mod h1:wJfORRmW1u3UXTncJ5qlYoELFm8eSnnEO6hX4iZ3EWY=
 github.com/grandcat/zeroconf v1.0.0 h1:uHhahLBKqwWBV6WZUDAT71044vwOTL+McW0mBJvo6kE=
 github.com/grandcat/zeroconf v1.0.0/go.mod h1:lTKmG1zh86XyCoUeIHSA4FJMBwCJiQmGfcP2PdzytEs=
-github.com/ianlancetaylor/demangle v0.0.0-20200824232613-28f6c0f3b639/go.mod h1:aSSvb/t6k1mPoxDqO4vJh6VOCGPwU4O0C2/Eqndh1Sc=
 github.com/jessevdk/go-flags v1.4.0/go.mod h1:4FA24M0QyGHXBuZZK/XkWh8h0e1EYbRYJSGM75WSRxI=
 github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY=
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
@@ -102,10 +90,6 @@ github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJ
 github.com/modern-go/reflect2 v1.0.2 h1:xBagoLtFs94CBntxluKeaWgTMpvLxC4ur3nMaC9Gz0M=
 github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
 github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno=
-github.com/onsi/ginkgo/v2 v2.9.5 h1:+6Hr4uxzP4XIUyAkg61dWBw8lb/gc4/X5luuxN/EC+Q=
-github.com/onsi/ginkgo/v2 v2.9.5/go.mod h1:tvAoo1QUJwNEU2ITftXTpR7R1RbCzoZUOs3RonqW57k=
-github.com/onsi/gomega v1.27.6 h1:ENqfyGeS5AX/rlXDd/ETokDz93u0YufY1Pgxuy/PvWE=
-github.com/onsi/gomega v1.27.6/go.mod h1:PIQNjfQwkP3aQAH7lf7j87O/5FiNr+ZR8+ipb+qQlhg=
 github.com/otiai10/copy v1.7.0/go.mod h1:rmRl6QPdJj6EiUqXQ/4Nn2lLXoNQjFCQbbNrxgc/t3U=
 github.com/otiai10/curr v0.0.0-20150429015615-9b4961190c95/go.mod h1:9qAhocn7zKJG+0mI8eUu6xqkFDYS2kb2saOteoSB3cE=
 github.com/otiai10/curr v1.0.0/go.mod h1:LskTG5wDwr8Rs+nNQ+1LlxRjAtTZZjtJW4rMXl6j4vs=
@@ -120,14 +104,12 @@ github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
-github.com/quic-go/qtls-go1-20 v0.4.1 h1:D33340mCNDAIKBqXuAvexTNMUByrYmFYVfKfDN5nfFs=
-github.com/quic-go/qtls-go1-20 v0.4.1/go.mod h1:X9Nh97ZL80Z+bX/gUXMbipO6OxdiDi58b/fMC9mAL+k=
-github.com/quic-go/quic-go v0.40.1-0.20231203135336-87ef8ec48d55 h1:I4N3ZRnkZPbDN935Tg8QDf8fRpHp3bZ0U0/L42jBgNE=
-github.com/quic-go/quic-go v0.40.1-0.20231203135336-87ef8ec48d55/go.mod h1:PeN7kuVJ4xZbxSv/4OX6S1USOX8MJvydwpTx31vx60c=
+github.com/quic-go/quic-go v0.59.1 h1:0Gmua0HW1Tv7ANR7hUYwRyD0MG5OJfgvYSZasGZzBic=
+github.com/quic-go/quic-go v0.59.1/go.mod h1:upnsH4Ju1YkqpLXC305eW3yDZ4NfnNbmQRCMWS58IKU=
 github.com/rogpeppe/go-internal v1.6.1/go.mod h1:xXDCJY+GAPziupqXw64V24skbSoqbTEfhy4qGm1nDQc=
 github.com/rogpeppe/go-internal v1.8.0/go.mod h1:WmiCO8CzOY8rg0OYDC4/i/2WRWAB6poM+XZ2dLUbcbE=
-github.com/rogpeppe/go-internal v1.9.0 h1:73kH8U+JUqXU8lRuOHeVHaa/SZPifC7BkcraZVejAe8=
-github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ=
+github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/shurcooL/sanitized_anchor_name v1.0.0/go.mod h1:1NzhyTcUVG4SuEtjjoZeVRXNmyL/1OwPU0+IJeTBvfc=
 github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
@@ -137,14 +119,16 @@ github.com/smartystreets/goconvey v1.6.4/go.mod h1:syvi0/a8iFYH4r/RixwvyeAJjdLS9
 github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8 h1:TG/diQgUe0pntT/2D9tmUCz4VNwm9MfrtPr0SU2qSX8=
 github.com/songgao/water v0.0.0-20200317203138-2b4b6d7c09d8/go.mod h1:P5HUIBuIWKbyjl083/loAegFkfbFNx5i2qEP4CNbm7E=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
-github.com/stretchr/objx v0.4.0 h1:M2gUjqZET1qApGOWNSnZ49BAIMX4F/1plDv3+l31EJ4=
 github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
-github.com/stretchr/testify v1.8.0 h1:pSgiaMZlXftHpm5L7V1+rVB+AZJydKsMxsQBIJw4PKk=
 github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/swaggo/files v0.0.0-20220610200504-28940afbdbfe/go.mod h1:lKJPbtWzJ9JhsTN1k1gZgleJWY/cqq0psdoMmaThG3w=
 github.com/swaggo/files v0.0.0-20220728132757-551d4a08d97a h1:kAe4YSu0O0UFn1DowNo2MY5p6xzqtJ/wQ7LZynSvGaY=
 github.com/swaggo/files v0.0.0-20220728132757-551d4a08d97a/go.mod h1:lKJPbtWzJ9JhsTN1k1gZgleJWY/cqq0psdoMmaThG3w=
@@ -164,22 +148,21 @@ github.com/vishvananda/netlink v1.3.1/go.mod h1:ARtKouGSTGchR8aMwmkzC0qiNPrrWO5J
 github.com/vishvananda/netns v0.0.5 h1:DfiHV+j8bA32MFM7bfEunvT8IAqQ/NzSJHtcmW5zdEY=
 github.com/vishvananda/netns v0.0.5/go.mod h1:SpkAiCQRtJ6TvvxPnOSyH3BMl6unz3xZlaprSwhNNJM=
 github.com/yuin/goldmark v1.4.0/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
-go.mozilla.org/pkcs7 v0.0.0-20210826202110-33d05740a352 h1:CCriYyAfq1Br1aIYettdHZTy8mBTIPo7We18TuO/bak=
-go.mozilla.org/pkcs7 v0.0.0-20210826202110-33d05740a352/go.mod h1:SNgMg+EgDFwmvSmLRTNKC5fegJjB7v23qTQ0XLGUNHk=
-go.uber.org/mock v0.3.0 h1:3mUxI1No2/60yUYax92Pt8eNOEecx2D3lcXZh2NEZJo=
-go.uber.org/mock v0.3.0/go.mod h1:a6FSlNadKUHUa9IP5Vyt1zh4fC7uAwxMutEAscFbkZc=
+go.mozilla.org/pkcs7 v0.9.0 h1:yM4/HS9dYv7ri2biPtxt8ikvB37a980dg69/pKmS+eI=
+go.mozilla.org/pkcs7 v0.9.0/go.mod h1:SNgMg+EgDFwmvSmLRTNKC5fegJjB7v23qTQ0XLGUNHk=
+go.uber.org/mock v0.5.2 h1:LbtPTcP8A5k9WPXj54PPPbjcI4Y6lhyOZXn+VS7wNko=
+go.uber.org/mock v0.5.2/go.mod h1:wLlUxC2vVTPTaE3UD51E0BGOAElKrILxhVSDYQLld5o=
 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
 golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
 golang.org/x/crypto v0.0.0-20210711020723-a769d52b0f97/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
-golang.org/x/crypto v0.0.0-20220331220935-ae2d96664a29/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
-golang.org/x/crypto v0.24.0 h1:mnl8DM0o513X8fdIkmyFE/5hTYxbwYOjDS/+rK6qpRI=
-golang.org/x/crypto v0.24.0/go.mod h1:Z1PMYSOR5nyMcyAVAIQSKCDwalqy85Aqn1x3Ws4L5DM=
+golang.org/x/crypto v0.52.0 h1:RMs7fP2rXdep0CftQlK8Uf+kibLm7qkCcradZWYz988=
+golang.org/x/crypto v0.52.0/go.mod h1:1QgfPxDqh0T2M/elOJtp9RvuR95kVjir0e6/BvEmGbc=
 golang.org/x/exp v0.0.0-20230725093048-515e97ebf090 h1:Di6/M8l0O2lCLc6VVRWhgCiApHV8MnQurBnFSHsQtNY=
 golang.org/x/exp v0.0.0-20230725093048-515e97ebf090/go.mod h1:FXUEEKJgO7OQYeo8N01OfiKP8RXMtf6e8aTskBGqWdc=
 golang.org/x/mod v0.1.1-0.20191105210325-c90efee705ee/go.mod h1:QqPTAvyqsEbceGzBzNggFXnrqF1CaUcvgkdR5Ot7KZg=
 golang.org/x/mod v0.4.2/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
-golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
-golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
+golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
 golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
 golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
@@ -188,18 +171,16 @@ golang.org/x/net v0.0.0-20200114155413-6afb5195e5aa/go.mod h1:z5CRVTTTmAJ677TzLL
 golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
 golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
 golang.org/x/net v0.0.0-20210805182204-aaa1db679c0d/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
 golang.org/x/net v0.0.0-20220425223048-2871e0cb64e4/go.mod h1:CfG3xpIq0wQ8r1q4Su4UZFWDARRcnwPjda9FqA0JpMk=
-golang.org/x/net v0.26.0 h1:soB7SVo0PWrY4vPW/+ay0jKDNScG2X9wFeYlXIvJsOQ=
-golang.org/x/net v0.26.0/go.mod h1:5YKkiSynbBIh3p6iOc/vibscux0x38BZDkn8sCUPxHE=
+golang.org/x/net v0.55.0 h1:bcvxaJn3e1U6InsFWt1JUq1aSjnRxLzT2rtD2KfkDF8=
+golang.org/x/net v0.55.0/go.mod h1:L5U2KuzuOe1lY7Z+aWVIKK6qEeJXnXV9yzGA+WCHJww=
 golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
 golang.org/x/sync v0.0.0-20210220032951-036812b2e83c/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
-golang.org/x/sync v0.7.0 h1:YsImfSBoP9QPYL0xyKJPq0gcaJdG3rInoqxTWbfQu9M=
-golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
 golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20190924154521-2837fb4f24fe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
-golang.org/x/sys v0.0.0-20191204072324-ce4227a45e2e/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210420072515-93ed5bcd2bfe/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210423082822-04245dca01da/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -211,16 +192,16 @@ golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.2.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.10.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.21.0 h1:rF+pYz3DAGSQAxAu1CbC7catZg4ebC4UIeIhKxBZvws=
-golang.org/x/sys v0.21.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.45.0 h1:dO4czNzziLiiXplLQgBCEpCvXQ3dnkn0SdaZSYdQ+FY=
+golang.org/x/sys v0.45.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
 golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
 golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
 golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
-golang.org/x/text v0.16.0 h1:a94ExnEXNtEwYLGJSIUxnWoxoRz/ZcCsV63ROupILh4=
-golang.org/x/text v0.16.0/go.mod h1:GhwF1Be+LQoKShO3cGOHzqOgRrGaYc9AvblQOmPVHnI=
+golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
+golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
 golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=
 golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
@@ -228,8 +209,8 @@ golang.org/x/tools v0.0.0-20190328211700-ab21143f2384/go.mod h1:LCzVGOaR6xXOjkQ3
 golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
 golang.org/x/tools v0.0.0-20191216052735-49a3e744a425/go.mod h1:TB2adYChydJhpapKDTa4BR/hXlZSLoq2Wpct/0txZ28=
 golang.org/x/tools v0.1.7/go.mod h1:LGqMHiF4EqQNHR1JncWGqT5BVaXmza+X+BDGol+dOxo=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d h1:vU5i/LfpvrRCpgM/VPfJLg5KjxD3E+hfT1SH+d9zLwg=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
+golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
+golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
@@ -258,7 +239,7 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gvisor.dev/gvisor v0.0.0-20240405191320-0878b34101b5 h1:DOUDfNS+CFMM46k18FRF5k/0yz5NhZYMiUQxf4xglIU=
 gvisor.dev/gvisor v0.0.0-20240405191320-0878b34101b5/go.mod h1:NQHVAzMwvZ+Qe3ElSiHmq9RUm1MdNHpUZ52fiEqvn+0=
-howett.net/plist v1.0.0 h1:7CrbWYbPPO/PyNy38b2EB/+gYbjCe2DXBxgtOOZbSQM=
-howett.net/plist v1.0.0/go.mod h1:lqaXoTrLY4hg8tnEzNru53gicrbv7rrk+2xJA/7hw9g=
-software.sslmate.com/src/go-pkcs12 v0.2.0 h1:nlFkj7bTysH6VkC4fGphtjXRbezREPgrHuJG20hBGPE=
-software.sslmate.com/src/go-pkcs12 v0.2.0/go.mod h1:23rNcYsMabIc1otwLpTkCCPwUq6kQsTyowttG/as0kQ=
+howett.net/plist v1.0.1 h1:37GdZ8tP09Q35o9ych3ehygcsL+HqKSwzctveSlarvM=
+howett.net/plist v1.0.1/go.mod h1:lqaXoTrLY4hg8tnEzNru53gicrbv7rrk+2xJA/7hw9g=
+software.sslmate.com/src/go-pkcs12 v0.7.2 h1:Rh9FoMaI5k7Oo6EOS+2/BnoZ+JFIS+XHjM0VGkSPXLM=
+software.sslmate.com/src/go-pkcs12 v0.7.2/go.mod h1:Qiz0EyvDRJjjxGyUQa2cCNZn/wMyzrRJ/qcDXOQazLI=