Teams & RBAC

Honesty Ledger (Provenance Layer): Member metadata and key registries are managed at the Server-known (Layer A) layer, while key wrapping and decryption run at the Client-derived (Layer B) layer.

ZK Trust Boundary:

• What the server sees: Member lists, role metadata, and wrapped DEK envelopes (opaque base64).
• What stays on device: Cleartext Data Encryption Keys (DEKs), private key parts, and plaintext memory content.

Zero-Knowledge Team Collaboration

Sharing encrypted memory contexts across multiple developers or AI agents is a key-distribution challenge. The Platform solves this using cryptographic envelope encryption, allowing teams to collaborate without ever exposing keys or memories to the replication server.

The Envelope Encryption Model

Each shared project has a single Data Encryption Key (DEK) that actually encrypts and decrypts memories. The DEK is never sent to the server. Instead, it is wrapped (encrypted) individually for each team member:

1. Member Keypair: When a member accepts an invitation, their client generates a local public/private keypair. Their public key is registered on the server.
2. Key Wrapping: The inviter's client retrieves the new member's public key, encrypts (wraps) the project DEK with it, and uploads the resulting envelope to the server as a key_grants entry.
3. Decryption: To read memories, the member's client downloads their wrapped DEK from the /grant endpoint and decrypts (unwraps) it using their local private key.

Role-Based Access Control (RBAC)

Operations are enforced both server-side and client-side:

• Admin: Full read/write access. Enforced server-side for member management and DEK rotation.
• Write: Can read and write memories. Enforced server-side against write requests.
• Read: Gated by whether the member holds a valid key grant. A reader without a grant only sees ciphertext.

The Revocation Protocol

Removing a member from a project must invalidate their access to future writes. A simple database delete is insufficient, as the ex-member would still hold the old DEK. The Platform enforces a strict three-step revocation protocol:

┌────────────────────────────────────────────────────────┐
│                   ADMIN REVOCATION FLOW                │
│                                                        │
│   1. Delete member grant from server database         │
│   2. Generate a fresh DEK locally in Admin's browser   │
│   3. Re-encrypt (re-wrap) new DEK for remaining users  │
│   4. Upload re-wrapped grants & commit new DEK epoch   │
│                                                        │
└────────────────────────────────────────────────────────┘

1. Delete Grant: The revoked member's key_grants row is deleted, and their status in team_members is set to inactive.
2. Rotate DEK: The admin's browser generates a fresh random DEK.
3. Re-wrap Remaining Members: The admin's browser downloads the public keys of all remaining active members, encrypts the new DEK to each public key, and updates the key_grants table. It records a new rotation epoch in dek_rotations.
4. Result: The revoked member's local cached key is useless for decrypting new memories synced after the rotation seq increment.

Per-Agent Sub-keys

To authorize autonomous agents, admins can issue scoped sov_live_ sub-keys bound to specific member grants. Each sub-key can be individually named, monitored, and revoked in under 5 seconds.

Offline Reference Analogs: This documentation was written with visual and rhythm reference to platform/features/platform-overview.html.