Signatures & AAD
Ed25519 signatures and AEAD additional authenticated data: entry points, byte formats, reasons and concrete examples.
API signatures
These entries use Ed25519 signatures. The first item of each signed array is its SignaturePurpose value; it separates proofs for different operations and is not a separate wire field.
Encrypted HTTP /graphql and /guest_graphql requests, and WSS /graphql frames, use session AEAD tags without Ed25519 signatures. API-token requests to /graphql use Bearer authentication. The entries below specify which request, response or nested payload carries a signature.
AUTH_SERVER_HELLO · WSS /auth · ServerHello
- Why it is signed
- Bind the device identity, client ID and both handshake messages. The browser checks the signed ServerHello before deriving the passwordless approval-channel key.
- Signing and verification
- Device signs ServerHello; connecting browser/client verifies it with the device identity public key.
- Signed JSON array
- javascript
["AUTH_SERVER_HELLO", deviceId, signaturePublicKey, clientId, clientHello, unsignedServerHello]
PEER_REQUEST · HTTP POST /peer_graphql
- Why it is signed
- Authenticate the sending device in addition to encrypting the request. Bind the original GraphQL request and its channel context so the proof cannot be moved to another channel. Request UUIDv7 freshness is checked separately.
- Signing and verification
- Sending peer signs the request; receiving peer verifies it with the sender’s saved identity public key.
- Signed JSON array
- javascript
["PEER_REQUEST", channelId, requestId, query, sortedVariables]
channelId is the second array value: empty for direct peer requests; otherwise exactly the c-cid channel ID. To compute the signature, sort object keys recursively in variables.
PAIR_REQUEST · POST /nearby · PAIR_REQUEST / BLE / QR
- Why it is signed
- Bind the requesting identity, intended recipient, device details and ECDH public key. The receiver can detect changes before deriving a shared key; QR scanning verifies the displayed invitation with the same purpose.
- Signing and verification
- Requesting device signs; receiving device or QR scanner verifies with the invitation’s signaturePublicKey. User confirmation or trusted identity matching remains necessary.
- Signed JSON array
- javascript
["PAIR_REQUEST", fromId, signaturePublicKey, toId, targetPublicKey, fromName, port, deviceType, ecdhPublicKey, timestamp, ips, awareSupported]
PAIRING_ACCEPT · POST /nearby / BLE · PAIRING_ACCEPT
- Why it is signed
- Bind the accepting device’s ECDH public key and connection details to one requestId. An unrelated or altered acceptance cannot complete the pending pairing.
- Signing and verification
- Accepting device signs; requesting device verifies with the expected peer identity public key.
- Signed JSON array
- javascript
["PAIRING_ACCEPT", requestId, signaturePublicKeyOrNull, fromNameOrNull, port, deviceType, ecdhPublicKey, ips, awareSupported]
PAIRING_REJECT · POST /nearby / BLE · PAIRING_REJECT
- Why it is signed
- Authenticate who rejected the pending request. Only requestId and signature are transmitted; rejection does not establish a shared key.
- Signing and verification
- Rejecting device signs; requesting device verifies with the expected peer identity public key.
- Signed JSON array
- javascript
["PAIRING_REJECT", requestId]
QR_PAIR_ACCEPT · POST /nearby · QR PAIRING_ACCEPT
- Why it is signed
- Bind the scanner identity and acceptance details to the exact scanned invitation. The outer Ed25519 signature authenticates the scanner; HMAC binds the response to request.signature.
- Signing and verification
- Scanning device signs; QR-displaying device verifies with the scanner’s signaturePublicKey in the reply and checks the scanned request binding.
- Signed JSON array
- javascript
["QR_PAIR_ACCEPT", Base64(HMAC-SHA256(UTF8(request.signature), UTF8(JSON.stringify(["qr-pair-accept", scannerId, acceptSignedArrayJSON]))))]
For QR acceptance, acceptSignedArrayJSON is the compact JSON string of the PAIRING_ACCEPT array, with the scanner identity and name. The scanner signs the QR_PAIR_ACCEPT array instead of signing that inner array directly. The HMAC key is the UTF-8 request.signature string, not its Base64-decoded bytes.
PAIR_CANCEL · POST /nearby · PAIR_CANCEL
- Why it is signed
- Authenticate cancellation and bind it to the original requestSignature and both devices, preventing cancellation of a different pairing attempt.
- Signing and verification
- Canceling device signs; receiving device verifies the identity and matches the pending request.
- Signed JSON array
- javascript
["PAIR_CANCEL", fromId, toId, requestSignature, signaturePublicKey, timestamp]
PEER_STATUS · WSS /status · client proof
- Why it is signed
- Authenticate the connecting peer and bind its proof to this connection’s complete encrypted init and ack frames, preventing reuse across connections.
- Signing and verification
- Connecting peer signs the client proof; status server verifies it with the saved peer identity public key.
- Signed JSON array
- javascript
["PEER_STATUS", clientId, Base64(initFrame), Base64(ackFrame)]
CHANNEL_MEMBERSHIP · /peer_graphql · channelSystemMessage payload
- Why it is signed
- Carry a verifiable membership proof inside the system-message payload, in addition to the outer peer request signature. Bind channel, version, action and target; receivers separately enforce owner/member permissions.
- Signing and verification
- The owner or acting member signs, depending on the action; the receiving member verifies the corresponding identity and permissions.
- Signed JSON array
- javascript
["CHANNEL_MEMBERSHIP", channelId, version, action, target]
PEER_TLS_CERTIFICATE · HTTP POST /init · tlsCertificateSignature
- Why it is signed
- Bind the advertised TLS certificate SHA-256 fingerprint to the device identity. A managed peer proxy verifies this proof before trusting that certificate fingerprint.
- Signing and verification
- Device signs tlsCertificateSignature in the /init response; attaching managed proxy verifies with the expected device identity public key.
- Signed JSON array
- javascript
["PEER_TLS_CERTIFICATE", tlsCertificateSha256]
purpose means the value in the entry heading. Serialize the shown array as compact JSON, encode it as UTF-8, then sign with the sender’s Ed25519 identity key; signature is Base64. Keep field order, types and original JSON strings unchanged. A signature identifies the signer; freshness and authorization are checked separately.
AAD reference
AAD is authenticated together with ciphertext, but is not encrypted or appended as a separate frame field. Both sides reconstruct the same bytes; any mismatch fails tag verification. Examples reuse the synthetic authentication and WebSocket frames in these docs.
The double vertical bar in formulas denotes byte concatenation. 0x00 is one zero byte. fields(x₁, …, xₙ) concatenates each uint32be(byteLength(xᵢ)) followed by xᵢ. SHA256 returns 32 raw bytes; hex is display-only. JSON.stringify means compact JSON with the specified field order. Each WebSocket direction starts its own sequence at 1.
WSS /auth · password login
AUTH_REQUEST / AUTH_RESPONSEBind the encrypted client information and approval result to this client and server identity; separate request and response directions.
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestThe OPAQUE Rust/WASM login result returns requestAad and responseAad. Use them directly without constructing the internal context. digest is the 32-byte digest portion, not an extra request field. LOGIN_PASSWORD is fixed inside the login library; callers do not supply a purpose parameter.
Concrete inputs and AAD bytes
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 44 B
415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46AAD · hex · 45 B
415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46WSS /auth · passwordless login
AUTH_REQUEST / AUTH_RESPONSEBind encrypted approval messages to this handshake, including both ephemeral public keys and the signed server response.
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digestThe handshake library maintains AAD internally. Use encryptRequest and decryptResponse without constructing the internal context. digest is the 32-byte digest portion, not an extra request field. LOGIN_NO_PASSWORD is fixed inside the login library; callers do not supply a purpose parameter.
Concrete inputs and AAD bytes
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 44 B
415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafdirection = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafAAD · hex · 45 B
415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0bafWSS /graphql, /screen, /image_editor, /status · init
WS_INITBind registration to the WebSocket path and client identity.
fields(WS_INIT, path, cid)path is the logical path, without scheme, host or query. cid is the original client ID before URL encoding. The example uses /graphql.
Concrete inputs and AAD bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001AAD · hex · 63 B
0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031WSS /graphql, /screen, /image_editor, /status · ack
WS_ACKBind the acknowledgment to the exact encrypted init frame, path and client identity.
fields(WS_ACK, path, cid, SHA256(initFrame))initFrame is the complete binary nonce + ciphertext + tag, not the decoded init JSON. SHA256(initFrame) is included as 32 raw bytes.
Concrete inputs and AAD bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19AAD · hex · 98 B
0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19WSS /graphql, /screen, /image_editor, /status · encrypted frames
WS_FRAMEBind each frame to its connection handshake, sending direction and sequence, preventing reuse in another connection or direction.
binding = SHA256(fields(initFrame, ackFrame))
AAD = fields(WS_FRAME, path, cid, binding, direction, uint64be(sequence))initFrame and ackFrame are complete encrypted binary frames. direction is client or server according to the sender. sequence is encoded as eight big-endian bytes; the example shows 1 in both independent directions, including the empty confirmation frame.
Concrete inputs and AAD bytes
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = client
sequence = 1AAD · hex · 122 B
0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006636c69656e74000000080000000000000001path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = server
sequence = 1AAD · hex · 122 B
0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006736572766572000000080000000000000001HTTP · encrypted requests
HTTP_REQUESTBind encrypted data to its logical HTTP method and endpoint, preventing reuse at another REST endpoint.
HTTP_REQUEST.{method}.{endpoint}POST /graphql, /guest_graphql, /peer_graphql, /init, /upload and /upload_chunk all use HTTP_REQUEST. Multipart uploads bind encrypted info metadata. Proxy/BLE/Aware forwarding uses the logical destination path, not the proxy URL.
Encrypted responses verify the tag with empty AAD. Their plaintext is 0x00 + SHA256(original encrypted request) + response JSON; clients check the request digest after decryption.
Concrete inputs and AAD bytes
method = POST
endpoint = /graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./graphql"AAD · hex · 26 B
485454505f524551554553542e504f53542e2f6772617068716cmethod = POST
endpoint = /guest_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./guest_graphql"AAD · hex · 32 B
485454505f524551554553542e504f53542e2f67756573745f6772617068716cmethod = POST
endpoint = /peer_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./peer_graphql"AAD · hex · 31 B
485454505f524551554553542e504f53542e2f706565725f6772617068716cmethod = POST
endpoint = /init
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./init"AAD · hex · 23 B
485454505f524551554553542e504f53542e2f696e6974method = POST
endpoint = /upload
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload"AAD · hex · 25 B
485454505f524551554553542e504f53542e2f75706c6f6164method = POST
endpoint = /upload_chunk
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload_chunk"AAD · hex · 31 B
485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6bResource URLs · /fs, /zip/* and /proxy/*
FS / ZIP_FILESBind encrypted URL payloads to their purpose, session/share scope and owner.
{purpose}.{mode}.{owner}FS covers file previews, directory downloads, proxy resources and attachment references; ZIP_FILES covers archive selections. mode is c for a session or s for a share; owner is the session client ID or share ID.
Concrete inputs and AAD bytes
purpose = FS
mode = c
owner = 706c6169-3b80-8f42-9a61-4e312e54d001
AAD (escaped UTF-8) = "FS.c.706c6169-3b80-8f42-9a61-4e312e54d001"AAD · hex · 41 B
46532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031purpose = FS
mode = s
owner = 01a1cd7b-b900-7331-9331-313131313134
AAD (escaped UTF-8) = "FS.s.01a1cd7b-b900-7331-9331-313131313134"AAD · hex · 41 B
46532e732e30316131636437622d623930302d373333312d393333312d333133313331333133313334purpose = ZIP_FILES
mode = c
owner = 706c6169-3b80-8f42-9a61-4e312e54d001
AAD (escaped UTF-8) = "ZIP_FILES.c.706c6169-3b80-8f42-9a61-4e312e54d001"AAD · hex · 48 B
5a49505f46494c45532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031