npm install @leanmcp/auth

npm install @leanmcp/auth

npm install @leanmcp/auth keytar

import { OAuthClient } from '@leanmcp/auth/client';
import { FileStorage } from '@leanmcp/auth/storage';

// Create client with file-based token storage
const client = new OAuthClient({
  serverUrl: 'https://api.example.com',
  authorizationEndpoint: 'https://api.example.com/oauth/authorize',
  tokenEndpoint: 'https://api.example.com/oauth/token',
  clientId: 'my-app',
  scopes: ['openid', 'profile'],
  storage: new FileStorage({
    filePath: '~/.myapp/tokens.json',
    prettyPrint: true,
  }),
  pkceEnabled: true,
  autoRefresh: true,
});

// Authenticate (opens browser)
const tokens = await client.authenticate();
console.log('Authenticated!', tokens.access_token);

// Get valid token (auto-refreshes if needed)
const token = await client.getValidToken();

// Use token in API calls
const response = await fetch('https://api.example.com/data', {
  headers: { Authorization: `Bearer ${token}` },
});

interface OAuthClientOptions {
  /** Base URL of the OAuth server */
  serverUrl: string;
  
  /** Authorization endpoint URL */
  authorizationEndpoint: string;
  
  /** Token endpoint URL */
  tokenEndpoint: string;
  
  /** Token storage backend */
  storage: TokenStorage;
  
  /** Client ID (required if not using dynamic registration) */
  clientId?: string;
  
  /** Client secret (for confidential clients) */
  clientSecret?: string;
  
  /** OAuth scopes to request */
  scopes?: string[];
  
  /** Enable PKCE (default: true) */
  pkceEnabled?: boolean;
  
  /** Automatically refresh tokens before expiry (default: false) */
  autoRefresh?: boolean;
  
  /** Callback URL for browser flow (default: http://localhost:PORT/callback) */
  redirectUri?: string;
  
  /** Port for local callback server (default: random available port) */
  callbackPort?: number;
}

const tokens = await client.authenticate();
// Returns: { access_token, token_type, expires_in, refresh_token?, scope? }

const token = await client.getValidToken();
// Returns: string (access token)

const tokens = await client.getTokens();
// Returns: TokenSet | null

await client.logout();

import { MemoryStorage } from '@leanmcp/auth/storage';

const storage = new MemoryStorage();

const client = new OAuthClient({
  // ...
  storage,
});

import { FileStorage } from '@leanmcp/auth/storage';

const storage = new FileStorage({
  /** Path to token file (supports ~ for home directory) */
  filePath: '~/.myapp/tokens.json',
  
  /** Encryption key (optional, enables AES-256-GCM encryption) */
  encryptionKey?: string,
  
  /** Pretty-print JSON (default: false) */
  prettyPrint?: boolean,
});

const storage = new FileStorage({
  filePath: '~/.myapp/tokens.json',
  encryptionKey: process.env.TOKEN_ENCRYPTION_KEY,
});

import { KeychainStorage } from '@leanmcp/auth/storage';

const storage = new KeychainStorage({
  /** Service name in keychain */
  service: 'my-app',
  
  /** Account name in keychain */
  account: 'oauth-tokens',
});

import type { TokenStorage, TokenSet } from '@leanmcp/auth/storage';

class RedisStorage implements TokenStorage {
  constructor(private redis: RedisClient, private key: string) {}
  
  async get(): Promise<TokenSet | null> {
    const data = await this.redis.get(this.key);
    return data ? JSON.parse(data) : null;
  }
  
  async set(tokens: TokenSet): Promise<void> {
    await this.redis.set(this.key, JSON.stringify(tokens));
  }
  
  async clear(): Promise<void> {
    await this.redis.del(this.key);
  }
}

// PKCE is enabled by default
const client = new OAuthClient({
  serverUrl: 'https://api.example.com',
  // ...
  pkceEnabled: true, // default
});

const client = new OAuthClient({
  // ...
  autoRefresh: true,
});

// Always returns a valid token
const token = await client.getValidToken();

const newTokens = await client.refreshTokens();

import { OAuthClient } from '@leanmcp/auth/client';
import { FileStorage } from '@leanmcp/auth/storage';

const SERVER_URL = 'https://api.example.com';

async function main() {
  const storage = new FileStorage({
    filePath: '~/.myapp/tokens.json',
    prettyPrint: true,
  });

  const client = new OAuthClient({
    serverUrl: SERVER_URL,
    authorizationEndpoint: `${SERVER_URL}/oauth/authorize`,
    tokenEndpoint: `${SERVER_URL}/oauth/token`,
    storage,
    clientId: 'my-cli-app',
    scopes: ['openid', 'profile', 'read:data'],
    pkceEnabled: true,
    autoRefresh: true,
  });

  // Check for existing tokens
  const existing = await client.getTokens();
  if (existing?.access_token) {
    console.log('Using existing session');
  } else {
    console.log('Opening browser for authentication...');
    await client.authenticate();
    console.log('Authenticated!');
  }

  // Make authenticated API call
  const token = await client.getValidToken();
  const response = await fetch(`${SERVER_URL}/api/user`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  
  const user = await response.json();
  console.log('User:', user);
}

main().catch(console.error);

interface TokenSet {
  access_token: string;
  token_type: string;
  expires_in?: number;
  refresh_token?: string;
  scope?: string;
  expires_at?: number; // Unix timestamp
}

interface TokenStorage {
  get(): Promise<TokenSet | null>;
  set(tokens: TokenSet): Promise<void>;
  clear(): Promise<void>;
}