Manage application, coding-agent, and source-control authentication from the WebUI

[dnviti]

Problem / Motivation

This feature depends on #170. Related context: #166, #169, and #137.

Every coding agent and source-control command-line tool needs an account before it can do useful work, but each exposes a different combination of browser approval, device code, subscription sign-in, API key, personal token, or externally managed credentials. The product can launch these tools from the browser, yet it has no complete place to see their account state or to connect, switch, recover, and disconnect them.

The current workaround is to leave the WebUI, find the correct execution environment, open a terminal, know the tool-specific login command, and complete the flow there. Authentication failures in a WebUI conversation or repository panel are often dead ends. This blocks every new user and execution environment, recurs whenever access expires or is revoked, and is especially poor from a phone or a remotely hosted installation.

Account ownership is also unclear across platforms. A local desktop instance should act as the person at that computer without an application login. A Linux or macOS server needs each externally authenticated person to work through their own operating-system account. A Windows server cannot offer the same isolation and must make its shared credentials explicit. Without those rules, a login that appears personal may actually change what everyone runs as.

Existing connected-host credentials and account-status work cover parts of this problem, but not general agent authentication, native browser flows, multiple accounts, or complete source-control CLI login. External application identities remain the responsibility of #170; this issue uses those identities rather than redefining them.

Goal

Make authentication a first-class WebUI capability. Users can enter the product under the correct platform identity, see every supported agent and source-control account in one place, complete every safe supported login method without a terminal, recover from expired access, choose the account their work uses, and disconnect it with clear scope and consequences.

Scope

Application and operating-system identity

• A local Electron instance opens directly as the current local operating-system user and never asks for application or GitHub sign-in.
• Server installations authenticate through the external identities provided by Sign-in providers: GitLab, Gitea, Microsoft, Google, LDAP and custom OIDC #170.
• On Linux and macOS servers, each external identity maps to a standard, non-administrator operating-system account. A missing account is created automatically, and all terminals, agents, files, git operations, and source-control tools for that user run as that account.
• Linking an external identity to an existing operating-system account requires administrator approval. Matching names or email addresses never link accounts automatically. A name collision produces a stable unique account and a visible mapping.
• If the mapped account cannot be created or activated, access is refused with a clear user message and an administrator alert. Work never falls back to a shared account.
• On Windows servers, all users work through one shared operating-system account. Everyone can see connection status, but only the installer can connect, switch, replace, or disconnect the shared integration accounts.
• Revoking external access immediately ends the user's WebUI sessions, stops their running terminals and agents, and disables their mapped operating-system account. Their home and project data remain available for recovery.
• A separate administrator action permanently deletes a disabled user's operating-system account, home and project data, personal credentials, and identity mappings after an explicit destructive confirmation.

Accounts experience

• Users manage their own personal integration accounts within the platform-specific limits below.
• A central Accounts center lists application identity, coding agents, model providers used by multi-provider agents, and source-control services. Contextual Connect and Reconnect actions also appear when launch, status, or repository access detects missing or invalid authentication.
• An agent launch that needs authentication pauses, completes the WebUI flow, and resumes the original launch automatically after success. Cancelling authentication cancels the pending launch without creating a broken session.
• The release covers every integration in the official product catalog: Claude Code, Codex, Cursor Agent, pi, Grok Build, Qwen Code, Kimi Code, Oh My Pi, Antigravity, GitHub, GitLab, Gitea, and Forgejo. A future integration does not become officially supported until its account behavior is represented here.
• Several accounts can be connected when the integration supports them. Each user has a default account and can choose a different account for a project or a new agent session without changing that default.
• Multi-provider agents show account state separately for each provider. A provider credential is reused across agents only when the provider and each affected integration explicitly support the same credential type and access.
• When the user's application identity belongs to the same source-control service, it becomes the active CLI account if its granted access is sufficient. Otherwise the user completes an explicit additional approval.
• Public and self-hosted GitHub, GitLab, Gitea, and Forgejo instances are covered. The installation owner approves new hostnames on a server; a local Electron user can add one on their own computer.
• Existing SSH access is reported as externally managed. Creating, uploading, selecting, rotating, and removing SSH keys is not included.
• Account management works across desktop and mobile layouts with keyboard, touch, and screen-reader access. It uses the product's current language.

Authentication methods and state

• The WebUI offers every authentication method the installed integration can safely complete. Browser approval is the default, device code is the fallback when redirects are unavailable, and subscription, API-key, and token flows are offered when the integration supports them.
• Credentials already managed safely by an integration remain there. The app protects only credentials it must retain itself, and never creates a second copy without need.
• Credentials supplied through environment settings, enterprise identity, or an operating-system credential helper are shown as externally managed. They can be observed but not revealed, imported, replaced, or deleted from the Accounts center.
• Credentials already present when the product is upgraded are detected and preserved. The upgrade never requires a reconnect merely to make an existing account visible.
• A missing tool is reported with setup guidance, but the account flow does not install software. A tool version that cannot expose a safe WebUI authentication flow keeps its existing account untouched and reports that an update is required.
• Only one login attempt per user and integration is active at a time. Reloading, closing, or reconnecting the browser preserves its progress until the provider expires it; the user can cancel or retry it.
• A credential that cannot be validated because the provider is unavailable is retained as Unverified and is never described as connected. A valid credential with insufficient access is retained as Needs attention, names the missing access, and remains inactive until replaced or reauthorized.
• One login follows the user to every authorized execution environment. Successful locations remain connected when another location fails, and the Accounts center names each affected location and offers a targeted retry.
• Account state is checked when connected, when the Accounts center opens, before use, and periodically in the background. A tool that cannot report reliable state is labeled Unknown. An offline provider leaves the last known account metadata visible and marks its validation stale.
• Expired, revoked, unverified, partially applied, and insufficient-access states produce persistent in-app guidance. Browser notifications are used only when that user has enabled them.
• Switching or disconnecting an integration account applies to future launches. Existing work continues, and affected sessions state that a restart is required before the new account choice applies.
• Disconnect removes local access immediately. When a provider supports remote revocation, that is offered as a separate, clearly destructive action.
• Application sign-out ends only the application session. Integration accounts remain connected until explicitly disconnected or the user is offboarded.
• Subscription-backed accounts show read-only plan or workspace context when reported. Detailed usage, quotas, billing, purchases, changes, and cancellation remain on their existing product surfaces or at the provider.

Non-goals

• Implementing or replacing the external identity providers and account-linking behavior tracked by Sign-in providers: GitLab, Gitea, Microsoft, Google, LDAP and custom OIDC #170.
• Installing or updating coding-agent and source-control tools from an authentication flow.
• Supporting arbitrary installed tools outside the official product catalog.
• Adding a public account-management API or a new product command-line interface.
• Managing SSH key creation, upload, selection, rotation, or removal.
• Importing, revealing, editing, or deleting credentials controlled by environment settings, enterprise identity, or operating-system credential helpers.
• Managing provider billing, subscription purchases or cancellation, quotas, or detailed usage.
• Interrupting active agent work merely because its integration account was switched or locally disconnected.
• Releasing an Accounts experience that covers only part of the official integration catalog.
• Automatically revoking provider-side credentials during ordinary local disconnect.
• Introducing a new localization system.
• Claiming certification against a named legal or compliance framework.

Security / Safety Considerations

• API keys, personal tokens, OAuth material, and refresh credentials are write-only after entry. No screen, log, export, notification, error, or audit event reveals their values.
• Each approval requests only the access needed for the selected integration and explains why additional access is required before the user grants it.
• New Linux and macOS accounts have standard user permissions. Identity collisions never grant access to an existing account, and provisioning failure never falls back to a shared identity.
• On Linux and macOS, the installation owner can see integration, account identity, status, access, expiry, affected environments, and audit events and can force a local disconnect during support or offboarding, but cannot connect, switch, or reveal another user's personal credential. On Windows, shared-account controls remain installer-only and are visibly labeled as affecting everyone.
• Authentication and validation contact only the selected provider or approved self-hosted service and send only data required for that account operation. Project files, conversations, prompts, and usage data are never sent as part of account management.
• The audit history records who connected, switched, disconnected, revoked, or deleted which integration, when, where, and with what outcome. It contains no secret values and is removed automatically after 90 days.
• Destructive operations distinguish local disconnect, provider revocation, user disablement, and permanent user-data deletion, and state their effects before confirmation.
• Public documentation, screenshots, and examples contain no real credentials, private account identifiers, private hostnames, infrastructure details, logs, or security-sensitive examples.

Acceptance Criteria

• A local Electron user reaches the product without application or GitHub sign-in, manages only the accounts belonging to the current local operating-system user, and can still connect GitHub explicitly for source-control work.
• A first-time Linux or macOS server user signs in through an enabled external identity, receives a standard operating-system account when needed, and every terminal, agent, file, git, and source-control action runs as that account.
• An existing operating-system account is linked only after administrator approval; a conflicting name creates a distinct stable account; neither path grants unintended access.
• A Linux or macOS provisioning failure refuses work with clear user and administrator guidance and never runs it through a shared account.
• A Windows server visibly reports that integration accounts are shared, lets every user see their status, and allows only the installer to change them.
• Revoking a server user's external access immediately ends their WebUI and running work, disables their mapped operating-system account, and retains their data until an administrator explicitly deletes it.
• Permanent user deletion requires destructive confirmation and removes the disabled account, retained work, credentials, and mappings without affecting another user.
• The Accounts center and contextual recovery paths represent every integration in the official catalog, including every provider account offered by multi-provider agents.
• A future catalog integration cannot be presented as supported without signed-in, signed-out, Unknown, expired, recovery, switching where available, and disconnect behavior in the Accounts experience.
• Each catalog integration completes every safe login method it advertises through the WebUI, with browser approval preferred and device code available when redirects cannot complete.
• No supported login path requires the user to open a terminal or run a command manually.
• A launch blocked by authentication resumes automatically after a successful login and leaves no broken session when login is cancelled or fails.
• Existing native credentials appear after upgrade without being moved, exposed, overwritten, or requiring a new login.
• Externally managed credentials are identifiable and read-only, and their values never appear in the browser.
• A missing tool and an unsupported tool version produce distinct, actionable guidance without installing or changing the tool.
• Multiple accounts can be connected and switched when the integration supports them; defaults and project or new-session overrides select the expected account.
• Provider credentials are shared across compatible agents only when their credential type and access are explicitly compatible.
• A sufficiently authorized application identity enables its matching source-control CLI without another login; insufficient authorization requests additional consent before activation.
• Public and administrator-approved self-hosted source-control instances can be connected, switched, validated, and locally disconnected; existing SSH access remains read-only.
• Reloading or closing the browser during login returns the user to the same pending flow until expiry, while a concurrent attempt opens that existing flow instead of starting another.
• An unreachable provider produces Unverified, insufficient access produces Needs attention, unreliable detection produces Unknown, and offline validation produces a visibly stale last-known state.
• A credential reaches every authorized execution environment; partial failure names the affected environments, preserves successful ones, and can be retried selectively.
• Expired or revoked credentials are detected proactively and produce persistent in-app guidance plus browser notifications only for users who enabled them.
• Switching or locally disconnecting an integration affects new launches, leaves existing work running, and marks sessions that require restart.
• Local disconnect and provider revocation are separate confirmations with distinct stated effects.
• Application sign-out leaves integration credentials intact, while offboarding follows the confirmed disablement and deletion lifecycle.
• Subscription accounts show only reported account context and do not expose billing or plan-management controls.
• No saved secret can be revealed after entry or recovered from any user-visible output, diagnostic output, export, notification, or audit history.
• The installation owner sees operational metadata and 90 days of secret-free audit history, can force-disconnect a personal account on Linux or macOS, and cannot connect or switch it for the user.
• Account management sends no project content, conversation content, prompts, or usage data to a provider.
• Every account and recovery flow works on desktop and mobile with keyboard, touch, and screen-reader use, without relying on color, icons, hover, or a second device alone.
• The full release matrix demonstrates every supported combination of local Electron, Linux server, macOS server, Windows server, authentication method, and catalog integration.
• In a controlled release run, at least 99 of 100 valid end-to-end attempts sampled across that matrix complete without terminal intervention; user cancellations and confirmed provider outages are excluded.
• User and administrator guides, migration and security notes, a changelog entry, and current screenshots document the complete experience and its platform differences.
• The repository owner reviews the matrix, security behavior, documentation, and user experience and provides final sign-off.

Suggested Phasing

1. Identity foundation — external identities from Sign-in providers: GitLab, Gitea, Microsoft, Google, LDAP and custom OIDC #170 drive the confirmed local-desktop, Linux/macOS account, Windows shared-account, revocation, disablement, and deletion behavior. This foundation may ship while the combined issue remains open.
2. Complete Accounts experience — central and contextual account management is completed across the entire official agent and source-control catalog. No partial catalog is released as the Accounts feature.
3. Release gate — the full platform and integration matrix, 99% controlled completion target, security review, documentation, screenshots, and repository-owner sign-off are complete before the issue closes.