Hit for real driving a first sign-in: `granthi-sync link` run through anything
that is not a terminal -- a wrapper, a pipe, `| tee setup.log` -- printed
NOTHING, while the code it was holding silently expired five minutes later.
Python buffers stdout when stdout is not a tty, and the two prints carrying
the verification URL and the user code did not flush.
They flush now. One regression test asserts both are printed with flush=True,
because this fails silently and only under redirection, which is exactly the
condition a test would otherwise never reproduce.
204 tests (was 203).
Written because the walkthrough only existed in a chat log, and a new machine
reads its instructions from the clone.
Leads with the thing that will otherwise look like a bug: a first sign-in can
produce a NEW EMPTY account rather than one you already had, because Granthi
refuses to hand over an existing account just because the login name lines up.
The guide explains why that rule exists and gives both ways forward -- fresh
account (recommended, since the saved token acts as whatever account it is
bound to) or joining an existing one via a verified email match.
Also documents what people actually trip on: an empty `list` is a permissions
answer not a failure; a bare repo name that matches two teams is refused
rather than guessed; sign-out takes effect at the server, immediately; and
restore always writes to a new folder.
Plain language throughout, per the estate's 5th-grade rule for docs.
Verified: all 13 commands and every flag referenced exist in the client.
Found by running the real flow on a fresh clone against production, not by a
test: `granthi-sync get Ai-Assistant` failed with "Repository not found".
`get <name>` meant `<your-login>/<name>` and nothing else, but of 172 repos
granted to this estate's own admin, 157 are owned by an ORG -- so the bare
name failed for 91% of what a user can actually see, with an error that reads
like a permissions problem rather than a naming one.
A bare name is now matched against the granted list, which is the forge's own
answer about what this account may have. An owner-qualified name is taken as
given. An ambiguous bare name is REFUSED with its candidates rather than
guessed -- picking one of two repos called `notes` owned by different teams is
not a guess worth making for someone.
Best effort by design: if the listing is unreachable, a fully-qualified name
still clones and a bare name degrades to the caller's own namespace, so a
network blip cannot block a clone. The clone that follows reports the real
problem precisely.
cmd_bootstrap carried the same assumption and is fixed with it.
203 tests (was 198). Verified live afterwards: the failing command now clones
Nirlabinc/Ai-Assistant, and `get shreai` lists both candidates instead of
guessing.
Closes the last piece of the product picture: give one person access to some
of your repos and not others.
- POST /v1/grants add|remove|list -- runs on the CALLER'S OWN token. Verified
against the live forge that a repo owner's scoped token adds and removes
collaborators (204), so sharing needs no elevated rights anywhere.
- POST /v1/invite -- records a promise against a VERIFIED email and creates
nothing until it is redeemed. Applied on first link.
- client: share / shared / invite.
Three properties the tests pin:
* the FORGE decides who may share (listing collaborators requires repo
admin, so its 200 is the authorisation answer, not ours);
* an unverified email collects nothing, and its invite stays pending rather
than being consumed;
* a failed grant never blocks a sign-in -- nobody is locked out of their own
account because a repo they were promised has since been deleted.
Applying an invite uses the admin credential deliberately: the inviter
authorised it at invite time and their session is long gone by redemption.
198 tests (was 184).
granthi-sync bootstrap <folder> reads a workspace.json and pulls the repos it
names, still bounded by what the forge grants: a manifest naming a repo this
account cannot see prints NOT GRANTED and continues, because that is a
permissions answer, not an error to route around.
It does NOT install applications. Dash, deck, genie and shiva each have their
own repo, deploy path and reviewers; a sync client installing them would
create a second unreviewed deploy path beside the real one. So apps are
REFERENCED -- the command prints each app's repo, model, setup doc and the
vault keys it needs, with the shre-cred line to supply them.
Per-repo mode overrides the default, so a documents folder can be declared
mirror while real projects stay on the safe snapshot default.
184 tests (was 178).
granthi-link is now public at https://granthi-link.shre.ai (cloudflared,
origin still tailnet-only), so the client defaults there instead of a tailnet
IP. Internal machines pass --server or GRANTHI_LINK_SERVER.
Two rollout traps recorded in the README: a third-level hostname
(link.granthi.shre.ai) fails TLS because Cloudflare Universal SSL covers
shre.ai and *.shre.ai only; and exposure REQUIRES trust_forwarded_for with
the tunnel as the sole trusted proxy, or every request looks like the tunnel
and one abuser spends everyone's rate budget.
178 tests.
Live QA: every call to /v1/devices/revoke returned 429 retry_after=3600.
The rule was written (0, 3600) with a comment saying 'never throttle someone
out of signing a lost laptop out' -- but in this limiter a limit of 0
DISABLES the endpoint outright. The comment said unlimited; the code said
never. Set to 600/hour instead.
Every unit test passed while the endpoint was 100% dead over HTTP, because
they called svc.revoke_device() directly and never went through the handler.
Added 4 tests that speak HTTP, including one that fails if ANY route in
DEFAULT_RATE_RULES is configured to 0.
176 tests (was 172).
Answers three questions that had no answer: which computers are connected,
how do I cut one off, and what is recorded.
- state.json gains a device registry hanging off the identity that owns it,
so 'which computers can reach my files' cannot drift from the identity map.
Clients older than v1.2 send no device_id and fall back to the token name,
so they still register.
- POST /v1/devices lists them; POST /v1/devices/revoke deletes that device's
forge token via admin basic auth + Sudo (verified 204 on 1.27.2, after
which the token is 401 immediately). Revocation is deliberately NOT rate
limited -- nobody should be throttled out of signing out a lost laptop.
- The device id is now part of the token NAME. Revocation deletes by name,
so two machines called 'macbook' linked in the same second would otherwise
collide and signing one out would kill the other.
- A failed forge deletion is not recorded as revoked: a registry claiming
'revoked' while the token still works is worse than an honest error.
- Append-only JSONL audit log (0600, rotates at 64MB), separate from
state.json because state is rewritten atomically on every change and an
audit trail the audited thing can rewrite is not one. A failed audit write
is logged loudly and never breaks the request.
- Authorisation everywhere: the forge decides who a token belongs to
(GET /api/v1/user). No login is ever read from the request body.
- Client: devices / logout / activity.
The audit log records granthi-link events only -- git pushes and pulls never
pass through this service. /v1/audit returns that caveat in its own response
rather than letting the log read as file activity.
172 tests (was 153).
Review found the read path scoped to the CURRENT device's uuid, which breaks
the exact case snapshot mode exists for: when the laptop dies, the
replacement machine has a new id, so snapshots printed 'no restore points
yet' while the backups sat on the forge, and restore errored. Reproduced,
then fixed by unscoping the READ only. Writing stays device-scoped (two
machines must not overwrite each other) and pruning stays device-scoped
(machine A must not apply its clock to machine B's refs); the docstring now
says why the three differ.
Also from the same review:
- mirror mode printed a %cI timestamp that restore could not accept, so
copying the first column looped the user back to snapshots. It now matches
the log, and refuses an ambiguous timestamp (two commits in one second)
with the candidate ids instead of guessing.
- the size guard advised 'add a .gitignore' while measuring with a plain
walk that ignored one. It now measures what git would sync, through a
throwaway git dir outside the folder so a refused add leaves no .git
behind.
- get --all caught only SystemExit, so a RuntimeError from any git call
abandoned the remaining repos.
- get --all mapped alice/notes and bob/notes to one path and reported the
second as 'already present'. Clashes now clone to <owner>-<name> and say so.
- the prune clock was in-memory, so watch --once under launchd pruned every
run. Persisted in config.
153 tests. Live-verified on the beta forge: machine A backed up uncommitted
work and was deleted; machine B, different device id, cloned the repo, listed
A's snapshot and restored both files.
Live QA against the beta forge failed its first push with 'Failed to
authenticate user' while the config held a valid token. Cause: credential.helper
is a list accumulated across system/global/repo config, and this machine has
osxkeychain (Xcode gitconfig) plus store (~/.gitconfig). A stale entry for the
forge host answered before our helper.
The same list is a token leak in the other direction: git calls approve on
every helper after a successful auth, so 'store' writes the forge token into
~/.git-credentials in plaintext -- undoing the 0600 config and the
no-token-in-URL rule. Confirmed accidentally during QA when a verification
clone with a URL-embedded token re-created exactly that entry.
Fix: set an empty credential.helper first (git reads that as 'forget the
inherited list'), then add ours -- in install_credential_helper and in the
git clone inside get.
2 regression tests, one of which drives 'git credential fill' against a
poisoned outer helper. 143 tests.
Two modes per linked folder. 'mirror' keeps today's behaviour for a plain
folder that add turned into a repo. 'snapshot' is new and is for a folder
that already had a git history: nothing is ever committed on the user's
behalf, and instead each pass builds a commit object from the working tree
via a scratch index + commit-tree and pushes it to
refs/granthi-backup/<device>/<ts>. HEAD, the index and every file stay
exactly as the user left them, so uncommitted, unmerged, half-finished work
leaves the machine with a timestamp to restore from.
Verified on the beta forge (Gitea 1.27.2) that a custom ref namespace is
accepted, readable via ls-remote, and absent from the branch list.
Also: retention (all for 24h, hourly for 7d, daily beyond; unparseable
timestamps kept), snapshots/restore commands, restore never writing over the
working tree, get --all bounded by what the forge grants, list <pattern>,
.gitignore seeding, an add size guard, and a persisted device_id.
141 tests (was 108).
Round 2 of review on the same branch:
- The fail-closed capacity guard was itself a DoS lever. MAX_RATE_KEYS was
global, and the limiter runs before auth, so a flood of cheap /v1/repos
keys could exhaust the table and 429 never-seen /v1/link clients until
live windows expired. Budgets are now per route.
- Rule values accepted booleans: bool subclasses int, so isinstance let
[5, true] through as a 1-SECOND window (5/hour -> ~5/sec) and false in the
limit slot disabled the endpoint. Now `type(x) is int`.
- trusted_proxies was unvalidated: a bare string would be iterated character
by character, malformed entries only surfaced as a per-request log line,
and 0.0.0.0/0 or ::/0 restored "trust XFF from any peer" — the exact hole
the setting closes. Now parsed and validated once at startup, wildcards
refused, and _ip_in_any takes pre-parsed networks so nothing can degrade
to a silent per-request skip.
Tests 99 -> 108: cross-route flood isolation, per-route reclamation windows,
every bool-in-rule position, bare-string and wildcard proxies, and a v4/v6
mismatch case.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
All four were real bypass or fail-open paths on an endpoint about to be
publicly exposed:
- X-Forwarded-For was trusted from ANY peer. The origin also listens on the
tailnet, so anyone reaching it directly could pick -- and rotate -- their
own rate-limit key by sending a header. Now honored only when the socket
peer is in a configured trusted_proxies list, and the last hop must parse
as a real IP. trust_forwarded_for without trusted_proxies REFUSES startup.
- Capacity eviction was fail-open and exploitable: an attacker able to mint
many distinct keys could evict their own live window and start fresh. Now
reclaims only EXPIRED windows and refuses the new key when all are live.
Fail closed -- /v1/link is invite-only, so hitting the cap is an attack.
- The clock was read outside the lock, so racing threads could append out of
order; both retry_after (hits[0]) and reclamation (v[-1]) assume the list
is chronological. Moved inside.
- Config types were unvalidated: `"enabled": null` or `0` silently disabled
limiting, and the string "false" enabled XFF trust (non-empty strings are
truthy). Booleans must now be real JSON booleans; rate_limit must be an
object.
Codex confirmed no path-variant bypass (dispatch is exact-match) and no
keep-alive/pipelining bypass (rejects set close_connection).
Tests 87 -> 99: capacity fail-closed with the victim's window proven
untouched through a 40-key flood, 200-thread chronological-order check,
untrusted-peer spoof, junk XFF, and every config-type trap.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
Last unbuilt item on the promotion-window hardening checklist. /v1/link
round-trips Zitadel, can CREATE a forge account and always mints a token, so
it is the endpoint that must not be free to hammer.
Sliding window per (route, client), ON by default -- unlimited has to be a
deliberate config act, not an omission. Defaults 5/hour and 60/hour; /health
never limited. 429 + Retry-After, decided BEFORE the body is read so an
abusive caller costs nothing.
Decisions worth naming:
- State is an in-process dict behind a lock. granthi-link is ONE
ThreadingHTTPServer, so that IS the store -- no redis. Kept behind a class
so a future multi-process move has one thing to change.
- Denied requests are NOT recorded. Recording them lets a hammering client
push its own window forward and lock itself out forever.
- Key store is capped; at capacity it drops least-recent windows and logs
loudly. Fail-open under key pressure, chosen over an unbounded dict that
is a memory DoS.
- trust_forwarded_for OFF by default. Behind cloudflared every request comes
from the tunnel, so limiting on the socket peer starves everyone; but XFF
is client-controlled. A caller can PREPEND, a trusted proxy APPENDS what it
actually saw -- so we read the LAST entry, never the first.
- A malformed rule refuses startup instead of silently meaning unlimited.
Tests 69 -> 87, including a 40-thread race proving the lock holds, the
self-lockout case, XFF spoof-resistance, and a real 429 on the wire.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
The client is downloadable from central now, but no document took an invited
user from clone to working state. Quickstart covers link -> list -> get/add
-> watch, plus the two things people get wrong: an expired device code
creates nothing (just re-run link), and merging is deliberately a forge
action because watch refuses to merge or force.
Also re-probed the token-minting mechanics the README pinned to 1.27.1,
since both forges now run 1.27.2. All three results still hold:
token-auth + Sudo header -> 401
token-auth + ?sudo= -> 401
admin basic auth + Sudo -> 201
Probe minted a token on the granthi-sync-e2e machine user and deleted it
(204 under basic auth). /v1/link's mint path is unaffected by the bump.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
list + get complete the onboarding flow (see my repos -> download -> work ->
sync). Both read the forge directly with the scoped user token, so no
granthi-link endpoint, service restart, or VPS config change is involved.
Codex-reviewed twice: 3 [P2] findings fixed, re-review clean. 69 tests pass.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
- parse_repo_arg(): validate <name> / <owner>/<name> against a strict segment
pattern. Not shell injection (argv list, no shell), but '?', '#', '..', an
encoded slash or an extra path component could redirect the clone URL and
the remote that gets persisted. Validate rather than quote — the forge's
own naming rules are this narrow anyway.
- list now keys local folders on full_name, not bare name: an account that
can see alice/cloud and bob/cloud showed BOTH as local when one was. `get`
and `add` both record full_name; older entries fall back to <login>/<name>.
- list_repos truncation was off by one page: a repo total that is an exact
multiple of the page size ends on a full page and was reported as
truncated. One sentinel fetch past the cap separates complete from
truncated.
Tests 65 -> 69, including hostile repo arguments and the exact-multiple case.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
`add` pushed a local folder up; nothing pulled a cloud repo down, so the
"show me my repos -> download -> start working" half of onboarding had no
implementation. Both new commands read the forge directly with the scoped
user token the link already handed us, so neither needs a granthi-link
endpoint, a service restart, or a VPS config edit.
- list: GET /api/v1/user/repos, pagination followed to a short page, with a
FORGE_MAX_PAGES guard whose trip is REPORTED — a bounded page must never
read as "that is all of them". Shows which repos are already local.
- get: clones with --origin granthi (the remote name watch looks for) and
-c credential.helper (the repo does not exist yet, so the helper cannot be
installed first), then registers the folder in the same shape `add` writes
— without that, watch silently ignores everything cloned.
- require_linked(): one failure mode for every forge-touching command.
- VERSION 1.0.0 -> 1.1.0, matching the README and the 1.1.0 hardening.
Tests 55 -> 65.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01LTARYHX7GPepi3CH3tp5pg
- main() exits 2 on permissive config (not just the predicate)
- 413 proven with an actual over-limit wire body, not header-only
- README: machine-user accounts need a seeded state.json mapping; only
granthi-sync-e2e required it in beta
Co-Authored-By: Claude Fable 5 <[email protected]>
claude