Repository navigation
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.
| 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.
| 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.
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 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.
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.
Baseline: source 76c63f9 · 2026-11-16 · Wiki home · Source repository. The wiki is a separate Git repository and is not synchronized with product sources automatically.