Account and Pro access services
The account subsystem gives the native CLI a safe boundary for account sign-in, session use, plan display, setup status, design and critique access, health data, taste preferences, world-based design seeding, prototype records, repository switches, and Pro rule access. It connects the CLI to one configured account service while keeping credentials local, making network access optional for core commands, and falling back to open rules when Pro access is not ready.
The page sits under Native runtime and CLI. For the wider command runtime, see Rust CLI runtime. The account service also supports the health and rule flows described by Agent protocol services, Design seed generation, Component composition operations, and Design foundations and taste.
Account service boundary
Service configuration
The account configuration identifies one account service and one local home. The default service is the production Impeccable origin. A different origin is allowed only when it is a secure origin or a loopback HTTP origin for local rehearsal. The origin also scopes the resource indicator and the local sign-in directory, so credentials for different services do not mix. (crates/…/config.rs• L7-60)
The HTTP boundary accepts only requests on that configured origin. It disables redirects and limits response size and time. This keeps tokens, authorization codes, and other account data inside the service selected by configuration. (crates/…/http.rs• L47-86)
References: crates/…/config.rs• L7-60 crates/…/http.rs• L47-86
Account HTTP interface
The subsystem uses a small account client for public JSON reads, form requests, authorized JSON requests, and bounded artifact reads. It turns service status replies into stable status and error-code results. Network failures stay separate from service refusals so callers can choose whether to retry, fall back, or report a signed-in but unreachable account. (crates/…/http.rs• L10-45, crates/…/http.rs• L99-220)
Every authorized call validates the bearer token before it reaches the HTTP header. The client also refuses malformed or oversized service answers. (crates/…/http.rs• L223-249)
References: crates/…/http.rs• L10-45 crates/…/http.rs• L99-220 crates/…/http.rs• L223-249
Sign-in and session lifecycle
OAuth login
Login uses the native-app OAuth flow. The CLI reads service metadata, checks that the service supports PKCE and issuer binding, opens a local callback, and sends the user to the browser. The authorization request carries the CLI resource and account scopes. Optional scopes for health, setup, foundations, DESIGN.md, critique uploads, worlds, and supported agent tools are requested only when the service advertises them. (crates/…/oauth.rs• L23-129, crates/…/oauth.rs• L147-170)
The callback accepts only the request's state and the configured issuer. The CLI then exchanges the code with the PKCE verifier and validates the token answer before storing it. A callback that does not belong to the active attempt cannot complete login. (crates/…/oauth.rs• L250-280, crates/…/oauth.rs• L315-428, crates/…/oauth.rs• L464-559)
The login flow ends an older grant after the new sign-in is saved. A sign-out that happens while the browser is open wins over the late callback. This prevents an old browser attempt from restoring access after the user has signed out. (crates/…/lib.rs• L34-146)
The following diagram shows the main login path.
sequenceDiagram
participant CLI
participant Service as Account service
participant Browser
participant Local as Local callback
CLI->>Service: Read OAuth metadata
CLI->>Local: Bind loopback callback
CLI->>Browser: Open authorization URL
Browser->>Service: Approve account access
Service->>Local: Return code, state, and issuer
Local-->>CLI: Validate callback
CLI->>Service: Exchange code with PKCE verifier
Service-->>CLI: Access and refresh tokens
CLI->>CLI: Save the new sign-in
CLI->>Service: Revoke replaced grant when needed
References: crates/…/oauth.rs• L57-129 crates/…/oauth.rs• L250-280 crates/…/oauth.rs• L315-428 crates/…/lib.rs• L34-146
Credential storage
The local store separates sign-in state from secret tokens. State records the service, sign-in generation, token endpoints, granted feature scopes, and selected secret backend. Tokens use the platform keychain where supported or a private file when selected. The backend stays fixed for that sign-in. (crates/…/store.rs• L1-16, crates/…/store.rs• L27-81)
One lifecycle lock orders login, logout, token refresh, and related Pro state changes. Writers re-read state under the lock and advance its generation. Logout writes a signed-out tombstone before it removes the secret, so an older process cannot resurrect the session. (crates/…/store.rs• L151-215, crates/…/store.rs• L280-394)
References: crates/…/store.rs• L1-16 crates/…/store.rs• L151-215 crates/…/store.rs• L280-394
Session access
The session layer presents a live access token to account operations. It refreshes near expiry under the lifecycle lock and adopts a newer generation when another process already rotated the tokens. A rejected refresh signs the machine out locally. (crates/…/session.rs• L44-149, crates/…/session.rs• L153-267)
Authorized calls retry once after a 401. This gives commands a stable account operation without exposing refresh-token rotation to each caller. (crates/…/session.rs• L271-309)
Background account work uses a non-interactive session with a short wait. It may renew credentials in a detached process, but it does not take ownership of the upload or report body. The worker checks the sign-in lineage again before it uses a renewed session, so a later login or logout cannot be changed by late work. (crates/…/session.rs• L73-130, crates/…/session.rs• L341-352, crates/…/session.rs• L424-476)
References: crates/…/session.rs• L44-149 crates/…/session.rs• L153-309 crates/…/session.rs• L341-352 crates/…/session.rs• L424-476
Scope state
Feature scopes are consent state, not live service configuration. Login asks for the scopes advertised by the service. Token responses record the granted set, and later refreshes keep that set when the service omits a scope field. A later metadata change cannot enlarge an existing grant; a new login is needed for newly available access. (crates/…/oauth.rs• L57-129, crates/…/oauth.rs• L474-559, crates/…/scopes.rs• L8-129)
Each optional service has a separate boundary. The CLI can therefore use account and rule access while skipping setup, foundations, taste, DESIGN.md, critique, prototype, world, or health work that was not offered or consented to. Taste refresh also removes its local copy when that grant is lost. (crates/…/oauth.rs• L131-170, crates/…/taste.rs• L55-116)
References: crates/…/oauth.rs• L57-170 crates/…/oauth.rs• L474-559 crates/…/scopes.rs• L8-129 crates/…/taste.rs• L16-27 crates/…/taste.rs• L55-116
Account information and service data
Plan and entitlement retrieval
The entitlement endpoint answers whether the current sign-in includes Pro and may name a known plan. The public plan catalog adds customer-facing plan text. Catalog failure does not hide the entitlement result; the CLI uses a short Pro or non-Pro message instead. (crates/…/session.rs• L311-338, crates/…/plans.rs• L1-99)
whoami combines local sign-in state, live entitlement, and optional plan data. Its human form explains the account and plan. Its JSON form gives scripts the account URL, sign-in state, Pro result, reason, and available plan fields. (crates/…/lib.rs• L259-347)
References: crates/…/session.rs• L311-338 crates/…/plans.rs• L1-99 crates/…/lib.rs• L259-347
Design health synchronization
Design health sends a full repository scan summary after detection when the user is signed in and local policy allows it. The service receives counts by rule and opaque finding fingerprints. With separate consent, the same sign-in can also send design-foundation evidence. Neither path sends code, snippets, file names, or remote URLs. Upload failure never changes detection output or its exit code. (crates/…/health.rs• L1-13, crates/…/health.rs• L120-192, crates/…/health.rs• L229-296, crates/…/health.rs• L583-644)
The CLI exposes impeccable health status, on, off, and forget. CI, telemetry opt-out, local disablement, unreadable health state, and no sign-in stop an upload before network or repository work begins. forget disables sync first and then asks the service to delete saved results. (crates/…/health.rs• L86-142, crates/…/health.rs• L343-467)
The health flow keeps detection independent from account availability.
flowchart LR
A[Full detect] --> B{Local policy allows sync?}
B -- No --> C[Return detect result]
B -- Yes --> D{Signed in?}
D -- No --> C
D -- Yes --> E[Build counts and opaque fingerprints]
E --> F[Upload health and permitted foundation data]
F --> C
F -. Failure is silent .-> C
References: crates/…/health.rs• L86-192 crates/…/health.rs• L229-296 crates/…/health.rs• L343-467 crates/…/health.rs• L583-644
Setup state reporting
Setup reporting gives the account a limited view of how Impeccable is installed on the machine. It runs at most once per day for a consented sign-in and sends approved counts and version data rather than private inventory details. The report is a best-effort side effect and does not block the command that collected the inventory. (crates/…/setup.rs• L69-190, crates/…/setup.rs• L193-299)
The CLI exposes impeccable setup status, on, off, and forget. A local preference epoch cancels an in-flight report when the user changes the setting. forget turns reporting off before asking the service to delete the saved report. (crates/…/setup.rs• L301-355)
References: crates/…/setup.rs• L69-190 crates/…/setup.rs• L193-299 crates/…/setup.rs• L301-355 crates/…/setup.rs• L8-197
Account setup status
Account setup status gives the CLI a service-owned view of connected tools, the current project, and the next setup step. The CLI presents the service's known states without trying to infer missing connections or reorder the recommended work. (crates/…/setup_status.rs• L1-18, crates/…/setup_status.rs• L72-111)
impeccable status prints a short human view for a terminal or the service answer as JSON for scripts. After login, the same read may print setup lines on stderr so stdout remains safe for automation. Unknown service states are omitted, and an unsupported answer fails rather than being guessed at. (crates/…/setup_status.rs• L114-182)
References: crates/…/setup_status.rs• L25-69 crates/…/setup_status.rs• L72-127 crates/…/setup_status.rs• L131-182
Design taste refresh
Design taste is a read-only set of account preferences that can guide local design work. When the user has consented to taste access and the short-lived local copy is stale, a detached refresh reads the person's rules and updates the cache without making the main command wait for network work. (crates/…/taste.rs• L1-28, crates/…/taste.rs• L74-87)
The cache is tied to both the configured account service and the sign-in lineage. A lost taste grant clears only the matching copy, while a changed login or concurrent local update prevents a late reply from replacing current data. (crates/…/taste.rs• L30-72, crates/…/taste.rs• L88-116)
References: crates/…/taste.rs• L1-28 crates/…/taste.rs• L30-72 crates/…/taste.rs• L74-116
Design document access
The DESIGN.md service shares the health control surface but has its own consent scope and local setting. When enabled, a successful scan may upload the current DESIGN.md text and a small approved sidecar of design metadata. The upload is bounded and tied to the repository identity. (crates/…/design.rs• L1-7, crates/…/design.rs• L61-118, crates/…/design.rs• L278-374)
The reader anchors access to the opened repository directory and rejects redirects, special files, oversized content, and identity changes. This keeps a background upload from reading a different path after a rename or link change. (crates/…/design_read.rs• L6-53, crates/…/design_read.rs• L256-319)
References: crates/…/design.rs• L1-7 crates/…/design.rs• L61-118 crates/…/design.rs• L278-374 crates/…/design_read.rs• L6-53
World design seeding
The world command starts a project from a design direction in the Impeccable catalog. The account service returns the finished DESIGN.md and its sidecar, so the catalog content and the mapping from a world to design files stay outside the CLI. (crates/…/world.rs• L1-9, crates/…/world.rs• L201-231)
impeccable world <id> writes only when the project has no design system. --print returns the seed for an agent or engineer to merge into an existing system. The command requires a signed-in account, and the service may gate a world on Pro. (crates/…/world.rs• L22-39, crates/…/world.rs• L177-199, crates/…/world.rs• L376-400)
References: crates/…/world.rs• L1-9 crates/…/world.rs• L128-270 crates/…/world.rs• L376-400
Critique report access
Critique sync uploads newly saved reports when the user has enabled it, is signed in, and has granted the critique scope. The service receives validated report metadata and text. It does not receive heuristic detail that is not present in saved metadata. (crates/…/critiques.rs• L1-10, crates/…/critiques.rs• L26-89, crates/…/critiques.rs• L91-225)
The CLI exposes impeccable critiques status, on, off, and forget. Uploads use a short time budget and no retry. A successful upload can produce a notice for human output, while quiet or machine-oriented work leaves that notice owed for a later human command. (crates/…/critiques.rs• L227-290, crates/…/upload_notice.rs• L1-31)
References: crates/…/critiques.rs• L1-10 crates/…/critiques.rs• L26-89 crates/…/critiques.rs• L91-225 crates/…/critiques.rs• L227-290 crates/…/upload_notice.rs• L1-31
Prototype acceptance records
Prototype records give the account service a small activity record after a person accepts a live prototype variant. The record identifies the project, target, variant count, and acceptance time; it does not upload the prototype image, code, or text. It uses the critique upload consent and the same short-lived, best-effort service boundary, so the accepted result remains local when account access is unavailable. (crates/…/prototypes.rs• L1-18, crates/…/prototypes.rs• L20-74)
References: crates/…/prototypes.rs• L1-18 crates/…/prototypes.rs• L20-74
Repository switch state
Repository switch state lets the native tooling read and save a person's rule choices for a repository. The account service supplies the person's choices and team defaults, while a refresh writes only known catalog ids as on or off. A refresh stays tied to the sign-in that began it, so a changed account cannot receive a write from an older operation. (crates/…/switches.rs• L1-18, crates/…/switches.rs• L37-86)
References: crates/…/switches.rs• L1-18 crates/…/switches.rs• L37-86
Pro entitlement and rule access
Pro entitlement state
The account service is the authority for the current sign-in's Pro entitlement. An explicit non-Pro answer removes the installed Pro state. An explicit Pro answer clears a prior denial and permits a new refresh. Answers are tied to the sign-in generation, so a result from an older sign-in cannot change the current one. (crates/…/mod.rs• L269-360)
The subsystem also keeps a revision floor outside the removable Pro state. Signing out or losing entitlement removes the active lease but does not permit a later refresh to install an older release. (crates/…/mod.rs• L234-260, crates/…/mod.rs• L388-403)
References: crates/…/mod.rs• L234-260 crates/…/mod.rs• L269-360 crates/…/mod.rs• L388-403
Pro refresh and verification
Refresh obtains a release manifest and a time-limited lease for the current CLI engine and platform. It verifies the release with keys trusted by the CLI, verifies the lease with keys published by the account service, downloads only the named artifact, and checks its digest before installation. A refresh does not hold the sign-in lock during network or artifact work. (crates/…/mod.rs• L479-631)
The verification layer separates two trust decisions. The release manifest must match the CLI build and a pinned release key. The lease must match the artifact, its published key, and its allowed time window. (crates/…/verify.rs• L11-32, crates/…/verify.rs• L67-132, crates/…/verify.rs• L135-243)
References: crates/…/mod.rs• L479-631 crates/…/verify.rs• L11-32 crates/…/verify.rs• L67-132 crates/…/verify.rs• L135-243
Pro scan dispatch
Before a scan, the native CLI makes an offline decision. It runs the Pro child only when the sign-in, entitlement marker, manifest, lease, artifact, and digest all pass. Otherwise it runs the open engine and reports a short reason when the output mode allows it. A near-expiry lease starts a background refresh. (crates/…/mod.rs• L733-791, crates/…/mod.rs• L800-858)
The dispatch boundary is limited to scan execution. It never dispatches another Pro child, an explicitly selected binary, a disabled Pro mode, or a non-scan command. This keeps account and Pro checks from changing unrelated CLI behavior. (crates/…/mod.rs• L692-710, crates/…/mod.rs• L800-815)
The following diagram shows how entitlement becomes scan behavior.
flowchart TD
A[Scan command] --> B{Pro dispatch allowed?}
B -- No --> C[Run open engine]
B -- Yes --> D[Check sign-in and entitlement state]
D --> E[Verify manifest, lease, and artifact]
E -- All checks pass --> F[Run Pro engine]
E -- Any check fails --> C
E --> G[Start background refresh when renewal is due]
References: crates/…/mod.rs• L733-791 crates/…/mod.rs• L800-858 crates/…/verify.rs• L104-132 crates/…/verify.rs• L180-243
CLI boundaries
Account commands
The public account commands are login, logout, whoami, and status. Login can open the browser or print one URL for scripts. Logout removes local access and best-effort revokes the service grant. Whoami returns a non-zero result when the machine is not signed in or the service cannot answer. Status reports the service-owned setup view for the current account. (crates/…/lib.rs• L153-215, crates/…/lib.rs• L239-347, crates/…/setup_status.rs• L131-182)
The account service also exposes separate control commands for optional data flows: health, health design, setup, and critiques. Each command controls local consent and, where supported, deletion of data already saved by the service. Prototype records and repository switch refreshes are side effects of their owning workflows rather than separate public account commands. (crates/…/health.rs• L343-467, crates/…/design.rs• L9-51, crates/…/setup.rs• L301-355, crates/…/critiques.rs• L363-425, crates/…/prototypes.rs• L14-18, crates/…/switches.rs• L46-86)
The world <id> command uses the account session to fetch a catalog seed and either creates a new design system or prints a seed for merging. The hidden pro-refresh command and upload-refresh commands support background renewal. They report refresh status or renew credentials but do not become second public account flows. (crates/…/world.rs• L128-231, crates/…/mod.rs• L875-935, crates/…/session.rs• L462-476)
References: crates/…/lib.rs• L153-215 crates/…/lib.rs• L239-347 crates/…/setup_status.rs• L131-182 crates/…/world.rs• L128-231 crates/…/health.rs• L343-467 crates/…/setup.rs• L301-355 crates/…/critiques.rs• L363-425 crates/…/prototypes.rs• L14-74 crates/…/mod.rs• L875-935
Native CLI integration
The account crate exposes operations for the native runtime to call. Login and logout own the account grant. Sessions own authorized service calls. Pro dispatch owns the decision to run the signed Pro engine or the open engine. Health, setup, DESIGN.md, critique, prototype, taste, and repository-switch work run as optional side effects with their own consent and time limits. World seeding remains an explicit account command that writes only a new design system. (crates/…/lib.rs• L1-18, crates/…/session.rs• L235-309, crates/…/health.rs• L95-192, crates/…/setup.rs• L247-299, crates/…/taste.rs• L74-116, crates/…/prototypes.rs• L14-74, crates/…/switches.rs• L46-86, crates/…/world.rs• L177-270)
This separation gives callers clear boundaries: account commands may need the network, scan dispatch can decide offline, and service uploads must not change the primary command result. Related runtime behavior belongs on the Native runtime and CLI page rather than here.
References: crates/…/lib.rs• L1-18 crates/…/session.rs• L235-309 crates/…/health.rs• L95-192 crates/…/setup.rs• L247-299 crates/…/design.rs• L61-250 crates/…/critiques.rs• L91-225 crates/…/prototypes.rs• L14-74 crates/…/switches.rs• L46-86 crates/…/taste.rs• L74-116 crates/…/world.rs• L177-270 crates/…/mod.rs• L800-858
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the configured issuer, OAuth metadata checks, resource indicator, and HTTP origin checks aligned. A mismatch can make a valid service unusable or send a request to the wrong origin.
- Keep token validation and secret-store size limits aligned. A token accepted by the HTTP layer must still fit every supported credential backend.
- Keep sign-in generation changes aligned across session refresh, logout tombstones, entitlement answers, optional upload claims, taste cache removal, repository switches, and Pro leases. A stale answer must not alter a newer sign-in.
- Keep advertised scopes aligned with token scope state and each optional service route. Adding a route without a consent path can silently widen access or cause a denied upload.
- Keep health, setup, DESIGN.md, critique, taste, setup-status, world, and prototype payload rules aligned with their service contracts. Changes must preserve privacy limits, response shape checks, size bounds, and deletion or no-overwrite behavior.
- Keep repository switch ids and team fallback behavior aligned with the rule catalog. Unknown ids or a changed revision can silently produce the wrong local rule state.
- Keep Pro manifest fields, release-key trust, lease claims, artifact digest checks, and the revision floor aligned. Changing one trust rule can create a downgrade or an unsafe dispatch path.
- Keep human notices separate from machine output. Upload success, stale-grant hints, setup status, and Pro status must not enter JSON, edit hooks, or other program-facing output.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| OAuth metadata names another issuer or an off-origin endpoint | Login stops before authorization or token exchange | Issuer, endpoint origin, PKCE, and issuer-response checks |
| Callback has the wrong state or issuer | The login attempt is ignored or rejected | Per-attempt state and issuer validation |
| Refresh token is reused after another process rotated it | The service may revoke the grant | One lifecycle lock and adoption of newer stored generations |
| Logout races with login or refresh | An old operation could restore access | Signed-out tombstone and generation checks |
| A new optional scope is advertised after an existing login | The old grant cannot use the new route | Scope state stays bound to the consented sign-in; login requests new access |
| Entitlement changes during a Pro refresh | A revoked account could install or keep Pro state | Sign-in-bound denial markers and locked install step |
| Manifest, lease, or artifact fails verification | The open engine runs instead of untrusted Pro code | Pinned release keys, published lease keys, time checks, and digest checks |
| Health, setup, DESIGN.md, critique, taste, or prototype service is unavailable or rejects an upload or read | The primary command still returns its normal result or keeps its last valid local state | Optional side effects with bounded waits and consent checks |
| A background data report or switch refresh finishes after its setting or sign-in changes | Data could be sent or switch state could be saved after the user's choice changed | Local locks, preference epochs, sign-in lineage, and final consent checks |
| Setup status returns an unknown version or state | The CLI could show a false connection or next step | Version and state checks; unknown values are omitted or rejected |
| A world seed arrives with the wrong id or an existing design system is present | The project could get the wrong design or lose local work | Id and size validation plus no-overwrite checks |
Key files
| File | Why to read it |
|---|---|
| crates/…/lib.rs | Public account commands and the top-level login, logout, and whoami behavior |
| crates/…/config.rs | Account origin, home directory, resource scope, and service isolation rules |
| crates/…/oauth.rs | Native OAuth login, optional scopes, and callback trust boundary |
| crates/…/store.rs | Local credential lifecycle, backend choice, locking, and logout tombstones |
| crates/…/session.rs | Access-token refresh, authorized calls, upload lineage, renewal, and entitlement retrieval |
| crates/…/setup_status.rs | Service-owned account setup view and human or JSON status output |
| crates/…/health.rs | Optional design health policy, repository identity, foundation evidence, and privacy-preserving scan upload |
| crates/…/setup.rs | Consent-bound setup inventory reporting and deletion controls |
| crates/…/taste.rs | Account taste preference reads, cache state, and consent-safe refresh |
| crates/…/design.rs | DESIGN.md upload policy and bounded post-scan reporting |
| crates/…/design_read.rs | Safe repository-root reads for DESIGN.md and its sidecar |
| crates/…/world.rs | Account-backed world seed retrieval and no-overwrite design creation |
| crates/…/critiques.rs | Saved critique report sync and its CLI controls |
| crates/…/prototypes.rs | Prototype acceptance records and their shared critique upload boundary |
| crates/…/switches.rs | Repository rule switch reads, team defaults, and account-safe writes |
| crates/…/plans.rs | Optional public plan catalog used by whoami |
| crates/…/mod.rs | Pro entitlement state, refresh, offline dispatch, and open-engine fallback |
| crates/…/verify.rs | Release manifest and lease trust rules |
| crates/…/http.rs | Shared network boundary and error model |
| crates/…/login.rs | End-to-end guarantees for OAuth, rotation, logout, and concurrent sign-in behavior |
| crates/…/scopes.rs | Guarantees that optional access stays attached to the original consented grant |
| crates/…/setup.rs | Guarantees for setup consent, daily limits, cancellation, and forget behavior |
| crates/…/pro.rs | End-to-end guarantees for Pro verification, entitlement changes, leases, and fallback |