scg-auth

A lightweight, zero-dependency OAuth 2.0 client library built from scratch.

Supports all major OAuth 2.0 flows with built-in PKCE and CSRF protection.

Features

• Authorization Code Flow — with PKCE (S256) support
• Client Credentials Flow — machine-to-machine / service accounts
• Refresh Token — seamless token renewal
• Device Code Flow — CLI tools, smart TVs, IoT devices
• Implicit Flow — parse-only (deprecated in OAuth 2.1)
• State / CSRF protection — automatic state generation and validation
• Token management — in-memory storage with expiry checking
• Zero dependencies — built entirely on Node.js built-ins
• TypeScript support — full .d.ts definitions included

Installation

npm install scg-auth

Quick Start

Authorization Code Flow (with PKCE)

const SCGAuth = require("scg-auth");

const client = new SCGAuth({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
  authorizationUrl: "https://provider.example.com/oauth/authorize",
  tokenUrl: "https://provider.example.com/oauth/token",
  redirectUri: "https://yourapp.com/callback",
  scopes: ["openid", "profile", "email"],
});

// 1. Generate the authorization URL
const { url, state, codeVerifier } = client.generateAuthUrl({ pkce: true });
// Redirect the user to `url`, store `state` and `codeVerifier` in the session

// 2. Handle the callback
const tokens = await client.exchangeCode(req.query.code, {
  state: req.query.state, // validates CSRF automatically
  codeVerifier, // or omit — resolved from state automatically
});
console.log(tokens.access_token);

// 3. Refresh when near expiry
if (client.isTokenExpired(120)) {
  const refreshed = await client.refreshToken(tokens.refresh_token);
}

Client Credentials Flow

const tokens = await client.clientCredentials();
console.log(tokens.access_token);

Device Code Flow

const deviceAuth = await client.deviceCode();
console.log(
  `Visit ${deviceAuth.verification_uri} and enter: ${deviceAuth.user_code}`,
);

const tokens = await client.pollDeviceToken(deviceAuth);
console.log(tokens.access_token);

API

new SCGAuth(config)

Option	Type	Required	Description
clientId	string	✓	OAuth client ID
authorizationUrl	string	✓	Provider authorization endpoint
tokenUrl	string	✓	Provider token endpoint
clientSecret	string		Client secret (required for confidential clients)
redirectUri	string		Redirect URI
scopes	string[]		Default scopes
deviceAuthorizationUrl	string		Device authorization endpoint

Methods

Method	Description
generateAuthUrl(options?)	Build auth URL + register CSRF state
validateState(state)	Validate CSRF state from callback
exchangeCode(code, options?)	Exchange code for tokens
clientCredentials(scopes?)	Client Credentials flow
refreshToken(refreshToken)	Refresh an access token
deviceCode(scopes?)	Initiate Device Code flow
pollDeviceToken(response, options?)	Poll until user authorizes
generateImplicitUrl(options?)	Build Implicit flow auth URL
parseImplicitResponse(urlOrFragment)	Parse Implicit flow response
getStoredTokens()	Get cached tokens
isTokenExpired(bufferSeconds?)	Check token expiry
clearTokens()	Clear cached tokens

Running Tests

npm test

License

MIT — Analytics With Harry / Squid Consultancy Group Limited