Skip to content

Security and Storage

develicit edited this page Nov 16, 2026 · 2 revisions

Security and Storage

ClipSync encrypts content on the sending client and decrypts it on the receiving client. During normal protocol operation, the relay does not receive plaintext, filenames, or room encryption keys. It can see routing metadata and connection/delivery timing.

Trust boundaries

Boundary Protection and assumptions
Client to relay HTTPS/WSS verifies the server identity and protects transport. Content is separately encrypted end to end.
Pairing participants Share the code through a separate authenticated channel. SPAKE2 and transcript confirmation validate key establishment.
Local user environment Unlocked devices, same-user processes, administrators, and OS services are part of the trusted environment.
Received files to filesystem Validate sizes, manifests, hashes, and chunk structure, and constrain filenames.
Relay to webhook Validate the external URL and DNS results, then connect only to validated addresses.

The relay generates the pairing code. The current model therefore covers an operator who follows the protocol while trying to inspect content; it does not assume protection against an actively malicious relay that knows the code and impersonates a participant. Choose a trusted relay and protect the endpoints themselves.

Keys and credentials

Type Purpose Lifetime and operational behavior
X25519 device key Device identity, Noise static key, epoch wrapping Long-term local secret
Pairing confirmation/wrapping keys Transcript confirmation and device-binding protection Secrets derived during pairing
Room root key First epoch key derivation Never sent to the relay
Room epoch key Basis for per-transfer content encryption keys Current clients keep the initial key until re-pairing
Per-transfer content key AES-GCM for text, manifests, and chunks Derived with HKDF from the epoch key and transfer ID
Device token Authorization to access a relay room Stored separately in a local secret file
Relay token signing key HMAC validation of server-issued tokens Supplied by the operator through the environment or a secret file; generated with OS randomness if unset

Revoking a relay token and rotating a room content key are separate operations. Current clients do not automatically rotate room keys on membership changes. Re-pair when a new room key is required. Compromise of a long-lived epoch secret can expose recorded content derived from that key; full forward secrecy for stored payloads is not provided.

Local file layout

Setting CLIPSYNC_HOME creates the layout below. Without it, the application uses OS-specific defaults; CLIPSYNC_CONFIG_DIR, CLIPSYNC_DATA_DIR, and other settings can override individual paths.

CLIPSYNC_HOME/
├── config/config.toml    User configuration
├── data/                Room/device metadata and secret files
├── logs/                Diagnostic logs
├── inbox/               Received files
└── run/                 IPC, PID, and other runtime state

Device and room keys are read from private files first and mirrored to macOS Keychain or Windows Credential Manager when available. Linux currently has no enabled Secret Service backend. Device tokens are stored separately as device-token-<hex-room-id>.secret, and webhook credentials as webhook.secret; these two credential types do not use keychain fallback.

New state.json and config.toml serialization omits these token/webhook secrets. Loading legacy inline credentials first saves the private secret file, then atomically replaces the metadata. A missing secret file causes an error rather than silently generating a replacement credential. Migration guarantees individual writes and their ordering, not a transaction across all files.

Unix secret files use 0600, and data/inbox directories use 0700. Windows relies on user-profile ACLs. Backups must protect the complete private data, not only metadata. Re-pair rather than downgrading migrated state to an older binary.

Webhooks

Webhooks carry metadata such as item kind, opaque IDs, encrypted size, timestamp, and status. HMAC-SHA-256 binds the timestamp, event ID, and exact JSON body. Each delivery resolves DNS, rejects responses containing private or special-purpose addresses, and pins the connection to the validated addresses. Redirect and proxy bypasses are blocked by policy.

This path is not documented as a durable job queue or a delivery guarantee. Do not assume retries based on the receiving server's response status.

Security evidence and reporting

The security model and assurance case connect intended properties to validation evidence and remaining limitations. Report vulnerabilities privately under the security policy; do not publish vulnerabilities or secret values in the wiki or public issues.

Implementation: secret storage, paths, relay key configuration, and webhooks.

Clone this wiki locally