Mesh Security

Mesh Security

Overview

Rokks runs as a mesh of backend services that talk to one another over a private internal network. Every one of those internal calls is authenticated: a service proves which service it is with a mutually verified TLS certificate, not a shared password. This page explains the guarantees that gives you as an integrator or operator, and how the platform sets it up on its own.

How it works

Each backend service holds its own certificate that names it. When one service calls another, both ends present certificates and each verifies the other’s name before any application data is exchanged — a mutual check, so neither side trusts an unverified peer. The name a service can present is fixed when its certificate is issued, so a service cannot claim to be a different one. If verification fails — because a call was misrouted, or because the caller holds no platform-issued certificate — the connection is refused at the handshake and the call never reaches application code. Browser and app traffic is handled separately at the public boundary by user sign-in; the certificate identity here governs only the internal service-to-service calls behind that boundary.

Identity is not blanket authorization

A valid service certificate answers “which service opened this connection?” It does not grant that service every operation exposed by the destination. Sensitive operations use a second, destination-side policy that names the services or user roles allowed to perform that operation.

Some services deliberately transport a user request without becoming the principal. The application edge and AI tooling forward the original user credential, and the destination verifies that credential again before authorizing the operation. This prevents an intermediary certificate from collapsing a scoped user into an all-powerful internal service identity.

Layer	Question it answers
Mutual TLS	Which platform service is connected?
User session verification	Which signed-in person initiated delegated work?
Operation policy	May this service or user invoke this operation?
Environment and tenant scope	Which isolated workspace may the operation address?
Data/resource policy	Which governed objects may the principal use?

What it guarantees

• Verified identity on every internal call. Each service holds a certificate that names it. Peers verify that name cryptographically before trusting the call, so one service cannot impersonate another.
• Least privilege at the destination. The receiving service evaluates the requested operation after transport authentication; mesh membership alone is not an administrator capability.
• Misrouted traffic fails safe. If an internal call ever lands on the wrong service — a recycled network address, a name-resolution race — it fails at the security handshake instead of being silently answered by the wrong component.
• A rogue container cannot join. A process that does not hold a platform-issued certificate is rejected at the handshake. Membership in the mesh is a credential, not merely being on the network.
• The public boundary is separate. Browser and app traffic enters through a single public edge and is authenticated by user sign-in (see Authentication). The certificate-based identity described here is for service-to-service calls behind that boundary — you never manage it as an end user.

Zero-touch provisioning

The trust material is self-provisioning — there is nothing for an operator to generate, upload, or rotate by hand:

1. At deploy time, a dedicated one-shot initialization step creates a single internal certificate authority for that installation and issues each service its own certificate, named for that service.
2. Each certificate is delivered privately to the service it belongs to, over a channel the platform controls, before that service makes its first network call. A service can only read its own credential; it can neither read nor request another service’s.
3. Every other service waits for that step to finish before it starts, so the mesh never comes up in a half-provisioned state.

Because each installation generates its own authority, separate environments (for example a staging installation and a production installation) are cryptographically isolated from one another automatically, with no shared configuration.

This design is deliberately portable to restricted environments: it needs only the platform’s own private storage, not privileged access to the host machine. That is what lets it run unchanged on a customer-managed install.

Certificate lifetime and revocation

Service certificates are long-lived for the life of the deployment, which keeps normal operation free of certificate churn. To revoke trust — for example if a component is believed compromised — the operator rotates the installation’s authority and redeploys; every service is re-issued a fresh certificate in one coordinated step, and the previous certificates no longer verify.

Observing mesh health

The platform continuously checks that every service is completing the secure handshake with its peers and reports the result in System Monitor → Live Health, on the Mesh mTLS card:

Card state	Meaning
Verified	Every mesh service is handshaking with no security faults.
Handshake failing	One or more services failed the security handshake; the affected services are listed.
Peers unreachable	Some services are unreachable, with no security fault detected.
Awaiting first probe	The first health cycle has not completed yet.

For operators rolling out or tightening mesh security, the Verified state on this card is the go/no-go signal that the mesh is healthy end to end.

What you need to do

For most integrators: nothing. Mesh identity is internal and self-managed. Your integration authenticates at the public boundary with user or client sign-in, and the platform handles service-to-service trust on its own. If you operate a self-managed installation, the only lever you ever touch is the coordinated authority rotation described above, and the only thing you watch is the Mesh mTLS card.