Skip to content

[WEBXP-417] Add circleci signup command with hybrid browser flow#1195

Draft
Fab10-CircleCi wants to merge 3 commits intoCircleCI-Public:mainfrom
Fab10-CircleCi:feat/signup-hybrid-browser-flow
Draft

[WEBXP-417] Add circleci signup command with hybrid browser flow#1195
Fab10-CircleCi wants to merge 3 commits intoCircleCI-Public:mainfrom
Fab10-CircleCi:feat/signup-hybrid-browser-flow

Conversation

@Fab10-CircleCi
Copy link
Copy Markdown

Checklist

=========

  • I have performed a self-review of my own code
  • I have commented my code, particularly in hard-to-understand areas
  • I have checked for similar issues and haven't found anything relevant.
  • This is not a security issue (which should be reported here: https://circleci.com/security/)
  • I have read Contribution Guidelines.

Internal Checklist

  • I am requesting a review from my own team as well as the owning team
  • I have a plan in place for the monitoring of the changes that I am making (this can include new monitors, logs to be aware of, etc...)

Changes

=======

  • Add newSignupCommand to cmd/signup.go with hybrid browser flow for CLI authentication
  • Start ephemeral HTTP server on 127.0.0.1:0 with /callback and /complete endpoints
  • Open browser to https://circleci.com/signup?source=cli&state=<hex>&return-to=http://127.0.0.1:<port>/callback
  • Serve HTML bridge page at /callback that reads URL fragment (#token=...&state=...) and relays to /complete via fetch
  • Handle error fragments (#error=token_creation_failed&state=...) from frontend PAT creation failures
  • Add fallback for missing token/error — never leave the CLI hanging on timeout
  • Validate CSRF state on /complete, store token in ~/.circleci/cli.yml on success
  • Add --no-browser flag that prints signup URL and prompts for manual PAT paste
  • Add telemetry event (cli-signup) and workflow step tracking (browser_opening, token_received, failed, timeout)
  • Register signup command in cmd/root.go
  • Add 13 unit tests in cmd/signup_unit_test.go

Rationale

=========

This PR implements the CLI side of the hybrid browser signup flow (WEBXP-417). The goal is to let new users run circleci signup, complete signup in the browser, and have the CLI automatically authenticated — no manual token copy-paste required.

The frontend counterpart (also WEBXP-417) modifies successful-signup.tsx to detect source=cli + localhost return-to, create a PAT via POST /api/v1/user/token, and redirect back to the CLI's local server with the token in the URL fragment.

Considerations

==============

  • Fragment-based handshake: URL fragments (#token=...) are never sent to the server by the browser, so the /callback endpoint serves an HTML page with JavaScript that reads window.location.hash and relays the values to /complete via fetch. This is the standard pattern for implicit-grant-style flows.
  • Error handling: The frontend may redirect with #error=token_creation_failed if PAT creation fails. The JavaScript detects this and forwards the error to /complete so the CLI exits immediately with a helpful message instead of silently timing out for 5 minutes.
  • State validation on error path: Relaxed — a missing state is tolerated (the frontend may not have had access to it), but a present-but-wrong state is still rejected as CSRF.
  • 5-minute timeout: Prevents the CLI from hanging indefinitely. All failure paths suggest circleci setup as fallback.
  • No new dependencies: Uses crypto/rand, net/http, pkg/browser — all already in the project.

🤖 Generated with Claude Code

Fab10-CircleCi and others added 3 commits March 24, 2026 15:12
Implements a new signup command that opens the browser to CircleCI's
signup page and receives the authentication token back via a local
HTTP server callback, with error handling for PAT creation failures
and a --no-browser fallback for manual token entry.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove HTML bridge page (handleCallback) — browser stays on circleci.com
- Frontend creates PAT and delivers it via cross-origin fetch to localhost
- Add CORS middleware pinned to https://app.circleci.com
- Rename handleComplete → handleToken, single /token endpoint
- Use cli_state/cli_port params to avoid collision with Auth0's state
- Build signup URL via url.Values with relative return-to path
- Update --no-browser to point to login page with token settings return-to
- Update tests: remove handleCallback tests, add CORS tests

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…mand

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant