Documentation / @zerotal/auth / FakeSocialDriver

Class: FakeSocialDriver

Defined in: auth/src/social/testing.ts:56

A drop-in OAuth2 driver for tests. Register it via SocialManager.fake (or Social.fake(...)) rather than constructing it directly.

redirect() is inherited unchanged — it builds the authorize URL and stores the CSRF state in the session, exactly like a real driver, so redirect-route tests pass. user() / userFromToken() skip code exchange and state checks and return the canned profile.

Extends

OAuth2Driver

Constructors

Constructor

new FakeSocialDriver(user?): FakeSocialDriver

Defined in: auth/src/social/testing.ts:59

Parameters

user?

SocialUser = ...

Returns

FakeSocialDriver

Overrides

OAuth2Driver.constructor

Configuration

stateless()

stateless(): this

Defined in: 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: 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: 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: 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

config

protected config: OAuth2Config

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

Inherited from

OAuth2Driver.config

extraAuthParams()

protected extraAuthParams(): Record<string, string>

Defined in: 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: auth/src/social/drivers/OAuth2Driver.ts:110

Separator used to join scope values. Default: space.

Returns

string

Inherited from

OAuth2Driver.scopeSeparator

includeResponseType()

protected includeResponseType(): boolean

Defined in: auth/src/social/drivers/OAuth2Driver.ts:119

Whether to include response_type=code in the authorization URL. Most providers require it; GitHub does not accept it and returns 404. Override to return false for providers that omit it.

Returns

boolean

Inherited from

OAuth2Driver.includeResponseType

usesPKCE()

protected usesPKCE(): boolean

Defined in: 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

afterNormalise()

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

Defined in: auth/src/social/drivers/OAuth2Driver.ts:138

Called after normalise() — override to enrich the user object (e.g. fetch a secondary endpoint). Default: returns the user unchanged.

Parameters

user

SocialUser

_token

string

Returns

Promise<SocialUser>

Inherited from

OAuth2Driver.afterNormalise

_extractCodeAndState()

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

Defined in: 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: 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: 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>>

OAuth2Driver.normalise

user()

user(): Promise<SocialUser>

Defined in: auth/src/social/testing.ts:81

Return the canned profile (a copy) without hitting the provider.

Returns

Promise<SocialUser>

Overrides

OAuth2Driver.user

userFromToken()

userFromToken(): Promise<SocialUser>

Defined in: auth/src/social/testing.ts:86

Return the canned profile (a copy) without hitting the provider.

Returns

Promise<SocialUser>

Overrides

OAuth2Driver.userFromToken

Redirect

redirectUrl()

redirectUrl(state, codeVerifier?): string

Defined in: 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: 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