Skip to content

Security: Wtrwx/vesper

Security

docs/SECURITY.md

Security, permissions and recovery

Trust boundaries

The operator controls the host workspace, configuration, SSH account, iPhone, Theos installation and optional IDA license. MCP clients are constrained to declared semantic tools. This is a local stdio service, with no public HTTP listener. No raw shell, unrestricted RPC, arbitrary JavaScript loader, password authentication, host-key auto-accept, or service-installation tool is exposed. An agent with separate unrestricted access to the operator's filesystem could edit approval state directly; the local CLI is a boundary for MCP clients, not a sandbox for arbitrary programs running as the operator.

Device IDs, app bundle IDs and system process name/executable pairs are explicitly allowlisted. App discovery/enumeration filters to allowed apps. System process discovery returns configured names and marks exact path matches; mismatched or missing paths cannot be attached. Every system attach rediscovers the current PID and requires one exact executable match. Frida attachments validate the observed PID plus the injected bundle identity for apps or Process.mainModule.path for system processes. No RPC/event access is permitted before host identity validation. Subsequent RPCs/events recheck the corresponding allowlist, including the exact system executable path. Detach remains available for cleanup after revocation. Paths are compared as reported by Frida; SSH /rootfs mappings are never stripped or treated as equivalent executable identities.

System sessions support bounded modules/symbols, selected metadata/memory reads, native traces, logs and cleanup, all outside the UIKit main queue. Native writes, calls, Swift/Objective-C/UI operations, spawn and restart are outside this interface. runtime_native and app_logs accept exactly one app bundle_id or existing session_id; stale session IDs never trigger an automatic attach. SSH uses key authentication and the configured known_hosts file with agent/password/keyboard-interactive auth disabled. Shell arguments are quoted from validated semantic inputs; rootless tool paths are added explicitly to PATH.

Approval lifecycle

An operation without a grant returns APPROVAL_REQUIRED with its full scope and approval ID. The operator separately runs vesper-approve, reviews the scope, and types approve. Only the local CLI grants requests. A grant is valid for ten minutes, exact-argument bound, single-use and consumed atomically in SQLite. Changing the session, artifact bytes, device or restart option requires a new request. Nothing is granted by a timeout or an unanswered prompt.

device_upload, app launch/termination, package installation, manual rollback and uninstall require approval. Read-only device calls, local project editing and compilation do not. Frida attach loads an inspection agent; hooks observe calls without replacing implementation results. Theos build runs trusted local Makefiles as the operator, so review externally modified project files.

The workflow requests deployment approval after building the package, then installs it directly. It creates no backup or rollback artifact and does not automatically uninstall or restore packages after a failed device action. Independent uninstall/rollback tools are explicit operations, not default steps.

Files, packages and recovery

Local file inputs are resolved within workspace/state roots. Device downloads can create only new files in state_dir/downloads; they cannot overwrite the approval DB, configuration, source or existing files. Remote transfers stay within configured roots, recheck canonical paths, reject staging symlinks and foreign owners, use a private staging directory and exclusive random temporary files, and bound transfer sizes. Approved generic uploads check the actual stream hash before renaming. Deployment verifies the remote package hash too.

Packages must contain exactly the expected dylib and its one-application filter plist. Maintainer scripts, global filters, symlinks, traversal and extra payloads are rejected. Package name/version/architecture and source fingerprints are checked. The approved transfer is checked internally before installation. An existing package can be replaced without a recoverable backup. A successful install command is followed directly by app restart and the requested device action; no installed-file hash, loaded-marker or crash sweep runs by default. Manual removal remains scoped to the selected deployment.

Cancellation waits for an active package installation to settle and leaves its result in place. It does not race dpkg with an automatic rollback or uninstall.

On a host/process crash, automatic actions cannot establish the device's final state. On restart, live sessions are invalidated and unfinished deployments are marked interrupted. server_status.recovery_required identifies those records. Check package status and device state first. Manual tweak_rollback or tweak_uninstall obtains a fresh approval and proceeds only if the installed version and dylib still match the interrupted record. A partially broken dpkg database or changed artifact requires explicit operator maintenance outside MCP; there is no generic privileged repair shell. Inspect only the affected operation when maintenance is needed; no backup is created.

Data and execution limits

UI text is opt-in, secure text fields redact their value, metadata queries do not read object contents, and trace arguments are bounded scalars/addresses. Screenshot requests can contain visible app data and must be deliberate. The workflow explicitly captures its selected button/title and bounded nearby hierarchy as evidence. Do not select unrelated private UI.

Secret-key fields, bearer values, common credential patterns and private-key blocks are redacted in results/events/audits. This is best-effort filtering, not a guarantee that all sensitive free text or image pixels can be recognized. objc_query_instances and explicit objc_inspect_object(include_values=true) read bounded ivars. Sensitive ivar/dictionary names are checked before reading their values; unknown objects return leased references. Only known Foundation string/number/collection accessors are used for bounded value serialization; arbitrary getters/descriptions and raw pointer dereferencing are not exposed. Native/Swift layouts and concurrent object mutation can still make reads unavailable or inconsistent; this is best-effort runtime inspection.

Audits store tool outcome and scoped approval metadata, not raw tool arguments. State files are private to the local operator. Delete/export them deliberately under the operator's data-retention policy.

Tools have execution deadlines. Process output, file sizes, object IDs, hooks, sessions, worker slots, jobs, events and UI traversals have caps. Event cursors include loss counts. Native object references are retained for identifier safety, reference-counted across expiring snapshot/operation leases, and released after their final lease ends or on detach. Active batched operations hold their input references across waits; RPCs, hooks and workflows protect sessions from idle reclamation. Retaining can delay app object deallocation. An abrupt host death may prevent release until the target process exits. Main-thread inspections and heap scans can briefly pause the app. These tools are debugging instrumentation and should be used on an isolated test device.

Crash logs are read only for a relevant failure, not as a routine post-install check. Queries inspect app-matching filenames and timestamps in the configured crash roots. Delayed report creation and inaccessible roots can limit results.

Static/runtime mapping requires matching Mach-O UUID and architecture, an observed module boundary, canonicalized IMP and compatible segment range. A database is correlated only when its input hash matches the accompanying binary. Address correlation is evidence of image identity and location, not proof of source-level behavior, especially for stripped or optimized code.

There aren't any published security advisories