I want to work on this document in private. How?!

1. Purpose

Enable a user to share a document with specific people by granting their accounts permission to sync it.

The system must support a progression from:

Private → Shared with specific accounts → Shared with a group → Public

The experience should feel as understandable as Dropbox, while preserving Seed’s distributed architecture, canonical document identities, authorship, version history, and cross-space publishing.

2. Example scenario

Juan and Jesús work in the same university department.

They each have:

A Seed account.

A laptop running Seed.

One or more personal or departmental Spaces.

They may also use the same university-hosted server to keep their Spaces online and synchronized.

Juan wants to share a document with Jesús.

The intended mental model is:

Juan shares the document with Jesús.
Jesús’s authorized peers can then sync it.

The user should not need to understand which machine stores the document or whether Juan and Jesús use the same server.

3. Product principles

People grant access to people, not machines

The user selects an account such as “Jesús,” not “Jesús’s laptop” or “the university server.”

Machines receive access indirectly because they operate on behalf of an authorized account or hold a narrowly scoped synchronization capability.

Sharing controls synchronization

Sharing a document means:

This account is allowed to receive and synchronize this document and its authorized updates.

It does not merely create a URL or add the document to a list.

Publishing is different from sharing

Share grants access to selected accounts.

Publish makes content available to an open audience within a defined public context.

Both operations affect who may synchronize the content, but they represent different user intentions.

Documents retain their identity

A document should have one stable identity independent of:

The peer storing it.

The server hosting it.

The Space presenting it.

The account currently reading it.

Spaces may publish or reference a document without becoming its canonical owner.

4. Terminology

Account

A cryptographic identity representing a person, organization, or agent.

An account can:

Author documents.

Receive capabilities.

Grant capabilities.

Manage multiple devices.

Participate in Spaces.

An account is the principal used in sharing decisions.

Peer

A running Seed node that participates in the network protocol.

A peer can:

Store blobs.

Exchange blobs with other peers.

Synchronize authorized documents.

Serve one or more accounts.

Run on a laptop, phone, local server, or cloud server.

A peer is a technical concept, not the primary user-facing sharing concept.

Server

A machine or service that runs one or more Seed peers and is expected to remain reachable.

Examples:

A university server in Frankfurt.

A personal home server.

A hosted Seed service.

Recommendation: use Peer consistently in the protocol and engineering model. Use server only to describe where a peer is deployed.

A server is not a separate network actor. It is infrastructure that runs a peer.

Space

A named knowledge repository and publishing context.

A Space can:

Organize documents.

Define navigation and presentation.

Publish documents.

Be managed by one or more accounts.

Be synchronized by multiple peers.

A Space does not automatically own the documents it presents.

Document

A stable, versioned collection of blocks with a persistent identity.

A document has:

An identity.

Authorship and provenance.

A version history.

Content-addressed changes.

Sharing and synchronization rules.

Zero or more publishing contexts.

The document is the primary unit of sharing in V1.

Capability

A signed authorization granting a principal permission to perform an action on a resource.

Example:

Jesús’s account may synchronize document D and its descendants.

A capability should define:

Issuer: who grants the permission.

Subject: the account or peer receiving it.

Resource: document, subtree, Space, or other object.

Actions: read, sync, write, comment, administer, delegate.

Scope: exact resource or hierarchical subtree.

Expiration: optional.

Delegation: whether the recipient may grant derived capabilities.

Revocation reference: how future authorization can be withdrawn.

Network

The set of peers exchanging Seed data and protocol messages.

There is no authoritative global server containing the complete current state. Each peer knows its local state and exchanges messages with other peers; a global view must therefore be assembled from distributed observations rather than assumed to exist in one place.

5. Peer versus server decision

Seed should settle on the following model:

A peer is a protocol participant. A server is a deployment environment for a peer.

For the Juan and Jesús example, the topology might be:

Juan’s laptop peer.

Jesús’s laptop peer.

One university-hosted peer.

The university peer may synchronize documents for both accounts while maintaining separate authorization state.

It does not need to become Juan or Jesús. Ideally, it receives synchronization capabilities without holding their primary authoring keys.

One peer or two peers on the shared server?

From the user’s perspective, this should not matter.

The implementation may use:

One multi-tenant peer serving several accounts, or

Separate isolated peer processes for each account.

The protocol and product model must not depend on this deployment choice.

For V1, a multi-account peer is acceptable provided that:

Authorization is evaluated per account and resource.

Account signing keys remain isolated.

One account cannot enumerate or sync another account’s private resources.

Capabilities can be independently revoked.

Logs clearly identify the requesting account and capability chain.

6. Sharing model

Default state

Every new document is private by default.

“Private” means that only its authoring account and explicitly authorized peers or accounts may synchronize it.

Share operation

When Juan shares a document with Jesús:

Juan selects Jesús’s account.

Juan selects the permitted actions.

Seed creates a signed capability.

Jesús receives or discovers the capability.

A peer acting for Jesús presents the capability when requesting the document.

An authorized peer sends the document blobs and subsequent permitted updates.

The document appears in Jesús’s shared content.

The system should communicate the result in human terms:

Jesús can now view and sync this document.

Not:

A capability blob was issued to Jesús’s peer.

Synchronization authorization

A peer may synchronize a document when it can present a valid capability chain authorizing the requested operation.

Conceptually:

Account or peer
    has capability
        for action: sync
        on resource: document
        within scope: exact document or subtree

7. Hierarchical capabilities

Capabilities may apply to a document hierarchy.

For example:

Department Research
├── Robotics
│   ├── Project Plan
│   └── Experiments
└── Administration

Sharing Robotics with Jesús may authorize synchronization of:

Robotics

Project Plan

Experiments

It should not authorize Administration.

V1 inheritance rule

A capability granted on a parent applies to all descendants unless the grant explicitly limits its depth or scope.

For V1, avoid negative overrides such as:

Share the parent, except this one private child.

Once a recipient has synchronized a parent subtree, confidentiality cannot be reliably restored by changing an inherited permission later.

Therefore:

Content that must remain more restricted should not be placed beneath a broadly shared document.

The interface must show inherited access clearly:

Shared with Jesús because the parent document “Robotics” is shared.

Revocation

Revocation stops future authorized synchronization.

It cannot guarantee deletion of content that has already been synchronized to another person’s device.

The UI must say this plainly:

Jesús will stop receiving updates. Previously downloaded content may remain on his devices.

8. Share versus publish

Use sharing when the audience is known.

Examples:

Share with Jesús.

Share with the Robotics group.

Share with all accounts from the department.

Shared content:

Requires authorization.

May not be discoverable publicly.

Can be synchronized only by authorized accounts and peers.

Publish

Use publishing when the audience is open or defined by a public publishing context.

Examples:

Publish on physics-university.hyper.media.

Publish as the homepage of a public Space.

Publish a paper for anyone to read.

Published content:

Is publicly discoverable within its publishing context.

Can be synchronized without per-user authorization.

Retains its document identity, authorship, and provenance.

Key rule

Visibility should be a property of the published document version, not an accidental consequence of where a reference appears.

A private document must not become public merely because it is embedded or referenced by a public Space.

Attempting to publish private content should require an explicit transition:

This document is currently private. Publishing it will make this version available to everyone.

9. Canonical documents and Spaces

Seed should adopt a canonical-document model.

A document has one persistent identity. A Space can include it without creating an unrelated copy.

Include in a Space

Including a document in a Space means:

The Space presents or organizes the document.

The original authorship remains intact.

The document identity remains intact.

Access remains subject to the document’s capabilities.

Republish in a Space

Republishing means that a Space intentionally makes a document available through its own publishing context.

Republishing should:

Preserve the original document identity where possible.

Preserve authorship and provenance.

Record which Space republished it.

Require the Space administrator to confirm the applicable license.

Never silently broaden private sharing permissions.

Republishing a public document does not make the Space its new canonical owner.

Forking

A user creates a fork when they need to:

Change the content independently.

Apply different licensing.

Publish content that cannot remain tied to the original authorization model.

Establish a new canonical lineage.

The fork must visibly preserve its relationship to the source document.

10. Permissions model

The initial actions should be:

Permission	Meaning
View	Read already available content
Sync	Receive the document and authorized updates
Comment	Create anchored conversations or comments
Edit	Create proposed or accepted document changes
Share	Grant limited derived access to others
Administer	Change permissions and manage capability grants

For the first implementation, the product may expose simplified roles:

User-facing role	Capabilities
Viewer	View + Sync
Commenter	View + Sync + Comment
Editor	View + Sync + Comment + Edit
Manager	All permissions, including Share and Administer

The underlying capability system should remain action-based even when the interface presents roles.

11. Customer journeys

Journey A: Share one private document

Juan opens a private document.

Juan selects Share.

Juan searches for Jesús by name, domain, or account ID.

Juan selects Viewer.

The interface explains that Jesús will be able to synchronize the document.

Juan confirms.

Jesús receives the document in “Shared with me.”

Jesús opens it on his laptop.

Jesús’s other authorized devices can also synchronize it.

Journey B: Share a document subtree

Juan opens the “Robotics” parent document.

Juan selects Share.

Juan selects Jesús.

Seed shows the descendants included in the grant.

Juan confirms.

Jesús can synchronize the parent and its current and future descendants.

Descendants display that their access is inherited.

Journey C: Publish a shared document

Juan opens a document currently shared only with Jesús.

Juan selects Publish.

Seed warns that publishing is broader than sharing.

Juan chooses a Space.

Seed shows the version and license that will become public.

Juan confirms.

The public version becomes discoverable.

Jesús’s private collaboration history remains private unless explicitly published.

Journey D: University-hosted synchronization

Juan connects his account to the university hosting service.

The hosted peer receives a limited synchronization capability.

The peer stores Juan’s authorized Spaces and documents.

Jesús uses the same hosted service.

Jesús’s authorization is evaluated independently.

Shared documents may be transferred locally within the hosted peer, but only after validating the capability.

Neither user needs to know whether the service runs one peer or multiple peer processes.

Journey E: Revoke access

Juan opens the sharing panel.

Juan removes Jesús.

Seed revokes or invalidates the relevant capability.

Jesús stops receiving new versions.

The interface explains that already synchronized content may remain available offline.

12. Interface requirements

The document sharing panel should answer:

Who can access this document?

Why do they have access?

What can they do?

Is their access direct or inherited?

Is the document published publicly?

Which Space publishes it?

What happens if access is removed?

Suggested structure:

Access

Private / Shared / Public

People with access
- Juan — Owner
- Jesús — Viewer
  Direct access

Inherited access
- Robotics Department
  Through parent: Robotics

Published in
- Physics Department Space
  Public

The primary controls should be:

Publish

Copy link

Manage access

“Copy link” must not imply that possessing the URL grants access.

13. Engineering requirements

Authorization

Every private synchronization request must be evaluated against:

Resource identity.

Requested action.

Capability subject.

Capability issuer.

Capability chain.

Scope.

Expiration.

Revocation state.

Storage

Peers may store:

Documents belonging to multiple accounts.

Public documents.

Encrypted or access-controlled private blobs.

Capability and revocation records.

Storage possession alone must not imply authority to republish or edit.

Discovery

The network needs a way for an authorized account to discover:

That a document has been shared.

Which peer can provide it.

Which capability authorizes the request.

The capability itself should not unnecessarily reveal private document metadata to unauthorized peers.

Offline behavior

An authorized user should be able to read already synchronized content offline.

Actions created offline, such as edits or comments, should be validated when synchronization resumes.

Auditability

The system should preserve a record of:

Who granted access.

Who received access.

Which resource was included.

Which permissions were granted.

Whether access was inherited.

When it was granted, changed, or revoked.

14. Non-goals for V1

Guaranteed deletion from another user’s device after revocation.

Arbitrary allow-and-deny rules at every level of a document tree.

Anonymous link sharing that bypasses account capabilities.

A complete enterprise policy language.

Making server deployment topology visible to normal users.

Automatically republishing private source material.

Treating a Space as the owner of every document it includes.

15. Product decisions

Account is the sharing principal.

Document is the primary unit of sharing.

Capability is the technical representation of permission.

Peer is the protocol participant.

Server describes deployment, not a separate domain object.

A peer may serve multiple accounts.

Spaces organize and publish documents but do not automatically own them.

Sharing grants selective synchronization.

Publishing grants public synchronization within a publishing context.

Documents retain canonical identities across Spaces.

Parent capabilities apply to descendants in V1.

Revocation prevents future synchronization but cannot retract existing copies.

Private content cannot become public through an implicit embed or republish action.

16. Open questions

Sharing boundaries

Can a single block be shared independently, or only a complete document?

Should comments inherit the document’s sharing rules?

Can a comment have a narrower audience than its target document?

Hierarchy

Are descendants determined by document paths, explicit relationships, or both?

What happens when a shared descendant moves outside the shared subtree?

What happens when an unshared document moves into a shared subtree?

Groups

Is a department represented as an account, group, Space membership list, or capability issuer?

How are group membership changes reflected in existing grants?

Publishing

Can different versions of the same document have different visibility?

Is the public object the document, a specific version, or a publication record pointing to a version?

Can a Space stop publishing a document without affecting publication by another Space?

Licensing

Which licenses permit republishing?

Must the Space explicitly accept the document license?

How should incompatible licenses be surfaced?

Hosted peers

Does the hosted peer store plaintext private content?

Can it synchronize encrypted blobs without receiving document decryption authority?

Should each account receive an isolated logical peer even when the process is shared?

17. Success criteria

The feature succeeds when:

Juan can share a document with Jesús without understanding peers or servers.

Jesús can synchronize it across his authorized devices.

Unauthorized accounts cannot retrieve the document.

The interface clearly distinguishes sharing from publishing.

Users understand inherited access.

A university server can host both users without merging their identities or permissions.

Documents preserve authorship and identity when presented in multiple Spaces.

Publishing private content always requires explicit confirmation.

Engineers can determine authorization from capabilities without relying on a central permissions database.

Share a document with certain users, using syncing rules.

Juan and Jesus are Peers from the same University department

Juan and Jesus may want to share the same server for both Spaces

With one Peer or two Peers?

Sometimes we use Peers and sometimes Servers. We must settle on one.

Share and Publish

Define each concept:

Peer

Space

Document

Accounts

Network

Capability

This account can sync this document.

Capabilities are hierarchical

Sync permissions per

Documents are the sharing

Inspiration

Dropbox

In Dropbox, there are no canonical copies? Or

Even old people immediately understood it.

Xanadu

Canonical Copies

Space

Republishing a document with a space implies accepting the copyright and the sharing permissions

Share vs Publish has a tension

Mental Model

Publish content; scale sharing permissions.

Create a new repo: Public or Private?

When

Customer Journey

Cuando compartes un documento con un usuario tienes que elegir un repositorio

Es el peer al que los repos delegan la validación de permisos

Customer Journey