Private beta · protocol 1
App access for local and hosted collections.
An application sends the user to Connect. The user chooses one compatible collection and approves exact actions. The application receives a collection-bound connection; local folder paths stay on the user's computer.
Where Connect sits
Connect is optional. Applications can also use a conforming mdbase implementation directly. Connect provides a common approval and routing path when independent applications need access to a user's collections.
- ApplicationDeclares compatible collections and requests exact operations.
- ConnectPresents the request, records the decision, and selects the route.
- Collection authorityRechecks the grant and executes each approved operation.
- mdbase collectionRemains the authoritative Markdown and collection history.
Local and hosted collections
Applications use the same SDK and operation envelopes. Routing changes according to which connector or provider currently holds the collection's authority.
| Authority | Where Markdown lives | Application route | What the control plane sees |
|---|---|---|---|
| Local connector | A folder on the user's computer | Direct loopback, then encrypted relay fallback | Account, grant, operation name, routing metadata, timing, and sizes |
| Hosted provider | Encrypted provider storage, with optional local mirror | Direct, short-lived provider capability | Account, grant, capability issuance, and provider routing metadata |
The provider must decrypt collection data to execute canonical mdbase operations. The provider acts as a trusted data processor for hosted collections.
Why one movable authority?
Authority is a coordination role, not the only copy of a collection. Writable mirrors can keep ordinary Markdown on several devices, accept changes while offline, and synchronize them later. One authority orders the final accepted changes, enforces collection-wide rules, and gives every mirror the same history to converge on.
Removing that role would not remove coordination. It would require every peer—including filesystem editors that only know how to rewrite a Markdown file—to preserve causal history and agree continuously about concurrent edits, renames, deletes, schema changes, revocation, and garbage collection.
| Concern | Equal peers would require | One movable authority provides |
|---|---|---|
| Ordinary Markdown tools | CRDT or event metadata preserved by every writer | Open files remain the editable local format |
| Concurrent changes | A deterministic merge for every body and frontmatter value | Revision checks, durable mutation receipts, and explicit conflicts |
| Renames, deletes, and configuration | Distributed agreement over paths, tombstones, schemas, and constraints | One canonical order for collection-wide decisions |
| Offline devices | Split-brain reconciliation and peer-membership machinery | Queued local work that safely converges when the mirror reconnects |
Authority transfer preserves the collection and record identities, advances an authority epoch, and retires the previous authority. When the previous authority was a local folder, that folder can continue as a mirror. A stale authority cannot accept writes after cutover.
The authorization sequence
The application declares what it understands
Its bundled v1 manifest declares web callbacks or portable distribution, required domain contracts, collection kind, and any type definitions that can be installed safely.
Connect checks collection compatibility
The local or hosted authority returns a readiness status for each collection: ready, provisionable, or incompatible. Collection contents remain private during authorization.
The user approves exact operations
The decision names one collection and concrete operations. Contract access is scoped to records that match the declared domain contracts unless full collection access is explicitly requested.
Every request is checked at the authority
The connector or hosted provider rechecks the current grant. Narrowing, pausing, or revoking access takes effect at the place that can open the data.
Who can read records
Connect limits the components that can read records. Local and hosted collections have different trust boundaries.
| Component | Can read collection records? | Responsibility |
|---|---|---|
| Application | Only through its current grant | Uses authorized results and protects its local SDK credentials |
| Local connector | Yes, for registered local collections | Final local authorization boundary and operation executor |
| Connect control plane | No local operation payloads or results | Identity, pairing, grants, short-lived tokens, and relay routing |
| Hosted provider | Yes, for hosted collections | Encrypted storage, canonical execution, sync, and durable receipts |
Release status
Release status
The private-beta stack includes local and hosted authorities, encrypted relay operations, grant narrowing and revocation, sync, notifications, the browser SDK, and key-bound authorization for downloaded HTML files. The npm packages have not yet received their first public release. Public registration, a production restore drill, signed desktop releases, and abuse-response operations are still required before public registration.
Terms used on this site
- Grant
- One user's approval for one application, one collection, and a concrete set of operations.
- Authority
- The movable coordination role that orders accepted changes, enforces collection rules, and makes the final authorization decision.
- Control plane
- The Connect service for identity, pairing, grants, short-lived tokens, and route coordination.
- Contract
- A portable declaration of domain behavior and its mapping to one collection type.
- Operation envelope
- A typed result containing a validity flag, result value, and structured diagnostics.