Skip to content
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
2a8d64d
feat(core)!: verify_chain returns the proof chain's root issuer
Vasanthdev2004 Aug 14, 2026
13a2424
fix(node): gate two Unix-only tests so the crate compiles on Windows
Vasanthdev2004 Aug 14, 2026
1b1c972
feat(node): carry the verified UCAN and its root into the request
Vasanthdev2004 Aug 14, 2026
f8b9cf1
feat(node): add ucan_grants_push, anchored at the repo owner
Vasanthdev2004 Aug 14, 2026
d27f0be
feat(node): honour a delegated git/push capability on the push path
Vasanthdev2004 Aug 14, 2026
d141e59
feat(gl): gl ucan import stores a delegation for the push helper
Vasanthdev2004 Aug 14, 2026
3d81f57
feat(git-remote): send a delegated push capability as X-Ucan
Vasanthdev2004 Aug 14, 2026
8843c4f
test(git-remote): cover pack-POST URL splitting
Vasanthdev2004 Aug 14, 2026
a9e9c48
build: sync Cargo.lock for the git-remote-gitlawb dependencies
Vasanthdev2004 Aug 14, 2026
f455726
fix(core,gl,git-remote): close two review findings on delegated push
Vasanthdev2004 Aug 14, 2026
a2502fc
fix(core,node,gl,git-remote): close the second review round on delega…
Vasanthdev2004 Aug 14, 2026
d503655
fix(gl): restrict the delegations directory, and state the contract
Vasanthdev2004 Aug 14, 2026
5071524
fix(gl,git-remote): make a delegation issued the documented way actua…
Vasanthdev2004 Aug 15, 2026
5dfd8c5
fix(gl): refuse a relative or non-UTF-8 GITLAWB_KEY when deriving the…
Vasanthdev2004 Aug 15, 2026
e15fa73
fix(identity): one resolver for GITLAWB_KEY across gl and the helper
Vasanthdev2004 Aug 16, 2026
05fc52d
test(git-remote): cover delegation_header end to end
Vasanthdev2004 Aug 16, 2026
75aa1a0
fix(gl): finish the identity-path sweep on the write side
Vasanthdev2004 Aug 16, 2026
fad75a6
fix(gl,core): close round five — lazy home, envelope reads, honest re…
Vasanthdev2004 Aug 18, 2026
82f2484
fix(node,gl,git-remote): enforce repo narrowing at the node, honour t…
Vasanthdev2004 Aug 22, 2026
a47ea93
fix(gl): align the MCP ucan_show tool with gl ucan show
Vasanthdev2004 Aug 22, 2026
ec4399c
fix(gl): drop a needless borrow in quickstart's unix key write
Vasanthdev2004 Aug 22, 2026
1ab55e5
fix(node,gl,git-remote): fix a delegation's scope at issuance
Vasanthdev2004 Aug 22, 2026
89fa647
Merge origin/main into feat/ucan-push-authorization
Vasanthdev2004 Aug 27, 2026
9cf48f5
fix(gl): drop an unused import in the unix-only refresh tests
Vasanthdev2004 Aug 27, 2026
04e7941
fix(node): pass the UCAN extension at the last two receive-pack call …
Vasanthdev2004 Aug 27, 2026
f79309b
fix(core,node,gl,git-remote): one definition of a usable push capability
Vasanthdev2004 Sep 8, 2026
4dc62b2
fix(node): drop repo_capability_matches, orphaned by the shared push …
Vasanthdev2004 Sep 8, 2026
1da4251
fix(core,gl): bound every proof-chain walk and make verify report the…
Vasanthdev2004 Sep 8, 2026
fb831b1
docs: state the two gates a delegated push crosses, and finish the sweep
Vasanthdev2004 Sep 8, 2026
8b91f28
fix(gl): store one repository per imported delegation; pin the two-ga…
Vasanthdev2004 Sep 8, 2026
e3314c6
fix(gl,core): sanitize token-derived output, prove the publish step, …
Vasanthdev2004 Sep 8, 2026
1b5cb7d
test(gl): count the MCP tool list at 41 with ucan_import
Vasanthdev2004 Sep 8, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
docs: state the two gates a delegated push crosses, and finish the sweep
Round eleven of #331, documentation half.

A `git push` crosses two independent gates: read visibility on the
`info/refs` advertisement, and push authorization on the receive-pack
POST. This PR implements the second and left the first as it was, and a
UCAN grants no read access — so on a private repository a delegate must
also be a reader. Nothing said so. RUN-A-NODE now states the contract
once, in the owner-push section, and the delegation section carries a
"Private repositories" note with the `gl visibility set` invocation and
a "One repository per token" note matching what import enforces.

The rest is the drift the earlier doc edits left behind: the README
env-var table still said a `git/push` capability was "verified but not
yet honored", the known-limitations bullet still said enforcement
defaults to `false`, and the RUN-A-NODE section opened with a blanket
403 for every non-owner two paragraphs above the text that says a
delegate can push. All three now describe the same node.
  • Loading branch information
Vasanthdev2004 committed Sep 8, 2026
commit fb831b103739ccfce72b434bb677644be8e72b57
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,8 +66,8 @@ Good today:

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 capabilities are consulted on the push path only. There, the chain's root issuer is anchored to the repository owner, so an owner-rooted, time-bounded delegation that names the repository grants scoped collaborator access for pushing to it, for the `git/push`, `*`, or `repo/admin` actions. A `*` *resource* is refused: a delegation must name the repository it applies to, so it cannot grow to cover repos created later. The rest is unchanged: there is no revocation path, `nb` constraints are refused rather than interpreted, and no other route — reads, pull requests, issues, agents — consults capabilities at all.
- Repository write authorization is one switch: `GITLAWB_ENFORCE_OWNER_PUSH`, on by default since #330. With it off — rolling upgrades only — a valid HTTP Signature identifies a pusher but does not authorize one, so every signed caller may push everywhere.
- UCAN capabilities are consulted on the push path only. There, the chain's root issuer is anchored to the repository owner, so an owner-rooted, time-bounded delegation that names the repository grants scoped collaborator access for pushing to it, for the `git/push`, `*`, or `repo/admin` actions. A `*` *resource* is refused: a delegation must name the repository it applies to, so it cannot grow to cover repos created later. Push-only cuts the other way too: a delegation grants no read access, so on a private repository the delegate must also be a reader (`gl visibility set`) — the two gates a push crosses are described in [`docs/RUN-A-NODE.md`](docs/RUN-A-NODE.md). The rest is unchanged: there is no revocation path, `nb` constraints are refused rather than interpreted, and no other route — reads, pull requests, issues, agents — consults capabilities at all.
- 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.
Expand Down Expand Up @@ -393,7 +393,7 @@ Important node settings:
| `GITLAWB_P2P_BOOTSTRAP` | Comma-separated libp2p multiaddrs. |
| `GITLAWB_BOOTSTRAP_DISABLE_SEEDS` | Disable embedded seed peers for isolated dev/test networks. |
| `GITLAWB_REQUIRE_SIGNED_PEER_WRITES` | Require signed peer announce/sync writes. Defaults to `false` during the staged rollout below. |
| `GITLAWB_ENFORCE_OWNER_PUSH` | Require the authenticated pusher to be the repo owner on `git-receive-pack`. **Defaults to `true`.** A `did:key` signature is authentication, not authorization — anyone can mint a key and sign — so with this off every signed caller may push to every repository, private ones included. Delegated and CI keys count as non-owners: a UCAN `git/push` capability is verified but not yet honored for authorization, so they cannot push while this is on. Set `false` only for a rolling upgrade; see [`docs/RUN-A-NODE.md`](docs/RUN-A-NODE.md). |
| `GITLAWB_ENFORCE_OWNER_PUSH` | Require the pusher on `git-receive-pack` to be the repo owner, or to present an owner-rooted, time-bounded UCAN `git/push` capability naming the repository (`X-Ucan`). **Defaults to `true`.** A `did:key` signature is authentication, not authorization — anyone can mint a key and sign — so with this off every signed caller may push to every repository, private ones included. A CI or delegated key with no such delegation counts as a non-owner and cannot push while this is on. The delegation clears the push gate only; on a private repository the delegate must also be a reader. Set `false` only for a rolling upgrade; see [`docs/RUN-A-NODE.md`](docs/RUN-A-NODE.md). |
| `GITLAWB_AUTO_SYNC` | Enable automatic sync from known peers. |
| `GITLAWB_MAX_PACK_BYTES` | Max git pack body size for smart-HTTP routes. |
| `GITLAWB_GIT_SERVICE_TIMEOUT_SECS` | Max seconds a served git upload-pack, receive-pack, or `info/refs` advertisement may run before it is aborted (504). Default 600. Also bounds the withheld-blob classification walk (on both the upload-pack serve and receive-pack replication paths) and the push-side pin-candidate discovery (`rev-list` / `cat-file`), each reaped via process-group teardown at the deadline. On the path-scoped upload-pack path the classification walk and the pack serve share ONE deadline, so this value bounds their combined duration rather than granting each stage a full budget: a walk that consumes it leaves the serve nothing and the clone gets a 504. Serving large path-scoped repos may therefore need a higher value than they did when each stage was budgeted separately. Accepted range is 1 to 3153600000 (100 years), since the node derives deadlines from this value and a larger one cannot be represented. |
Expand Down
43 changes: 40 additions & 3 deletions docs/RUN-A-NODE.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,9 +143,11 @@ During the cooldown your node still earns rewards if it keeps heartbeating.

## Owner-only push

The node requires the authenticated pusher to be the repo owner on **every**
branch. A push whose authenticated DID is not the repo owner is rejected with
HTTP 403 before any ref update is applied. The owner is matched in both the full
On the `git-receive-pack` POST — the push itself — the node requires the
authenticated pusher to be the repo owner, or to present a UCAN whose proof chain
roots at the owner and carries `git/push` for this repository (see *Delegating
push to a CI agent* below). Anyone else is rejected with HTTP 403 before any ref
update is applied, on **every** branch. The owner is matched in both the full
`did:key:z6Mk…` form and its bare `z6Mk…` suffix.

This is on by default, and the default is the point. The node authenticates every
Expand All @@ -155,6 +157,20 @@ Authentication is not authorization, so without this gate every signed caller ca
push to every repository — private ones included — on any branch that is not
explicitly protected.

A `git push` crosses two independent gates, and this section is about the second:

1. **Read visibility**, on the `info/refs` advertisement that precedes every fetch
*and* every push. The node admits the owner, anyone on a public repository, and
a caller that a visibility rule names among its readers; everyone else gets a
404, since a private repository is not confirmed to exist for a non-reader. A
UCAN plays no part here — a delegation grants no read access.
2. **Push authorization**, on the `git-receive-pack` POST: the owner, or an
owner-rooted, bounded, repository-scoped push delegation.

Both must pass. On a public repository the first is open to everyone, so a
delegation alone is enough; on a private one the delegate must also be a reader —
see *Private repositories* below.

### Turning it off

```bash
Expand Down Expand Up @@ -200,6 +216,27 @@ What the node requires, and why:
| No `nb` constraints | Constraints are reserved but not yet interpreted, so a capability carrying them authorizes nothing rather than silently granting more than the owner intended. |
| The token is addressed to the pusher | The node requires the proof's audience to equal the invocation's issuer, and `gl ucan import` refuses a token addressed to another identity rather than storing one that can only fail. |

**Private repositories.** A delegation clears the push gate only. The `info/refs`
advertisement that `git push` fetches first is read-gated, and a UCAN grants no
read access, so on a private repository the delegate must also be a reader:

```bash
# Owner: let the agent read the whole repository
gl visibility set / --repo <repo> --readers did:key:z6MkAgent…
```

Without it the agent's push fails at the advertisement with a 404 — the same
answer a stranger gets, because a private repository is not confirmed to exist
for a non-reader — even though the delegation itself is valid and would clear the
push gate. On a public repository this step is unnecessary. The two gates are
independent in the other direction as well: a reader with no delegation is still
refused on the push.

**One repository per token.** `gl ucan delegate` issues one capability per token,
and `gl ucan import` stores one repository per token. A hand-built token that
names several repositories is refused at import rather than applied to some of
them; ask the owner for one delegation per repository.

**A delegation does not override branch protection.** A protected branch is your
explicit marker that even routine writes should stop, so a delegate is still
refused there and only the owner may push. That is deliberate: if a delegation
Expand Down