# 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](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 \0" || body`, where `` is one of `chunk blob change checkpoint op attest identity policy state` and `` 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 `//oxy/v1/`: | Method and path | Body | Response | |---|---|---| | `GET …/capabilities` | — | capabilities | | `GET …/refs` | — | refs response | | `POST …/negotiate` | negotiate request | `{0: [hashes]}` | | `POST …/fetch` | fetch request | Bundle | | `POST …/objects` | objects request | Bundle | | `POST …/checkpoint` | checkpoint request | Bundle | | `POST …/shallow` | shallow request | `{0: [hashes]}` | | `POST …/push` | push request | push response | 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 ` 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..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. Client capabilities: the reference client sends `User-Agent: oxy/` and `Oxy-Features: [,…]` on every request, a comma-separated list (blanks around entries and case are ignored, unknown entries too) of what it understands beyond the oxy 0.5.0 feature set. Servers may tailor their answers to the features a request declares, and a request without the header is a client of that era. Features so far: - `certified-tags`: the client authorizes a tag signed by a short-lived, certified key by a subject grant, its certificate checked at the time the host accepted the tag (spec §14.7; oxygen#129). A client without it authorizes a tag only by a key the policy's rule lists, a delegate of one or a rotation predecessor, and fails the whole clone or fetch on any other. So under a policy, a server leaves out of a `refs` answer to such a client every tag whose attestation's signer none of those authorizes (`Repo::refs_for_client`, applied by `oxy serve` and by default by every `oxy_server` host): that client sees the repository as if those tags did not exist. If it holds one of them already and pushes, it sends the tag again (it is not in the answer); the server already has it in the same state and takes it as it is. 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, `adjust_refs`, which tailors a refs answer to the request's headers and by default applies the rule above, 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; and `push_notes`, with which a host adds a note to a reference the push moved, which the client shows in place of "updated", #148), 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]]`. | Message | Encoding | |---|---| | Signature | `{0: key id bytes(32), 1: alg (1 = Ed25519 + ML-DSA-65), 2: Ed25519 bytes(64), 3: ML-DSA-65 bytes(3309)}` | | Signed attestation | `[attest bytes, [Signature]]` | | Signed policy | `[policy bytes, [Signature]]` (also the policy proposal file format) | | Capabilities | `{0: [protocol versions], 1: repo id bytes(16), 2: [feature names]}`; version `1`; features currently `["seal"]` | | Refs response | `{0: [ref], 1: repo id, 2: signed policy or null, 3: [tag], 4: [signed policy], 8: [tag]}`; key 8 (optional, only when there are any; oxygenhub#301) lists the tags withdrawn there, each a tag whose attestation is its `untag` attestation and whose key 4 is that attestation's acceptance when a short-lived key signed it; older readers ignore it | | ref | `{0: name, 1: state ref, 2: [heads], 3: signed attestation or null, 4: last serial or null, 5: signed acceptance}`; the attestation is present only when it describes the current state; `last serial` is the highest attestation serial ever recorded for the name; key 5 (optional, only when there is one) is the host's `accepted` attestation of that attestation (spec §14.7); key 6 (optional) is `[entry number, entry bytes, [proof hash]]`, the attestation's inclusion proof in the host's transparency log against the response's key 6, the latest checkpoint as a signed note (spec §14.8) | | tag | `{0: name, 1: state ref, 2: [heads], 3: signed attestation or null, 4: signed acceptance, 5: log place, 6: [cosigned checkpoint]}`; keys 4 to 6 (optional, each only when there is one; oxygen#129) are for the tag's attestation what a ref's keys 5 to 7 are for its own: the issuer's `accepted` attestation when a short-lived key signed the tag (spec §14.7), which a fetch checks the certificate at, and its place in the host's transparency log with the cosigned checkpoints that first held it (spec §14.8); a push carries key 4 when the client has one; older readers ignore them | | Negotiate request | `{0: [have], 1: [want]}`; response `{0: [hashes]}` in dependency order (no change before its dependencies) | | Fetch request | `{0: [hashes], 1: max blob size or null}`; response a Bundle whose blobs above the size (and their chunks) are omitted | | Objects request | `{0: [refs]}`; response a Bundle carrying only objects; a blob is accompanied by its chunks | | Checkpoint request | `{0: [heads]}`; response a Bundle of objects: the checkpoint of exactly those heads, its payload blob, and the blob's chunks; the server computes one when it has none for those heads | | Shallow request | `{0: [heads], 1: depth}`; response `{0: [hashes]}`: the changes within `depth` dependency steps of the heads, dependencies first | | Bundle | `{0: [[change bytes, [Signature]]], 1: [signed attestation], 2: [[type name, object bytes]], 3: [signed policy]}` | | Push request | `{0: Bundle, 1: [update], 2: signed policy or null, 3: [tag]}`; a tag whose attestation is an `untag` attestation withdraws that tag (oxygenhub#301), reported as `tags/`; an older server refuses it as an attestation of the wrong kind | | update | `{0: name, 1: old state ref, 2: new state ref, 3: force (bool), 4: signed attestation or null}` | | Push response | `{0: [{0: name, 1: ok (bool), 2: reason (text)}]}`; a result named `policy` reports the policy update, `tags/` each tag | 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//`. 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`.