Skip to content
PulsVaultDocs
Get started
PersonalPremiumFamilyTeamBusinessEnterprise

Vault sharing & DEK re-wrapping

How PulsVault shares encrypted data without the server ever seeing a key — per-recipient RSA wrapping of vault DEKs, ephemeral keys for item shares, and client-side DEK rotation on revoke.

Sharing is the hardest problem in a zero-knowledge system: the server must broker access to encrypted data without ever holding a usable key. PulsVault solves it with key re-wrapping — vault items are never re-encrypted for a recipient; instead, the key that decrypts them is wrapped for each recipient individually.

The mechanism: wrap the key, not the data#

Every user generates an RSA-2048 keypair during the signup key ceremony. The public key is stored on the server; the private key is stored wrapped by the user's UMK, so even the private key is opaque to the server.

To share a vault, the owner's client:

  1. Unwraps the vault DEK with their own UMK (client-side).
  2. Fetches the recipient's RSA public key from the server.
  3. Encrypts the raw DEK with RSA-2048-OAEP to that public key.
  4. Sends only the wrapped DEK; the server stores it against the share record.

The recipient's client unwraps their RSA private key with their own UMK, decrypts the DEK, and reads the vault normally. The server relayed a share it can never open. Because the recipient holds the same DEK, vault shares are live: updates by the owner are immediately readable.

Three sharing modes, three key strategies#

Mode Key material Data model Server sees
Vault share Vault DEK, RSA-wrapped per recipient Live reference — same DEK Wrapped DEK only
Item share Fresh ephemeral AES key per share, RSA-wrapped Frozen snapshot at share time Wrapped key + ciphertext snapshot
Secure link Random AES-256 key in the URL #fragment One-time snapshot Ciphertext only — never the key

Item shares use an ephemeral key precisely so the vault DEK is never exposed for a single item. The trade-off is staleness: an item share is a point-in-time copy and does not track later edits (see Item sharing). Secure links keep the decryption key in the URL fragment, which the browser never transmits to the server; links carry expiry, view limits, and optional email-OTP restriction (see Secure links).

Revocation and DEK rotation#

Revoking access requires rotating the key — on the client

Deleting a share record stops the server from returning data, but a revoked recipient still knows the old DEK. So on vault-share revocation the owner's client generates a new DEK, re-encrypts the vault's items with it, and re-wraps the new DEK for each remaining member. The server cannot do this — it never has a DEK — which is why rotation is a client-side operation by design. The dek_version field tracks rotations.

Guardrails#

  • The primary vault is never shareable — not by user share, not by link, not by any API. Enforced client-side and server-side.
  • OWNER is never assignable via sharing — recipients get at most EDITOR; access levels are MANAGER, EDITOR, VIEWER, and LIMITED (autofill without plaintext reveal). See Access levels.
  • Secure links are item-scoped only — a leaked link can never expose a whole vault.
  • Organization containment — Team/Business/Enterprise data cannot leave the organization circle unless an admin explicitly enables external sharing (optionally with per-share approval). Family plans share vaults inside the Family Circle only; items may go external.
  • Plan limits — active-share and secure-link quotas scale by plan (see Plan comparison).
Was this page helpful?