@tekcify/auth-core-client 1.0.0

package/README.md

@@ -0,0 +1,374 @@
+# @tekcify/auth-core-client
+
+Core OAuth 2.0 client utilities for Tekcify Auth. This package provides low-level OAuth helpers that can be used across different frameworks and environments (browser, Node.js, React, Vue, etc.).
+
+## Installation
+
+```bash
+npm install @tekcify/auth-core-client
+# or
+pnpm add @tekcify/auth-core-client
+# or
+yarn add @tekcify/auth-core-client
+```
+
+## Overview
+
+This package provides the foundational OAuth 2.0 functionality for Tekcify Auth, including:
+
+- **PKCE (Proof Key for Code Exchange)** generation for secure OAuth flows
+- **OAuth Client** class for managing authentication flows
+- **Standalone functions** for framework-agnostic usage
+- **Type definitions** for TypeScript support
+
+## Quick Start
+
+### 1. Generate PKCE Parameters
+
+PKCE is required for secure OAuth flows, especially for public clients (SPAs, mobile apps).
+
+```typescript
+import { generateCodeVerifier, generateCodeChallenge } from '@tekcify/auth-core-client';
+
+// Generate a code verifier (43-128 characters)
+const codeVerifier = generateCodeVerifier();
+
+// Generate the code challenge (SHA256 hash)
+const codeChallenge = await generateCodeChallenge(codeVerifier, 'S256');
+
+// Store the verifier securely (you'll need it later)
+localStorage.setItem('code_verifier', codeVerifier);
+```
+
+### 2. Build Authorization URL
+
+```typescript
+import { buildAuthorizeUrl } from '@tekcify/auth-core-client';
+
+const authUrl = buildAuthorizeUrl('https://auth.example.com', {
+  clientId: 'your-client-id',
+  redirectUri: 'https://yourapp.com/callback',
+  scopes: ['read:profile', 'write:profile'],
+  state: crypto.randomUUID(), // CSRF protection
+  codeChallenge: codeChallenge,
+  codeChallengeMethod: 'S256',
+});
+
+// Redirect user to authUrl
+window.location.href = authUrl;
+```
+
+### 3. Exchange Authorization Code for Tokens
+
+After the user is redirected back with an authorization code:
+
+```typescript
+import { exchangeCode } from '@tekcify/auth-core-client';
+
+const urlParams = new URLSearchParams(window.location.search);
+const code = urlParams.get('code');
+const state = urlParams.get('state');
+
+// Verify state matches (CSRF protection)
+if (state !== expectedState) {
+  throw new Error('Invalid state parameter');
+}
+
+// Retrieve the stored code verifier
+const codeVerifier = localStorage.getItem('code_verifier');
+
+const tokens = await exchangeCode('https://auth.example.com', {
+  code: code!,
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret', // Only for confidential clients
+  redirectUri: 'https://yourapp.com/callback',
+  codeVerifier: codeVerifier!,
+});
+
+// tokens.accessToken - Use for API requests
+// tokens.refreshToken - Store securely for token refresh
+// tokens.expiresIn - Token expiration time in seconds
+```
+
+### 4. Refresh Access Token
+
+Access tokens expire. Use the refresh token to get a new one:
+
+```typescript
+import { refreshAccessToken } from '@tekcify/auth-core-client';
+
+const newTokens = await refreshAccessToken('https://auth.example.com', {
+  refreshToken: storedRefreshToken,
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+});
+
+// Update stored tokens
+localStorage.setItem('access_token', newTokens.accessToken);
+localStorage.setItem('refresh_token', newTokens.refreshToken);
+```
+
+### 5. Get User Information
+
+```typescript
+import { getUserInfo } from '@tekcify/auth-core-client';
+
+const userInfo = await getUserInfo('https://auth.example.com', accessToken);
+
+console.log(userInfo.email); // appdever01@gmail.com
+console.log(userInfo.name); // John Doe
+console.log(userInfo.email_verified); // true
+```
+
+## Using the OAuth Client Class
+
+For a more object-oriented approach, use the `OAuthClient` class:
+
+```typescript
+import { OAuthClient } from '@tekcify/auth-core-client';
+
+const client = new OAuthClient({
+  authServerUrl: 'https://auth.example.com',
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  redirectUri: 'https://yourapp.com/callback',
+  scopes: ['read:profile', 'write:profile'],
+});
+
+// Build authorization URL
+const authUrl = await client.buildAuthorizeUrl({
+  state: 'random-state',
+  codeChallenge: codeChallenge,
+  codeChallengeMethod: 'S256',
+});
+
+// Exchange code
+const tokens = await client.exchangeCode(code, codeVerifier);
+
+// Refresh token
+const newTokens = await client.refreshAccessToken(refreshToken);
+
+// Get user info
+const userInfo = await client.getUserInfo(accessToken);
+
+// Revoke token (logout)
+await client.revokeToken(accessToken);
+
+// Introspect token (check if valid)
+const introspection = await client.introspectToken(accessToken);
+if (introspection.active) {
+  console.log('Token is valid');
+}
+```
+
+## Complete OAuth Flow Example
+
+Here's a complete example of implementing the OAuth flow:
+
+```typescript
+import {
+  OAuthClient,
+  generateCodeVerifier,
+  generateCodeChallenge,
+} from '@tekcify/auth-core-client';
+
+// Initialize client
+const client = new OAuthClient({
+  authServerUrl: process.env.AUTH_SERVER_URL!,
+  clientId: process.env.CLIENT_ID!,
+  clientSecret: process.env.CLIENT_SECRET!,
+  redirectUri: process.env.REDIRECT_URI!,
+  scopes: ['read:profile'],
+});
+
+// Step 1: Start login flow
+async function login() {
+  const verifier = generateCodeVerifier();
+  const challenge = await generateCodeChallenge(verifier, 'S256');
+  const state = crypto.randomUUID();
+
+  // Store verifier and state securely
+  sessionStorage.setItem('oauth_verifier', verifier);
+  sessionStorage.setItem('oauth_state', state);
+
+  // Build and redirect to authorization URL
+  const authUrl = await client.buildAuthorizeUrl({
+    state,
+    codeChallenge: challenge,
+    codeChallengeMethod: 'S256',
+  });
+
+  window.location.href = authUrl;
+}
+
+// Step 2: Handle callback
+async function handleCallback() {
+  const urlParams = new URLSearchParams(window.location.search);
+  const code = urlParams.get('code');
+  const state = urlParams.get('state');
+  const storedState = sessionStorage.getItem('oauth_state');
+  const verifier = sessionStorage.getItem('oauth_verifier');
+
+  // Verify state
+  if (state !== storedState) {
+    throw new Error('Invalid state parameter');
+  }
+
+  if (!code || !verifier) {
+    throw new Error('Missing authorization code or verifier');
+  }
+
+  // Exchange code for tokens
+  const tokens = await client.exchangeCode(code, verifier);
+
+  // Store tokens securely
+  localStorage.setItem('access_token', tokens.accessToken);
+  localStorage.setItem('refresh_token', tokens.refreshToken);
+  localStorage.setItem('token_expires_at', String(Date.now() + tokens.expiresIn * 1000));
+
+  // Clean up
+  sessionStorage.removeItem('oauth_verifier');
+  sessionStorage.removeItem('oauth_state');
+
+  return tokens;
+}
+
+// Step 3: Make authenticated requests
+async function fetchProtectedData() {
+  let accessToken = localStorage.getItem('access_token');
+  const expiresAt = parseInt(localStorage.getItem('token_expires_at') || '0');
+
+  // Refresh if expired
+  if (Date.now() >= expiresAt) {
+    const refreshToken = localStorage.getItem('refresh_token');
+    if (!refreshToken) {
+      throw new Error('No refresh token available');
+    }
+
+    const newTokens = await client.refreshAccessToken(refreshToken);
+    accessToken = newTokens.accessToken;
+    localStorage.setItem('access_token', newTokens.accessToken);
+    localStorage.setItem('refresh_token', newTokens.refreshToken);
+    localStorage.setItem('token_expires_at', String(Date.now() + newTokens.expiresIn * 1000));
+  }
+
+  // Use access token
+  const response = await fetch('https://api.example.com/protected', {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+  });
+
+  return response.json();
+}
+
+// Step 4: Logout
+async function logout() {
+  const accessToken = localStorage.getItem('access_token');
+  if (accessToken) {
+    await client.revokeToken(accessToken);
+  }
+
+  localStorage.removeItem('access_token');
+  localStorage.removeItem('refresh_token');
+  localStorage.removeItem('token_expires_at');
+}
+```
+
+## API Reference
+
+### Functions
+
+#### `generateCodeVerifier(): string`
+
+Generates a cryptographically random code verifier (43-128 characters) for PKCE.
+
+#### `generateCodeChallenge(verifier: string, method?: 'plain' | 'S256'): Promise<string>`
+
+Generates a code challenge from a verifier. Use `S256` (SHA256) for security.
+
+#### `buildAuthorizeUrl(authServerUrl: string, config: AuthorizeConfig): string`
+
+Builds the OAuth authorization URL.
+
+#### `exchangeCode(authServerUrl: string, config: ExchangeCodeConfig): Promise<TokenResponse>`
+
+Exchanges an authorization code for access and refresh tokens.
+
+#### `refreshAccessToken(authServerUrl: string, config: RefreshTokenConfig): Promise<TokenResponse>`
+
+Refreshes an expired access token using a refresh token.
+
+#### `revokeToken(authServerUrl: string, config: RevokeTokenConfig): Promise<void>`
+
+Revokes an access or refresh token.
+
+#### `introspectToken(authServerUrl: string, config: IntrospectConfig): Promise<IntrospectResult>`
+
+Checks if a token is valid and returns its metadata.
+
+#### `getUserInfo(authServerUrl: string, accessToken: string): Promise<UserInfo>`
+
+Retrieves user information using an access token.
+
+### Types
+
+```typescript
+interface TokenResponse {
+  accessToken: string;
+  refreshToken: string;
+  tokenType: string; // Usually "Bearer"
+  expiresIn: number; // Seconds until expiration
+  scope: string; // Space-separated scopes
+}
+
+interface UserInfo {
+  sub: string; // User ID
+  email: string;
+  email_verified: boolean;
+  given_name: string | null;
+  family_name: string | null;
+  name: string | null;
+  picture: string | null;
+  updated_at: number; // Unix timestamp
+}
+
+interface IntrospectResult {
+  active: boolean;
+  clientId?: string;
+  username?: string;
+  scope?: string;
+  sub?: string;
+  exp?: number;
+  iat?: number;
+  tokenType?: string;
+}
+```
+
+## Security Best Practices
+
+1. **Always use PKCE**: Required for public clients, recommended for all
+2. **Store tokens securely**: Use httpOnly cookies or secure storage
+3. **Validate state parameter**: Prevents CSRF attacks
+4. **Never expose client secrets**: Only use in server-side code
+5. **Handle token expiration**: Implement automatic refresh logic
+6. **Revoke tokens on logout**: Prevents unauthorized access
+
+## Browser Compatibility
+
+This package uses modern Web APIs:
+- `crypto.getRandomValues()` for random number generation
+- `crypto.subtle.digest()` for SHA256 hashing
+- `fetch()` for HTTP requests
+
+Supported in all modern browsers (Chrome, Firefox, Safari, Edge).
+
+## Node.js Usage
+
+For Node.js environments, ensure you have:
+- Node.js 18+ (for native fetch support)
+- Or use a fetch polyfill like `node-fetch`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@tekcify/auth-core-client",
+  "version": "1.0.0",
+  "description": "Core OAuth 2.0 client utilities for Tekcify Auth",
+  "author": "Tekcify",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tekcify/auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tekcify/auth/issues"
+  },
+  "homepage": "https://github.com/tekcify/auth#readme",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings=0",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "oauth",
+    "oauth2",
+    "pkce",
+    "auth"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.15"
+  }
+}
+

package/src/__tests__/pkce.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { generateCodeVerifier, generateCodeChallenge } from '../pkce';
+
+describe('PKCE', () => {
+  it('should generate a code verifier', () => {
+    const verifier = generateCodeVerifier();
+    expect(verifier).toBeDefined();
+    expect(verifier.length).toBeGreaterThanOrEqual(43);
+    expect(verifier.length).toBeLessThanOrEqual(128);
+  });
+
+  it('should generate different verifiers each time', () => {
+    const verifier1 = generateCodeVerifier();
+    const verifier2 = generateCodeVerifier();
+    expect(verifier1).not.toBe(verifier2);
+  });
+
+  it('should generate a code challenge from verifier (S256)', async () => {
+    const verifier = generateCodeVerifier();
+    const challenge = await generateCodeChallenge(verifier, 'S256');
+    expect(challenge).toBeDefined();
+    expect(challenge).not.toBe(verifier);
+    expect(challenge.length).toBeGreaterThan(0);
+  });
+
+  it('should generate a plain code challenge', async () => {
+    const verifier = generateCodeVerifier();
+    const challenge = await generateCodeChallenge(verifier, 'plain');
+    expect(challenge).toBe(verifier);
+  });
+});

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './pkce';
+export * from './oauth';

package/src/oauth.ts

@@ -0,0 +1,250 @@
+import type {
+  TokenResponse,
+  UserInfo,
+  IntrospectResult,
+  OAuthConfig,
+} from './types';
+import { generateCodeVerifier, generateCodeChallenge } from './pkce';
+
+export function buildAuthorizeUrl(
+  authServerUrl: string,
+  config: {
+    clientId: string;
+    redirectUri: string;
+    scopes: string[];
+    state?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'plain' | 'S256';
+  },
+): string {
+  const url = new URL(`${authServerUrl}/oauth/authorize`);
+  url.searchParams.set('clientId', config.clientId);
+  url.searchParams.set('redirectUri', config.redirectUri);
+  url.searchParams.set('scopes', config.scopes.join(' '));
+  if (config.state) {
+    url.searchParams.set('state', config.state);
+  }
+  if (config.codeChallenge) {
+    url.searchParams.set('codeChallenge', config.codeChallenge);
+    url.searchParams.set(
+      'codeChallengeMethod',
+      config.codeChallengeMethod ?? 'S256',
+    );
+  }
+  return url.toString();
+}
+
+export async function exchangeCode(
+  authServerUrl: string,
+  config: {
+    code: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    codeVerifier?: string;
+  },
+): Promise<TokenResponse> {
+  const response = await fetch(`${authServerUrl}/oauth/token`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      grant_type: 'authorization_code',
+      code: config.code,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+      redirectUri: config.redirectUri,
+      codeVerifier: config.codeVerifier,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json().catch(() => ({}))) as {
+      message?: string;
+    };
+    throw new Error(error.message ?? 'Failed to exchange authorization code');
+  }
+
+  return (await response.json()) as TokenResponse;
+}
+
+export async function refreshAccessToken(
+  authServerUrl: string,
+  config: {
+    refreshToken: string;
+    clientId: string;
+    clientSecret: string;
+  },
+): Promise<TokenResponse> {
+  const response = await fetch(`${authServerUrl}/oauth/token`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      grant_type: 'refresh_token',
+      refreshToken: config.refreshToken,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json().catch(() => ({}))) as {
+      message?: string;
+    };
+    throw new Error(error.message ?? 'Failed to refresh access token');
+  }
+
+  return (await response.json()) as TokenResponse;
+}
+
+export async function revokeToken(
+  authServerUrl: string,
+  config: {
+    token: string;
+    clientId: string;
+    clientSecret: string;
+  },
+): Promise<void> {
+  const response = await fetch(`${authServerUrl}/oauth/revoke`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      token: config.token,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json().catch(() => ({}))) as {
+      message?: string;
+    };
+    throw new Error(error.message ?? 'Failed to revoke token');
+  }
+}
+
+export async function introspectToken(
+  authServerUrl: string,
+  config: {
+    token: string;
+    clientId?: string;
+    clientSecret?: string;
+  },
+): Promise<IntrospectResult> {
+  const body: Record<string, string> = {
+    token: config.token,
+  };
+
+  if (config.clientId) {
+    body.clientId = config.clientId;
+  }
+  if (config.clientSecret) {
+    body.clientSecret = config.clientSecret;
+  }
+
+  const response = await fetch(`${authServerUrl}/oauth/token/introspect`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const error = (await response.json().catch(() => ({}))) as {
+      message?: string;
+    };
+    throw new Error(error.message ?? 'Failed to introspect token');
+  }
+
+  return (await response.json()) as IntrospectResult;
+}
+
+export async function getUserInfo(
+  authServerUrl: string,
+  accessToken: string,
+): Promise<UserInfo> {
+  const response = await fetch(`${authServerUrl}/oauth/userinfo`, {
+    method: 'GET',
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+  });
+
+  if (!response.ok) {
+    const error = (await response.json().catch(() => ({}))) as {
+      message?: string;
+    };
+    throw new Error(error.message ?? 'Failed to get user info');
+  }
+
+  return (await response.json()) as UserInfo;
+}
+
+export class OAuthClient {
+  constructor(private config: OAuthConfig) {}
+
+  async buildAuthorizeUrl(options?: {
+    state?: string;
+    codeChallenge?: string;
+    codeChallengeMethod?: 'plain' | 'S256';
+  }): Promise<string> {
+    return buildAuthorizeUrl(this.config.authServerUrl, {
+      clientId: this.config.clientId,
+      redirectUri: this.config.redirectUri,
+      scopes: this.config.scopes,
+      ...options,
+    });
+  }
+
+  async exchangeCode(
+    code: string,
+    codeVerifier?: string,
+  ): Promise<TokenResponse> {
+    return exchangeCode(this.config.authServerUrl, {
+      code,
+      clientId: this.config.clientId,
+      clientSecret: this.config.clientSecret,
+      redirectUri: this.config.redirectUri,
+      codeVerifier,
+    });
+  }
+
+  async refreshAccessToken(refreshToken: string): Promise<TokenResponse> {
+    return refreshAccessToken(this.config.authServerUrl, {
+      refreshToken,
+      clientId: this.config.clientId,
+      clientSecret: this.config.clientSecret,
+    });
+  }
+
+  async revokeToken(token: string): Promise<void> {
+    return revokeToken(this.config.authServerUrl, {
+      token,
+      clientId: this.config.clientId,
+      clientSecret: this.config.clientSecret,
+    });
+  }
+
+  async introspectToken(
+    token: string,
+    options?: { clientId?: string; clientSecret?: string },
+  ): Promise<IntrospectResult> {
+    return introspectToken(this.config.authServerUrl, {
+      token,
+      clientId: options?.clientId ?? this.config.clientId,
+      clientSecret: options?.clientSecret ?? this.config.clientSecret,
+    });
+  }
+
+  async getUserInfo(accessToken: string): Promise<UserInfo> {
+    return getUserInfo(this.config.authServerUrl, accessToken);
+  }
+}
+
+export { generateCodeVerifier, generateCodeChallenge };