or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

access-token.md authorization-code.md client-credentials.md index.md resource-owner-password.md

tile.json

tessl/npm-simple-oauth2

Node.js client for OAuth2

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/simple-oauth2@5.1.x

To install, run

npx @tessl/cli install tessl/npm-simple-oauth2@5.1.0

Simple OAuth2

Simple OAuth2 provides a comprehensive Node.js client library for the OAuth 2.0 authorization framework, enabling developers to implement OAuth 2.0 authentication flows in their applications. It supports all three main OAuth 2.0 grant types with a clean, promise-based API and built-in token management capabilities.

Package Information

Package Name: simple-oauth2
Package Type: npm
Language: JavaScript
Installation: npm install simple-oauth2

Core Imports

const { AuthorizationCode, ClientCredentials, ResourceOwnerPassword } = require('simple-oauth2');

For ES modules:

import { AuthorizationCode, ClientCredentials, ResourceOwnerPassword } from 'simple-oauth2';

Basic Usage

const { AuthorizationCode } = require('simple-oauth2');

// Configure OAuth2 client
const client = new AuthorizationCode({
  client: {
    id: 'your-client-id',
    secret: 'your-client-secret'
  },
  auth: {
    tokenHost: 'https://oauth-provider.com'
  }
});

// Generate authorization URL
const authorizationUri = client.authorizeURL({
  redirectURI: 'http://localhost:3000/callback',
  scope: 'read write',
  state: 'random-state-string'
});

// Exchange authorization code for access token
const tokenParams = {
  code: 'authorization-code-from-callback',
  redirectURI: 'http://localhost:3000/callback'
};

const accessToken = await client.getToken(tokenParams);

Architecture

Simple OAuth2 follows a modular architecture with three main grant type classes and a shared AccessToken management system:

Grant Type Classes: Handle OAuth 2.0 flow-specific logic (AuthorizationCode, ClientCredentials, ResourceOwnerPassword)
AccessToken Class: Provides token lifecycle management (expiration checking, refresh, revocation)
Configuration System: Joi-based validation ensuring correct OAuth 2.0 compliance
HTTP Client: Underlying request handling with configurable options

Configuration

All grant type classes accept a configuration object with these sections:

interface OAuth2Config {
  client: {
    id: string;
    secret: string;
    idParamName?: string;
    secretParamName?: string;
  };
  auth: {
    tokenHost: string;
    tokenPath?: string;
    refreshPath?: string;
    revokePath?: string;
    authorizeHost?: string;
    authorizePath?: string;
  };
  options?: {
    scopeSeparator?: string;
    credentialsEncodingMode?: 'strict' | 'loose';
    bodyFormat?: 'form' | 'json';
    authorizationMethod?: 'header' | 'body';
  };
  http?: {
    // Any options supported by @hapi/wreck except baseUrl
    [key: string]: any;
  };
}

Capabilities

Authorization Code Grant

For web applications requiring user authorization through browser redirects.

class AuthorizationCode {
  constructor(options: OAuth2Config);
  authorizeURL(params: AuthorizeParams): string;
  getToken(params: TokenParams, httpOptions?: any): Promise<AccessToken>;
  createToken(token: any): AccessToken;
}

interface AuthorizeParams {
  redirectURI: string;
  scope?: string | string[];
  state?: string;
  [key: string]: any;
}

interface TokenParams {
  code: string;
  redirectURI: string;
  scope?: string | string[];
  [key: string]: any;
}

Authorization Code Grant Details

Client Credentials Grant

For service-to-service authentication without user involvement.

class ClientCredentials {
  constructor(options: OAuth2Config);
  getToken(params?: ClientCredentialsParams, httpOptions?: any): Promise<AccessToken>;
  createToken(token: any): AccessToken;
}

interface ClientCredentialsParams {
  scope?: string | string[];
  [key: string]: any;
}

Client Credentials Grant Details

Resource Owner Password Grant

For trusted applications where users provide credentials directly (deprecated but supported).

class ResourceOwnerPassword {
  constructor(options: OAuth2Config);
  getToken(params: PasswordParams, httpOptions?: any): Promise<AccessToken>;
  createToken(token: any): AccessToken;
}

interface PasswordParams {
  username: string;
  password: string;
  scope?: string | string[];
  [key: string]: any;
}

Resource Owner Password Grant Details

Access Token Management

Comprehensive token lifecycle management for all grant types.

class AccessToken {
  readonly token: TokenObject;
  
  expired(expirationWindowSeconds?: number): boolean;
  refresh(params?: RefreshParams, httpOptions?: any): Promise<AccessToken>;
  revoke(tokenType: 'access_token' | 'refresh_token', httpOptions?: any): Promise<void>;
  revokeAll(httpOptions?: any): Promise<void>;
  toJSON(): TokenObject;
}

interface TokenObject {
  access_token: string;
  refresh_token?: string;
  expires_at?: Date;
  token_type?: string;
  scope?: string;
  [key: string]: any;
}

interface RefreshParams {
  scope?: string | string[];
  [key: string]: any;
}

Access Token Management Details