stellaops-cli scope census and the operator-identity split

Verified against: commit 387a960602 (2026-09-05, SPRINT_20260722_016 AUTH-15). Re-verify:

# the ceiling, the YAML grant, the migration and the rollback agree (7 facts)
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

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:

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.

Eight 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; the corresponding verbs cannot mint through stellaops-cli until an operator adds them, which the ceiling permits.

Table A — the ceiling (93 scopes; 85 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; the guard asserts S058 ⊂ S060.

Table B — the 59 scopes that left stellaops-cli

“Consumers” counts the census entries (Table C) that requested the scope through stellaops-cli.

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. It converges an existing estate (on the first boot of an image that embeds it) and a fresh bootstrap (after S057) on the same set. 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 (93 entries, every one in StellaOpsScopes.All or OIDC, the 28 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 (S060) equals the ceiling, and the prior one (S058) is a strict subset of it — a successor never drops a scope;
4. the rollback file lists the 143-scope pre-change row plus the EA-5 scope (144) and is a superset of the current grant;
5. the five operator identities have the D-AAI9 shape and only catalogued scopes; the break-glass identity is exactly openid profile;
6. 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).

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 eight 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.