grove.oauth.prepare()

Prepare host-owned state and PKCE for a brokered authorization flow.

Signature

grove.oauth.prepare(): Promise<{
  readonly transactionID: string; readonly redirectURI: string
  readonly state: string; readonly codeChallenge: string
  readonly codeChallengeMethod: 'S256'
}>

Availability

Runtime with oauth.authorize. Settings pages cannot use OAuth. The later authorization and service requests need their own accepted HTTPS destinations.

Parameters

None.

Return value

Resolves to a frozen transaction object. transactionID identifies the pending transaction in this document; redirectURI is mango://grove/oauth; state is a random value; codeChallenge is the base64url S256 PKCE challenge. The verifier is not returned.

Behavior and errors

Does not open a browser or contact the service. A new preparation replaces this instance’s unused preparation. An active authorization session in this instance rejects preparation. Pass transactionID to authorize to consume the preparation; it is not durable across document reload or stop. The authorization session remains app-wide exclusive.

Preparation only generates transaction material; it does not verify a broker uses it. The broker must preserve the returned redirectURI, state, codeChallenge, and codeChallengeMethod in its provider request and enforce PKCE at exchange. Read the broker trust boundary before using this flow.

Example

try {
  const transaction = await grove.oauth.prepare()
  // Send redirectURI, state and codeChallenge to your broker's start API.
  console.info('Authorization transaction prepared')
} catch {
  console.error('Could not prepare authorization.')
}

See grove.oauth.authorize() and the complete brokered flow.