Grants & Sharing

Consent-based, time-limited, zero-knowledge document sharing — how grants work, the full lifecycle, and what the server never learns.

Sharing is consent-based, time-limited, and zero-knowledge. You decide who gets access, for how long, and you can revoke it at any time — all without the server knowing who's sharing with whom or which document is involved.

The grant system manages document sharing. A grant is a secure, encrypted package that gives a recipient everything they need to access a specific document — but only the intended recipient can open it. The server stores grants but cannot read them, identify recipients, or determine which documents are being shared.

1. Create A Grant (Grantor)

When you want to share a document, you create a grant:

Your device wraps the document's encryption key with the recipient's public encryption key, so only they can unwrap it.
The wrapped key and related data are encrypted into a sealed payload.
A small view tag (a single-byte marker) is attached so the recipient can efficiently scan for grants meant for them.
An optional hash-lock commitment can target the grant to a specific recipient, ensuring no one else can claim it.
An expiration time is set — all grants have a mandatory time limit.

The server stores the grant but cannot read the payload, identify the recipient, or determine which document is being shared.

2. Discover A Grant (Grantee)

The recipient discovers grants by sending view tags — lightweight markers that match roughly 1-in-256 grants by design. This noise floor prevents the server from knowing which grant is actually for them.

Recipient sends their view tags to the server
Server returns all matching grants — the genuine grant plus any statistical collisions at the ~1-in-256 rate
Recipient attempts to decrypt each with their private key — only the genuine one opens
All others decrypt to garbage

Analogy: Numbered mailboxes with your initials. The postal service delivers to all boxes labeled with your initials — genuine letter plus decoys. You open each one; only yours contains a real letter. The server sees "these tags were checked," but cannot tell which grant was meant for you.

3. Claim The Grant (Grantee)

Once the recipient finds and decrypts their grant, they claim it:

The recipient provides a per-grant claim token — a unique cryptographic value specific to this grant, derived from the recipient's own secret. This token is different for every grant, so the server cannot link claims from the same person.
For targeted grants, the recipient also proves their identity through a cryptographic signature verified against the hash-lock commitment set by the grantor.
The grant moves to a pending acceptance state.

4. Accept Or Deny (Grantor)

The grantor reviews and approves (or denies) the claim:

Accept — the grant becomes active, and the grantee can now access the document's encryption key and submit their own search tokens.
Deny — the grant is closed, and the claim token is cleared.

These operations use cryptographic authorization tokens rather than user identifiers — the server verifies token matches without knowing who the grantor or grantee actually are.

5. Use The Grant (Grantee)

With an active grant, the recipient can:

Decrypt the document using the key material from the grant.
Submit blind index tokens so the document appears in their personal search results.
Tokens submitted through a grant are scoped to that specific grant's claim token, enabling precise cleanup when access is revoked.

6. Revocation

Access can be revoked in three ways:

Grantor revoke — the document owner revokes the grant at any time. The grant is immediately deactivated and blind index tokens scoped to the claim token are cleaned up on a best-effort basis.
Grantee self-revoke — the recipient can voluntarily give up access. This requires only the claim token, not a login session. Blind index cleanup is fully awaited.
Automatic expiry — when the grant's time limit expires, an automated expiry process revokes it and cleans up blind index tokens scoped to the claim token.

In all cases, revocation marks the grant before any cleanup begins, ensuring access is immediately terminated even if cleanup takes time.

Grant Status Reference

Status	API value	Description
Unclaimed	`unclaimed`	Grant created; no one has claimed it yet
Pending acceptance	`pending_acceptance`	Grantee claimed; waiting for grantor to accept or deny
Active	`active`	Grantor accepted; grantee can decrypt the document
Denied	`denied`	Grantor denied the claim; terminal
Revoked by grantor	`revoked_by_grantor`	Grantor explicitly revoked access; terminal
Revoked by grantee	`revoked_by_grantee`	Grantee self-revoked using their `grant_claim_token`; terminal
Expired	`revoked_by_ttl`	TTL elapsed; automatically revoked by the expiry process; terminal

Claim token design: Each grant carries a grant_claim_token — a unique per-grant cryptographic value derived from the grantee's secret. Because the token is different for every grant, the server cannot link multiple claims from the same person. Grantee self-revoke (revoked_by_grantee) requires only this token — no authenticated session is needed.

Automatic expiry: The expiry process fires at expires_at, deletes consumer blind indexes scoped to the claim token, then marks the grant revoked_by_ttl. The operation is idempotent — if the grant is already in any terminal state, it is a no-op.

What The Server Sees (And Doesn't)

The server sees	The server does NOT see
An encrypted grant payload exists	Who the grant is for
A 1-byte view tag (ambiguous)	Which document is being shared
Opaque claim tokens (one-way)	The relationship between grantor and grantee
Grant status (`unclaimed`, `pending_acceptance`, `active`, `denied`, `revoked_by_grantor`, `revoked_by_grantee`, `revoked_by_ttl`)	The contents of the shared document
Expiration timestamp	Whether two grants involve the same person

Think of it like a secure drop box: You place a sealed envelope in a numbered box. The recipient checks boxes matching their number, finds the one they can open, and claims it. The postal service sees boxes and envelopes but never reads the letters — and it can't tell who's writing to whom.

A common scenario is sharing verified documents between a consumer (a person who owns the document) and an institution (an organization that needs to verify it).

The institution requests access — an institution lets the consumer know (outside the platform) that it needs to verify a document.
The consumer creates a grant — the consumer selects the document and creates a time-limited grant targeted at the institution.
The institution discovers and claims — the institution periodically checks for new grants. When it finds the one from the consumer, it proves its identity and claims the grant.
The consumer approves — the consumer reviews and accepts the claim. The institution now has access to decrypt and verify the document.
Access expires automatically — when the time limit is reached, access is revoked and all associated tokens are cleaned up. The consumer can also revoke access early at any time.

Both Parties Stay In Control

Consumers choose exactly which documents to share, with whom, and for how long. They can revoke access at any point.
Institutions can verify documents directly without relying on the platform to vouch for authenticity — they decrypt and verify the original.
The server facilitates the exchange but never sees the document content, who is sharing with whom, or the relationship between parties.

Targeted sharing: When a grant is targeted at a specific recipient, the recipient must prove their identity using a cryptographic signature before the grant can be claimed. This prevents anyone else from intercepting the grant — even if they discover it.

Zero-Knowledge Model — how the server never sees your data or identity associations
Document Lifecycle — the full journey of a document from upload to deletion, including how it becomes shareable
Key Hierarchy — the different types of encryption keys that make sharing possible
Encrypted Search — how shared documents become searchable for the recipient without revealing search terms
Entities & Memberships — how organizations manage members and share documents at the group level
Blind Routing — how sensitive relationships are tokenized to prevent relationship mapping

On this page