@mantlejs/auth-google

Google OAuth 2.0 strategy for Mantle JS. Implements the authorization code flow with PKCE — no Passport.js dependency. Registers GET /auth/google and GET /auth/google/callback on the configured HTTP transport (@mantlejs/express, @mantlejs/koa, or @mantlejs/http), then finds or creates a user record and returns a Mantle JWT pair.

Installation

npm install @mantlejs/auth-google

Concepts

PKCE

Google Sign-In uses the authorization code flow with PKCE (Proof Key for Code Exchange). On each redirect request the plugin generates a fresh code_verifier (via Arctic, which also derives the SHA-256 / base64url code_challenge — see ADR-002). The verifier is stored server-side against a random state token and passed to the token exchange on callback.

Find-or-create

On callback the plugin searches the configured user service for a record where googleId (configurable) matches the sub claim from Google's userinfo endpoint. If no record is found, it creates one with { googleId, email, name } from the profile. The same user is returned on every subsequent sign-in.

Quick start

import { mantle } from "@mantlejs/mantle";
import { express } from "@mantlejs/express";
import { auth } from "@mantlejs/auth";
import { googleStrategy } from "@mantlejs/auth-google";

const app = mantle()
  .configure(express())
  .configure(auth({ secret: process.env.JWT_SECRET! }))
  .configure(googleStrategy({
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  }));

app.listen(3030);

Sign-in flow:

1. Redirect the browser to GET /auth/google
2. User authenticates on Google and consents
3. Google redirects to GET /auth/google/callback?code=...&state=...
4. The plugin exchanges the code, fetches the profile, finds or creates the user, and responds:

{
  "accessToken": "eyJhbGciOiJIUzI1NiJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
  "user": { "id": "1", "googleId": "108...", "email": "[email protected]", "name": "Alice" }
}

API

googleStrategy(config)

function googleStrategy(config: GoogleStrategyConfig): MantlePlugin;

type GoogleStrategyConfig = {
  clientId: string;
  clientSecret: string;
  callbackUrl?: string;    // Default: '/auth/google/callback'
  scope?: string[];        // Default: ['openid', 'profile', 'email']
  entity?: string;         // Default: 'users'
  entityIdField?: string;  // Default: 'googleId'
};

| Field | Type | Default | Description | | --- | --- | --- | --- | | clientId | string | — | Google OAuth client ID (required) | | clientSecret | string | — | Google OAuth client secret (required) | | callbackUrl | string | '/auth/google/callback' | Callback path — must match the redirect URI registered in Google Cloud Console | | scope | string[] | ['openid', 'profile', 'email'] | Google OAuth scopes | | entity | string | 'users' | Mantle service used to find or create users | | entityIdField | string | 'googleId' | Field on the user record matched against Google's sub claim | | redirectUrl | string | none — returns JSON | Frontend URL to redirect to on completion, with tokens (or an error) in the URL fragment — see @mantlejs/auth-oauth |

Routes registered:

| Method | Path | Description | | --- | --- | --- | | GET | /auth/google | Redirect to Google consent screen | | GET | /auth/google/callback | Handle callback, issue Mantle JWT pair |

Must be configured after an HTTP transport (@mantlejs/express, @mantlejs/koa, or @mantlejs/http) and auth().

Types

import type { GoogleStrategyConfig } from "@mantlejs/auth-google";

GoogleStrategyConfig is an alias for OAuthPluginConfig from @mantlejs/auth-oauth.

Google Cloud Console setup

No API needs to be enabled — this strategy calls Google's OpenID Connect userinfo endpoint directly for the openid/profile/email scopes, not the (long since shut down) Google+ API or the People API.

1. Create a project at console.cloud.google.com
2. Under Google Auth Platform → Branding, configure the app name and support email, then under Audience set the publishing status. openid, email, and profile are non-sensitive scopes that don't require verification. If the app stays in Testing mode, add your own Google account under Audience → Test users or sign-in will be blocked.
3. Under Google Auth Platform → Clients, create a client (application type Web application)
4. Add the callback URL to Authorized redirect URIs: https://your-domain.com/auth/google/callback
5. Copy the Client ID and Client Secret into your environment

(Google has renamed/reshuffled this console section before and may again — if these labels have drifted, look for "OAuth consent screen"/"Branding" and "Credentials"/"Clients"; the underlying steps are the same.)

Development

npx nx build auth-google   # compile
npx nx test auth-google    # run tests
npx nx lint auth-google    # lint

Publishing

npx nx build auth-google
cd packages/auth-google
npm publish --access public