diff --git a/plans/api/ownership-claims.md b/plans/api/ownership-claims.md new file mode 100644 index 00000000..7698dd6c --- /dev/null +++ b/plans/api/ownership-claims.md @@ -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. diff --git a/plans/api/production-credentials.md b/plans/api/production-credentials.md new file mode 100644 index 00000000..725f8dec --- /dev/null +++ b/plans/api/production-credentials.md @@ -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. diff --git a/plans/api/qlaas-loop.md b/plans/api/qlaas-loop.md new file mode 100644 index 00000000..1655668f --- /dev/null +++ b/plans/api/qlaas-loop.md @@ -0,0 +1,113 @@ +# A failed authoring session resumes from the step on screen + +**Status:** The loop runs to review. A session home is deleted when the run ends, the model is a +flag, and ql-mcp calls outside six tools are refused by name. + +## Why this exists + +The icons in [AuthoringSteps.razor](../../ui/Shared/AuthoringSteps.razor) are `target`, `help`, +`expected`, `database`, `ast`, `compiles` and `tests`, derived from files on disk. They are not +checkpoints. [session.go](../../internal/harness/session.go) deletes the session directory when +the run ends, and [authoringsession.go](../../internal/store/authoringsession.go) stores no +runtime session id, so the SDK's resume has nothing to load. A live session takes the request's +prompt and whatever `Next` appends when the agent goes idle. It has no way to accept a person's +prompt while it is running, or after it has failed. + +The model is `--authoring-model`, default `claude-opus-5` in +[copilot.go](../../internal/harness/copilot.go). That name is already absent from the picker a +Copilot subscription shows. A hardcoded catalog will be wrong again the next time a model is +retired. The pinned SDK (`github.com/github/copilot-sdk/go` v1.0.14) already has `ListModels`, +`ResumeSession`, `SetModel` (reasoning effort and context tier) and `Send` with `immediate` and +`enqueue`. The gap is that ABOM does not call them. + +The operator was stopped while the agent validated QL. `codeql_lsp_diagnostics` is already one of +the six tools in `loopTools`. `packURI` in [confine.go](../../internal/harness/confine.go) +requires a `file://` URI. The ql-mcp server documents a plain directory path for `workspace_uri`, +not a URI. A model that follows the server is refused. The other LSP tools — +`codeql_lsp_completion`, `codeql_lsp_definition`, `codeql_lsp_references` — are refused by name +before any argument is checked. Read one refused event from a real session before changing the +allowlist: the name may already have been allowed, and the argument is what failed. + +## Pending + +1. **Confirm the refusal, then offer the server's tools.** Read one real session's refused event. + Offer every ql-mcp tool the pinned server advertises, not a list copied from a document that + will drift. LSP tools take the arguments the server documents: a plain pack directory for + `workspace_uri`, 0-based positions, and `file_path` as well as `ql_code`. **The fix for the + `packURI` mismatch is to accept the plain directory path the server documents and keep + confinement unchanged:** the path is resolved through links and must be the pack or inside it, + exactly as `packFile` already judges it. A `file://` URI stays accepted for the same check, and + is normalized to a path first. ABOM does not rewrite the argument it forwards. The same rule + applies to `workspace_uri` on every LSP tool. A tool the server does not advertise is still + refused by name. Depends on nothing. +2. **Three tools stay refused, by name, with the reason.** `codeql_test_accept` makes the query's + own output the expected result, so the test can never fail. `codeql_pack_install` rewrites the + lock ABOM resolves. `create_codeql_query` writes a layout ABOM did not choose. An argument that + leaves the session's bounds stays refused: `additionalArgs`, an output or log path outside the + scratch ABOM owns, a write outside the target, a read outside the pack and the libraries, and + `learn`. Offering the server's tools does not weaken that. Depends on 1. +3. **Each icon is a snapshot.** When a step transitions, snapshot the writable target files and + record the test-database identity. The icon is that snapshot. A step with no snapshot says so + and is not a restore point. `target` is a decision: restoring it re-binds the query and does + not invent a file that was not written. `database` restores the recorded identity, not a + database the agent wrote — only the CLI writes that. Depends on nothing. The resume that uses + the snapshot is 4. +4. **Resume rewinds, then continues.** Persist the runtime session id. Keep the session home until + the operator discards it or the request is closed. Resume uses `ResumeSession` against that + home. Resuming from an icon rewinds the target files to that snapshot first. Later edits at + that step and after it are undone, and the timeline says so before the agent runs. A failed, + stopped or interrupted session on an open request can be resumed. A request that is done or + declined cannot. A live session takes an in-UI prompt: `Send` with `immediate` to steer the + current turn, `enqueue` to run after it. The prompt is recorded before it is sent. If the + runtime transcript cannot be loaded, say so and start a new session on the restored files. + Do not pretend the conversation survived. Depends on 3. +5. **The model list is the runtime's.** `ListModels` on the credential the session will use — + the user's, when no App is configured; the organization's, when + [production-credentials.md](production-credentials.md) mints the Copilot token. Render id, + name, policy state, supported reasoning efforts and context tier. Do not invent a retiring + badge the runtime did not send. Pass the selected effort and tier to `SetModel` on a live + session and to the next create or resume. A model the runtime does not list is unavailable, + including the flag default. A list that could not be read is an error, not an empty catalog + and not `claude-opus-5` presented as the catalog. The flag names the session's model only when + that id is in the list. Depends on nothing for the local path. The production list depends on + the Copilot installation token existing; the control is the same. + +## Decided + +**Rewind is the restore.** An icon that only resumed the conversation and left the files as they +are would be a bookmark. The operator chose the rewind. It is recorded, and it is not silent. + +**Confinement survives resume.** Restoring files does not restore a permission the gate refused. +Two agents still cannot write one request. A steer is a prompt event, not a side channel. + +**This does not wait on the credential split to be useful locally.** A workstation with `gh auth` +can resume, steer and list models before production mints an installation token. The production +list is that token's `ListModels`, not a second catalog. + +## The constraint that must not be broken + +**The agent writes inside bounds ABOM sets, including after a resume.** A restored tree is the +target's files at that step. It is not a permission to read the session home, the database, or a +path the gate already denied. The three named refusals stay refusals because each one makes a +later test unable to mean what it says. + +**A model the runtime did not list is not a model the session runs.** Substituting the flag +default when the list omits it is the failure this plan exists to stop. + +**Say what was not restored.** A missing snapshot, a missing transcript, or a list that could not +be read is that fact on screen. It is not a successful resume and not an empty picker. + +## Verification + +- A diagnostics call with the plain pack path the server documents is allowed. One with a + workspace outside the pack is not. `codeql_lsp_definition` is offered. `codeql_test_accept` is + still refused, with the existing reason. An `additionalArgs` write outside the pack is still + refused. +- A failed session resumed from Compiles has the query bytes from that snapshot, and the timeline + records the rewind. A prompt sent while the agent is working arrives as `immediate` without a + second session. A request that is done is refused. +- The picker contains whatever `ListModels` returned for that credential and does not contain a + model the runtime omitted. A failed list is an error, and the session does not start on + `claude-opus-5` because the flag still says so. +- A resumed session is still confined: the home stays denied, and a second start on the same + request is still refused while one is running. diff --git a/plans/db/owned-scope.md b/plans/db/owned-scope.md index 4664dd5a..4d523363 100644 --- a/plans/db/owned-scope.md +++ b/plans/db/owned-scope.md @@ -7,7 +7,8 @@ a row's repository; *What you own* (`scope=owned`) holds exactly that, and *Your (`scope=supply-chain`) is the closure. Settings asks `gh` on arrival, offers the accounts it can declare, and builds an include list from GitHub's own answer, or a property scope from the organization's custom properties. A repository administered inside an organization the operator -does not own still cannot be declared, deliberately: see item 2. +does not own still cannot be declared. That claim is +[ownership claims](../api/ownership-claims.md), not a refinement of this plan. ## Why this exists @@ -34,42 +35,18 @@ the operator both has the privilege to analyze and the responsibility to remedia already in scope, and never widens or narrows what is discovered. It is refused as a pattern for the same reason this one is — see the waiver rules in [`../../.github/instructions/architecture.instructions.md`](../../.github/instructions/architecture.instructions.md). -2. **Deferred: a member declaring the repositories they administer.** In an organization where - the operator is only a member, the account as a whole is not declarable, and a repository they - administer there has no representation. Deferred because nothing could read what such a - declaration names, not for want of a picker. Measured with the operator's own token on - 2026-10-06: - - **Every one checked is private**: `ps-resources/es-offerings-ops`, `ps-resources/github-msft`, - `TaxPilotAI/TaxLing`, `els-ai/ghas-guzzlers`. ABOM reads and fetches through its GitHub App, - and only an organization owner can install an App that asks for organization permissions, - which ABOM's does. A repository administrator may install only an App limited to repository - permissions, and only where the organization allows it. A declaration made today would be - listed and then never read. - - **Finding them costs a route choice, and the cheap one misses most.** - `GET /user/repos?affiliation=collaborator` is one call in 1.3 s and finds 11 outside owned - organizations (`github` 9, `TaxPilotAI` 1, `els-ai` 1), only direct grants. Team grants find - 208 more (206 in `github`, 2 in `ps-resources`) at 31 teams and 172 s. Listing a whole - organization and keeping `permissions.admin` is complete and costs its size: `dsp-testing` is - 4,454 repositories, 45 pages, 84 s. - - **`dsp-testing`'s 14 are all temporary GHSA advisory forks** (`…-ghsa-…`), granted through - advisory collaboration, which neither the collaborator nor the team route reports. They are - not repositories anyone should declare, so they are not the fixture they were taken for. - - Resumes when one of these holds: the App is installed on the repositories in question (an owner - approves a request), or reading a member's declaration with the operator's own token is decided - as a credential the crawl may use. The owned tier and the pinning split already decide per - repository, so 11 declared repositories in `github` would be the owned tier and no other - `github` repository would join it; only Settings' owner-candidate mark stays account-level, and - it says *declared in part*. Enumeration still lists an include-only account whole before - filtering it, which for `github` is about 192 pages every full listing. - - **Constraints this must keep:** membership still decides nothing on its own; listing is - read-only against GitHub and paid from the reader's own token, never the App's; every name - offered comes from GitHub's answer, never from the store. -3. **The pre-flight does not check per-account permissions.** `gh` verification is recorded and - shown beside each declaration, and the gate asks only whether a scope is declared. Checking that - the operator holds the access each declaration claims is worth doing, and is not what stops a - crawl from being unbounded. +2. **Who may declare, including a member's repositories, is not this plan.** The role rules, + the security-manager and maintainer checks, and the App-installation eligibility are + [ownership claims](../api/ownership-claims.md), which lands with + [production credentials](../api/production-credentials.md). The measurement that sized the + deferral — private repositories, the cheap listing missing team grants, advisory forks that + are not claims — lives there. This plan keeps the predicate those claims are saved into. + Membership still decides nothing on its own. The person's token is not a crawl credential. +3. **The pre-flight role check is deferred to the ownership plan.** `gh` verification is recorded and shown beside + each declaration, and the gate asks only whether a scope is declared. Checking that the + recorded role still supports the claim is [ownership claims](../api/ownership-claims.md). It + is not what stops a crawl from being unbounded, and it is not a second reader of the honored + view. 4. **No browser gate draws the declaration picker.** The e2e server's `gh` is a stub that answers as logged out (`ui/tests/e2e/stubs/gh`), so the declarable list never appears, and the fixture corpus declares `acme-corp` by property scope and the other three whole, with no include list, diff --git a/plans/next.md b/plans/next.md index 07aaf585..0a841035 100644 --- a/plans/next.md +++ b/plans/next.md @@ -84,7 +84,22 @@ The checks still unbuilt live in the plans that own what they depend on, and `codeql-abom check` names each one's plan. Declaring ownership by repository property, which the operator ranked ahead of them, is built. -1. **[Practice safely in a startup-only Demo instance](tools/demo-mode.md)** — a marked Demo +1. **[A production instance does not need a person's token](api/production-credentials.md), and + [an ownership claim names the role that made it](api/ownership-claims.md)** — one + implementation, not two PRs. Reads already use the App. Copilot, the declaration check, + dependency snapshots and the default-setup language add still use a person's token, and the + only roles that may declare are personal owner and organization admin. A production pod has + no `gh auth` session, so a credential split that still cannot say who may declare has not + closed the hole. Ranked here, above Demo, because the operator named it the highest priority + and will implement the two together. Everything previously ranked keeps its relative order + beneath them. +2. **[A failed authoring session resumes from the step on screen](api/qlaas-loop.md)** — the + loop is built as far as `review`. A session home is deleted when the run ends, the model is a + flag, and ql-mcp calls outside six tools are refused by name. `codeql_lsp_diagnostics` is + already offered and refuses the workspace path the server documents. Local `gh auth` sessions + can land before the credential split; the production model list is the organization's, once + that split mints the Copilot token. +3. **[Practice safely in a startup-only Demo instance](tools/demo-mode.md)** — a marked Demo now serves fictional repositories from a loopback-only simulated GitHub, builds real CodeQL databases and results from them, and enables Copilot authoring only behind an egress allowlist; [the repository's default dev container](../.devcontainer/devcontainer.json) is its ephemeral @@ -92,21 +107,21 @@ ownership by repository property, which the operator ranked ahead of them, is bu finish qualifying that Codespace (a session's hosts, token type, the prebuild, zero retention), admit the Demo's user to its own loopback services only, then comparison provenance, linked examples, practice for the remaining lessons, and the scripted offline profile. -2. **[Hiding something is a decision somebody signs](db/exclusions-and-exceptions.md)** — every +4. **[Hiding something is a decision somebody signs](db/exclusions-and-exceptions.md)** — every organization carries things it has decided not to look at and things it has decided not to act on yet. `abom_policy_waiver` already models both, with a required reason, an author, and an expiry that is required for an exception and read when the decision is applied. It reaches nothing but a policy verdict. What is owed is a scope beyond one policy, an exclusion that actually stops work, an exception that hides a result while the work still runs and records, and a screen that refuses to write either without a reason and a review date. -3. **[Use GitHub's tooling to keep workflow locks current](tools/actions-lock.md)** — ranked here +5. **[Use GitHub's tooling to keep workflow locks current](tools/actions-lock.md)** — ranked here for the compatibility matrix and supported-workflow documentation that can start locally. Record the pinned toolchain and existing evidence without treating this repository's observed enforcement as proof for other platforms or nested pins. New enforcement experiments and an observed Dependabot update of workflow and lock need an approved target, coordinated with [the native coverage crosscheck](api/dependency-graph-crosscheck.md). GitHub owns generation and verification, not a second ABOM pinning tool. -4. **[Measure native Actions coverage before filling a gap](api/dependency-graph-crosscheck.md)** - +6. **[Measure native Actions coverage before filling a gap](api/dependency-graph-crosscheck.md)** — the isolated source-extraction comparison at identical commits runs continuously against GitHub's own parsers as the checker's check 1; native lock evidence and the reference action's parser are still to compare over the same trees, and need no submission or live test target. @@ -114,7 +129,7 @@ ownership by repository property, which the operator ranked ahead of them, is bu approved clean target, without historical custom submissions masquerading as native data. A default-branch SBOM cannot replace a pinned revision. Publication expansion waits for a concrete residual gap; this comparison does not promise one exists. -5. **[A gate that blocks, and can say whose rule it was](api/verdict-gate.md)** — ABOM can apply +7. **[A gate that blocks, and can say whose rule it was](api/verdict-gate.md)** — ABOM can apply declared policy to an organization's recorded transitive dependency evidence. **The policy half is built** — drafted, simulated, adopted, waived and auditable — so what remains is the base-versus-head closure diff, the verdict endpoint and the check run, over @@ -126,19 +141,19 @@ ownership by repository property, which the operator ranked ahead of them, is bu is built: findings or advisories, how an owned repository reaches either, and other policies by name. Its verdict-only client remains deferred in [api/abom-check.md](api/abom-check.md). -6. **[A commit-pinned action can still be named as a version](db/version-resolution.md)** - measured +8. **[A commit-pinned action can still be named as a version](db/version-resolution.md)** — measured crawl mappings already feed versions into the existing submission path. Remaining lookup fills version-evidence gaps, including native lock refs whose release association is unverified; it never substitutes a live tag for the commit a [lock selects](../docs/architecture.md#locks). Direct-pin publication and upstream aliases remain deferred until [the native coverage crosscheck](api/dependency-graph-crosscheck.md) establishes a native gap. -7. **[A finding that stops being reported is never removed](db/finding-lifecycle.md)** — unblocked. +9. **[A finding that stops being reported is never removed](db/finding-lifecycle.md)** — unblocked. The sweep has only run where nothing was sighted, so it has proved nothing. The crawled organization holds **10,192 finding sightings**, so the tombstone and the `_live` view can be exercised against a finding that really does stop being reported. **First, the report judges a finding by runs of its suite rather than of its rule**, and never by a crawl lane: on a copy of the verification store, two on-demand runs of one query each over 15 repositories moved it from 313 findings to 712, 396 of the new ones for rules neither run evaluated. -8. **[The same graph draws a different picture every time](ui/graph-layout.md)** — a decision a +10. **[The same graph draws a different picture every time](ui/graph-layout.md)** — a decision a reader has to settle rather than work, and a defect that is work. The browser draws where the engine placed it, **fitted to the nodes it is actually drawing**, and names which layout is on screen; the view refuses above **300 nodes** without explicit approval and there is **no @@ -156,7 +171,7 @@ ownership by repository property, which the operator ranked ahead of them, is bu line, five nodes across 26,887 × 233. [The closure figure](ui/closure-figure.md)'s placement, which lays out a subset alone, is built for it to use. A third: a key ending in a backslash comes back from Graphviz under another name, so the export never places it. -9. **[Remediation summarizes two things into their more reassuring halves](ui/remediation-honesty.md)** +11. **[Remediation summarizes two things into their more reassuring halves](ui/remediation-honesty.md)** — down to one half, and that half turns out to be **latent rather than live**. The strip-versus-table gap is closed: the advisories unit carries an `unreached` count and states it under the table, so **3 reaching you** and **8 reaching nothing** are both on screen and sum @@ -164,7 +179,7 @@ ownership by repository property, which the operator ranked ahead of them, is bu ranges include **no fix published**, with 5 repositories sitting in exactly that range — and it reaches **no column today**. That makes it cheaper to settle, not safer to ignore: the field is on the model, and the next surface wanting a Fix column will find it and believe it. -10. **[A backup is a command, not a thing everybody is told to remember](db/backup-and-restore.md)** +12. **[A backup is a command, not a thing everybody is told to remember](db/backup-and-restore.md)** — the correct incantation is written in the working-style instructions, printed by `make e2e` when it refuses the working database, and implemented nowhere. Getting it wrong raises no error: `cp` does not read the WAL, so the baseline is silently missing recent commits and a change that @@ -173,34 +188,34 @@ ownership by repository property, which the operator ranked ahead of them, is bu is a correctness fix rather than an ergonomic one is the epoch — a restore moves generation history backwards underneath every connected client, and nothing currently tells them to reload. -11. **[Code quality, measured by our own tool](tools/code-quality.md)** — the gate holds new +13. **[Code quality, measured by our own tool](tools/code-quality.md)** — the gate holds new findings at zero in all five analyses. What is left is complexity: **125 production functions over 10, total excess 362**, most between 11 and 16. The worst are `Store.Migrate`, `findingReviewPlan` and `Supervisor.cycle`; the first and last wait on tests they do not have yet. Cleanup rather than risk reduction, which is why it sits here. -12. **[The crawl says what it is doing, wherever a reader is](ui/crawl-visibility.md)** — down to +14. **[The crawl says what it is doing, wherever a reader is](ui/crawl-visibility.md)** — down to how Settings is grouped. The state, the queue, a problem marker and the refresh interval are on the bar of every page, a restart starts nothing unless somebody configured it to, and the suite binding is chosen on the CodeQL page and stated in Settings. What is left is that Settings holds four unrelated decisions in one scroll, and that an on-demand run is visible only on the CodeQL page's Runs tab while it spends the same cores. -13. **[An action remembers its upstream without becoming it](db/fork-provenance.md)** — forks and +15. **[An action remembers its upstream without becoming it](db/fork-provenance.md)** — forks and naming-convention mirrors need attributed upstream context without replacing the declared dependency or inventing a `uses:` edge. Same-host identity collection can start independently; cross-host lookup consumes [GitHub hosts](api/github-hosts.md), and version explanations consume measured evidence from [version resolution](db/version-resolution.md). -14. **[A repository lookup names its host and its credential](api/github-hosts.md)** — Git, REST +16. **[A repository lookup names its host and its credential](api/github-hosts.md)** — Git, REST and `gh` currently choose destinations separately. Start with a shared host/identity contract and two-host tests, preserving declared ownership and destination-scoped credentials. Coordinate cache identity with the [checkout cache](db/checkout-cache.md), which keys a fetch by commit and sparse filter and carries no host in that key; advertising enterprise-host support still requires an authorized environment, not only mocks. -15. **[Record the container references Actions actually declares](db/container-inventory.md)** — +17. **[Record the container references Actions actually declares](db/container-inventory.md)** — job/service images, Docker action metadata and referenced Dockerfile `FROM` declarations are a broader inventory than the existing `docker://` edges. Begin with a literal-source coverage spike and the shared adapter contract; full dynamic/dataflow resolution is not a prerequisite. No image execution, package scanning or GitHub container-alert claim is included. -16. **[Reach is computed one way, and nothing checks it](ql/reachability-crosscheck.md)** — +18. **[Reach is computed one way, and nothing checks it](ql/reachability-crosscheck.md)** — unblocked by closure databases, and ranked last because nothing a reader sees moves until its third item reports the comparison. A CodeQL walk over each owned repository's closure is a second derivation of reach sharing no code with the Go walk. A closure stages callables only, @@ -230,13 +245,16 @@ endpoint. [Exclusions and exceptions](db/exclusions-and-exceptions.md) is what r refactoring: a named scope already means the same thing on every surface, each of its terms applied or refused by name, and every Inventory unit's columns and actions are its own. -**The ordering is a decision, not drift.** First-release safe practice leads by the operator's -decision: [Demo](tools/demo-mode.md) extends the [Tutorial experience](../docs/tutorials.md). -It deliberately takes precedence over exclusions, workflow-lock work and the rest of the ranked -backlog, preserving their relative order and the parallel deployment/query-request priorities -above. Enterprise scale and commit-awareness still underpin -the remaining work. Exclusions lead that remainder because hiding something is the next claim an -organization makes about its own data, and nothing records who made it. The interface +**The ordering is a decision, not drift.** Production credentials and ownership claims lead, as +one implementation, by the operator's decision: a production instance cannot serve without a +person's token, and a credential split that still cannot say who may declare has not closed that. +That displaces [Demo](tools/demo-mode.md), which an earlier decision put first so first-release +safe practice would extend the [Tutorial experience](../docs/tutorials.md). Demo stays immediately +beneath the QLaaS loop, and everything that was already ranked keeps its relative order. +Exclusions still lead that previous remainder, because hiding something is the next claim an +organization makes about its own data, and nothing records who made it. The parallel +deployment and query-request priorities above are unchanged. Enterprise scale and +commit-awareness still underpin the remaining work. The interface entries follow because each is a claim a reader can already see and misread. The [checkout cache](db/checkout-cache.md) and [database cache](db/database-cache.md) are built and reused, each keeping its retention default as a measured refinement; the database cache also holds @@ -267,11 +285,6 @@ refusal. checkout of this repository. [Deployment](tools/deployment.md) owns bundling them for installed runtimes; that does not require or resume registry publication. -- **[A member declares the repositories they administer](db/owned-scope.md)** — nothing could - read what it names. Every such repository measured is private, ABOM reads through its App, and - only an organization owner can install an App asking for organization permissions. Resumes with - an App installation on those repositories or a decision that the operator's own token may crawl - them; ownership is already decided per repository, so it no longer waits on that. - **[A client in the workflow, thin enough to trust](api/abom-check.md)** — deferred by decision rather than by obstacle. Its planned release is verdict-only, over exact base/head commits and their lock contexts. It performs no analysis or native fixing and has no submission authority. @@ -290,21 +303,24 @@ refusal. latency problem on an assumption. Its first item needs none of that: two thirds of every retained database is build logs nothing reads. - **[An address the enterprise can reach, an identity it granted, and readers GitHub - authorizes](api/enterprise-server.md)** — ABOM runs as a private, read-only GitHub App with - installation tokens and installations as evidence, re-read on installation events; a workstation - receives its deliveries through a relay, verified end to end on `has-ghas`. Deferred: a production - address needs ingress this workstation lacks, and readers signing in through the App and workflow - callers wait on it. Installing on a second account waits on a decision the plan names: a private - App installs only on its owner. + authorizes](api/enterprise-server.md)** — ABOM runs as a private GitHub App with installation + tokens and installations as evidence, re-read on installation events; a workstation receives its + deliveries through a relay, verified end to end on `has-ghas`. The grants that stop being + read-only are [production credentials](api/production-credentials.md), not this deferral. + Deferred: a production address needs ingress this workstation lacks, and readers signing in + through the App and workflow callers wait on it. Installing on a second account waits on a + decision the plan names: a private App installs only on its owner. - **[Findings are a pluggable class](db/finding-providers.md)** — the seam is built and carries real data; a second provider is deferred by decision. - **[Every action has an API](api/api-first-invariant.md)** — already true, and not yet provable. Upkeep, with no client that needs it until the gate does. - **[Collapse `name@ref` back to one node](ui/explorer-references.md)** — per-reference nodes are the useful default and the only behavior. The counts for the other reading already ride on every node. -- **[Retain guarded submissions until native coverage is measured](api/dependency-submission.md)** - +- **[Retain guarded submissions until native coverage is measured](api/dependency-submission.md)** — existing manual submission and its ledger remain built; new client modes, write grants and - automation are deferred. [The native coverage crosscheck](api/dependency-graph-crosscheck.md) + automation are deferred. Moving the existing submission's credential onto the App is + [production credentials](api/production-credentials.md), not this expansion. + [The native coverage crosscheck](api/dependency-graph-crosscheck.md) must demonstrate a residual gap before expansion is reopened. Native replacement would require a deliberate release of historical snapshots on approved targets, not simply removing code. No timer or automatic first submission is introduced. @@ -320,7 +336,7 @@ refusal. addable; those implementations are not in this plan. [Container inventory](db/container-inventory.md) owns container declarations, not image contents. The shared model remains unranked. -- **[A report somebody can hand to somebody else](ui/printable-report.md)** - still blocked on +- **[A report somebody can hand to somebody else](ui/printable-report.md)** — still blocked on [graph layout](ui/graph-layout.md), for a different reason than before. A drawing that was different every run cannot be printed, and that half is fixed: a placed scope is byte-identical across runs. What cannot be printed now is a **161:1** canvas, and a scope wide enough to be @@ -355,7 +371,7 @@ measurement makes it urgent. | [db/data-efficiency.md](db/data-efficiency.md) | the standing cost review; one endpoint is still linear in rows | | [db/declaration-provenance.md](db/declaration-provenance.md) | how a declaration arrived, and what contradicts it | | [db/observations.md](db/observations.md) | the fact table's keys and its readers | -| [db/owned-scope.md](db/owned-scope.md) | ownership edges the declaration does not yet settle: per-account access in the pre-flight, a browser gate that never draws the declaration picker, and a failed declaration read shown as nothing declared | +| [db/owned-scope.md](db/owned-scope.md) | a browser gate that never draws the declaration picker, and a failed declaration read shown as nothing declared. Who may declare, including a member's repositories, is [ownership claims](api/ownership-claims.md) | | [db/pruning.md](db/pruning.md) | tombstones, compaction and what a delta reports | | [db/ref-provenance.md](db/ref-provenance.md) | requested refs, governing locks and analyzed commits through the ledger | | [db/supply-chain.md](db/supply-chain.md) | classification over the reachable dependency closure |