Skip to content

fix(github): scope an installation token's cache by its reach, not its bytes - #347

Open
sweepies wants to merge 2 commits into
mainfrom
fix/token-cache-scope
Open

sweepies wants to merge 2 commits into
mainfrom
fix/token-cache-scope

Conversation

@sweepies

@sweepies sweepies commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What and why

A token run (the CLI and the action) named its GitHub-side cache scope after sha256("Bearer <token>"). Installation tokens are minted fresh every Action run, so nothing keyed by the scope carried over: ETags, get_immutable Git objects, catalog state, LookupHint, inventory-actor and the nix/mise listings. The server already used a stable github-app:{id}/installation:{id}.

  • Client::identify (crates/github/src/identity.rs) runs for ghs_ tokens only, which includes GITHUB_TOKEN. It makes live requests that never touch the cache: GET /installation/repositories?per_page=100 (at most 10 pages, walked to the end), GraphQL viewer { databaseId }, and a contents proof. The scope is always {api root}|app:{bot id}/repos:{sha256 of sorted listed ids}. repository_selection must be all or selected and stay the same across pages, but it never shapes the key. So a token narrowed to fewer repositories can't share the full installation's entries, whatever GitHub calls its selection.
  • It falls back to the token hash on any non-2xx answer, a missing or unknown selection, a selection that changes between pages, a listing past the page cap, an empty listing, a duplicate id, a count that differs from total_count, a viewer without an id, or a failed contents proof. An installation with more than 1,000 repositories therefore keeps the token hash.
  • PATs (ghp_, github_pat_), gho_ and ghu_ tokens keep the token hash and make no request.
  • Permissions are not in the key, and that rule is now enforced in code. unrevalidated::ENDPOINTS is the one list of endpoints the cache answers without asking GitHub: Git blobs, recursive trees and commits, under repos/{owner}/{repo} or a renamed repository's repositories/{id}. Each needs only contents: read. Any other read that skips revalidation fails with Error::Unrevalidated, and a unit test checks the format! path of every get_immutable call in the workspace against the list. The scope is used only after the token reads repos/{r}/commits?per_page=1 on a repository in its set, a private one if there is any.
  • Cached blobs are checked against their SHA. A cached blob that doesn't hash to its SHA is dropped and read again. The REST pass of blobs() now always asks GitHub.
  • The action now restores and saves the cache in separate steps. A step before the save checks the repository through the API, sending the token over stdin so it never appears on a command line. A private repository saves. A public repository saves only when the token is a ghs_ token whose listing is exactly that repository. Everything else saves nothing and leaves a notice, including failed checks and personal tokens. The reason: a fork's pull request can restore a public repository's cache, and the cache is as confidential as the widest token that filled it.
  • Engine::from_settings is now async so a token run can call identify before the client is cloned.
  • Docs:
    • The threat model's "Cache scopes" section now covers:
      • the scope rules and the enforced endpoint list;
      • planting: trees, commits, catalogs, listings and hints can still be planted by whoever can write the restored cache, which is operator-level;
      • confidentiality;
      • a repository that leaves an installation: its cached objects stay readable under the installation's scope until evicted.
    • internals/github-client.md gains a "Token scope" section, and internals/cache.md links to it.
    • guide/github-actions.md says what carries over (blobs, catalogs, listings, hints; no 304s promised) and adds a caution for public repositories. It tells users to run organization-wide tokens from a private runner repository and to delete caches older action versions saved.

State versions

The crates/github/src/ tree, blobs.rs and datasource/src/lib.rs are hashed sources, so these are bumped and their rows updated:

  • states: extract, files, config, config-files, source-head, tag-catalog, tag-object, release-notes
  • the cascade from those constants' files: catalog, catalog-controls, changelog, notes-adapter
  • derived: github-release-head, notes-adapter-listing, parsed-postgres-sgml, parsed-go-history

Tests

All offline, in crates/github/tests/identity.rs and src/unrevalidated.rs:

  • the key for all and for two-page selected listings
  • every non-installation token kind: token hash and zero requests
  • 14 fail-closed branches
  • carry-over between two ghs_ tokens with the same listing, including all against selected over the same ids
  • no sharing with a token narrowed to fewer repositories even when it reports all, or with another App's bot
  • an unchanged shared client
  • a rejected unlisted endpoint
  • a planted blob that is rejected and replaced
  • the endpoint matcher, and the workspace call-site scan

Ran on the VM: cargo test and clippy with -D warnings for github, datasource, notes, engine, update, cli and server. Locally: zizmor and jactionlint on action.yml, gh actions-lock --no-fix (lock unchanged).

Follow-ups

  • Measure whether GitHub answers 304 across rotated tokens before promising it in the docs.
  • Check that GITHUB_TOKEN can call GET /installation/repositories. If it can't, a GITHUB_TOKEN run keeps the token hash, and in a public repository it doesn't save the cache. Both fail closed.

…s bytes

A token run named its GitHub-side cache scope after a hash of the token.
Installation tokens (an Action's App token or GITHUB_TOKEN) are minted
every run, so ETags, immutable Git objects, catalogs, hints, the
inventory actor and nix/mise listings never carried over between runs.

`Client::identify` now scopes a `ghs_` token by the API root, its App's
bot user id and either the account (`all`) or the sorted repository ids
(`selected`), read live from installation/repositories and GraphQL
viewer. It uses that scope only after the token reads a repository's
contents in the run, and keeps the token hash on any unexpected answer.
Other tokens keep the token hash. Cached blobs are now checked against
their SHA, since the scope is no longer secret. The threat model states
the invariants.
@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Deploying with  Cloudflare Workers  Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status Name Latest Commit Preview URL Updated (UTC)
✅ Deployment successful!
View logs
count-patchula 782d15a Commit Preview URL

Branch Preview URL
Nov 16 2026, 02:23 AM

…unrevalidated endpoints, gate the action's cache save

Drop the repository_selection "all" branch: every ghs_ token is keyed by
its bot and the sorted ids it lists, so a narrowed token can never share
the full installation's scope whatever GitHub calls its selection.

List the endpoints the scoped cache answers without revalidation in
unrevalidated::ENDPOINTS; any other such read fails, and a test checks
every get_immutable call site against the list.

The action now restores and saves separately and saves in a public
repository only when the token is an installation token listing that
repository alone, since fork pull requests can restore the cache. The
threat model covers confidentiality and repositories leaving an
installation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant