AGENTS.md

1# Authentication Service Usage Guide
2 
3## Overview
4 
5`IAuthenticationService` manages GitHub and Copilot authentication. It provides GitHub sessions (OAuth tokens) and Copilot tokens (CAPI tokens).
6 
7## Choosing a Session Kind
8 
9`getGitHubSession` requires a `kind` parameter. Choose thoughtfully:
10 
11- **`'any'`** — Accepts whatever GitHub session is available, even one with minimal scopes (e.g., just `user:email`). Use this when you only need basic access and don't require repo or write permissions.
12- **`'permissive'`** — Requires a session with broader scopes (`read:user`, `user:email`, `repo`, `workflow`). Use when you need private repo access or write permissions.
13 
14## The Three Overloads of `getGitHubSession`
15 
16### 1. Interactive — prompt user to sign in
17 
18Returns `AuthenticationSession` (never `undefined`). Throws if the user cancels.
19 
20Requires `createIfNone` with a `StrictAuthenticationPresentationOptions` containing a **localized `detail` string** explaining why auth is needed:
21 
22```ts
23const session = await authService.getGitHubSession('any', {
24  createIfNone: { detail: l10n.t('Sign in to GitHub to use feature X.') }
25});
26```
27 
28### 2. Interactive — force a new session
29 
30Same as above but forces re-authentication even if a session exists. Use when the current token has lost authorization:
31 
32```ts
33const session = await authService.getGitHubSession('any', {
34  forceNewSession: { detail: l10n.t('Sign in again to restore access.') }
35});
36```
37 
38### 3. Silent — no user prompt
39 
40Returns `AuthenticationSession | undefined`. Never shows UI. Use when auth is optional:
41 
42```ts
43const session = await authService.getGitHubSession('any', { silent: true });
44if (!session) {
45  // No session available, handle gracefully
46}
47```
48 
49## Important Constraints
50 
51- **`createIfNone` and `forceNewSession` do NOT accept `boolean`**. You must pass a `StrictAuthenticationPresentationOptions` with a required `detail` string.  Passing `true`, `false`, or `{}` will not compile.
52- **The `detail` string must be localized** using `l10n.t('...')`.
53- The silent overload's options type is `Omit<AuthenticationGetSessionOptions, 'createIfNone' | 'forceNewSession'>` — you cannot sneak a boolean `createIfNone` through it.
54 
55## Synchronous Cache Properties
56 
57For non-blocking checks (no network, no UI), use the cached properties:
58 
59- `authService.anyGitHubSession` — cached `'any'` session or `undefined`
60- `authService.permissiveGitHubSession` — cached `'permissive'` session or `undefined`
61- `authService.copilotToken` — cached Copilot token (without the raw token string) or `undefined`
62 
63React to `onDidAuthenticationChange` for identity changes (sign in/out, account switch).
64React to `onDidCopilotTokenChange` for token-level updates (quota, feature flags, routine ~20-minute refreshes).
65 
66## Copilot Tokens
67 
68Most callers just need a valid CAPI token. `getCopilotToken()` handles refresh automatically:
69 
70```ts
71const token = await authService.getCopilotToken();
72```
73 
74## Minimal Mode
75 
76When `authService.isMinimalMode` is `true`, the service will not fetch permissive tokens:
77- Interactive `'permissive'` calls throw `MinimalModeError`
78- Silent `'permissive'` calls return `undefined`
79 
80## Auth State Flows
81 
82There are three states a user can be in:
83 
841. **Not signed in** — No `'any'` session exists. The user has no GitHub session at all. An interactive `createIfNone` call will show VS Code's built-in sign-in dialog.
85 
862. **Signed in from VS Code** — The user explicitly signed in through VS Code (e.g., via Accounts menu or a `createIfNone` prompt). In this case, VS Code automatically acquires the permissive token since it requests the broader scopes upfront. Both `'any'` and `'permissive'` sessions are available.
87 
883. **Signed in passively** (e.g., via Settings Sync) — The user is signed into GitHub through a passive mechanism that only grants minimal scopes. Copilot Chat works with the `'any'` token, but no `'permissive'` token is available. A `'permissive'` call with `createIfNone` will prompt the user to grant additional permissions.
89