The graph owns identity: signed contributors, invites and revocations

[BY571]

The graph owns identity

Phase 2 of shared graphs (on top of #32, the transport). Who may write is written down in the graph and signed, not held on the server.

• contributors.yaml beside graph.yaml: {name: {key, role, revoked?, invited_by?, invite: {blob, sig}?}}. Keys are ed25519 signing keys (SSH key format, ssh-keygen -Y); everything still travels over HTTPS, there is no SSH access.

• knoten remote create makes your key, lists you as admin, and commits that constitution before the server hears about the graph. knoten key NAME shows or makes a key.

• knoten invite signs the invite with the admin's key; the server verifies it at /invite and again at /join. An invite is a bearer of a name and a role; the newcomer binds their own key when they join.

• knoten join clones, makes the newcomer's key, adds their own entry (carrying the admin-signed invite) and pushes it. Readers hold a token only; they are not listed.

• knoten revoke marks revoked: YYYY-MM-DD in the graph, signed by an admin, pushes, then kills the token. Idempotent; a failed server call after the push says to re-run.

• The gate is now Python (knoten gate, exec'd by the pre-receive hook) and checks every pushed commit against the contributors at its parent. Three shapes: unchanged constitution, any active writer; one added entry with an admin-signed invite, the newcomer's own key and nothing else in the commit; anything else, an active admin of the previous version. Merges refused; names are revoked, never removed; the constitution is never deleted.

• A hosted graph is one line of history: one branch, no tags, no deletions, no force-pushes, checked in the gate itself.

• Under knoten serve, only the admin token may bootstrap a constitution into a phase-1 graph, and that commit touches nothing else.

• Team workflow, added after review: knoten pull rebases (the gate refuses merges, so a merge could never be pushed; replayed commits are re-signed); knoten push refuses while the graph has uncommitted changes (knoten commit files a node, git commits it); a push behind the remote says pull first; knoten remote add on a signed graph configures signing for a listed name whose key is on this machine (the second-laptop path). SKILL.md has an "In a shared graph" section; README a worked team in three places, every command test-verified.

Known properties (by design)

• An invite is a bearer of a name and a role, not of a key: whoever holds the blob and signature joins as that name under any key. The role cannot be escalated, and a redeemed name cannot be joined again.
• The expires inside the signed invite blob is enforced nowhere; the server's own record of the invite gates /join. Same number, checked in one place.
• A hosted graph's directory cannot be renamed once it has a constitution: git mv g h is indistinguishable from deleting g's contributors.yaml, which is refused.
• Only under knoten serve does the admin token gate the first constitution. A bare repo gated by hand with knoten hook --server has no tokens, so there any key that names itself admin can bootstrap a phase-1 graph.
• Revocation is prompt, not instant: a push already past authentication runs to completion.
• Each pushed commit costs one signature verification per graph directory; MAX_PUSH_BYTES is the only bound on how much work one push can ask for.

Verification

python -m pytest tests -q -W error: 609 passed, no warnings (was 461 at the base of this branch).

Reviewed per task and as a whole by separate agents with mutation checks (each defence removed, a named test fails, restored). Spec section 17 "phase 2 as built" records the decisions.

🤖 Generated with Claude Code

https://claude.ai/code/session_013cJ97A5dq8ww3d7qoDfYxb