From 505c45237873e1212b2bcffbcc099c91488a4e7c Mon Sep 17 00:00:00 2001 From: anandh8x Date: Fri, 14 Aug 2026 20:19:11 +0530 Subject: [PATCH 1/2] docs: correct security and workspace status --- README.md | 18 +++++++++++------- SECURITY.md | 47 +++++++++++++++++++++++++++-------------------- 2 files changed, 38 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 1588161f..d71c9068 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ The mission is simple: once code is pushed to the network, it should not disappe ## What is in this repository? -This is a Rust workspace with four crates: +This is a Rust workspace with six crates: | Crate | Purpose | |---|---| @@ -27,6 +27,8 @@ This is a Rust workspace with four crates: | `gl` | The Gitlawb CLI for identity, repos, issues, PRs, bounties, tasks, peers, node status, MCP, and setup flows. | | `git-remote-gitlawb` | Git remote helper for `gitlawb://` URLs, so normal `git clone`, `git fetch`, and `git push` can talk to Gitlawb nodes. | | `gitlawb-core` | Shared primitives: Ed25519 identities, `did:key`, CIDs, RFC 9421 HTTP signatures, certificates, and UCAN tokens. | +| `gitlawb-attest` | Pluggable external provenance attestations for ref-update certificates. | +| `icaptcha-client` | Client for the iCaptcha proof-of-intelligence flow used to protect spam-prone writes. | --- @@ -54,6 +56,7 @@ Good today: - Bare git repository storage. - Git smart-HTTP clone/fetch/push. - RFC 9421-signed writes. +- Repository and path-scoped read visibility enforcement, including 404-shaped denials. - DID identities. - `gl` CLI workflows. - libp2p peer discovery/gossip foundation. @@ -63,11 +66,12 @@ Good today: Known limitations: -- Private repository read enforcement is not wired yet. Treat public nodes as public infrastructure unless you restrict access at your proxy/firewall. -- UCAN chain validation and revocation are not complete. -- Repository write authorization is not capability-complete yet; HTTP signatures prove identity, not full authorization policy. +- Repository write authorization is not secure by default: `GITLAWB_ENFORCE_OWNER_PUSH` defaults to `false` for compatibility, so a valid HTTP Signature identifies a pusher but does not enforce owner-only pushes. +- UCAN proof chains are validated when supplied, but UCAN capabilities are not consulted by write authorization and the root issuer is not independently trust-anchored. UCANs therefore do not yet grant scoped collaborator access. +- Agent lifecycle revocation is not enforced by HTTP Signature authorization; do not rely on removing or revoking an agent record to block a compromised signer. - Peer writes are signed by upgraded nodes, but strict signed-peer enforcement is opt-in during rolling upgrades. -- GraphQL mutations need mutation-aware auth before becoming a public write surface. +- Current GraphQL mutations require an authenticated signer, but there is no mutation-specific guardrail that prevents a future mutation from omitting that check. +- Pull-request review comments do not yet have threaded line-level anchors, and merges do not enforce approval requirements. See: @@ -466,8 +470,8 @@ Short-term priorities: 2. Add Docker and installer smoke tests. 3. Improve operator docs and `gl doctor` checks. 4. Harden peer writes and publish the signed-peer rollout plan. -5. Implement repo write authorization: owner checks, protected branches, and UCAN capability checks. -6. Implement private-read enforcement or remove private repo affordances until it exists. +5. Close default-open write authorization and wire trusted UCAN delegation into repository permissions. +6. Add threaded, line-level pull-request discussions and enforce approval requirements on merges. 7. Add metrics for pushes, fetches, pack sizes, peer sync, failed auth, and webhooks. Product direction: diff --git a/SECURITY.md b/SECURITY.md index 422c1582..9fa7ecf8 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -28,10 +28,11 @@ We will acknowledge receipt within 48 hours and aim to release a fix within 14 d - Every git object is content-addressed via CIDv1 (SHA-256) - Tamper-evident by construction — a modified object changes its CID -**UCAN capability tokens** -- Bootstrap UCAN tokens issued at registration -- Capability-scoped: `git:push`, `git:fetch`, `issue:create`, `pr:open` -- JWT-format tokens with expiry +**UCAN token validation** +- Bootstrap UCAN tokens are issued at registration. +- A supplied token's signature, audience, expiry, and proof-chain attenuation are validated. +- Tokens use a signed JSON wire format with expiry. +- Capability grants are not yet consulted by repository write authorization; see the limitations below. **Smart contracts (Base Sepolia testnet)** - `GitlawbDIDRegistry` — on-chain DID → document registry @@ -48,21 +49,20 @@ We will acknowledge receipt within 48 hours and aim to release a fix within 14 d --- -## Known Limitations (Planned for v0.2) +## Known Limitations -These are **documented, accepted limitations** for the current live release and should be prioritized without breaking existing nodes during rolling upgrades. +These are documented limitations of the current live release. They should be prioritized without breaking existing nodes during rolling upgrades. -### UCAN chain validation -- The auth middleware verifies HTTP Signatures and token structure, but does not yet walk the full UCAN delegation chain. -- **Impact:** A node cannot yet enforce fine-grained capability delegation. Currently, any registered agent with a valid HTTP Signature can push. -- **Mitigation:** Keep write endpoints signed, treat public nodes as public infrastructure, and treat trust scores as soft rate-limiting signals rather than authorization. -- **Fix target:** v0.2 +### Repository write authorization defaults +- `git-receive-pack` verifies HTTP Signatures, but `GITLAWB_ENFORCE_OWNER_PUSH` defaults to `false` for compatibility during rollout. +- **Impact:** With the default setting, a valid signature authenticates the pusher but does not require that DID to be the repository owner. +- **Mitigation:** Set `GITLAWB_ENFORCE_OWNER_PUSH=true` on nodes where owner-only pushes are required. Confirm that every legitimate pusher uses the owner DID before enabling it. -### UCAN revocation -- Issued UCAN tokens cannot be revoked before expiry. -- **Impact:** If a keypair is compromised, the attacker retains access until the UCAN expires (default: 30 days). -- **Mitigation:** Regenerate your identity (`gl identity new --force`) and re-register to issue a new UCAN. Until revocation/blocklisting is implemented, operators should remove compromised DIDs directly from their local database. -- **Fix target:** v0.2 +### UCAN delegation and revocation +- The middleware validates a supplied UCAN's complete proof chain, but a root token is accepted without an independently trusted issuer anchor. `Ucan::can` is not yet used by write handlers, so a UCAN does not grant scoped repository access. +- Agent lifecycle revocation is not checked by HTTP Signature authorization. Removing or revoking an agent record does not itself block a compromised DID from authenticating. +- **Impact:** Do not use UCANs for collaborator permissions or rely on agent-record revocation as a key-compromise response. +- **Mitigation:** Keep sensitive deployments behind operational network controls and enable owner-only push enforcement where it fits the deployment until trusted delegation and authorization-aware revocation are implemented. ### git-receive-pack authentication - The `git-receive-pack` endpoint enforces HTTP Signature auth. Plain Git smart-HTTP clients do not generate those headers, so the `git-remote-gitlawb` helper is required for pushes. @@ -71,10 +71,17 @@ These are **documented, accepted limitations** for the current live release and - **Fix target:** v0.2 ### Private repository reads -- Repository records have an `is_public` field and the node exposes `GITLAWB_PUBLIC_READ`, but per-repository private-read enforcement is not wired in the current live release. -- **Impact:** Do not store private repositories or secrets on public nodes. -- **Mitigation:** Run isolated nodes for non-public data and restrict network access at the reverse proxy or firewall layer. -- **Fix target:** v0.2 +- Repository and path-scoped visibility checks are enforced for API and Git content reads. A denied read returns the same 404 shape as a missing repository, so the denial does not reveal repository or withheld-path existence. +- **Impact:** Callers can read only repositories and paths their visibility rules permit. +- **Remaining boundary:** This read control does not address the independent write-authorization and UCAN-delegation limitations described above. + +### Pull-request review enforcement +- Pull-request review comments are not yet threaded or line-anchored, and merges do not enforce required approvals. +- **Impact:** Teams must use their own review policy or external controls for merge approval requirements. + +### GraphQL mutation coverage +- Existing GraphQL mutations require an authenticated signer, but a mutation-specific source-level guardrail has not yet been added for future mutations. +- **Impact:** A new mutation could accidentally omit its signer check without an explicit test fence. ### Peer route hardening rollout - Peer announce and sync notification routes accept signed requests and verify DID matches when a signature is present. From 0b47e1fc08a94a013677f369022423a9bfe1fcd2 Mon Sep 17 00:00:00 2001 From: anandh8x Date: Sat, 15 Aug 2026 10:32:24 +0530 Subject: [PATCH 2/2] docs: clarify visibility limits --- CONTRIBUTING.md | 6 ++++-- README.md | 3 ++- SECURITY.md | 11 +++++++---- docs/MAINTAINER-ROADMAP.md | 4 ++-- docs/OSS-READINESS-AUDIT.md | 5 +++++ 5 files changed, 20 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ad8e8c1..33f2f133 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,9 @@ crates/ ├── gitlawb-core/ crypto primitives (DID, CID, HTTP sigs, UCAN, ref certs) ├── gitlawb-node/ axum HTTP server, git smart HTTP, P2P, GraphQL ├── gl/ CLI — identity, repos, MCP server, Base L2 names -└── git-remote-gitlawb/ git remote helper for gitlawb:// URLs +├── git-remote-gitlawb/ git remote helper for gitlawb:// URLs +├── gitlawb-attest/ provenance attestations for ref-update certificates +└── icaptcha-client/ client for the iCaptcha proof-of-intelligence service docs/ Operator guides scripts/ Build helpers ``` @@ -106,7 +108,7 @@ cargo test -p gitlawb-node - **TypeScript SDK** (`@gitlawb/sdk`) — client library for the HTTP API - **Python SDK** (`gitlawb`) — for ML/agent pipeline integration -- **UCAN chain validation** — complete the auth middleware +- **UCAN authorization** — add trusted issuer anchoring, capability checks, and authorization-aware revocation - **Filecoin storage tier** — wire up cold storage deals - **Documentation** — guides, tutorials, API examples - **Node operators** — run a public node and report issues diff --git a/README.md b/README.md index d71c9068..643992c2 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Good today: - Bare git repository storage. - Git smart-HTTP clone/fetch/push. - RFC 9421-signed writes. -- Repository and path-scoped read visibility enforcement, including 404-shaped denials. +- Repository and path-scoped visibility enforcement for repository and Git content reads, with 404-shaped repository denials. - DID identities. - `gl` CLI workflows. - libp2p peer discovery/gossip foundation. @@ -69,6 +69,7 @@ Known limitations: - Repository write authorization is not secure by default: `GITLAWB_ENFORCE_OWNER_PUSH` defaults to `false` for compatibility, so a valid HTTP Signature identifies a pusher but does not enforce owner-only pushes. - UCAN proof chains are validated when supplied, but UCAN capabilities are not consulted by write authorization and the root issuer is not independently trust-anchored. UCANs therefore do not yet grant scoped collaborator access. - Agent lifecycle revocation is not enforced by HTTP Signature authorization; do not rely on removing or revoking an agent record to block a compromised signer. +- Read visibility is not a blanket data-classification boundary: task, IPFS-pin, and Arweave-anchor listings are not repository-gated; withheld path names can be visible to a root reader; and later visibility changes cannot retract content already announced or externally anchored. - Peer writes are signed by upgraded nodes, but strict signed-peer enforcement is opt-in during rolling upgrades. - Current GraphQL mutations require an authenticated signer, but there is no mutation-specific guardrail that prevents a future mutation from omitting that check. - Pull-request review comments do not yet have threaded line-level anchors, and merges do not enforce approval requirements. diff --git a/SECURITY.md b/SECURITY.md index 9fa7ecf8..bbe97e7e 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -71,8 +71,11 @@ These are documented limitations of the current live release. They should be pri - **Fix target:** v0.2 ### Private repository reads -- Repository and path-scoped visibility checks are enforced for API and Git content reads. A denied read returns the same 404 shape as a missing repository, so the denial does not reveal repository or withheld-path existence. -- **Impact:** Callers can read only repositories and paths their visibility rules permit. +- Repository and path-scoped visibility checks are enforced for repository API and Git content reads. A denied whole-repository or root read returns the same 404 shape as a missing repository, so the denial does not reveal private-repository existence. +- Sparse-clone support exposes withheld path globs to callers who may read the repository root. Do not put sensitive information in withheld path names. +- `GET /api/v1/tasks`, `/api/v1/ipfs/pins`, and `/api/v1/arweave/anchors` are not repository-gated. Task records include a UCAN token; pin and anchor listings expose object and ref metadata. +- Changing a repository's visibility controls future serving, but cannot retract ref metadata or configured external pins and anchors already announced while the repository was public. Do not push secrets to an announceable repository. +- **Impact:** Visibility policies protect the repository and Git content routes they gate, not every metadata endpoint or previously published content. - **Remaining boundary:** This read control does not address the independent write-authorization and UCAN-delegation limitations described above. ### Pull-request review enforcement @@ -108,7 +111,7 @@ These are documented limitations of the current live release. They should be pri | Key storage | PKCS#8 PEM, 0600 permissions | | Content hashing | SHA-256 via CIDv1 | | HTTP Signatures | RFC 9421 (Ed25519 + SHA-256 Content-Digest) | -| UCAN tokens | JWT (Ed25519 signatures) | +| UCAN tokens | Signed JSON object (Ed25519 signature) | | On-chain | ECDSA secp256k1 (Base L2 / Ethereum) | --- @@ -116,7 +119,7 @@ These are documented limitations of the current live release. They should be pri ## Threat Model gitlawb is designed to be secure against: -- **Unauthorized writes** — HTTP Signature auth on all write endpoints +- **Unauthenticated writes** — HTTP Signature auth on protected write endpoints; see Known Limitations for owner and capability authorization gaps - **Tampered git objects** — CIDv1 content addressing detects modification - **Identity spoofing** — DIDs derived from public keys, unforgeable without the private key - **Centralized takedown** — no single point of control; data on IPFS + Arweave diff --git a/docs/MAINTAINER-ROADMAP.md b/docs/MAINTAINER-ROADMAP.md index 9e1a73fd..0fb2eb77 100644 --- a/docs/MAINTAINER-ROADMAP.md +++ b/docs/MAINTAINER-ROADMAP.md @@ -38,8 +38,8 @@ Owner focus: node reliability. Owner focus: protocol/auth. -- Implement repo write authorization: repo owner checks, protected branches, UCAN capability checks, and clear delegation semantics. -- Implement private-read enforcement or remove private-repo affordances until it exists. +- Close default-open repo write authorization and wire trusted UCAN delegation into repository permissions. +- Close the remaining visibility gaps: restrict or document task, pin, and anchor metadata routes, and publish an irreversible-publication policy. - Add UCAN revocation or blocklisting, with an emergency compromised-key runbook. - Add mutation-aware GraphQL auth before GraphQL becomes a public write API surface. - Harden peer registration and outbound peer calls against SSRF and peer-list poisoning. diff --git a/docs/OSS-READINESS-AUDIT.md b/docs/OSS-READINESS-AUDIT.md index 0a0bc5f2..653e0453 100644 --- a/docs/OSS-READINESS-AUDIT.md +++ b/docs/OSS-READINESS-AUDIT.md @@ -3,6 +3,11 @@ Date: 2026-05-28 Repo state inspected: `main` tracking `origin/main`, starting at `b12c6bc feat: per-DID rate limiting on creation endpoints (10/hour) (#13)`. +> **Historical snapshot.** This audit describes the repository at the commit above. Its +> statements about incomplete UCAN chain validation and absent per-repository read +> enforcement have been superseded; see [`SECURITY.md`](../SECURITY.md) for the current +> security posture. + ## Commands run ```sh