Design: credential handling
Status: built, 2026-10-19 (issue 12).
The problem
zz repo clone builds a git remote URL with the token embedded (https://<token>@zzmq.dev/<owner>/<repo>). That token then lives in .git/config's remote.origin.url in plaintext for as long as the clone exists -- visible in git remote -v, copied wherever the repo directory is copied, logged by anything that prints the remote. Git compatibility documents this as the current mechanism; it isn't the one Cloudflare's own docs for Artifacts point at.
What Artifacts actually offers
Confirmed directly against Cloudflare's docs, not assumed: Artifacts exposes a standard git smart-HTTP remote (https://<account>.artifacts.cloudflare.net/git/<namespace>/<repo>.git), authenticated with repo-scoped Bearer tokens -- read scope for clone/fetch/pull, write scope for push. No SSH. Their own example for authenticated access is git -c http.extraHeader="Authorization: Bearer <TOKEN>" -- a header, not a URL-embedded credential.
That's better than what zz does today, but still not the fix on its own: setting http.extraHeader persistently in local config is the same long-lived plaintext secret under a different key, not a real improvement. The actual problem is two separable things -- where the secret is stored, and how long it's valid -- and both have standard answers.
The design
A git credential helper, the mechanism gh/glab/Google Cloud's own git integration all use for exactly this problem: a small program git invokes on demand over stdin/stdout, so the secret never gets written into the repo's own config at all.
zz repo cloneconfigurescredential.https://zzmq.dev.helper-- scoped to that one host, so it never touches whatever helper the user already has configured forgithub.comor anywhere else.- The helper is the
zzbinary itself (zz credential-helper), implementing git's documentedget/store/eraseprotocol. - It reads from
~/.zz/credentials.json-- the storezz loginalready writes. No new storage mechanism. A baregit pullrun outside thezzCLI gets the same credential transparently, which is the actual UX complaint this design exists to fix: no copy-paste into a Basic Auth prompt, ever.
Short-lived tokens, minted on demand, not stored long-lived. zz work --as <agent> already mints a fresh token on start and revokes it on exit, using the logged-in session's own mint authority -- that discipline doesn't currently extend to a human's own plain git pull/git push. The credential helper should mint a fresh, scoped token per request (or per some short window, cached briefly to avoid minting on every single git subprocess call) rather than handing git one token that lives indefinitely. A leaked token is then a liability for minutes, not until someone notices and manually revokes it.
Public repos are unaffected. Reading one already needs no credential; git only invokes a credential helper at all on a 401, which a public read never triggers.
What's actually built
zz credential-helper get/store/erase(cli/commands/credential-helper.ts) implementing the real protocol over stdin/stdout.store/eraseare no-ops --~/.zz/credentials.jsonis the real store this reads from; there's nothing in git's own credential cache to add or remove.zz repo cloneno longer builds a token-embedded URL. It clones with-c credential.https://<host>.helper=!zz credential-helper(there's no.git/configto set this in permanently until the clone finishes) and then persists the same helper reference -- never a token -- into the new clone's own config, so a later plaingit fetch/git pushrun outside thezzCLI gets a credential transparently too.- Self-rotating, not a server-enforced TTL. No expiry column exists on
agent_tokenstoday, and adding one is a bigger, separate change to the core auth schema -- out of scope here. Instead, eachgetcall revokes whatever token this helper minted last time for that host (tracked in a small local~/.zz/credential-helper-state.json) before minting a fresh one. At most one helper-minted token is ever alive at once, continuously rotating -- a leaked one is a liability for about as long as it takes the next git operation to run, not indefinitely. - Public repos are genuinely unaffected -- confirmed live, a plain clone of a public repo never invokes the helper at all, since git only calls a credential helper on a 401.
- Migration note for existing clones, unchanged from the original design: a clone made before this exists still has the old URL-embedded token in its remote URL until re-cloned or the remote URL is manually rewritten. Not force-migrated.
Verified live against the real deployed Worker: git remote -v on a fresh zz repo clone shows the plain URL, no token; a real git push (unauthenticated past the public-read case) correctly triggered the helper, which minted a working token; a second invocation minted a genuinely different token; the first token was confirmed revoked server-side (a direct API call with it returned 401, not just locally forgotten).
Tracked as
- issue 12 Git credential helper: stop embedding tokens in the clone URL.