API Reference

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_RESPONSE

Bind the encrypted client information and approval result to this client and server identity; separate request and response directions.

text
digest = SHA256(fields(LOGIN_PASSWORD, cid, signaturePublicKeyRaw32))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest

The 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

text
direction = request
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 44 B

415554485f52455155455354ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
text
direction = response
digest (hex) = ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46

AAD · hex · 45 B

415554485f524553504f4e5345ceb939c0aea0cd455e9ae012637db919b59c2ac1f1b8147bdc10c4da99bcbc46
WSS /auth · passwordless login
AUTH_REQUEST / AUTH_RESPONSE

Bind encrypted approval messages to this handshake, including both ephemeral public keys and the signed server response.

text
digest = SHA256(compactJSON(["LOGIN_NO_PASSWORD", cid, deviceId, clientHello, serverHello]))
requestAAD = AUTH_REQUEST || digest
responseAAD = AUTH_RESPONSE || digest

The 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

text
direction = request
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf

AAD · hex · 44 B

415554485f5245515545535415a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf
text
direction = response
digest (hex) = 15a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf

AAD · hex · 45 B

415554485f524553504f4e534515a4d5fb0d91e2542b7781792ccba9e4852c595c733f16760de7a629d3eb0baf
WSS /graphql, /screen, /image_editor, /status · init
WS_INIT

Bind registration to the WebSocket path and client identity.

text
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

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001

AAD · hex · 63 B

0000000757535f494e4954000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d346533313265353464303031
WSS /graphql, /screen, /image_editor, /status · ack
WS_ACK

Bind the acknowledgment to the exact encrypted init frame, path and client identity.

text
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

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
SHA256(initFrame) (hex) = d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19

AAD · hex · 98 B

0000000657535f41434b000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020d2993a61129be20fec64fe9bdfb615eb5f1a55e8895c1485768308de45141f19
WSS /graphql, /screen, /image_editor, /status · encrypted frames
WS_FRAME

Bind each frame to its connection handshake, sending direction and sequence, preventing reuse in another connection or direction.

text
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

text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = client
sequence = 1

AAD · hex · 122 B

0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006636c69656e74000000080000000000000001
text
path = /graphql
cid = 706c6169-3b80-8f42-9a61-4e312e54d001
binding (hex) = e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f6
direction = server
sequence = 1

AAD · hex · 122 B

0000000857535f4652414d45000000082f6772617068716c0000002437303663363136392d336238302d386634322d396136312d34653331326535346430303100000020e2cbfb5e4931d0d1d0e443dc8712c252233e67375f1f5a369fdd6a8f0d6264f600000006736572766572000000080000000000000001
HTTP · encrypted requests
HTTP_REQUEST

Bind encrypted data to its logical HTTP method and endpoint, preventing reuse at another REST endpoint.

text
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

text
method = POST
endpoint = /graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./graphql"

AAD · hex · 26 B

485454505f524551554553542e504f53542e2f6772617068716c
text
method = POST
endpoint = /guest_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./guest_graphql"

AAD · hex · 32 B

485454505f524551554553542e504f53542e2f67756573745f6772617068716c
text
method = POST
endpoint = /peer_graphql
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./peer_graphql"

AAD · hex · 31 B

485454505f524551554553542e504f53542e2f706565725f6772617068716c
text
method = POST
endpoint = /init
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./init"

AAD · hex · 23 B

485454505f524551554553542e504f53542e2f696e6974
text
method = POST
endpoint = /upload
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload"

AAD · hex · 25 B

485454505f524551554553542e504f53542e2f75706c6f6164
text
method = POST
endpoint = /upload_chunk
AAD (escaped UTF-8) = "HTTP_REQUEST.POST./upload_chunk"

AAD · hex · 31 B

485454505f524551554553542e504f53542e2f75706c6f61645f6368756e6b
Resource URLs · /fs, /zip/* and /proxy/*
FS / ZIP_FILES

Bind encrypted URL payloads to their purpose, session/share scope and owner.

text
{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

text
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

46532e632e37303663363136392d336238302d386634322d396136312d346533313265353464303031
text
purpose = FS
mode = s
owner = 01a1cd7b-b900-7331-9331-313131313134
AAD (escaped UTF-8) = "FS.s.01a1cd7b-b900-7331-9331-313131313134"

AAD · hex · 41 B

46532e732e30316131636437622d623930302d373333312d393333312d333133313331333133313334
text
purpose = 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