Blind Routing

How sensitive relationships and lookup predicates are tokenized to prevent the server from mapping who owns what, who shares with whom, and which users belong to which organizations.

Sensitive relationships — document ownership, grant associations, entity memberships — are represented as blind cryptographic tokens rather than plaintext identifiers. The server stores and compares these tokens but cannot reverse them to recover the underlying associations.

Request routing uses opaque resource identifiers (UUIDs) for path parameters — the server assigns these and they carry no sensitive meaning. What the server cannot do is reconstruct relationships from what it stores.

The Problem With Traditional Identifiers

In typical applications, databases use straightforward identifiers — user IDs, document IDs, grant IDs. These make it trivial for anyone with database access to answer questions like:

"Which documents does this user own?"
"Who shared this document with whom?"
"Which organization does this person belong to?"

Even with document content encrypted, these associations are themselves sensitive information. Knowing that User A shared Document B with User C reveals a relationship — without reading the document.

Instead of storing plaintext foreign keys, the system stores blind tokens — one-way cryptographic values derived from the original identifiers using your personal keys. The server can match tokens for equality but cannot reverse them to recover the original identifiers or reconstruct the relationship graph.

Document Tokens

Document ownership and cross-surface references use a document token (doc_token):

Your device computes a one-way token from the document's identity using your personal key.
This token is submitted at document creation alongside the encrypted content.
All subsequent surfaces — grant creation, blind index entries, content authorization — reference the document by its token, not its UUID.
The server can match tokens to find which indexes belong to which document, but cannot map a token back to a document identity without your key.

Ownership Tokens

Document ownership is established through an owner token — a one-way value derived from your identity:

Your device computes an owner token and submits it at document creation.
The server uses this token to verify ownership on subsequent requests.
The server cannot determine which user the token represents.

Grant Tokens

The grant system uses several blind tokens to prevent correlation:

Grantor token — identifies the document owner in grant operations without revealing their identity. The server validates grants against this token instead of joining user tables.
Claim token — derived fresh for each individual grant. Because every sharing relationship produces its own unique claim token, the server cannot link different grants to the same person — even if the same user claims multiple grants.
Document token — used in grant queries so the server does not need a plaintext document identifier. Grant creation and discovery use doc_token for all stored predicates and lookup operations.

Search Tokens

When you search your encrypted documents, blind index tokens scope the query:

Your device generates tokens for searchable fields and submits them.
When you search, your device computes a query token and sends it to the server.
The server compares tokens to find matches — the tokens reveal nothing about the underlying values.
Entity-scoped search uses entity_token to scope the query, so the server never needs a plaintext entity identifier to execute the search.

Membership Tokens

Organization membership records use multiple layers of blind tokens:

Entity token — identifies the organization without revealing its resource ID.
Entity member token — identifies a specific membership within an organization, derived by the secure enclave.
User member token — your personal membership token, derived from your own key material.

Persistent membership storage uses these tokens in place of plaintext foreign keys. The server can perform membership lookups by comparing tokens, but cannot determine which user belongs to which entity by reading the database.

Anti-Oracle Design

Blind routing doesn't just protect what's stored — it also protects what the API reveals. When a request references a blind token, the server deliberately avoids leaking whether that token corresponds to a real resource.

For example, if you submit a token that doesn't match any document you have access to, the server returns a generic 404 Not Found response — both missing resources and permission failures produce the same status code and response shape. This is intentional: if the server returned different responses for invalid tokens versus valid-but-unauthorized ones, an attacker could probe tokens to learn which resources exist.

This pattern applies to sensitive token lookup paths: document lookups, grant operations, and membership queries. It is not uniform across every endpoint — behavior varies by route.

Without blind routing, a database breach would reveal a complete map of relationships:

Who owns which documents
Who shared what with whom
Which users belong to which organizations
The entire sharing history between any two parties

With blind routing, a database breach reveals only:

Encrypted blobs and opaque tokens
No way to associate tokens with real identities
No way to correlate activity across different tokens

The Design Boundary

Blind routing applies primarily to data at rest — what the database stores. API path parameters use opaque resource UUIDs for routing; these are server-assigned identifiers that carry no sensitive meaning. Request and response bodies use blind tokens for all authorization decisions, stored relationships, and lookup predicates.

Blind routing operates at two levels:

At rest: fully zero-knowledge — the database contains only opaque tokens and ciphertext for sensitive relationships. No plaintext foreign keys or user associations are stored.
In transit: authorization decisions and stored relationships are token-based. Path parameters use server-assigned resource UUIDs for routing only.

The key insight is that persistent storage is the threat model. A database breach reveals only encrypted blobs and opaque tokens — no way to reconstruct who owns what, who shared with whom, or which users belong to which organizations.

Token Lifecycle

Blind tokens are tied to your personal keys. If you need to recover your account and regenerate your keys, all of your blind tokens are re-derived and rotated in a single atomic operation. The server swaps the old tokens for new ones without ever learning the mapping between them — preserving the zero-knowledge property even during key recovery.

Think of it like a phone system with encrypted caller ID: The switching network routes your call to the right destination, but the call logs record only scrambled numbers. Anyone reading the logs can see that calls happened, but not who called whom.

Zero-Knowledge Model — the foundation: what the server can and can't see
Key Hierarchy — the keys used to derive blind tokens
Grants & Sharing — how blind tokens enable private document sharing
Encrypted Search — how search works over blind-indexed documents