Repository navigation
Add CLI sign-in and JWT credential management #1562
Description
Problem or use case
The Scope CLI can send a bearer supplied through SCOPE_TOKEN, but users cannot
yet sign in through the CLI or have it acquire, securely persist, and refresh
their credentials. Manually sourcing access tokens is not a complete interactive
authentication experience.
This is the human CLI authentication delivery under parent #17. RBAC policy and
administration belong to #1300; internal service/job JWT authentication belongs
to #1557.
Proposed change
Implement human sign-in and the credential lifecycle for the CLI:
scope auth login: authenticate through the existing IdP, acquire an access
token for the Scope API, and explicitly enroll throughPOST /api/v1/users/me.scope auth logout: clear the selected locally cached credentials/account
context. Do not imply that local logout revokes already-issued bearer tokens.scope auth status/scope auth whoami: show the selected API/account and
Scope identity/role without exposing credentials; use read-only user lookup.- Persist the authentication SDK's cache through secure storage and silently
acquire/refresh access tokens for ordinary commands. - Reuse the centralized API client's token-provider and reauthentication hooks.
PreserveSCOPE_TOKENsupplied-bearer support, public/offline commands, and
separation from external HTTP requests such as update checks. - Provide actionable credential errors and deterministic non-interactive
behavior. Do not unexpectedly launch login or open a browser in automation.
Authentication boundary
The CLI uses a human IdP access JWT for the Scope API, not a worker
service/job token. JWT is the format, not a shared identity or signing key.
Preserve the API's unchanged-IdP-bearer and explicit-enrollment contract:
ordinary commands, status reads, and token refresh must never implicitly enroll.
Do not forward human bearer tokens into jobs or place client secrets/signing
private keys in the CLI.
JWT infrastructure and public-client/API configuration are assumed supplied.
This issue consumes the configured authority, API audience/scopes, client
registration, consent, and redirect/local-development settings; infrastructure
research and provisioning are not part of this implementation.
Application decisions to settle
- Adopt or explicitly amend the existing device-code/MSAL/SecretStore design in
docs/architecture/auth-rbac.mdsection 7. The Azure CLI-style browser-first
flow with a device-code option is a proposal, not a selected default. - Define account/API-origin binding, account selection, and
SCOPE_TOKEN
precedence and failure behavior. - Select secure persistence and its failure/fallback policy, including
headless environments. Do not silently downgrade storage security. - Define refresh concurrency, bounded reauthentication/retry, logout, and
rejected/expired-session behavior. - Resolve secure-storage dependencies against the standalone CLI distribution
contract, not just source-mode execution.
Acceptance criteria
- A user can sign in without manually sourcing a bearer and intentionally
enroll through the existing API contract. - Ordinary commands authenticate with the human API access token; refresh
and read-only identity/status calls never implicitly enroll. - Secure cache persistence, access-token expiry/refresh, local logout,
account/API isolation, and storage failures are covered. - Existing
SCOPE_TOKENusage remains compatible under documented
precedence; non-interactive failures are actionable and do not prompt. - Concurrent token acquisition/refresh is bounded and deduplicated; invalid
credentials do not cause unbounded retries or anonymous fallback. - Tokens are redacted from diagnostics and never attached to external
destinations, queues, agent environments, or AI-visible tools. - The actual standalone installed bundle supports the chosen authentication
and storage implementation, including supported headless behavior. - CLI help, command snapshots, environment guidance, and authentication/
distribution documentation describe the delivered behavior.
Alternatives
Continue requiring users to provide SCOPE_TOKEN manually. Keep that option for
supplied-bearer automation, but it does not replace interactive login, secure
cache persistence, and silent renewal.
Reuse internal service/job credentials for human CLI calls. Reject this because
it would conflate human identity with service authority.
Introduce a human Scope-token exchange or Scope PAT issuance. Neither is needed
for the existing human IdP-token contract; both remain outside this issue.
Additional context
- Parent tracker: Deliver authentication and RBAC across Scope #17.
- Human project authorization and administration: Enforce project membership RBAC and administration #1300; implementation PR feat: add project membership RBAC and administration #1532.
- Internal service/job authentication: Authenticate internal services with JWT #1557. CLI development need not wait for
that service implementation. - JWT foundation is an external assumption; infrastructure research is tracked
in growth-ecosystems/scope-core-infra#150.
This does not assert that infrastructure is deployed. - Existing design:
docs/architecture/auth-rbac.mdsection 7. - Existing client hooks:
apps/cli/src/utils/api-client.ts. - Standalone contract:
docs/architecture/cli-distribution.md. - Report authentication/post-run triggers, submitter-rights binding, user PATs,
and unrelated internal-service endpoints remain outside this delivery.
Activity