How Gumpbox Pairs and Syncs Devices Securely

Gumpbox is becoming more than a Mac app. With iPhone and iPad in the loop, Gumpbox can become a small trusted device mesh: your Mac can keep doing server and automation work, while your iPhone acts as the control plane for pairing, approvals, credential sync, and device removal.

That sounds simple from the UI: scan a code, confirm a prompt, and the devices appear connected. Under the hood, the design has one strict rule: CloudKit can help deliver messages, but it is never the source of trust.

This post explains the pairing and sync mechanism at a high level, and why the security model is intentionally conservative.

The product model: iPhone as the control plane

Gumpbox now treats iPhone as the primary device-control surface.

In practice:

• iPhone starts pairing by scanning or entering a code shown by a passive node.
• Mac and iPad can be passive nodes that show pairing codes and wait for confirmation.
• Only iPhone removes devices from the trusted device list.
• Passive nodes can apply trust changes, but they do not become the authority for device management.

This avoids messy multi-master trust decisions. Instead of every device being equally allowed to add or remove every other device, Gumpbox keeps the user-facing trust control in one place: the iPhone.

That matters because device removal is a security operation. If a Mac is lost, retired, or no longer trusted, the iPhone should be the place where you revoke it.

Pairing flow: scan, request, confirm

The pairing flow is intentionally explicit.

A passive node, such as a Mac, generates a short-lived pairing payload. That payload includes public metadata needed to start pairing:

• the device name
• the device kind
• a stable device identifier
• a public key
• a public key fingerprint
• an expiration time
• a pairing session identifier

The iPhone scans the QR code or enters the manual code. It then sends a pairing request through the private iCloud relay.

The passive node does not silently trust the request. It shows a confirmation prompt. Only after the user confirms does Gumpbox save trust locally and establish an encrypted device channel.

So the flow is:

• Passive node shows a code.
• iPhone scans the code.
• iPhone sends a pairing request through iCloud.
• Passive node asks the user to confirm.
• Both sides store local trust and encrypted channel material.

This makes pairing both convenient and deliberate. A scan alone is not enough; the receiving device still has to confirm the relationship.

CloudKit is a relay, not a database of trust

Gumpbox uses CloudKit private database records as a relay layer. That means iCloud helps devices find messages addressed to them, but it does not define whether a device is trusted.

The important distinction is this:

• CloudKit can say, “there is a message for this device.”
• Local Gumpbox state decides, “this sender is trusted and allowed.”

SwiftData remains local-only for trust state. The app does not use SwiftData CloudKit sync for trusted devices. The model container is configured without CloudKit database sync, and device trust is stored locally on each device.

CloudKit relay records carry delivery metadata and encrypted/advisory events. They do not contain plaintext credentials, private keys, command logs, MCP session tokens, or credential payloads.

This keeps the trust boundary on-device.

End-to-end encrypted device channels

After pairing, devices communicate through encrypted channel messages.

Each device has a local Curve25519 identity key. During pairing, devices exchange public keys and derive per-device channel keys. Message payloads are sealed with authenticated encryption before they are sent through the relay.

The relay sees metadata needed to route messages, but sensitive payloads are encrypted before CloudKit receives them.

This is used for things like:

• approval requests
• approval responses
• credential sync offers
• credential sync payloads
• credential sync acknowledgements
• heartbeats

Before processing a message, Gumpbox validates that:

• the message is addressed to the local device
• the message has not expired
• the message has not already been replayed
• the sender is a locally trusted device
• the sender has not been revoked
• the encrypted payload can be opened with the expected channel key

If any of those checks fail, the message is ignored or marked failed.

Readiness before pairing

Pairing depends on private iCloud relay availability, so Gumpbox checks readiness before allowing the user to start.

The app verifies that it can:

• access the expected CloudKit container
• read and write private relay records
• create or access the relay zone
• install CloudKit subscriptions for updates

The UI distinguishes between checking, ready, limited, and unavailable states. The goal is to avoid a confusing pairing experience where a user scans a code but nothing can be delivered.

When iCloud is ready, pairing can proceed. When it is not, Gumpbox explains what needs attention, such as signing into iCloud, checking connectivity, or using a properly signed build with the right entitlement.

Hot sync windows instead of constant polling

Device sync should feel fast, but it should not require aggressive background polling forever.

Gumpbox uses short “hot sync windows” around important events:

• active pairing
• approvals
• credential sync
• device-list refresh
• device revocation

During a hot sync window, the app fetches pending relay work more frequently. Outside those windows, it relies on lifecycle events, CloudKit pushes, foreground refreshes, and normal heartbeat behavior.

This gives the app responsive pairing and removal behavior without turning CloudKit into a noisy always-on polling loop.

Device removal and revocation

Device removal is monotonic: once a device is revoked, stale messages should not bring it back.

When iPhone removes a paired device, Gumpbox publishes a revocation event through the CloudKit relay. That event includes:

• the revoked device ID
• the revoking device ID
• an event ID
• an event kind
• schema version information
• a target audience of relevant trusted devices
• consumed-by-device tracking

Every device that sees the event applies it idempotently. If the revoked device exists locally, Gumpbox marks it revoked, clears connection timestamps, revokes its channel, deletes its channel key, and writes a local tombstone.

The tombstone is important. It prevents stale pairing responses, old user-device records, heartbeats, or delayed relay messages from resurrecting a device that was intentionally removed.

A revoked device cannot keep sending approvals or credential sync messages that restore trust. Fresh trust requires a fresh pairing flow.

Why iPhone-only removal is safer

Multi-device sync systems can become complicated when every device is allowed to make trust decisions.

For Gumpbox, the safer model is:

• iPhone controls pairing and removal.
• Passive nodes confirm incoming pairing.
• Passive nodes apply revocations.
• Revoked devices cannot silently rejoin.

This keeps the authority model understandable. If you want to remove a Mac, you remove it from iPhone. The Mac receives that removal, revokes the iPhone/control-plane relationship locally, and stops accepting trusted device traffic from that relationship.

Other devices can also observe and apply the revocation if they know the removed device. The system is designed to converge without letting stale records undo a removal.

Versioned, idempotent relay events

The relay format is designed to evolve.

Every security-sensitive sync event includes versioning fields such as schema version and minimum supported schema version. Handlers are written to be idempotent: applying the same event twice should not produce duplicate state or accidental re-trust.

That gives Gumpbox room to add more device-state events later without rewriting the entire relay mechanism.

The rules are simple:

• Additive optional fields can evolve safely.
• Breaking semantic changes require a schema version bump.
• Older clients should ignore events they cannot safely understand.
• CloudKit delivery metadata is never treated as authorization.
• Local trust and local cryptographic validation remain authoritative.

What is not stored in CloudKit

Just as important as what Gumpbox syncs is what it refuses to sync in plaintext.

Gumpbox does not put these in CloudKit relay records:

• plaintext SSH credentials
• private keys
• command logs
• MCP session tokens
• plaintext credential payloads
• local SwiftData trust databases

Credential sync, when used, travels as encrypted device-channel payloads. CloudKit is only the transport.

The security posture

The design is built around layered checks rather than a single point of trust.

The layers are:

• User confirmation before passive nodes accept pairing.
• iPhone-only control for device addition and removal.
• Local-only trust storage using SwiftData without CloudKit database sync.
• Per-device cryptographic channels derived during pairing.
• Encrypted relay payloads before data enters CloudKit.
• Replay and expiration checks on incoming device messages.
• Monotonic revocation tombstones to prevent stale resurrection.
• Schema-gated sync events for forward-compatible safety.

This makes the system practical without making CloudKit a trusted authority. If a relay message arrives late, arrives twice, or arrives after a device was revoked, local validation still decides what happens.

Why this matters for AI-assisted server management

Gumpbox is increasingly about controlled automation: server management, workflows, approvals, credential movement, and MCP-powered AI assistance.

That makes device trust critical. If an iPhone is used to approve actions, and a Mac is used to execute them, the connection between those devices has to be explicit, revocable, and auditable.

Secure pairing and revocation are the foundation for that.

The goal is not just “sync devices.” The goal is to let multiple Apple devices cooperate while keeping authority, secrets, and trust decisions local and understandable.

Conclusion

Gumpbox device sync is designed around a simple principle: use iCloud for delivery, not trust.

The iPhone acts as the control plane. Passive nodes show pairing codes and confirm trust. CloudKit relays encrypted messages. Local cryptographic state decides what is valid. Revocation is monotonic, versioned, and resistant to stale records.

That combination gives Gumpbox a secure path toward multi-device server management: convenient enough to use every day, but strict enough for workflows that involve credentials, approvals, and AI-assisted operations.