Security and authorization

Device identity

Each device derives its off1… address from an Ed25519 identity key. Verification binds the presented key to that address. It does not establish a person’s role or permission to act on equipment. Your application enrolls identities and enforces authorization.

Encrypted application data

The SDK uses MLS for application messaging and group communication. Keep encryption required, handle session failures and preserve cryptographic state. Forward secrecy and recovery depend on the protocol lifecycle and key management described in the threat model.

Control traffic

Service advertisements and discovery are signed plaintext control messages in v0.31.0, and transport observers can read them. From v0.29.0 a service request or response body is sealed inside the 1:1 MLS session with the other device once that device advertises support and the session is confirmed; service_request_received and service_response_received then carry encrypted: true. Toward an older peer, and before the session confirms, the body still leaves as signed plaintext, so the first request to a provider a device has never met is readable by the devices that carry it. Check encrypted before trusting that a body stayed private, and keep secrets out of first-contact requests. encryption.encryptServiceMessages (default true) turns sealing off. Signatures and encryption provide different protections. The HTTP front always carries a call inside an encrypted direct message. It does not authorize callers: any device with a session can call every registered service, and the provider decides on X-Offline-Protocol-Sender.

Local storage

Identity/session secrets and persisted protocol state use separate storage roles. Protect both and keep the application/profile namespace stable. On a host without a platform keystore, v0.31.0 offers built-in file stores sealed under an operator-supplied store key; see Python. A custom storage implementation must honor atomicity and durability requirements. Validate power-loss and restart behaviour before deployment.

Application policy

Authorize senders, validate schemas, bound payloads and retain idempotency records for operations with side effects. Define credential expiry and revocation behaviour during disconnected periods. An offline verifier cannot learn a new central revocation until it receives updated information. The security documentation records trust boundaries and residual risks. Report suspected vulnerabilities privately to security@offlineprotocol.com under the responsible disclosure policy.

Residual risks in v0.31.0

The release threat model records limitations that applications must account for:

Risk	Deployment consequence
R5: MLS-free groups	Plaintext group messages can be unauthenticated. Require MLS for trusted group workflows.
R10: gateway delivery	Gateway delivery is not authenticated proof of destination acceptance. Verify application receipts.
R11: document decoding	A crafted document blob can crash the process. Restrict participating peers and qualify recovery.
R13: telemetry credential	A key embedded in the app can be extracted. Scope, monitor and revoke it.
R14: telemetry roots	From v0.30.0 the uploader trusts only the roots that issue the telemetry endpoint’s certificate. If that endpoint ever moves to a root a shipped SDK does not carry, that SDK’s telemetry stops, with a network error in `telemetryStats().lastError`. Update the SDK.
R16: identity assertions	Assertions can be replayed. Discovery labels are not session authentication; use MLS and signatures.
R7b: clock freshness	Freshness checks depend on the verifier clock. Wrong clocks can reject legitimate control frames.
R17: application ID	The `app_id` on every frame, including a per-send ID, is cleartext and unsigned. Route on it; never authorize on it.
R18: store key	On a host without a keystore, the built-in file stores’ key sits wherever the process reads it. Deliver it as a managed secret.
R19 to R21: custody	A custodian holds third-party ciphertext and routing metadata and can receive deposit spam. Custody is off by default; keep its quotas tight.
R22: Android Wi-Fi Direct group	The group passphrase derives from the app ID, so any device that knows it can join. Streams still prove each peer and payloads stay encrypted.
R23: HTTP front	The front trusts every process that can reach it, and does not authorize. Use a token off loopback and on a host where a browser runs, authorize in the provider, and trust `X-Offline-Protocol-Sender` only when nothing but the front reaches the callback.
R25: undecryptable answers on the relay	The relay learns which of its frames a device could not decrypt. The answer goes only to the claimed sender, over the relay, never on a mesh or peer-stream link.
R24: sessions across the mesh	Any device a mesh path reaches can make this device build a session and send a Welcome, by signing a key package under an address of its own. Forwarding allowances, budgets and caps bound the rate; authorize at the application layer.
R26: browser store key	A browser node’s store key is sealed by a non-extractable key on its origin, so any script that runs on the origin can unseal it or drive the node. Do not host a node whose identity matters on an origin that runs third-party script you do not control.
R27 and R28: WebRTC codes and room codes	A connection code names local addresses and is unauthenticated; a room code admits whoever holds it. The engine’s identity proof and MLS still decide who is on a link, so show the joining address before sharing anything with it.
R29: Bluetooth LE signal strength	With `advertiseNodeHash` on, an Android phone advertises a stable digest of its address that scanners can follow. Signal strength is unauthenticated: never treat `peer_rssi` as evidence of who is near.
R30: nearby rooms	Anyone who can guess a network’s public address can read who is present in its nearby room and offer to connect. Ask the person in `admit` before answering.
R31: Web Bluetooth grants	A device a person picks in the browser’s chooser stays granted to the origin until the person revokes it.

On iOS, Keychain identity state survives uninstall unless explicitly wiped. Include identity and document deletion in the account lifecycle. Profiles are sent to relays as X-Device-ID; do not put personal data or secrets in them.

SDK setup

API by task

Types and events

Architecture

Device identity

Encrypted application data

Control traffic

Local storage

Application policy

Residual risks in v0.31.0

​Device identity

​Encrypted application data

​Control traffic

​Local storage

​Application policy

​Residual risks in v0.31.0

Device identity

Encrypted application data

Control traffic

Local storage

Application policy

Residual risks in v0.31.0