Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 117 additions & 0 deletions plans/api/ownership-claims.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
# An ownership claim names the role that made it

**Status:** A personal owner or an organization admin may declare. A security manager comes back as
a member and may not. A repository maintainer is not consulted.

## Why this exists

`CanDeclare` in [accounts.go](../../internal/store/accounts.go) is `owner` or `admin`, with a
comment that finer roles belong with scoped-token support. That is this plan.
`GET /user/memberships/orgs` returns `admin` or `member` only, so a security manager is recorded
as `member` and the picker refuses the organization. Repository permission is never read.
[owned-scope.md](../db/owned-scope.md) deferred a member declaring the repositories they
administer for a different reason, measured on the operator's own token: every such repository
checked was private (`ps-resources/es-offerings-ops`, `ps-resources/github-msft`,
`TaxPilotAI/TaxLing`, `els-ai/ghas-guzzlers`), and only an organization owner can install an App
that asks for organization permissions. A declaration made then would have been listed and never
read.

Finding those repositories is not one cheap call. `GET /user/repos?affiliation=collaborator`
is one call and finds direct grants only — 11 outside owned organizations in that measurement.
Team grants found 208 more, at 31 teams. Listing a whole organization and keeping
`permissions.admin` is complete and costs the organization's size: `dsp-testing` was 4,454
repositories, 45 pages. Fourteen of those were temporary GHSA advisory forks (`…-ghsa-…`), which
are not repositories anyone should declare. Enumeration still lists an include-only account whole
before filtering it.

This lands in the same implementation as [production-credentials.md](production-credentials.md).
A production pod that can read and still cannot say who may declare has not stopped needing a
person. The gh-auth role rules and the App eligibility rules are one change to the picker, not a
follow-up PR.

## Pending

1. **gh-auth roles, decided.** Personal account: the authenticated user, as now (`owner`).
Organization: membership role `admin` — GitHub's name for an organization owner — or the
security-manager role. `member` alone still cannot declare the organization. Repository, inside
an organization the user cannot declare whole: permission `admin` or `maintain` on that
repository, saved as an include list, not as a declaration of the account. Write, triage and
read do not qualify. There is no repository role named Owner; an organization owner appears as
`admin` on the repo. Advisory-fork grants stay excluded. Depends on nothing for the rule. The
picker that offers it in production depends on 2 and on
[production-credentials.md](production-credentials.md).
2. **Security manager is a second read, not a membership role.** `user/memberships/orgs` cannot
say it. The check is the organization's security-manager assignment — the teams
`GET /orgs/{org}/security-managers` returns, and a direct organization-role assignment where
the token can read one. A failed read is "cannot say", shown beside the account, not a
contradiction and not a denial. A fine-grained token that reports no classic scopes already
must not be treated as a complete membership list; the same rule applies here. Depends on 1.
3. **Repository permission is a second read too.**
`GET /repos/{owner}/{repo}/collaborators/{username}/permission` is `admin` or `maintain`, or it
is not a claim. A 404 from a token that cannot see the repository is "cannot say", not "not a
maintainer". The listing that offers names still comes from GitHub's answer, never from the
store. The route that finds team grants is the expensive one; do not ship the collaborator
affiliation list as if it were complete, and do not list an organization's every repository to
discover eleven. Depends on 1.
4. **An App installation makes an organization eligible. It does not declare it.** When an App is
configured, an organization is offered for an org-level claim only when this App is installed
on it. GitHub already required an organization owner to install an App that requests
organization permissions. Record the installer from the installation delivery's `sender.login`
on the installation evidence, which [appinstallation.go](../../internal/store/appinstallation.go)
does not store today. A delivery with no sender leaves the installer unknown, which is not
"nobody installed". Do not re-check the creator on a timer. Saving is still an explicit
declaration; nothing is preselected. A security manager cannot install that App and cannot
originate the org-level production claim. They declare through the gh-auth path, and they
operate an instance an owner installed. Depends on
[production-credentials.md](production-credentials.md) for the process having an App and no
`gh`, and on 1 for what "eligible" then allows the picker to offer.
5. **A repository is readable in production only when the installation includes it.** A maintainer
cannot widen the installation. An include naming a repository the App is not installed on stays
declared and unread — listed, marked, not crawled. The person's token does not become a crawl
credential. That was the resumption condition owned-scope named, and it is refused. Depends on 4.
6. **The pre-flight checks the role the declaration claims.** Verification is recorded and shown
beside each declaration. The gate still asks whether a scope is declared; this check says
whether the recorded role still supports it, and a failure to read the role is "cannot say",
not a crawl that will not start. It is not what bounds discovery. That item lived on
owned-scope and is this plan's. Depends on 1 and 2.

## Decided

**Two paths, one picker.** gh-auth: owner, admin, security manager at the organization;
admin or maintainer at the repository, as an include. App: an organization is eligible when this
App is installed, because the installer was an organization owner. Installation remains evidence
beside the declaration, never the declaration. [enterprise-server.md](enterprise-server.md) already
states that, and this plan does not grow a second reader of `abom_owned_scope_honored`.

**A security manager does not originate a production org claim.** Doing so would need a user
identity in production, which [production-credentials.md](production-credentials.md) exists to
remove.

## The constraint that must not be broken

**Membership still decides nothing on its own.** A role makes an account eligible to be offered.
Nothing becomes owned until a selection is saved. The picker offers; it never declares.

**A declaration is the only source of ownership.** Every "yours" figure still reads the honored
view. An installation, a security-manager assignment, and a repository permission are evidence
about access. Provenance is still not ownership on screen.

**Absent is not a denial.** A token that cannot list security managers, or cannot see a
repository's permission, does not remove a saved claim and does not contradict one.

**The person's token is not a crawl credential.** Listing for the picker may use it on the gh-auth
path. Discovery and fetch do not. A private repository the App is not installed on stays unread.

## Verification

- A `member` cannot declare the organization. A security manager can, on the gh-auth path, even
though memberships says `member`. A maintainer can declare that repository and no other. Write,
triage and read cannot. An advisory fork is not offered.
- An installation offers the organization and does not save it until someone does. The installer
is the delivery's sender when one was present, and unknown when it was not. A security manager
with no installation is not offered the organization on the App path.
- A failed permission read does not delete a saved claim and does not stop discovery by itself.
- An include for a repository the App is not installed on is marked unread. No crawl request for
it carries the person's token.
- With nothing declared, discovery is still refused. Declared-but-disabled is still refused. An
empty include list on an include-governed account still scopes to nothing.
126 changes: 126 additions & 0 deletions plans/api/production-credentials.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# A production instance does not need a person's token

**Status:** Reads of an installed account use the App. Copilot, the declaration check, dependency
snapshots and the default-setup language add still use a person's token. Lands in one
implementation with [ownership-claims.md](ownership-claims.md): a pod that can read and still
cannot say who may declare has not stopped needing a person.

## Why this exists

A production pod has no `gh auth` session. The server still will not author, will not say who may
declare, and will not perform the two writes it already performs, without one.

`githubToken` in [discover.go](../../cmd/codeql-abom/discover.go) is `GITHUB_TOKEN`, then
`GH_TOKEN`, then `gh auth token`. It is what [serve.go](../../cmd/codeql-abom/serve.go) hands to
dependency submission and to the `HeadSHA` that submission resolves, and what
[codescanningstatus.go](../../cmd/codeql-abom/codescanningstatus.go) hands to the default-setup
write. [authoring.go](../../cmd/codeql-abom/authoring.go) asks `ghauth.Token` for every Copilot
session and for the readiness probe. [accounts.go](../../cmd/codeql-abom/accounts.go) and the
serve default for `Verify` shell out to `gh api`. With no App, [newReader](../../cmd/codeql-abom/credentials.go)
and the advisory client use the same person's token; with an App, those two already do not.

`tokenFor` in [app.go](../../internal/ghapp/app.go) posts to
`/app/installations/{id}/access_tokens` with no `permissions` body, and caches one token per
installation. GitHub then returns every permission the installation holds. After this plan adds
write grants, that cache would hand a crawl the write token, or a write the Copilot token,
whichever was minted first.

GitHub's server-to-server path for Copilot is an installation token (`ghs_`) with organization
permission `organization_copilot_requests: read`, passed explicitly, with logged-in-user fallback
off. It is billed to the installing organization. It needs that organization's policy allowing
Copilot requests from GitHub App installations. It expires in one hour. It is not a user
subscription, and a classic `ghp_` token is not a supported Copilot credential. The pinned SDK
(`github.com/github/copilot-sdk/go` v1.0.14) already takes `GitHubToken` and
`GitHubTokenProvider`, and defaults `UseLoggedInUser` to false when a token is set.

## Pending

1. **Mint a token for the call, not for the installation.** The cache key is the installation plus
the permission set. `POST /app/installations/{id}/access_tokens` sends a `permissions` body that
is a subset of what the installation was granted. A crawl token carries the existing read set
and nothing else. A snapshot token carries `contents: write` and the reads that snapshot needs,
not Copilot. A default-setup write carries `administration: write`, not Copilot and not
`contents: write`. A Copilot token carries `organization_copilot_requests: read` and nothing
else. A permission the installation has not granted yet refuses that call, with that reason. It
does not borrow another token, and it does not fall back to `GITHUB_TOKEN`, `GH_TOKEN`, or
`gh`. Depends on nothing.
2. **Copilot uses the App when one is configured.** The session's `GitHubTokenProvider` mints on
`initial` and on `refresh`, through the call in 1, for the organization the session is billed
to. `UseLoggedInUser` is false. The child process does not inherit `GH_TOKEN` or
`GITHUB_TOKEN`. When no App is configured, the session keeps `ghauth.Token`, which is the local
and development path. A missing Copilot grant, or GitHub's refusal that App installation tokens
are not enabled for that organization, refuses the session and is what readiness says. It is
not "no agent" and not a 403 discovered mid-turn. Depends on 1.
3. **The two existing writes use the App when one is configured.** Dependency submission, including
the `HeadSHA` it resolves, uses the snapshot token from 1. The default-setup language add uses
the administration-write token from 1. Both stay explicitly requested, ledgered, and bounded to
approved targets. This is not a new publisher, not a timer, and not a workflow grant — those
stay deferred in [dependency-submission.md](dependency-submission.md). When no App is
configured, both keep the person's token. Depends on 1.
4. **Add the three grants to the manifest, traced to the call that needs each.**
`organization_copilot_requests: read` to the Copilot session.
`contents: write` to the existing snapshot submission — the current contents grant is read, and
the dependency submission API requires write.
`administration: write` to `PATCH /repos/{owner}/{repo}/code-scanning/default-setup` — the
current administration grant is read, which covers the GET. An already-installed App that has
not been re-approved reports the missing grant as in 1, rather than calling and reading the 403
as a product failure. The manifest trace test still fails a grant no call needs. Depends on 1.
5. **Declaration checks do not shell out to `gh` for the server to run.** When an App is
configured, identity and the declaration picker use the App, as
[ownership-claims.md](ownership-claims.md) specifies. When no App is configured, `ghauth.Verify`
stays. A production process with an App and no `gh` does not record "you belong to nothing".
Depends on 1. The role rules are the other plan's; this one only stops the missing CLI from
being the answer.
6. **Readiness names the credential.** `GET /api/authoring/readiness` says whether authoring will
use an installation token or `gh`, and the org-policy refusal when that is the reason it cannot.
It does not print a token. Analysis workers still receive neither the Copilot token nor a write
token; [deployment.md](../tools/deployment.md) keeps that separation, and the token they would
receive is an installation token, not a PAT. Depends on 2.
7. **Say what the system does, once the grants exist.** The architecture sentence that writes keep
the person's credential, and [enterprise-server.md](enterprise-server.md)'s status line that the
App is read-only, move to what this plan made true. Not before the grants land.

## Decided

**One App, three tokens.** The owner re-approves the registration once. A second App is not
required. The separation enterprise-server requires — a credential that reads is not the
credential that writes — is the minted token's permission set, not a second registration.
[github-hosts.md](github-hosts.md) still chooses the host. This plan does not send a token minted
for one host to another, and does not invent a second router.

**No person's token is a production requirement.** Local and development runs with no App keep
`gh auth token` for reads, Copilot, declaration checks and the two writes. Production with an App
never consults it. An empty environment is not an empty identity.

**Copilot is billed to the installing organization.** There is no user subscription on that path,
and the model list that path returns is the organization's. The user's list is the no-App path,
which [qlaas-loop.md](qlaas-loop.md) renders. Same control, different credential.

## The constraint that must not be broken

**A missing user token is not a denial and not an empty membership.** Production with an App and
no `gh` starts and reads. It authors, or it says which grant or org policy is missing. It does not
fall back to an ambient token, and it does not record that the operator belongs to nothing because
the CLI was absent.

**A token is never stored, logged, or written into an event.** The App's key stays a 0600 file
beside the database, as it is now. The Copilot child receives the installation token as the SDK's
explicit credential and not as an inherited environment variable.

**A write stays irreversible and explicit.** Moving the existing snapshot and default-setup writes
onto an installation token does not add a timer, a first submission, or a client that submits.
[dependency-submission.md](dependency-submission.md) still defers those. A write whose grant is
absent is refused before GitHub is asked.

## Verification

- A process with no `gh`, no `GITHUB_TOKEN` and no `GH_TOKEN`, and an App configured, serves and
reads an installed account. A Copilot session is offered a `ghs_` token minted for that call. A
refresh mints another. The crawl's token does not carry `contents: write` or
`organization_copilot_requests`. The snapshot token does not carry Copilot.
- A process with no App still uses `gh auth token` for those same calls. The two paths are tested
by which credential function runs, not by elapsed time.
- An installation that has not re-approved the new grants refuses the session and the write with
the missing permission named. It does not attempt the person's token.
- No token appears in a log line, an authoring event, or the database. The readiness body names the
credential kind and the refusal, not the secret.
Loading
Loading