Sharing and access
A hosted draft is already encrypted. You can share access through a secret link or encrypt a version for specific wallet identities. Neither requires putting the document on chain.
Two encrypted layers
Document
Wallet or reader-link identity → unwrap document key → open this version
Live room
Room invitation → decrypt live edits, annotations, and presence
These permissions are separate. Reading a document does not grant access to an existing room or permission to publish its next version.
What is in a guest link?
| Part | What it does |
|---|---|
/d/h_ID | Locates the encrypted document. No decryption power. |
#k=… | A throwaway reader private key that unwraps the document key. |
room=…&collab=… | Identifies a live room and supplies its separate secret invitation. |
The reader key is neither your funding-wallet key nor the AES document key. “Ephemeral” means a throwaway identity; it does not mean the link expires. Anyone holding it can read versions encrypted for that identity.
Browsers do not send URL fragments in HTTP requests, but page scripts can read them and copied links can leak them. Treat the complete invitation like a password. A reader-only link omits room access.
Invite a person or bot by identity
Your private address book
The CLI can sync a snapshot of your contacts and teams, encrypted only for its connected wallet. In the Publish sidebar, the owner can choose Private copy and unlock contacts using that same identity. Your book is not included in the plan, its annotations, or its collaboration room.
Review your local contacts before syncing: this explicitly replaces that wallet’s previous hosted address book. It does not change the local book or grant anyone plan access. Different wallets have separate books, even on the same device. Sync requires a CLI build that includes contacts sync; check its help before running it.
Select a team, then adjust individual recipients. Only selected public keys enter the sharing handoff; private contact labels and team names do not. Initials identify contacts without claiming a roster character or verified live presence. Contributors see the current recipients read-only; they cannot change the document's access. Direct creation of a private live copy is not wired yet: the sidebar still hands off to your agent and does not re-encrypt an existing room.
Ask for their BRC-100 public identity key and verify it with them. Never request their private key. Contacts and teams are managed locally in the CLI; syncing them is optional. Adding a member does not change any encrypted version yet.
Run updates from the CLI installation holding this draft's update secret. The next envelope wraps a fresh content key for its recipients. Their wallet needs the matching private identity to open it; knowing a public key is insufficient. Share the plain document URL and confirm they can open the new version with their wallet.
“Self” means the publishing wallet, not every wallet on your device. Add your other wallet identities as recipients too. Team names stay in your private book; recipient public keys are visible in the envelope header.
Move away from link access
- Review the current document and live annotations before preparing the next version. CLI fetch alone does not include the room.
- Remove the old link reader from the new version, then add the intended wallet recipients.
- Verify wallet decryption before distributing a URL without a key.
For a CLI-managed draft, this currently takes two hosted versions: first --private removes all additional readers; then --share-with adds the team. These flags cannot be combined.
Review each confirmation. Simply omitting --link preserves inherited readers. Deleting #k from a URL changes no access rights. Old links can still decrypt old versions; re-encryption cannot revoke copies someone already has.
Where the transition stops today
Connecting a wallet does not re-encrypt a guest draft or its live room. Browser starters do not retain the hosted update secret needed for CLI replacement. Preserve their reviewed content in a new wallet-managed draft; there is no automatic in-place ownership conversion.
Live rooms still use secret invitations, including when the document uses wallet recipients. Wallet-only room membership, invitation rotation, and verified participant identities are not implemented. A character or displayed public key is not proof of identity. Opening a document without its room invitation may create a different room.
Encryption and publishing boundaries
Documents use AES-256-GCM with a separately wrapped key per reader. Rooms derive separate AES-GCM encryption and authorization keys from their invitation using HKDF-SHA-256. Convex receives the authorization proof and encrypted values, plus routing metadata, sizes, and timing.
Reading rights do not confer publishing rights: hosted updates need the separate update secret; on-chain revisions need control of the current ordinal. Saving live edits does not create an inscription.
See the envelope format or agent setup.