AuthFlow

Category: Providers

Source: auth_flow.dart

Sealed types describing what the user must do to connect a provider.

/provider add inspects the flow returned by [ProviderAdapter.beginInteractiveAuth] and picks the right UI: [ApiKeyFlow] → masked single-input modal, [DeviceCodeFlow] → URL + short code + polling spinner, [PkceFlow] → (scaffolded; not implemented this pass).

Classes

sealed AuthFlow

Constructor

const AuthFlow({required this.providerId, required this.providerName})

Properties

Property	Type	Description
providerId	String
providerName	String

ApiKeyFlow

User pastes an API key. Most providers use this.

Constructor

const ApiKeyFlow({
    required super.providerId,
    required super.providerName,
    this.envVar,
    this.envPresent,
    this.helpUrl,
  })

Properties

Property	Type	Description
envVar	String?	Name of the env var that can back this key, if declared in catalog.
envPresent	String?	Current env value when [envVar] is set at runtime (for the "[using $ENV]" hint). Never logged; never displayed beyond a placeholder note.
helpUrl	String?

DeviceCodeFlow

OAuth 2.0 device authorization grant — what GitHub Copilot uses. The user visits [verificationUri], enters [userCode], and approves; we poll.

Constructor

const DeviceCodeFlow({
    required super.providerId,
    required super.providerName,
    required this.verificationUri,
    required this.userCode,
    required this.pollInterval,
    required this.expiresAt,
    required this.progress,
  })

Properties

Property	Type	Description
verificationUri	String
userCode	String
pollInterval	Duration
expiresAt	DateTime
progress	Stream<AuthFlowProgress>	Emits [AuthFlowPolling] while waiting, then terminates with [AuthFlowSucceeded] (with the stored fields) or [AuthFlowFailed].
authUrl	String
state	String
redirectPort	int
fields	Map<String, String>	The credentials to store under this provider — the exact key/value shape is adapter-defined (e.g. {github_token, copilot_token, copilot_token_expires_at} for Copilot).
reason	String	User-facing reason string. Must not include secrets.

Methods

`DeviceCodeRequestedEvent toRequestEvent({

required TurnId turnId,
required int sequence,
DateTime? timestamp,

})`

Builds the typed proposed-core [DeviceCodeRequestedEvent] for this flow. Future surfaces (ACP server, web UI) consume this event from the session event stream rather than reading the [DeviceCodeFlow] fields directly. Today's CLI still uses the legacy fields; this method exists so new surfaces can build on the typed contract.

`const PkceFlow({

required super.providerId,
required super.providerName,
required this.authUrl,
required this.state,
required this.redirectPort,

})`

const AuthFlowProgress()

const AuthFlowPolling()

const AuthFlowSucceeded({required this.fields})

const AuthFlowFailed({required this.reason})

`DeviceCodeResolvedEvent? toResolvedEvent({

required TurnId turnId,
required int sequence,
DateTime? timestamp,

})`

PkceFlow

OAuth 2.0 Authorization Code + PKCE. Opens a browser to [authUrl]; a local loopback HTTP server on [redirectPort] receives the callback.

Scaffolded for Gemini / Google accounts — no adapter implements it yet.

Constructor

const PkceFlow({
    required super.providerId,
    required super.providerName,
    required this.authUrl,
    required this.state,
    required this.redirectPort,
  })

Properties

Property	Type	Description
authUrl	String
state	String
redirectPort	int

sealed AuthFlowProgress

Events emitted on [DeviceCodeFlow.progress] while the UI is waiting for the user to approve in their browser.

Constructor

const AuthFlowProgress()

AuthFlowPolling

Constructor

const AuthFlowPolling()

AuthFlowSucceeded

Constructor

const AuthFlowSucceeded({required this.fields})

Properties

Property	Type	Description
fields	Map<String, String>	The credentials to store under this provider — the exact key/value shape is adapter-defined (e.g. {github_token, copilot_token, copilot_token_expires_at} for Copilot).

AuthFlowFailed

Constructor

const AuthFlowFailed({required this.reason})

Properties

Property	Type	Description
reason	String	User-facing reason string. Must not include secrets.