🧱 OAuth blocks

OAuth blocks are reusable provider initiation, callback, and identity-resolution operations exported through blocks from @nodeblocks/backend-sdk. They return neverthrow Result values consumed by the public OAuth routes.

Inventory

Export	Kind	Inputs	Result / behavior / errors
requestGoogleOAuth	Initiator	Secrets, Google driver request, request/response, state inputs	Result<Promise<void>, Error>; token-generation failure is AuthenticationInvalidTokenError.
authenticateGoogleOAuth	Callback adapter	Google driver callback, request/response	Resolves ok(GoogleProfile); driver rejection escapes.
verifyGoogleOAuth	Identity resolver	identities, decoded state, Google profile	Finds/creates provider identity; input, not-found, and DB errors.
requestLineOAuth	Initiator	Secrets, LINE driver request, request/response, state inputs	Result<Promise<void>, Error>; token-generation failure is AuthenticationInvalidTokenError.
authenticateLineOAuth	Callback adapter	LINE driver callback, request/response	Resolves ok(LineProfile); driver rejection escapes.
verifyLineOAuth	Identity resolver	identities, decoded state, LINE profile	Finds/creates provider identity; input, not-found, and DB errors.
prepareTwitterCallbackState	State builder	Purpose, redirect URL, type ID	Returns exactly { purpose, redirectUrl, typeId }.
requestTwitterOAuth	Initiator	Twitter driver request, request/response, state	Returns ok(driverPromise).
authenticateTwitterOAuth	Callback adapter	Twitter driver callback, request/response	Returns profile/state or AuthenticationOAuthError.
verifyTwitterOAuth	Identity resolver	identities, purpose, type ID, Twitter profile	Finds/creates provider identity; input, not-found, and DB errors.
generateRedirectURL	URL helper	One-time token, redirect URL	ok(decodeURIComponent(url) + '?onetimeToken=' + token); decode errors throw.
extractOAuthLoginState	State decoder	Secrets, state	Returns decoded one-time-token data or AuthenticationInvalidTokenError; JWT decode can throw.

Details

requestGoogleOAuth

Implementation

Signature: requestGoogleOAuth(authSecrets, requestAuthentication, request, response, fp, purpose, redirectUrl, typeId, jwtSignOptions?): Result<Promise<void>, Error>. It creates state with the supplied values and user agent, signs it as a one-time token using provider fingerprint 'googleOAuth', then calls the driver. Only signing exceptions become AuthenticationInvalidTokenError('Error generating onetime token'); a synchronous driver throw is not converted to Result. Used by googleOAuthRoute.

authenticateGoogleOAuth

Implementation

Signature: authenticateGoogleOAuth(callback, request, response): Promise<Result<GoogleProfile, Error>>. It awaits the injected driver callback and wraps its resolved profile in ok; it does not catch a thrown callback error. Used by googleOAuthCallbackRoute.

verifyGoogleOAuth

Implementation

Signature: verifyGoogleOAuth(identitiesCollection, loginState, profile): Promise<Result<string, Error>>. It looks up identities by provider: 'google' and providerId: String(profile.id). If absent for oauth-signup, it requires loginState.typeId and inserts a base entity with profile email, displayName, a generated hashed password, provider fields, and type ID. It returns ok(identity.id.toString()), AuthenticationInvalidInputError for missing type ID/failed insert, AuthenticationUnexpectedDBError for database failures, or AuthenticationNotFoundError for a login with no identity. Used by googleOAuthCallbackRoute.

requestLineOAuth

Implementation

Signature: requestLineOAuth(authSecrets, requestAuthentication, request, response, fp, purpose, redirectUrl, typeId, jwtSignOptions?): Result<Promise<void>, Error>. It has the same state shape and signing behavior as requestGoogleOAuth, calls the LINE driver, and uses provider fingerprint 'lineOAuth'. Signing failures become AuthenticationInvalidTokenError('Error generating onetime token'); a synchronous driver throw is not converted. Used by lineOAuthRoute.

authenticateLineOAuth

Implementation

Signature: authenticateLineOAuth(callback, request, response): Promise<Result<LineProfile, never>>. It wraps the resolved driver profile in ok but does not catch a thrown callback error. Used by lineOAuthCallbackRoute.

verifyLineOAuth

Implementation

Signature: verifyLineOAuth(identitiesCollection, loginState, profile): Promise<Result<string, Error>>. It looks up identities by provider: 'line' and providerId: String(profile.sub). A signup creates a base entity with name, generated hashed password, provider fields, and required state type ID. It returns the identity ID or the same input/DB error classes as verifyGoogleOAuth, with the LINE-specific not-found message. Used by lineOAuthCallbackRoute.

prepareTwitterCallbackState

Implementation

Signature: prepareTwitterCallbackState(purpose: OAuthLoginPurpose, redirectUrl: string, typeId: string): { purpose; redirectUrl; typeId }. It performs no validation or conversion and returns those three fields exactly. Used by twitterOAuthRoute.

requestTwitterOAuth

Implementation

Signature: requestTwitterOAuth(requestAuthentication, request, response, state): Result<Promise<void>, Error>. It immediately returns ok(requestAuthentication(request, response, state)); a synchronous driver throw is not converted. Used by twitterOAuthRoute.

authenticateTwitterOAuth

Implementation

Signature: authenticateTwitterOAuth(callback, request, response). It returns ok({ user, state? }); an existing AuthenticationOAuthError, Passport InternalOAuthError, or any other thrown value becomes AuthenticationOAuthError (the last uses 'Twitter OAuth authentication failed with unknown error'). Used by twitterOAuthCallbackRoute.

verifyTwitterOAuth

Implementation

Signature: verifyTwitterOAuth(identitiesCollection, purpose, typeId, profile): Promise<Result<string, Error>>, where typeId is string | undefined. It looks up identities by provider: 'twitter' and providerId: String(profile.id). An oauth-signup creates an entity with displayName, generated hashed password, provider fields, and required type ID. It returns the identity ID or the same input/DB error classes as the other resolvers and its Twitter-specific missing-account error. Used by twitterOAuthCallbackRoute.

generateRedirectURL

Implementation

Signature: generateRedirectURL(onetimeToken, redirectUrl): Result<string, Error>. It decodes the supplied URL and appends ?onetimeToken=<token> verbatim. An existing query string remains in the decoded URL, so the result contains a second ? rather than a merged query; decodeURIComponent can throw before ok is returned. Used by googleOAuthCallbackRoute, lineOAuthCallbackRoute, and twitterOAuthCallbackRoute.

extractOAuthLoginState

Implementation

Signature: extractOAuthLoginState(authSecrets, state): Result<OAuthLoginState, Error>. It calls decryptAndVerifyJWT, requires an onetime token, and returns its data cast as OAuth state. A non-one-time token is AuthenticationInvalidTokenError('Invalid onetime token'); JWT decode is not safely wrapped and can throw. Used by googleOAuthCallbackRoute and lineOAuthCallbackRoute.