Skip to main content
zerotal

Documentation

Documentation / zerotal / auth / GitHubDriver

Class: GitHubDriver

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:17

Authenticates users via GitHub OAuth. Reads the profile from api.github.com/user, and — because GitHub hides emails by default — falls back to /user/emails to recover the primary verified address.

Extends

Constructors

Constructor

new GitHubDriver(config): GitHubDriver

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:92

Parameters

config

OAuth2Config

Returns

GitHubDriver

Inherited from

OAuth2Driver.constructor

Callback

userFromToken()

userFromToken(token): Promise<SocialUser>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:186

Retrieve a user's profile from an access token you already hold — e.g. a native/mobile app that obtained the token via its own SDK. Skips the code-exchange step entirely; the returned user carries no refresh token or expiry (those come from exchange).

const socialUser = await Social.driver('github').userFromToken(accessToken);

Parameters

token

string

An access token already obtained out-of-band (e.g. a mobile SDK).

Returns

Promise<SocialUser>

The normalized profile for that token.

Throws

If the provider's user-info request fails.

Inherited from

OAuth2Driver.userFromToken

user()

user(code?): Promise<SocialUser>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:386

Handle the OAuth2 callback, or exchange a raw code in stateless mode.

Stateful (session-based): call with no arguments — the driver reads the current HttpContext from async-local storage, extracts code + state, verifies state against the session, then exchanges the code for a profile:

async callback({ params }: HttpContext) {
  const socialUser = await Social.driver(params.provider).user();
}

Stateless (SPA / mobile): call with the raw code — skips session/state verification entirely:

const socialUser = await Social.driver('github').stateless().user(rawCode);

Throws Error('invalid_state') or Error('missing_code') on validation failure — catch in your controller and redirect accordingly.

Parameters

code?

string

Optional raw authorization code for stateless flows; omit for the stateful session-based callback.

Returns

Promise<SocialUser>

The normalized SocialUser for the authenticated account.

Throws

When the callback state is missing or mismatched.

Throws

When no authorization code is present.

Throws

When the provider's token exchange fails.

Inherited from

OAuth2Driver.user

Configuration

stateless()

stateless(): this

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:208

Return a shallow copy of this driver with CSRF state verification disabled.

Use this for stateless API/mobile endpoints that receive a raw code directly (no session, no state param):

const socialUser = await Social.driver('google').stateless().user(rawCode);

A copy is returned so the registered singleton is never mutated.

Returns

this

Inherited from

OAuth2Driver.stateless

scopes()

scopes(scopes): this

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:224

Add scopes to the authorization request, merged with the default/configured scopes. Returns a copy so the registered singleton is never mutated.

Social.driver('github').scopes(['read:user', 'public_repo']).redirect();

Parameters

scopes

string[]

Returns

this

Inherited from

OAuth2Driver.scopes

setScopes()

setScopes(scopes): this

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:236

Replace all scopes on the authorization request. Returns a copy so the registered singleton is never mutated.

Parameters

scopes

string[]

Returns

this

Inherited from

OAuth2Driver.setScopes

with()

with(params): this

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:259

Append optional parameters to the authorization redirect URL. Useful for provider-specific options such as Google's access_type=offline + prompt=consent (required to receive a refresh token) or hd for hosted-domain restriction.

Do not pass reserved keys (client_id, redirect_uri, scope, state, response_type) — those are managed by the driver. Returns a copy.

Social.driver('google')
  .with({ access_type: 'offline', prompt: 'consent' })
  .redirect();

Parameters

params

Record<string, string>

Returns

this

Inherited from

OAuth2Driver.with

Other

authUrl()

protected authUrl(): string

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:18

Returns

string

Overrides

OAuth2Driver.authUrl

tokenUrl()

protected tokenUrl(): string

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:21

Returns

string

Overrides

OAuth2Driver.tokenUrl

userUrl()

protected userUrl(): string

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:24

Returns

string

Overrides

OAuth2Driver.userUrl

defaultScopes()

protected defaultScopes(): string[]

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:28

Returns

string[]

Overrides

OAuth2Driver.defaultScopes

includeResponseType()

protected includeResponseType(): boolean

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:33

GitHub does not accept response_type=code and returns 404 if present.

Returns

boolean

Overrides

OAuth2Driver.includeResponseType

normalise()

protected normalise(raw, token): SocialUser

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:37

Parameters

raw

Record<string, unknown>

token

string

Returns

SocialUser

Overrides

OAuth2Driver.normalise

afterNormalise()

protected afterNormalise(user, token): Promise<SocialUser>

Defined in: packages/auth/src/social/drivers/GitHubDriver.ts:59

If the user has hidden their email, GitHub returns null on the /user endpoint. This hook automatically fetches the primary verified address from /user/emails — no extra code needed in your controller.

Parameters

user

SocialUser

token

string

Returns

Promise<SocialUser>

Overrides

OAuth2Driver.afterNormalise

config

protected config: OAuth2Config

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:87

Inherited from

OAuth2Driver.config

extraAuthParams()

protected extraAuthParams(): Record<string, string>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:105

Extra query parameters appended to the authorization redirect URL.

Returns

Record<string, string>

Inherited from

OAuth2Driver.extraAuthParams

scopeSeparator()

protected scopeSeparator(): string

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:110

Separator used to join scope values. Default: space.

Returns

string

Inherited from

OAuth2Driver.scopeSeparator

usesPKCE()

protected usesPKCE(): boolean

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:130

Whether to use PKCE (RFC 7636, S256) on the authorization-code flow. Default true: a stolen authorization code cannot be exchanged without the per-flow code_verifier held in the session, and providers that do not support PKCE simply ignore the extra parameters. Override to return false for a provider that rejects unknown params.

Returns

boolean

Inherited from

OAuth2Driver.usesPKCE

_extractCodeAndState()

protected _extractCodeAndState(ctx): Promise<{ code: string | null; state: string | null; }>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:150

Override to change how code and state are extracted from the incoming request. Default: reads ?code=&state= from the query string.

This is an internal hook called by user() — it receives the HttpContext resolved from async-local storage. Apple overrides this to read from a POST form body instead.

Parameters

ctx

SocialHttpContext

Returns

Promise<{ code: string | null; state: string | null; }>

Inherited from

OAuth2Driver._extractCodeAndState

_doUser()

protected _doUser(code, codeVerifier?): Promise<SocialUser>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:162

Override to change the full code→SocialUser pipeline. Apple overrides this to decode an id_token JWT instead of calling a user-info endpoint.

Parameters

code

string

codeVerifier?

string

Returns

Promise<SocialUser>

Inherited from

OAuth2Driver._doUser

_exchangeCode()

protected _exchangeCode(code, codeVerifier?): Promise<TokenBundle>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:434

Parameters

code

string

codeVerifier?

string

Returns

Promise<TokenBundle>

Inherited from

OAuth2Driver._exchangeCode

_fetchRaw()

protected _fetchRaw(token): Promise<Record<string, unknown>>

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:475

Parameters

token

string

Returns

Promise<Record<string, unknown>>

Inherited from

OAuth2Driver._fetchRaw

Redirect

redirectUrl()

redirectUrl(state, codeVerifier?): string

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:293

Build the full authorization URL (for low-level use or testing). Prefer redirect() in controllers.

When a PKCE codeVerifier is supplied, its S256 challenge is sent as code_challenge + code_challenge_method (RFC 7636 §4.3).

Parameters

state

string

The CSRF state token to embed in the URL.

codeVerifier?

string

Optional PKCE verifier; when present its S256 challenge is sent.

Returns

string

The fully-built authorization URL.

Inherited from

OAuth2Driver.redirectUrl

redirect()

redirect(): void

Defined in: packages/auth/src/social/drivers/OAuth2Driver.ts:336

Generate a CSRF state token, store it in the session, and redirect the user to the provider's authorization page.

The current HTTP context is read automatically from async-local storage — no need to pass it explicitly:

async redirect({ params }: HttpContext) {
  return Social.driver(params.provider).redirect();
}

Returns

void

Throws

If called outside an HTTP request; use .stateless().user(code) for request-less flows.

Inherited from

OAuth2Driver.redirect