QSCS Trust Layer

Keypair-anchored identity over an end-to-end encrypted transport.

Trust in QSCS does not rely on secrets that can be copied, cookies that can be stolen, or bearer tokens that can be replayed. Every client and every node holds a cryptographic keypair. Every authenticated request is signed. Every byte on the wire, including the identifiers themselves, travels inside an encrypted channel.

This page describes how that actually works, in the same terms as the running code.

1. Identities Are Keypairs, Not Secrets

When a browser first loads the QSCS substrate, it generates two things locally, inside the WebAssembly module:

A random UUIDv4, a stable identifier for that client.
An Ed25519 keypair. The private key is held as a non-extractable key and never leaves the client. The public key is shared.

The UUID is an identifier, not a credential. It is sent to the daemon in plain form in the X-QSCS-Client-Uuid header, the daemon reads it, and the daemon stores it. There is no hashing step, and nothing about the UUID needs to be secret. Security does not come from hiding the UUID. It comes from the fact that only the genuine client holds the matching Ed25519 private key, and every meaningful request must be signed with it.

So the correct mental model is simple: your identity is a public key. Proving your identity means signing with the private half that only you hold.

2. Why Identifiers Are Not Readable on the Wire

The UUID is not a secret, but that does not mean an eavesdropper can read it. They cannot, because QSCS carries all traffic inside an encrypted channel. There are two legs, and both are encrypted end to end.

Browser to edge

The connection between the browser and the QSCS edge is standard TLS (HTTPS), terminated at the reverse proxy in front of the daemon. The UUID, the public key, credentials at login, and every signed request arrive already encrypted.

Node to node

Traffic between QSCS nodes does not use TLS. It uses a purpose-built encrypted transport on port 4443:

An ephemeral X25519 key exchange (ECDH) on connect, so each session derives fresh keys.
A session key derived with HKDF-SHA256 over the shared secret and both public keys.
Every frame encrypted and authenticated with AES-256-GCM, with a per-direction nonce counter that is never reused, and associated data that binds the protocol version and direction into each frame.

The practical result: a network observer sees only ciphertext and framing. The UUID, the identity bindings, and the state deltas are never visible. And even in the impossible case that an identifier leaked, it is useless on its own, because it is not a credential. Without the Ed25519 private key, it signs nothing.

3. Authentication Is Proof of Key Possession

QSCS never checks a shared secret on the wire. It checks a signature. Every authenticated request carries four headers:

X-QSCS-Client-Uuid, the client identifier.
X-QSCS-Ts, a millisecond timestamp.
X-QSCS-Nonce, sixteen random bytes.
X-QSCS-Sig, an Ed25519 signature.

The signature covers a canonical message built from the request itself:

METHOD \n HOST \n URI \n BODY \n TIMESTAMP \n NONCE

Because the body and target are inside the signed message, a valid signature proves the request was produced by the holder of the private key and was not altered in transit.

Login

A login is a POST /auth/login carrying the username, password, client UUID, and public key, and it is signed like any other request. The daemon does three things, in order:

Verifies the signature against the supplied public key. This proves the caller actually holds the private key.
Verifies the credentials by asking the control plane to authenticate the username and password. The daemon never stores or judges the password itself.
Binds the identity, writing a record of (uuid, origin) to the username and public key into its local identity store, then replicating that binding to the cluster.

From that point on, every request for a protected resource is verified against the stored public key for that (uuid, origin). There is no session cookie and no bearer token. There is nothing to steal and replay, because possession of the private key is required on every request.

4. Replay and Freshness

A signature alone would let an attacker capture a valid request and send it again. QSCS closes that with two bindings on every signed request:

A timestamp that must fall within sixty seconds of the daemon's clock. Anything older or further in the future is rejected.
A nonce that must be unique. Each client has a ring of its most recent nonces, and a repeat is refused.

A captured request is therefore only valid for a very short window, and only once. Logging out clears the client's nonce history and its binding, so a reconnect must authenticate again.

5. Node and Cluster Trust

Client identity is only half of the model. Nodes must also trust each other and the control plane.

License-anchored node identity

Each node has its own stable node UUID and a license. At startup the daemon validates its license, node UUID plus license token, with the control plane. If validation fails, if the license is expired, or if the node has been revoked, the daemon refuses to start. A copied node UUID is worthless without the matching license token, and the control plane can revoke a node centrally.

Encrypted, gated peer connections

Node-to-node connections are protected in layers:

An address-level identity gate rejects connections from peers that are not recognised, before any handshake work is done.
Recognised peers complete the X25519 key exchange described earlier, so all peer traffic is encrypted with AES-256-GCM.
Over that encrypted channel, a domain membership handshake confirms both nodes belong to the same cluster before any state is exchanged.

Consistent, scoped replication

Identity bindings and logouts are replicated across the cluster as deltas scoped to (uuid, origin). Authenticating on one node makes you known cluster-wide, and logging out revokes that binding everywhere. Because bindings carry the origin they belong to, an identity for one origin can never be used to speak for another.

6. The Per-Origin Identity Gate

An origin can be marked as identity-protected in the node configuration. For those origins the daemon enforces a gate on every request:

Public pages and static assets are served normally, so the login screen and the substrate can load.
The /auth/ routes are exempt, because they carry their own signature verification.
Genuinely public pre-auth actions such as register, verify email, and forgot password are allowed through.
Everything else requires an authenticated identity and a valid signature on that specific request. A missing identity or a bad signature is answered with 401.

This means a protected endpoint cannot be reached by simply replaying a page load or guessing a URL. The request must be signed, fresh, and bound to an identity the daemon already trusts for that origin.

7. What This Means for an Attacker

The trust model is easier to judge by what it denies:

Identity in QSCS is a public key you prove ownership of, carried over a channel nobody else can read, checked fresh on every request, and anchored to a control plane that can revoke trust at any time. That is the whole model, and it is exactly what the code does.