Support device-flow sign-in for local instances, with optional remembered login

Support device-flow sign-in for local instances, with optional remembered login

Context

Chopin already provides the browser workspace and an MCP interface for external coding agents. A local integration can start Chopin and direct users to the existing browser UI without needing to duplicate either interface.

The remaining authentication friction is that each local deployment currently needs a GitHub App client secret. Reusing a shared App registration across independently operated local instances would require distributing that secret, while separate App registrations add onboarding steps for each deployment.

GitHub Apps support device authorization using a public client ID. Users approve a code on GitHub, and the local process receives user-scoped access and refresh tokens. GitHub also supports refreshing device-issued tokens without the App client secret. App installation, organization policies, and the signed-in user's repository permissions still apply.

Current behavior

• apps/server/src/auth/config.ts requires GITHUB_APP_CLIENT_SECRET.
• apps/server/src/auth/routes.ts implements browser authorization-code login and passes the client secret to token exchange and refresh.
• apps/server/src/auth/session.ts keeps browser cookie verifiers and GitHub credentials in process memory.
• Startup clears browser-session registry rows and Planner ownership after acquiring the database writer lease.

The restart behavior is an explicit security choice in #56, not an accidental omission. Remembered local login would be a new, opt-in persistence boundary rather than a change to hosted defaults.

Proposal

Consider an explicit local authentication mode with two separable capabilities:

1. Device-flow browser sign-in. Show GitHub's verification URL and user code in Chopin, handle pending/denied/expired authorization, and create a normal Chopin session after identity and admission checks. Reuse existing repository authorization, session refresh coordination, logout, and Planner invalidation behavior.
2. Optional remembered local login. With explicit user consent, retain the minimum credential material in the operating system's credential store so the same browser can re-establish a session after a local server restart without another device-code approval. Session-only device login should remain possible.

The existing web OAuth flow and process-local credential behavior would remain the default. App identifiers would remain operator-configurable; this would not hardcode a particular App or coding-agent product into Chopin.

Boundaries to preserve

• The local mode is restricted to a loopback-bound server with an exact loopback origin. It is not an alternative authentication mode for an exposed multi-user deployment.
• Device authorization is bound to the initiating browser with an unpredictable, HttpOnly attempt cookie. A different browser cannot claim the grant just by learning an attempt ID.
• Remembered credentials are scoped to the installation, origin, GitHub App, account, and browser binding. Finding a stored account is not sufficient to authenticate an arbitrary browser.
• GitHub tokens do not enter PostgreSQL, browser storage, JavaScript-readable cookies, logs, or MCP responses. OS-store unavailability must not trigger plaintext fallback.
• Token rotation, server crashes, concurrent requests, logout, revocation, and storage failures must not restore an invalidated remembered login. Any unavoidable interrupted-refresh recovery should fail back to sign-in rather than reuse a stale refresh token.
• Restored credentials still require current identity/admission checks and normal repository-installation/role checks. Restoring browser access does not reclaim Planner ownership or replay interrupted model work.
• Existing MCP bearer authentication stays separate. No token-export endpoint or implicit conversion of MCP credentials into a browser session is proposed.

Expected user experience

First local sign-in
  Open Chopin → approve a code on GitHub → enter the existing workspace
  Optionally choose “Remember this browser on this machine”

After restart
  The remembered browser proves its binding → credentials are revalidated/refreshed
  → a new normal Chopin session is issued

After logout, revocation, expiry, or an unrecoverable refresh
  Show sign-in again; do not silently recover an invalidated login

Validation expectations

• Existing OAuth, MCP, repository authorization, and hosted restart tests continue to pass unchanged in default mode.
• Device-flow tests cover pending authorization, slow_down, denial, expiry, cancellation, malformed provider replies, and cross-browser/cross-origin attempts.
• Remembered-login tests cover a real server restart, refresh rotation, logout races, interrupted persistence, App/account isolation, and unavailable or locked OS credential storage.
• Browser tests use production auth/session handlers with a fake GitHub network boundary. Native credential-store checks are distinguished from mocks and run on each claimed supported platform.

Scope and alternatives

This proposal does not include local service provisioning, a coding-agent startup hook, changes to the editor, an alternative database, automatic repository installation, or a new hosted authentication broker. Device sign-in could be reviewed before the optional remembered-login capability.

Alternatives are retaining one App registration per deployment, requiring users to sign in after every local restart, or operating a central OAuth service. The proposed mode aims to avoid a shared client secret while keeping authentication inside Chopin.

Related work and references

I found no matching issue or PR after reviewing the current issue list and searching issues, PRs, and comments for device flow, remembered login, and persistent authentication. #151 mentions onboarding work but does not describe this authentication proposal. #56 establishes the current credential boundary; #80 establishes the separate MCP bearer path.

• Chopin authentication guide
• GitHub App device authorization
• Refreshing device-issued user tokens