stellaops-cli scope census and the operator-identity split

Verified against: commit 387a960602 (2026-09-05, SPRINT_20260722_016 AUTH-15). Re-verified for the analytics.read withdrawal against: commit dff4651e77 (2026-10-01, SPRINT_20260930_006 PCD-228). Re-verified for the policy:operate admission against: commit 78eb198a8f (2026-10-09, SPRINT_20261008_004 WSF-2). Re-verify:

# the ceiling, production source floor, YAML grant, migration lineage, startup companions and rollback agree
pwsh ./tools/scripts/test-targeted-xunit.ps1 \
  -Project src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard.Tests/StellaOps.Authority.Plugin.Standard.Tests.csproj \
  -Class "*StellaOpsCliClientScopeCeilingTests*"
# the persisted row on a running estate is within the ceiling (reads authority.clients, not the YAML)
bash tools/scripts/deploy/postgres/apply-stellaops-cli-scope-ceiling.sh --verify

PCD-323 default-posture convergence

Startup migration 034_authority_stellaops_cli_scope_ceiling.sql applies the complete human CLI ceiling even when Authority:Bootstrap:Enabled=false. It intersects the persisted stellaops-cli.allowed_scopes with the same ceiling as S065 and repairs the properties.allowedScopes mirror. An absent client is a no-op, and a row already within the ceiling is not rewritten. The migration creates no client and adds no scope. Its successor 035_authority_stellaops_cli_scope_ceiling_policy_operate.sql (WSF-2) does the same with the current S066 ceiling; 034 stays applied and unchanged.

The Standard bootstrapper’s union cannot restore a surplus because the mounted descriptor is pinned within that ceiling. Keep the Startup companion, current Seed ceiling and StellaOpsCliClientScopeCeilingTests aligned when a future reviewed ceiling changes. The operator script remains a verification and explicit repair tool; normal upgrades converge through startup rather than requiring its --apply step.

Re-verify default-posture SQL behavior with CliScopeCeilingStartupTests in the Authority persistence suite: an old surplus row, JSON-only drift, unrelated-client isolation, NOBYPASSRLS execution, no Seed application and idempotent fresh/repeated startup.

PCD-285 source floor and read retirement at its accepted revision

The 2026-10-05 census finds 38 distinct StellaOpsScopes constants in production CLI source. The ceiling test pins that exact roster and verifies each value; test projects and build output are excluded. The earlier tier totals below are the dated AUTH-15 review, not a fresh source count.

S064 removes orch:read and scheduler:read from the permitted ceiling. Startup 032 removes exactly those permissions from the persisted CLI column and JSON mirror even with Seed disabled. The mounted YAML loses the same two grants, so a union reseed cannot restore them. Other clients and the scope catalog remain unchanged.

The source census also finds symbols:read and symbols:write on the existing Symbols client. S064 admits them to the permitted ceiling for that existing route/policy contract. Neither enters the YAML grant, and an intersection cannot add a missing scope. No standing Symbols or administrative grant is introduced. At the PCD-285 revision the ceiling contained 92 entries and the standing YAML grant narrowed from 84 to 82.

PCD-296 call graph upload

scan graph --upload calls POST /api/v1/scans/{scanId}/callgraphs through the backend operations client and requests ScannerCallGraphIngest (scanner.callgraph.ingest). Scanner registers that policy in ScannerWebService/Program.cs. S065 adds this one existing catalog permission to the permitted ceiling (93 entries), and the mounted CLI descriptor grants it. Registry handlers now name their three existing read/cache/admin constants, so the source floor becomes 42 constants. The standing grant becomes 83 scopes. A provider restart converges existing clients through the provisioning union; no other identity gains a permission.

WSF-2 risk budget consumption — 2026-10-09

The CLI budget consume command (src/Cli/StellaOps.Cli/Commands/Budget/RiskBudgetCommandGroup.cs) requests StellaOpsScopes.PolicyOperate (policy:operate) and calls the Policy Engine consume route listed in the budget command guide. src/Policy/StellaOps.Policy.Engine/Endpoints/RiskBudgetEndpoints.cs registers that route with RequireStellaOpsScopes(StellaOpsScopes.PolicyOperate). Until this change the scope was outside the ceiling, so Authority refused the token request and the command never reached the owner.

Decision. Owner ruling 2026-10-09, recorded in the CLI scope-floor follow-up sprint (WSF-2, option (a)), admits policy:operate to the ceiling instead of withdrawing the verb. For the human CLI consume verb this ruling supersedes the AUTH-15 Table B entry, which classified policy:operate as per-incident on stellaops-break-glass-operator.

• Seed S066_stellaops_cli_scope_ceiling_policy_operate.sql adds this one catalog permission to the permitted ceiling (94 entries). Startup 035_authority_stellaops_cli_scope_ceiling_policy_operate.sql applies the same ceiling with bootstrap disabled. Both intersect and cannot add a scope.
• The mounted CLI descriptor grants the scope, so the standing grant becomes 84 scopes and a provider restart puts it on existing rows through the provisioning union. No other identity gains a permission.
• The source floor pins PolicyOperate (45 constants). The rollback list already contained policy:operate from the pre-AUTH-15 row, so it stays at 145 scopes.

Effect beyond the consume verb. A token issued to stellaops-cli with this scope also satisfies the other Policy Engine routes that require it: unknowns budget check (BudgetEndpoints.cs), console export jobs (ConsoleExportEndpoints.cs), four exception routes (Gateway/ExceptionEndpoints.cs), gate jobs (Gateway/GateJobEndpoints.cs), the NIS2 control-register snapshot (Nis2ControlRegisterEndpoints.cs) and two unknowns routes (UnknownsEndpoints.cs). policy:operate is not one of the PCD-290 operation-bound scopes, so a password grant that omits scope also receives it. Policy Studio scopes still require a tenant assignment.

Re-verify with StellaOpsCliClientScopeCeilingTests (the guard named above), MigrationS066StellaOpsCliPolicyOperateCeilingTests and CliScopeCeilingStartupTests in the Authority persistence suite. A running estate gets the new ceiling and grant only after Authority is rebuilt from a commit that carries them and restarted.

General login versus operation-bound grants

PCD-290 (owner decision, 2026-10-04): a password grant that omits scope receives the client’s allowed scopes except policy:publish, policy:promote, obs:incident, packs.approve, exceptions:approve and release:gate-bypass. A login supplies no operation metadata or approval context. Keeping these permissions in the ceiling lets an explicit operation request them under the existing metadata, MFA and authorization checks; it does not make them general login scopes. This changes no client ceiling, automation grant or explicitly requested scope.

Re-verify the rule and the explicit-request negative controls with PasswordGrantHandlersTests in StellaOps.Authority.Tests, including NoScopePasswordGrant_OmitsOperationBoundScopes_WithoutPrincipalFallbackReintroducingThem.

Watchlist source boundary — 2026-10-07

Verified against c0b0490da306d66a818486b09ae9fd440a3bda1b. Evidence composes the watchlist API at /api/evidence/v1/watchlist. WatchlistEndpoints.cs attaches the watchlist:read / watchlist:write policies; Security/AttestorPolicies.cs admits the corresponding trust:read / trust:write catalog scopes and the documented higher-privilege alternatives.

CLI consumer (PCD-449; re-verified 2026-10-08 against d1931de29f). The fail-closed placeholder this section described on 2026-10-07 is gone. The CLI now calls the owner. src/Cli/StellaOps.Cli/Commands/Watchlist/WatchlistCommandHandlers.cs sends POST and GET on the collection, GET, PUT and DELETE on {id} (update reads the definition first) and POST {id}/test, all under /api/evidence/v1/watchlist. List, get and test request trust:read. Add, update and remove request trust:write. Both scopes are in the ceiling and the standing grant, and the source-floor roster pins TrustRead and TrustWrite. The CLI never requests trust:admin, which stays outside the ceiling (Table B). Creating or deleting a global definition must pass the owner’s in-endpoint administrator check (trust:admin, watchlist:admin or the admin role); a caller who fails it gets 403. The CLI sends no alert-history request. Re-verify the CLI side with WatchlistOwnerRouteTests in StellaOps.Cli.Tests.

The Table A route bindings below for trust:read and trust:write cite the predecessor command group and route. They are historical AUTH-15 census evidence; the paragraph above is the current binding. Neither correction changes a grant or the scope ceiling.

The current ceiling/source roster is owned by src/Authority/StellaOps.Authority/StellaOps.Authority.Plugin.Standard.Tests/StellaOpsCliClientScopeCeilingTests.cs, which selects S066 and Startup 035. Re-run that guard rather than treating older tier counts or migration lists below as today’s grant. Startup 034 and its successor 035 apply the complete ceiling with bootstrap disabled, as the PCD-323 section above explains; older text saying an operator script is mandatory is superseded.

Guard failure resolved (2026-10-09). On 2026-10-08 SourceScopeFloor_MatchesTheCurrentProductionCliCensus failed on main because PCD-427’s budget consume names StellaOpsScopes.PolicyOperate, which was outside the ceiling. The owner chose to admit the scope (WSF-2, see the section above). S066, Startup 035, the standing grant and the guard’s roster now include it, and the whole class passes.

Historical AUTH-15 census and operator notes withdrawn 2026-10-07

The material below preserves the 2026-09-05 review, later dated annotations and its historical procedures. Its static counts, route bindings, rollback captures and pre-PCD-323 default-posture instructions do not override current source or the accepted changes above. No current database repair is authorized by this historical appendix.

Why this document exists

stellaops-cli is the shipped human CLI client (authorization_code password refresh_token). Until 2026-09-05 it was also the estate’s manual-mint and break-glass identity: every operator script, runbook curl and QA harness that needed a human-bound token minted through it, and every grant those procedures ever needed was appended to its allowedScopes. The live authority.clients row carried 143 scopes; the shipped CLI can exercise 88. Two consequences followed:

• every CLI login token was a potential estate-administration token, bounded only by the user’s role;
• the only audience common to every break-glass token was the estate-wide stellaops, which is why the router gateway’s introspection identity for findings:recovery had to be registered under it (SPRINT_20260722_010 FND-17).

This page records the census that decided what the CLI client keeps, where everything else went, and the two mechanisms that keep the split from silently regressing.

Method — how “the CLI needs it” was decided

A scope stays on stellaops-cli when one of three machine-checkable facts holds:

These tier counts record the earlier review. The current source-constant floor is verified above; the ceiling contains 92 entries. AUTH-15 recorded 41 / +18 / +29 / +4 = 92 (this table said +19 until 2026-10-01; Table A as first committed, ced09a106c, lists 18 tier-2 rows). envstate:time-anchor:write joined tier 1 on 2026-09-14 (S060, 93) and analytics.read left tier 2 on 2026-10-01 (S063, 92).

orch:quota is named in docs/modules/cli but excluded: the token endpoint requires quota_reason for it and the CLI never sends one (S001 records the same decision). Tier 1 alone is the “27 constants” figure often quoted; it under-counts because the CLI supplies most scopes through the operator’s configured Authority:Scope rather than naming them, and because a whole endpoint group can be gated by a scope the CLI never spells out (/console/* requires ui.read, so stella auth token mint needs it).

Everything else on the live row (59 scopes) leaves the CLI client. Each was checked for a consumer: operator scripts under devops/ and tools/, .gitea workflows, QA harnesses and fixtures under src/__Tests and src/Web, and runbook curl recipes. The consumers group into five operational procedures, and each procedure now has its own password-grant identity carrying exactly the union of scopes its scripts request.

Ten ceiling scopes are not granted today and were not added by this change (a narrowing change adds nothing): authority:idp.read, authority:idp.write, obs:read, ops.admin, platform.setup.admin, platform.setup.read, policy:promote, vex:ingest. The CLI names them; symbols:read and symbols:write are also permitted but ungranted. The corresponding verbs cannot mint through stellaops-cli until an operator adds them, which the ceiling permits.

Table A — the ceiling (92 scopes; 82 granted)

2026-09-14 (SPRINT_20260914_002 EA-5): envstate:time-anchor:write joined the ceiling and the grant. stella airgap time-anchor declare PUTs /api/v1/platform/environment-state/time-anchor/{scope} and Platform’s custody policy for that class accepts only this scope (no legacy alias, unlike airgap-seal); the CLI now requests it per class (BackendOperationsClient.ResolveEnvironmentStateWriteScope). The widening shipped as migration S060 in S058’s intersection shape — S058 is applied and checksum-pinned, so it is never edited.

2026-10-01 (SPRINT_20260930_006 PCD-228): analytics.read left the ceiling and the grant; its row moved to Table B. It was tier 2 (docs/modules/cli/guides/commands/analytics.md). PCD-127 withdrew the CLI analytics command group with Platform’s /api/analytics/* endpoints, no src/Cli source names the scope, and the one surface that still enforces it, Platform’s NIS2 telemetry group (/api/telemetry/nis2, PlatformPolicies.AnalyticsRead), is called by no CLI route literal (stella export nis2-effectiveness reads a local --report file and posts it to ExportCenter under export.operator / export.viewer). The narrowing shipped as migration S063 in the same intersection shape, with startup companion 031 for the default posture (see the union-reseed section). The guard pins each successor’s exact delta: S058 → S060 adds envstate:time-anchor:write; S060 → S063 drops analytics.read.

Table B — the 62 scopes that left stellaops-cli

“Consumers” counts the census entries (Table C) that requested the scope through stellaops-cli. 59 left at AUTH-15 (2026-09-05); analytics.read left on 2026-10-01 (PCD-228), and the two JobEngine reads left under PCD-285.

Table C — every consumer that minted through stellaops-cli, and where it mints now

Consumers that stay on stellaops-cli do so because every scope they request is a product-CLI scope: they simulate a CLI user and should keep exercising the product path. Where a harness requested a scope it never used (platform.context.read, release.policy-bindings.*, evidence:create/hold), the request was trimmed rather than the identity widened.

Table D — the operator identities

All five follow the shape stellaops-advisory-ai-operator established: allowedGrantTypes: password (human-bound, role-gated), tenantId and tenants pinned to default (two tenants without a singular tenantId suppresses the tenant bind and advisory scopes are rejected), allowedAudiences: stellaops only (the router gateway validates aud=stellaops; per-service audiences are inert under Router__AuthorizationTrustMode=GatewayEnforced), public (the credential is the operator’s own login).

Which identity an operator reaches for:

The stella CLI itself can mint through any of them: set STELLAOPS_AUTHORITY_CLIENT_ID (or --Authority:ClientId) to the identity and request only the scopes the procedure needs.

Scope break-glass after this change

This is the scope break-glass (an elevated grant for one incident). It is distinct from the credential-recovery break-glass in docs/runbooks/authority/authority-break-glass-recovery.md.

• Scope issuance is gated by the client ceiling only. PasswordGrantHandlers resolves the requested scopes against the client’s allowedScopes (ClientCredentialsHandlers.ResolveGrantedScopes); there is no intersection with the user’s role permissions at mint time. Consequently a scope that sits on any public password-grant client is mintable by every user who can log in — which is exactly why the CLI client’s ceiling is a security boundary and why stellaops-break-glass-operator carries no break-glass scope at rest (openid profile; non-empty because an empty allowed set grants anything requested).
• findings:recovery is granted to no bootstrap client (RepositoryStandardDescriptors_GrantFindingsRecoveryToNoClient pins the FND-17 doctrine). The procedure in docs/runbooks/findings/findings-service-deploy.md: append the scope to the break-glass row for the incident, assign the incident-findings-recovery role, mint through stellaops-break-glass-operator, run the audited transitions, revoke role and token, then reset the break-glass row in the database (the reseed never removes what was appended).
• Any other emergency scope (the “none” rows of Table B: signer:rotate, authority:signing-keys.*, issuer-directory:admin, platform:federation:*, …) follows the same path — onto the break-glass row for the incident, through the Console client editor (authority:clients.write, i.e. via stellaops-estate-admin-operator) or standard.yaml + restart, and off it again with the same UPDATE. Never onto stellaops-cli: the ceiling test fails the commit and the migration removes it from the database.
• Superseded 2026-09-08 by AUTH-17. When this census was written the gateway’s break-glass introspection client was registered under stellaops — the audience every token in the estate carries — so it covered every break-glass token by construction, whichever client minted it. AUTH-17 narrowed it: the introspection client is now stellaops-gateway-introspection, only stellaops-break-glass-operator names that id in its allowedAudiences, and the estate-wide stellaops client is deleted (migration S059_retire_estate_wide_introspection_client.sql). Consequence for the procedures above: a findings:recovery token must be minted through stellaops-break-glass-operator, or the gateway refuses it 503 break_glass_introspection_not_authorized_party before any revocation question is asked.

The union-reseed asymmetry — why the database step is mandatory

StandardClientProvisioningStore.CreateOrUpdateAsync merges DB ∪ YAML for allowedScopes, audiences and tenants on every Authority boot and never shrinks a grant (Sprint 20260520_084, RESIDUAL-2). Therefore:

• Adding a scope to standard.yaml lands on the live row with a plain restart.
• Removing a scope from standard.yaml changes nothing on a running estate, and on a fresh database S001 + S034…S057 re-append the historical grants before the bootstrapper runs.

The narrowing is therefore a forward-only migration, S058_stellaops_cli_scope_ceiling.sql, which sorts after every append migration and intersects the persisted row with the ceiling. Its successors restate the ceiling in the same shape: S060 (adds envstate:time-anchor:write) and S063_stellaops_cli_scope_ceiling_analytics_withdrawal.sql (drops analytics.read), followed by current S064_stellaops_cli_scope_ceiling_jobengine_withdrawal.sql. S064 drops orch:read and scheduler:read and admits the existing Symbols scopes to the ceiling without adding standing grants.

These are Seed-category migrations. The startup host applies Seed migrations only when AUTHORITY_BOOTSTRAP_ENABLED=true (RunSeedMigrations); the shipped default is false. With bootstrap enabled, the ceiling converges an existing estate (on the first boot of an image that embeds it) and a fresh bootstrap (after S057) on the same set. In the default posture none of them runs: a fresh install holds only the YAML grant, which the guard keeps inside the ceiling, and an existing row is narrowed to the ceiling only by the script below. A scope that a successor drops must also leave existing rows in the default posture, so it ships with a Startup-category companion that removes exactly that scope from stellaops-cli: 031_authority_stellaops_cli_analytics_read_retirement.sql for analytics.read, and 032_authority_stellaops_cli_jobengine_read_retirement.sql for the two JobEngine reads. A narrowing successor converges because the YAML narrows with it: the guard keeps the YAML grant inside the current ceiling, so the reseed union cannot put the dropped scope back.

Because embedded SQL needs an image rebuild, an estate that has not taken that image applies the identical statement by hand:

bash tools/scripts/deploy/postgres/apply-stellaops-cli-scope-ceiling.sh --apply     # snapshots the row first
bash tools/scripts/deploy/postgres/apply-stellaops-cli-scope-ceiling.sh --verify    # row ⊆ ceiling, reads the DB
bash tools/scripts/deploy/postgres/apply-stellaops-cli-scope-ceiling.sh --rollback  # the 143-scope pre-change row
bash tools/scripts/deploy/postgres/apply-stellaops-cli-scope-ceiling.sh --self-test # proves --verify detects

The script parses the ceiling out of the migration file rather than carrying its own copy, so the two cannot disagree. The rollback file (rollback-stellaops-cli-scope-ceiling.sql) is the exact pre-change row captured on 2026-09-05 — 139 YAML scopes plus four DB-only survivors (signals:read, signals:write, stellaops.admin, stellaops.api) — and RollbackScript_RestoresThePreChangeRowAndCoversEveryCurrentGrant pins that it is a superset of the current grant. Restoring the YAML alone is not a rollback: the reseed re-adds exactly what the YAML declares and nothing else.

Verify against the database, never the file. The YAML is the intent; the row is what Authority mints from.

The guard

StellaOpsCliClientScopeCeilingTests (StellaOps.Authority.Plugin.Standard.Tests) pins:

1. the ceiling is catalogued, distinct, sorted and non-vacuous (92 entries, every one in StellaOpsScopes.All or OIDC, the current 38 source constants present);
2. stellaops-cli’s allowedScopes in standard.yaml ⊆ ceiling, and carries openid profile email offline_access and at least 50 scopes (a rewrite that drops half the grant fails too);
3. the ARRAY[...] literal in the CURRENT ceiling migration (S064) equals the ceiling;
4. every ceiling-shaped migration on disk is in the recorded lineage (S058, S060, S063, S064), and each successor differs from its predecessor by exactly the recorded delta;
5. every scope a successor drops has a Startup-category companion that retires exactly that scope from stellaops-cli (031 for analytics.read, 032 for the two JobEngine reads), and the YAML grant does not declare it;
6. the rollback file lists the 143-scope pre-change row plus the EA-5 scope (144) and is a superset of the current grant;
7. the five operator identities have the D-AAI9 shape and only catalogued scopes; the break-glass identity is exactly openid profile;
8. findings:recovery is granted to no bootstrap client at all.

Red-proof (2026-09-05): adding signer:rotate to the YAML grant fails fact 2 naming signer:rotate; deleting vuln:operate from the migration array fails fact 3 naming it. The deploy script’s --self-test proves its own detector the same way (an in-ceiling row passes, one out-of-ceiling scope fails). Red-proof (2026-10-01, PCD-228): with the pre-change YAML and no S063, facts 2, 3, 4 and 5 fail (4 of 9 cases); with analytics.read put back into S063’s array, facts 3 and 4 fail naming it. MigrationS063StellaOpsCliAnalyticsWithdrawalTests and Migration031StellaOpsCliAnalyticsReadRetirementTests (StellaOps.Authority.Persistence.Tests, real PostgreSQL) prove both files remove the scope from the column and the JSON mirror, keep every other scope, leave other clients alone and are idempotent.

Limitations recorded, not fixed

• src/Web/StellaOps.Web/e2e/vexlens-token-scope-forcing-function.e2e.spec.ts and src/Web/StellaOps.Web/tests/e2e/integrations/distro-vex-advisory-only-not-capped.spec.ts mint vexlens.read / vexlens.write through stellaops-cli. No endpoint enforces either scope and no service registers /api/v1/vexlens/*, so both specs were already non-functional against the current estate; they now also fail at the token endpoint (invalid_scope). They need re-homing onto the stella-ops-ui grant they actually assert, which is Console work, not Authority work.
• tools/scripts/qa/Invoke-AdvancedAssuranceRerun.ps1 requests roles, which is not a scope; the request was refused before this change and is unaffected by it.
• stellaops-cli keeps audiences signer and registry (needed by the kept signer:sign and registry.* scopes) and api://issuer-directory (no kept scope needs it; audiences union on reseed exactly like scopes, so removing it is its own DB step and was not part of this change).
• The ten ceiling scopes the CLI names but is not granted (see Method) remain a pre-existing gap.
• stellaops-cli still declares tenants: default tenant-golden-local; the operator identities are default-only and gain further tenants only through the console tenant-create auto-grant, which extends every firstParty client.
• The ceiling migrations are Seed-category, so in the default posture (AUTHORITY_BOOTSTRAP_ENABLED=false) a stellaops-cli row that predates AUTH-15 keeps every scope the YAML ever granted until apply-stellaops-cli-scope-ceiling.sh --apply runs. The Startup companions 031 and 032 retire only analytics.read, orch:read and scheduler:read; they do not apply the rest of the ceiling.
• A CLI configuration whose Authority:Scope (STELLAOPS_AUTHORITY_SCOPE) still lists analytics.read is now refused as a whole with invalid_scope: the password grant rejects a request that names any scope outside the client’s allowed set. No shipped default lists it.
• PCD-324 removes the unrequested analytics.read grant from stellaops-cli-automation in standard.yaml and Startup migration 033_authority_cli_automation_analytics_read_retirement.sql. Source verification: bb8ae339ad (2026-10-05). The migration narrows both allowed_scopes and the optional properties.allowedScopes mirror, including JSON-only drift, and leaves other scopes, clients, audiences and tenant bindings intact. This runs with bootstrap disabled; the Standard reseed cannot re-add a scope absent from YAML. The scope catalog and the Console’s NIS2 grant remain. Re-verify with RepositoryAutomationGrant_DoesNotIncludeUnrequestedAnalyticsRead and Migration033AutomationAnalyticsReadRetirementTests, plus both adjacent plugin and persistence suites. This does not apply the separate whole-CLI ceiling decision tracked by PCD-323.