|
| 1 | +# OAuth login |
| 2 | + |
| 3 | +## User outcome |
| 4 | + |
| 5 | +A user signs in, approves the registered CLI permissions, and receives an OAuth |
| 6 | +grant. Google sign-in carries the same consent request through the provider |
| 7 | +redirect. Retired scopes are absent from both browser and device requests. |
| 8 | + |
| 9 | +## Entry points and prerequisites |
| 10 | + |
| 11 | +`polylane auth login` uses browser consent. `polylane auth login --no-browser` |
| 12 | +uses device authorization. The interactive login offers Google sign-in. |
| 13 | +Use a released binary with its registered OAuth client, or a local build with |
| 14 | +`POLYLANE_OAUTH_CLIENT_ID` and `POLYLANE_OAUTH_CLIENT_SECRET` from the target |
| 15 | +environment's secret store. The user needs a verified account and workspace |
| 16 | +membership. Use a test account and a separate operating-system user for manual |
| 17 | +checks: the CLI stores credentials under that user's `~/.polylane` directory. |
| 18 | + |
| 19 | +## Local checks |
| 20 | + |
| 21 | +From the CLI repository, run `npm ci`, `npm run typecheck`, `npm run lint`, |
| 22 | +`npm run test`, and `npm run build`. Typecheck regenerates the live API types. |
| 23 | +The default scope list must satisfy `OAuthClient.scopes`; a retired scope |
| 24 | +must cause a type error. |
| 25 | + |
| 26 | +`test/onboarding-run.test.ts` checks the Google redirect without a browser or |
| 27 | +network request. It requires that the nested consent URL omit all three |
| 28 | +`datasets:*` scopes. `test/oauth-client.test.ts` preserves the issue, agent |
| 29 | +tool, and page permissions. The type error and Google regression both fail |
| 30 | +when the retired dataset scopes are restored. |
| 31 | + |
| 32 | +## Manual sign-in |
| 33 | + |
| 34 | +Check `polylane --version` and `polylane auth status` before using the released |
| 35 | +build. Start browser login under the test operating-system user, select Google, finish |
| 36 | +sign-in, and approve consent. Expect the CLI to finish sign-in without |
| 37 | +`Invalid scopes requested`. Confirm `polylane auth status` and |
| 38 | +`polylane workspace list`. Repeat with `--no-browser` to check device consent. |
| 39 | +Confirm the grant's scopes stay within the registered client allowlist. |
| 40 | + |
| 41 | +Use an account you own. Keep credentials out of proof logs and run |
| 42 | +`polylane auth logout` after the check. This attempts access-token revocation |
| 43 | +and removes local credentials; it does not revoke the refresh token. |
| 44 | + |
| 45 | +## Boundaries and proof status |
| 46 | + |
| 47 | +The server rejects a scope outside the registered client allowlist. Keep that |
| 48 | +refusal; removing a product permission does not permit restoring it for login. |
| 49 | +The offline checks prove request construction and the generated API contract. |
| 50 | +They do not prove Google acceptance, the token exchange, or a customer login. |
| 51 | +Live browser and device sign-in on a released build remain a manual check. |
| 52 | +Record the tested revision, build, environment, result, and sanitized evidence |
| 53 | +in the pull request before claiming that user outcome passed. |
| 54 | + |
| 55 | +## Source anchors |
| 56 | + |
| 57 | +- `src/auth/oauth.ts`: requested scopes, browser URLs, and device requests. |
| 58 | +- `src/commands/auth/login.ts`: login entry point and coordination. |
| 59 | +- `src/auth/credentials.ts`: credential persistence. |
| 60 | +- `src/generated/types.ts`: generated OAuth client scope contract. |
0 commit comments