00 — Overview

Status: Draft, v0.1. License: CC-BY-4.0 — see LICENSE-DOCS.

Purpose

This document defines the terminology and two-layer model used throughout the rest of this specification. It describes the protocol as a set of guarantees and message contracts between independent parties — not as a description of any particular implementation.

Core model

Two things about a connection are never inherited or assumed in Bonafide: what each party presents to it, and what moves across it once it exists.

A connection is independent of every other connection either party has. It carries its own key material, generated for it alone, and what a party presents into it — a name, a profile, anything else — is particular to that connection, asserted directly into it rather than drawn from some canonical account both connections happen to reference. A connection with a coworker and a connection with a sibling can look entirely different, the way they already do without computers, because nothing requires them to resolve back to one consistent picture of who's on the other end. Bonafide isn't restricting access to a central account that exists underneath; there's no center to restrict access to — the connection itself is the whole of the relationship. Layer 1 MUST NOT expose any mechanism — a routing token, connection metadata, or anything else visible to a party outside the connection — that would let two connections belonging to the same party be correlated back to each other.

This guarantee is scoped to Layer 1. What a domain's Layer 2 content does with it is the domain's own decision: a domain MAY define content or commands that let two parties voluntarily disclose, to each other, that they're the same party behind more than one connection — or a domain MAY just as deliberately withhold that capability and keep connections uncorrelatable even at the content level. Either way, the protocol imposes nothing here; it only guarantees that Layer 1 itself never makes that decision for a domain, or leaks the correlation to someone who wasn't given it on purpose.

A connection implies reachability between its two parties — nothing about what either shares or receives. That is controlled by each party on its own, through Layer 1's access control mechanism: a subscription to a label on the shared data, independent of whichever domain uses it. A party sends nothing under a label it hasn't subscribed to share, and gets nothing under a label it hasn't subscribed to receive — content under a label moves only once both are true.

Terminology

• Connection — a unique, bidirectional relationship between two parties, established via a one-time out-of-band code exchange and backed by its own independently generated key material. An implementation MUST NOT share or reuse a connection's key material with any other connection — this keeps a compromise of one connection's keys from exposing any other connection, and keeps key reuse from becoming a correlation vector between connections (see 02-connections.md).
• Domain — a named Layer 2 contract: a shared vocabulary of content types, subscription classifications, and commands that defines what can be exchanged between connections participating in it. A domain is not itself a piece of software — email is a domain in this sense, and Gmail, Outlook, and Thunderbird are different applications that interoperate because they all implement it. Pools is, so far, the one application implementing the pools domain; other applications may implement the same domain and interoperate with it without being Pools. A single connection may be extended to span multiple domains, each potentially implemented by a different application, without creating a second connection (see 03-cross-domain.md).
• Content — any object shared between connections, typed by an isA descriptor and validated against a schema a domain registers for its namespace (see 05-content-model.md).
• Command — a one-off, imperative instruction one party sends the other over an established connection — e.g. reporting a piece of content — rather than data to be stored or further propagated. A domain defines the commands it supports the same way it defines content types, but a command carries no state of its own beyond the operation it names (see 05-content-model.md).
• Subscription — the mechanism by which a connection is granted ongoing access to a label-based category of content, with labels defined by the domain. Establishing a subscription, like establishing a connection itself, requires both parties — one offering a category of content, the other agreeing to receive it; which party initiates, and how content categories are discovered, is left to the domain. This is the enforcement point for content access control: a connection MUST NOT receive any content it has not been subscribed to. A command (see below) is not content and is not subject to this gate (see 04-access-control.md).
• Router — an operator-run relay that moves encrypted messages between the two parties of a connection without ever being able to read their content. Addressed by an opaque routing token, not by domain or identity.
• Bonafide Agent — the software, run by an application, that implements this specification: it stores content, enforces its domain's content-type contract, and drives connection and subscription state on behalf of its users.

Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in RFC 2119 and RFC 8174, when, and only when, they appear in all capitals as shown here.

An agent that implements every MUST and MUST NOT requirement of a document is a conformant implementation of that document. SHOULD/SHOULD NOT marks a requirement an implementation can deviate from, but only for a reason it can justify — conformance is not forfeited by a single deviation, but an implementation that ignores SHOULD requirements broadly should not expect to interoperate reliably with others that don't share its assumptions.

The two-layer model

• Layer 1 — Connections & Access Control. Establishes a private relationship between two parties and determines what, if anything, one party is permitted to receive from the other. Layer 1 has no knowledge of what is being shared — only of who is allowed to receive something, once it exists.
• Layer 2 — Content & Domain. Defines what is actually shared over an established Layer 1 connection: the shape of content, how it propagates, the commands two parties may send each other, and how an application's content types interoperate with other applications in the same domain.

Layer 2 is always built on top of an established Layer 1 connection — there is no content exchange without two things already being true at Layer 1: the connection between the two parties MUST exist, and a subscription granting access to that content's label MUST exist. The connection is foundational — nothing happens between two parties without one — but it is not itself the access-control decision; that decision is the subscription (see Subscription, above).

Interoperability

Two applications that each correctly implement Layer 1 and the same domain's Layer 2 contract interoperate with each other without prior coordination between their developers — the same way two independently built email applications interoperate because they both implement the same mail protocols, not because their developers agreed with each other directly. Making this possible is one of Bonafide's explicit aims: publishing a domain's Layer 2 contract — not only the connection and access-control layer — as a specification, rather than leaving it as an implementation detail private to one application, is what allows independently developed applications to interoperate at all. An application that satisfies a domain's specification is an implementation of that domain, regardless of who built it or what software it runs.

Scope of this draft

Features explicitly out of scope for v0.1 (per-field schema subsets, cross-operator host migration) are listed in the repository README and are not described further in this document. They are fast following features.