Oxygen wire protocol for implementers

This document describes what a second implementation needs to talk to an Oxygen server or client: the transport, the message encodings, the order of requests, and the checks each side performs. It is derived from spec.md §5.5, §14, §16 and §17; where the two disagree the specification wins, and this document says which section to read.

Everything on the wire is deterministic CBOR (§5.1): maps have unsigned integer keys in increasing order, integers use the shortest form, no floats, no indefinite lengths, no tags. Objects travel as their canonical bytes, so the receiver hashes exactly what the sender signed.

1. Identifiers and hashing

• ObjectRef (32 bytes) = BLAKE3 of "oxy1 <type> <len>\0" || body, where <type> is one of chunk blob change checkpoint op attest identity policy state and <len> is the decimal body length. A ChangeHash is the ObjectRef of a change; a KeyId is the ObjectRef of an identity.
• ChangeId (16 random bytes) survives rewrites of a change.
• Repository id (16 random bytes) is chosen at init and returned by capabilities; a client refuses to push to a repository whose id differs from its own.

Object encodings are in spec §5.5 (conventions), §6.1 (change), §11 (checkpoint), §12.1 (op), §14.2 (identity), §14.4 (attestation), §14.5 (policy) and §10.1 (state).

2. Transport

The reference server (oxy serve) exposes one repository per subdirectory of its root at <base>/<repo>/oxy/v1/<endpoint>:

Rules:

• Request and response bodies are CBOR with Content-Type: application/oxy-cbor. A body is a single CBOR item (not a sequence).
• Repository names are [A-Za-z0-9._-]+ and may not start with .; anything else, and any directory without .oxy/, is 404.
• Reads are unauthenticated. push requires Authorization: Bearer <token> when the server was started with tokens; a missing or wrong token is 401.
• Errors are plain-text bodies with a 4xx or 5xx status; the client shows the text. A push that is refused (policy, compare-and-swap) is a 200 with ok = false in the push response, not an HTTP error; one a host refuses by its content (vet_push, spec §16.4) is an HTTP error with the host's reason as its text, and nothing of it is stored.
• TLS is ordinary HTTPS. The reference client trusts the system web roots plus an optional PEM file (remote.<name>.ca or OXY_CA); servers with self-signed certificates are expected to hand that file out.
• Pushes to one repository are serialised by the server; reads are not.
• A hosted repository may be unbound: created empty with no id, so an existing repository can be pushed to it and keep its identity. Its capabilities reports an all-zero id. A client refuses to clone or fetch from an unbound remote and accepts it for a push, sending its own id in the Oxy-Repo-Id request header (32 hex characters); the server binds the repository to that id under the push lock before validating the push, and refuses a push to an unbound repository that carries no header with 400. Clients send the header on every request when they have an id; servers ignore it on bound repositories.

Embedding: oxy_server::Server answers any endpoint for a repository name a host's Backend resolves and authorises (open, authorize, and an after_push hook, and vet_push, with which a host refuses a push by what it adds before anything is stored: an HTTP error, 422 say, whose text, several lines perhaps, the client shows as it is; spec §16.4), so a hub with owner/name paths and its own accounts routes /{owner}/{name}/oxy/v1/{endpoint} to Server::handle; oxy serve is DirBackend on that same server.

The spec (§16) also defines framing for Noise and ZCT transports (u32 big-endian length || bytes); the reference implementation speaks HTTP only.

3. Messages

Keys are CBOR unsigned integers. [x] is an array of x; bytes(32) an ObjectRef; "signed X" is [X bytes, [Signature]].

Bundle details:

• Changes are in dependency order, each with its individual signatures (possibly none).
• Key 1 carries seals (kind = seal) covering the changes.
• Key 2 objects are only chunk, blob, identity, state, checkpoint; a receiver rejects any other type.
• Key 3 (optional) carries the policies between the receiver's serial and the one in the push request, ascending, so the receiver can verify each step (§14.5). The refs response carries the same history in its key 4.

Sizes: a seal lists at most 4096 hashes, sorted and unique. Chunks are 32–256 KiB (FastCDC, average 64 KiB, gear table from the BLAKE3 XOF of "oxy1 fastcdc gear", spec §13.2); a receiver re-hashes every object.

4. Sequences

4.1 Clone or fetch

1. capabilities: check protocol version 1 and record the repository id.
2. refs: for each wanted bookmark note state, heads, attestation; take the policy and history.
3. Policy (spec §14.5): with no local policy, accept the remote's if it is for this repository and carries a valid signature by one of its own roots (trust on first use). With a local policy, refuse a lower serial or a different policy at the same serial; otherwise verify each policy in the chain against the one before it (signatures by the previous roots meeting the previous threshold, serial strictly increasing) and adopt them in order. Record the highest serial this remote has ever presented and refuse a remote that later presents none or a lower one.
4. negotiate with have = local heads of every bookmark, want = the remote heads. The response lists the missing changes.
5. fetch those hashes (with max blob size for a partial clone). Store objects, changes and seals; verify every change's signatures and seals; under a policy, authenticate each new change (§14.4: signer is the author or a delegate of the author) and check it is authorised for the bookmark by the first matching rule (a rule key covers its rotation predecessors, and a delegate's signature counts for the author).
6. Verify the bookmark's attestation (kind = ref: repo id, name, old state, new state, serial) against the policy and against the serial you last recorded for that reference (rollback protection), then update remotes/<name>/<bookmark>.
7. Tags: adopt those not yet held, checking their attestations the same way.

A shallow clone replaces steps 4–5 by shallow (the hashes within the depth) plus checkpoint for the heads, and fetches only the listed changes; their missing dependencies form the boundary. Lazy blobs are fetched later with objects.

4.2 Push

1. capabilities and refs as above; refuse if the remote's policy is newer than yours (fetch first).
2. Compute the changes the remote lacks (negotiate with the roles reversed, or locally from the remote heads), bundle them in dependency order with their signatures, seal your unsigned changes with one seal attestation, and attach identities, blobs, chunks and the new state object.
3. Attest the reference: kind = ref with serial = the remote's last serial + 1, signed by your key.
4. Send push with old state = the state the remote reported (empty state ref when the bookmark is new), the new state, and your policy with its intermediate history when the remote's serial is behind.

4.3 What a server checks on push

In this order, spec §16.4: adopt the policy chain if present (each step verified against the previous policy); import the bundle, verifying every object's hash and, under a policy, every change's authentication and authorisation; verify the reference attestation (signer authorised for the name, serial above the last recorded); check old state equals the current state (compare-and-swap; force skips this check only); check the rule's allow_conflicts and require (signed, sealed, any); check every dependency of every change is present; then update the references atomically and record the attestation. Any failure rejects the whole push with ok = false and a reason.

4.4 Editors and tools on the same machine

A tool that drives a local repository does not speak this protocol; it runs oxy with --json (spec §24) and reads one JSON document per command. The VS Code extension in oxygen-vscode/docs/spec.md §4 lists the commands it relies on.

5. Minimal implementations

A read-only client needs: CBOR decode, BLAKE3, the change and state decoders, capabilities/refs/negotiate/fetch, and the ability to materialise a state (spec §7–§9). Signature verification (Ed25519 and ML-DSA-65) is required to honour a policy; without it, treat every repository as unverified and say so.

A server needs the above plus storage, the push checks of §4.3, per- repository write serialisation, and the policy chain (refs key 4, bundle key 3). It never needs a private key of its own: servers store and forward signatures, they do not make them.

Test material: the encoders and decoders in crates/oxy-core/src/protocol.rs (wire module) and the round-trip and corruption tests beside them; the signature vectors in crates/oxy-core/src/identity.rs; and the chunking bounds test in crates/oxy-core/src/chunk.rs.