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