From 6c3f577842962dd57e9b14060fc2238d7f3ee30c Mon Sep 17 00:00:00 2001 From: tatulatu700-lang Date: Thu, 20 Aug 2026 16:46:50 +1000 Subject: [PATCH 1/3] docs: add initial language-agnostic PROTOCOL.md wire specification --- PROTOCOL.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 PROTOCOL.md diff --git a/PROTOCOL.md b/PROTOCOL.md new file mode 100644 index 000000000..f8761ff04 --- /dev/null +++ b/PROTOCOL.md @@ -0,0 +1,24 @@ +# Gitlawb Wire Protocol Specification (v1) + +## 1. Identity & DIDs +- **Key Type:** Ed25519 (`ed25519`). +- **Supported Methods:** `did:key`, `did:web`, and `did:gitlawb`. +- **Resolution:** Deterministic public key extraction from multicodec prefixes for verification. + +## 2. Authentication (RFC 9421) +- **HTTP Signatures:** Route requests require `Signature-Input` covering `@method`, `@path`, and `content-digest`. +- **Signer Identity:** `keyid` points to the actor DID; algorithm standard is `alg="ed25519"`. +- **Integrity:** `Content-Digest` SHA-256 header validation on mutating POST/PUT endpoints. + +## 3. Proof of Intelligence (iCaptcha) +- **Gate:** Enforced via `403 icaptcha_proof_required` responses. +- **Headers:** Clients must present `x-icaptcha-url`, `x-icaptcha-level`, and a valid `x-icaptcha-proof`. + +## 4. Ref-Update Certificate +- **Schema:** `gitlawb/ref-update/v1`. +- **Payload:** Canonical JSON bytes including target repository, commit OID, previous OID, and actor DID. +- **Validation:** Multi-signature threshold validation against configured branch protection rules. + +## 5. Storage & Git Transport +- **Smart-HTTP:** Standard `/{owner}/{repo}/info/refs` and `git-upload-pack` endpoints. +- **Content Addressing:** Git SHA-256 mapped to IPFS CID chunks with IPNS-backed branch pointers. From 3b00725fd37ff73c638017ec1047603a57599739 Mon Sep 17 00:00:00 2001 From: tatulatu700-lang Date: Thu, 20 Aug 2026 16:50:29 +1000 Subject: [PATCH 2/3] docs: add language-agnostic PROTOCOL.md wire spec --- PROTOCOL.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/PROTOCOL.md b/PROTOCOL.md index f8761ff04..72fcf3241 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -1,24 +1,23 @@ # Gitlawb Wire Protocol Specification (v1) ## 1. Identity & DIDs -- **Key Type:** Ed25519 (`ed25519`). -- **Supported Methods:** `did:key`, `did:web`, and `did:gitlawb`. -- **Resolution:** Deterministic public key extraction from multicodec prefixes for verification. +- **Key Types:** Ed25519 (`ed25519`). +- **Methods:** `did:key`, `did:web`, `did:gitlawb`. +- **Resolution:** Deterministic public key extraction from multicodec prefixes. ## 2. Authentication (RFC 9421) -- **HTTP Signatures:** Route requests require `Signature-Input` covering `@method`, `@path`, and `content-digest`. -- **Signer Identity:** `keyid` points to the actor DID; algorithm standard is `alg="ed25519"`. -- **Integrity:** `Content-Digest` SHA-256 header validation on mutating POST/PUT endpoints. +- **HTTP Signatures:** Requires `Signature-Input` covering `@method`, `@path`, and `content-digest`. +- **Signer Identity:** `keyid` points to the actor DID; algorithm is `alg="ed25519"`. +- **Integrity:** SHA-256 `Content-Digest` verification on write endpoints. ## 3. Proof of Intelligence (iCaptcha) - **Gate:** Enforced via `403 icaptcha_proof_required` responses. -- **Headers:** Clients must present `x-icaptcha-url`, `x-icaptcha-level`, and a valid `x-icaptcha-proof`. +- **Headers:** Clients must present `x-icaptcha-url`, `x-icaptcha-level`, and `x-icaptcha-proof`. ## 4. Ref-Update Certificate - **Schema:** `gitlawb/ref-update/v1`. -- **Payload:** Canonical JSON bytes including target repository, commit OID, previous OID, and actor DID. -- **Validation:** Multi-signature threshold validation against configured branch protection rules. +- **Payload:** Canonical JSON bytes defining target repo, commit OID, previous OID, and actor DID. ## 5. Storage & Git Transport -- **Smart-HTTP:** Standard `/{owner}/{repo}/info/refs` and `git-upload-pack` endpoints. +- **Smart-HTTP:** Endpoints at `/{owner}/{repo}/info/refs` and `git-upload-pack`. - **Content Addressing:** Git SHA-256 mapped to IPFS CID chunks with IPNS-backed branch pointers. From 31343d25af2b68146445f85c974440fa565aa26e Mon Sep 17 00:00:00 2001 From: Kevin Codex Date: Mon, 31 Aug 2026 14:35:09 +0800 Subject: [PATCH 3/3] docs: scope PROTOCOL.md to shipped alpha behavior Address all five review findings: did:key-only resolution (did:web / did:gitlawb marked planned), SHA-1 object format with IPNS demoted to planned and the REST refs CID mapping described instead, the receive-pack route and the 404-fetch vs 401-push auth split documented, iCaptcha wire shape corrected (client sends only x-icaptcha-proof; url/level are 403 response headers; ICAPTCHA_MODE defaults off over a small endpoint set), and the core gitlawb/ref-update/v1 schema spelled out field-for-field with node push receipts explicitly split off as a different document. --- PROTOCOL.md | 80 ++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 67 insertions(+), 13 deletions(-) diff --git a/PROTOCOL.md b/PROTOCOL.md index 72fcf3241..93c579635 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -1,23 +1,77 @@ -# Gitlawb Wire Protocol Specification (v1) +# Gitlawb Wire Protocol Specification (v1, alpha) + +This document describes the wire behavior a second implementation can interop +with **today**. Anything the node does not ship yet is explicitly marked +*planned*; nothing below is aspirational unless it says so. ## 1. Identity & DIDs -- **Key Types:** Ed25519 (`ed25519`). -- **Methods:** `did:key`, `did:web`, `did:gitlawb`. -- **Resolution:** Deterministic public key extraction from multicodec prefixes. + +- **Key type:** Ed25519. +- **Method (alpha):** `did:key` only. Resolution is deterministic public-key + extraction from the multicodec prefix (`z6Mk…`, multicodec `0xed01`). +- Signed requests presenting any other DID method are rejected; the node's + auth layer answers with a hint that only `did:key` is supported in alpha. +- *Planned:* `did:web` and `did:gitlawb` resolution. Clients MUST NOT assume + either is accepted anywhere yet. ## 2. Authentication (RFC 9421) -- **HTTP Signatures:** Requires `Signature-Input` covering `@method`, `@path`, and `content-digest`. -- **Signer Identity:** `keyid` points to the actor DID; algorithm is `alg="ed25519"`. -- **Integrity:** SHA-256 `Content-Digest` verification on write endpoints. + +- **HTTP signatures:** `Signature-Input` covers `@method`, `@path`, and + `content-digest`: + `sig1=("@method" "@path" "content-digest");keyid="did:key:…";alg="ed25519";created=` +- **Signer identity:** `keyid` is the actor DID (`did:key` only, see §1). +- **Integrity:** `Content-Digest` is SHA-256 over the request body and is + verified when the header is present. ## 3. Proof of Intelligence (iCaptcha) -- **Gate:** Enforced via `403 icaptcha_proof_required` responses. -- **Headers:** Clients must present `x-icaptcha-url`, `x-icaptcha-level`, and `x-icaptcha-proof`. + +- **Mode:** controlled by `ICAPTCHA_MODE` = `off` | `shadow` | `enforce`, + **default `off`**. A node with the gate off never demands proof. +- **Scope:** the gate applies to a small set of write endpoints (agent + registration and repo create/fork), not to all writes. +- **Wire shape:** the client-supplied header is `x-icaptcha-proof` — that is + the only iCaptcha header a node reads from a request. When proof is + required and missing/invalid, the node answers + `403 icaptcha_proof_required` and sets `x-icaptcha-url` and + `x-icaptcha-level` **on the response** (also mirrored as JSON fields) so + the client can go solve a challenge and retry. ## 4. Ref-Update Certificate -- **Schema:** `gitlawb/ref-update/v1`. -- **Payload:** Canonical JSON bytes defining target repo, commit OID, previous OID, and actor DID. + +Two distinct certificate-shaped payloads exist; this section documents the +**core signing schema**, which is what `gitlawb/ref-update/v1` names: + +- **Type string:** `gitlawb/ref-update/v1`. +- **Body (canonical JSON, the signed bytes):** `type`, `repo` (the + repository DID), `ref_name`, `from` (previous hash, 64 hex chars, + all-zeros for a new ref), `to` (target hash, 64 hex chars), `seq` + (monotonically increasing, replay prevention), `timestamp` (RFC 3339), + `nonce`. +- **Signatures:** a list of `{signer: did:key, sig: base64url-unpadded + Ed25519}` entries appended outside the signed body; thresholds are counted + over distinct signers that verify. + +The node's REST API separately serves **push receipts** — a different, +node-issued JSON payload attesting that a push was processed. Receipts are +not `gitlawb/ref-update/v1` documents and are not interchangeable with them; +they are documented with the node's HTTP API, not here. ## 5. Storage & Git Transport -- **Smart-HTTP:** Endpoints at `/{owner}/{repo}/info/refs` and `git-upload-pack`. -- **Content Addressing:** Git SHA-256 mapped to IPFS CID chunks with IPNS-backed branch pointers. + +- **Object format:** bare repositories are created with + `--object-format=sha1`; production OIDs are 40 hex chars. *Planned:* + SHA-256 object format. +- **Smart-HTTP endpoints:** + - `GET /{owner}/{repo}/info/refs` — ref advertisement (fetch and push + service discovery). + - `POST /{owner}/{repo}/git-upload-pack` — clone/fetch. + - `POST /{owner}/{repo}/git-receive-pack` — push. **Authentication is + mandatory**: an unsigned push is refused with `401`. +- **Fetch vs push auth split:** fetch-side requests against a withheld or + private repo answer `404` (existence is not confirmed to unauthorized + callers), while the push path answers `401` for missing/invalid + signatures. A second implementation must not treat the two symmetrically. +- **Content addressing:** the node records IPFS CID metadata per branch and + serves it over REST (the repo `refs` endpoint maps branch heads to CIDs). + *Planned:* IPNS-backed branch pointers; IPNS is not part of the shipped + wire contract.