@mantlejs/auth-github

GitHub OAuth 2.0 strategy for Mantle JS. Implements the authorization code flow — no Passport.js dependency. Registers GET /auth/github and GET /auth/github/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-github

---

Concepts

Authorization code flow

GitHub Sign-In uses the standard authorization code flow (without PKCE — GitHub does not support it for server-side apps). On each redirect request the plugin generates a random state token stored server-side for CSRF protection and passed through the OAuth exchange. URL construction and token exchange go through Arctic (see ADR-002); the token request authenticates with HTTP Basic credentials.

Find-or-create

On callback the plugin searches the configured user service for a record where githubId (configurable) matches the id field from GitHub’s /user endpoint. If no record is found, it creates one with { githubId, 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 { githubStrategy } from "@mantlejs/auth-github";

const app = mantle()
  .configure(express())
  .configure(auth({ secret: process.env.JWT_SECRET! }))
  .configure(
    githubStrategy({
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    }),
  );

app.listen(3030);

Sign-in flow:

1. Redirect the browser to GET /auth/github
2. User authenticates on GitHub and consents
3. GitHub redirects to GET /auth/github/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", "githubId": "12345", "email": "alice@github.com", "name": "Alice" }
}

---

API

githubStrategy(config)

function githubStrategy(config: GitHubStrategyConfig): MantlePlugin;

type GitHubStrategyConfig = {
  clientId: string;
  clientSecret: string;
  callbackUrl?: string; // Default: '/auth/github/callback'
  scope?: string[]; // Default: ['read:user', 'user:email']
  entity?: string; // Default: 'users'
  entityIdField?: string; // Default: 'githubId'
};

Field	Type	Default	Description
clientId	string	—	GitHub OAuth App client ID (required)
clientSecret	string	—	GitHub OAuth App client secret (required)
callbackUrl	string	'/auth/github/callback'	Callback path — must match the Authorization callback URL registered in your GitHub OAuth App
scope	string[]	['read:user', 'user:email']	GitHub OAuth scopes
entity	string	'users'	Mantle service used to find or create users
entityIdField	string	'githubId'	Field on the user record matched against GitHub’s id value
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/github	Redirect to GitHub consent screen
GET	/auth/github/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 { GitHubStrategyConfig } from "@mantlejs/auth-github";

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

---

GitHub OAuth App setup

1. Go to Settings → Developer settings → OAuth Apps at github.com
2. Click New OAuth App
3. Set the Authorization callback URL to https://your-domain.com/auth/github/callback
4. Copy the Client ID and generate a Client Secret
5. Add both to your environment variables

---

Development

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

---

Publishing

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