Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Enclave Design Patterns

This document catalogs application-level enclave design patterns — Shared, Personal, Group Chat, and DM. The patterns are informative: the core protocol does not mandate any of them. They illustrate how the RBAC v2 state/trait model and the confidentiality plugins compose into recognisable application archetypes.

Table of Contents

  1. Shared Enclave
  2. Personal Enclave
  3. Group Chat
  4. How to Choose
  5. DM (Direct Message)
  6. Enclave Kind Metadata

Shared Enclave

A Shared Enclave is an enclave whose data and access-control are intended to be jointly used by multiple identities.

Typical characteristics
  • Multi-writer / multi-reader by design
  • RBAC is centered on group roles (e.g., Admin/Member/Moderator)
  • Data is considered collective (not owned by a single identity)
Examples
  • Group chat enclave
  • A protocol-level registry/directory enclave
  • DAO / project coordination enclave
  • Shared public feed with moderators

Personal Enclave

For the full RBAC v2 design, see Personal Enclave.

A Personal Enclave is an enclave whose data is logically owned and controlled by a single identity, even if many others can read or contribute under permission.

Typical characteristics
  • A single "owner" identity is the final authority for RBAC and lifecycle
  • Designed for portable identity-scoped data with a unified API
  • Others can write into it (e.g., comments, reactions) but the enclave remains owner-governed
Examples
  • A user's posts / profile / settings enclave
  • A user's inbox / notifications enclave
  • Personal "data vault" enclave used across apps

Confidentiality is split across two plugins: identity-aead seals owner-only private events (deterministic HKDF from identity_priv), and ecdh-envelope seals cross-enclave inbound notice events (one-shot sender→recipient ECDH with optional handoff sub-encryption for group-invite bootstrap).

For the full RBAC v2 manifest, state transitions, and event-operator matrix, see Personal Enclave.

Registration

After creating a personal enclave, the owner can publish a discovery record so others can find it by public key. The Registry enclave is one such mechanism (see enclaves/registry.md → reg_identity with the enclaves.personal field). Other mechanisms (a well-known URL on the owner's domain, a custom directory enclave) are equally valid; the core protocol does not mandate Registry-based discovery:

id_pub → reg_identity → enclaves.personal → enclave_id → reg_enclave → node

Group Chat

A Group Chat Enclave is a shared space for multi-party messaging. It uses the RBAC v2 State/trait model with PENDING, MEMBER, and BLOCKED states, plus owner/admin/muted/dataview traits. Multiple join paths (application, auto-join, direct invite), gated transitions, and trait-based moderation. Confidentiality is provided by the mls-lazy plugin (lazy-MLS binary ratchet tree with O(log N) epoch distribution and an additive OR-wrap fallback for sub-key wallets).

For the full design pattern, see Group Chat Enclave.

How to Choose

Use Shared when:

  • The enclave represents a group object (a room, project, DAO, registry)
  • Governance and policy are collective or moderator-driven
  • Many identities are primary contributors

Use Personal when:

  • The enclave represents identity-scoped state (my profile, my posts, my inbox)
  • You want data to be portable across apps
  • One identity should remain the owner-of-record

DM (Direct Message)

For the full RBAC v2 design, see DM Enclave. Confidentiality is provided by the ratchet-pair plugin (per-contact epochs with a per-sender ratchet inside each epoch).

DM is a sibling enclave kind — a personal mailbox dedicated to direct messaging. It is distinct from the Personal Enclave (the identity-anchor enclave above) and lives behind its own enclave_id. When the Registry enclave is used for discovery, the DM enclave's id is published under reg_identity.enclaves.dm. Per enclaves/dm.md, the DM enclave has its own RBAC schema (states OWNER, FRIEND, BLOCKED; customs invite, message, sent, rotate) — entirely separate from the Personal enclave's public / private / notice events.

Each identity therefore maintains TWO enclaves: a Personal (identity, profile, private docs, inbound notices) and a DM (incoming messages from contacts). Cross-enclave notices (e.g. group-invite) land in the Personal notice rail; per-contact messages land in the DM message rail.

How it works
  • Alice sends a message event to Bob's DM enclave
  • Bob replies by sending a message event to Alice's DM enclave
  • Bob's client MAY also store a local copy of his outgoing reply in Bob's own enclave.
Properties
  • Messages are asymmetric by default (each direction is a separate write)
  • Each participant maintains a complete local history inside their own enclave
  • Ownership and RBAC are enforced per enclave, independently
  • No shared or mutually-owned log is required
Implication

DM is modeled as:

"write into the recipient's enclave, optionally mirror into the sender's enclave"

—not:

"append to a shared conversation log"

Enclave Kind Metadata

There is no mandatory "type" field. You MAY include a hint in metadata (e.g., meta.enclave_kind = "shared" | "personal"), but clients must not rely on it for security decisions.