iglobals-auth-client 1.0.0

package/README.md

@@ -0,0 +1,367 @@
+# iGlobals Auth Client - JavaScript/TypeScript SDK
+
+Official JavaScript/TypeScript SDK for integrating with iGlobals Central Auth (ICA) - an OAuth 2.0 and OpenID Connect authentication server.
+
+## Installation
+
+```bash
+npm install @iglobals/auth-client
+```
+
+## Quick Start
+
+```typescript
+import { ICAClient } from '@iglobals/auth-client';
+
+// Initialize the client
+const client = new ICAClient({
+  baseUrl: 'https://auth.yourdomain.com',      // Your ICA deployment URL
+  clientId: 'your-client-id',                  // From admin portal
+  clientSecret: 'your-client-secret',          // From admin portal
+  redirectUri: 'https://yourapp.com/callback', // Your callback URL
+  scopes: ['openid', 'profile', 'email']       // Optional, defaults shown
+});
+
+// Generate PKCE challenge
+const { codeVerifier, codeChallenge } = client.generatePKCE();
+const state = crypto.randomUUID();
+
+// Get authorization URL
+const authUrl = client.getAuthorizationUrl(state, codeChallenge);
+
+// Redirect user to authUrl
+window.location.href = authUrl;
+```
+
+## Complete OAuth Flow Example
+
+```typescript
+import express from 'express';
+import { ICAClient } from '@iglobals/auth-client';
+
+const app = express();
+
+const client = new ICAClient({
+  baseUrl: 'https://auth.yourdomain.com',
+  clientId: process.env.ICA_CLIENT_ID!,
+  clientSecret: process.env.ICA_CLIENT_SECRET!,
+  redirectUri: 'http://localhost:3000/callback',
+});
+
+// Store PKCE values per session (use proper session management in production)
+const sessions = new Map();
+
+// Login route
+app.get('/login', (req, res) => {
+  const { codeVerifier, codeChallenge } = client.generatePKCE();
+  const state = crypto.randomUUID();
+  
+  // Store for callback
+  sessions.set(state, { codeVerifier });
+  
+  const authUrl = client.getAuthorizationUrl(state, codeChallenge);
+  res.redirect(authUrl);
+});
+
+// Callback route
+app.get('/callback', async (req, res) => {
+  const { code, state } = req.query;
+  
+  const session = sessions.get(state);
+  if (!session) {
+    return res.status(400).send('Invalid state');
+  }
+  
+  try {
+    // Exchange code for tokens
+    const tokens = await client.exchangeCode(code as string, session.codeVerifier);
+    
+    // Get user info
+    const userInfo = await client.getUserInfo(tokens.access_token);
+    
+    // Store tokens securely (use httpOnly cookies in production)
+    res.json({
+      user: userInfo,
+      tokens: tokens
+    });
+  } catch (error) {
+    console.error('Auth error:', error);
+    res.status(500).send('Authentication failed');
+  }
+});
+
+app.listen(3000);
+```
+
+## API Reference
+
+### `ICAClient`
+
+#### Constructor
+
+```typescript
+new ICAClient(config: ICAConfig)
+```
+
+**Config Options:**
+- `baseUrl` (string, required): Your ICA server URL (e.g., `https://auth.yourdomain.com`)
+- `clientId` (string, required): OAuth client ID from ICA admin portal
+- `clientSecret` (string, required): OAuth client secret from ICA admin portal
+- `redirectUri` (string, required): Your application's callback URL
+- `scopes` (string[], optional): OAuth scopes. Default: `['openid', 'profile', 'email']`
+
+#### Methods
+
+##### `generatePKCE()`
+Generates a PKCE code verifier and challenge.
+
+```typescript
+const { codeVerifier, codeChallenge } = client.generatePKCE();
+```
+
+**Returns:**
+- `codeVerifier`: Random string to verify the authorization
+- `codeChallenge`: SHA-256 hash for the authorization request
+
+---
+
+##### `getAuthorizationUrl(state: string, codeChallenge: string)`
+Builds the OAuth authorization URL.
+
+```typescript
+const authUrl = client.getAuthorizationUrl(state, codeChallenge);
+```
+
+**Parameters:**
+- `state`: Random string for CSRF protection
+- `codeChallenge`: From `generatePKCE()`
+
+**Returns:** Authorization URL to redirect the user to
+
+---
+
+##### `exchangeCode(code: string, codeVerifier: string)`
+Exchanges authorization code for tokens.
+
+```typescript
+const tokens = await client.exchangeCode(code, codeVerifier);
+```
+
+**Parameters:**
+- `code`: Authorization code from callback
+- `codeVerifier`: From `generatePKCE()`
+
+**Returns:** `TokenSet`
+```typescript
+{
+  access_token: string;
+  token_type: 'Bearer';
+  expires_in: number;        // Seconds until expiration
+  refresh_token: string;
+  id_token?: string;         // If 'openid' scope requested
+  scope: string;
+}
+```
+
+---
+
+##### `refreshAccessToken(refreshToken: string)`
+Gets a new access token using a refresh token.
+
+```typescript
+const newTokens = await client.refreshAccessToken(tokens.refresh_token);
+```
+
+**Returns:** New `TokenSet`
+
+---
+
+##### `getUserInfo(accessToken: string)`
+Fetches user profile information.
+
+```typescript
+const userInfo = await client.getUserInfo(tokens.access_token);
+```
+
+**Returns:** `UserInfoClaims`
+```typescript
+{
+  sub: string;                  // User ID
+  email?: string;              // If 'email' scope
+  email_verified?: boolean;
+  given_name?: string;         // If 'profile' scope
+  family_name?: string;
+  phone_number?: string;       // If 'phone' scope
+  phone_number_verified?: boolean;
+  address?: {                  // If 'address' scope
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+  };
+}
+```
+
+---
+
+##### `verifyToken(jwt: string)`
+Verifies a JWT token's signature using JWKS.
+
+```typescript
+const payload = await client.verifyToken(tokens.access_token);
+```
+
+**Returns:** Decoded JWT payload
+
+---
+
+##### `revokeToken(refreshToken: string)`
+Revokes a refresh token.
+
+```typescript
+await client.revokeToken(tokens.refresh_token);
+```
+
+**Returns:** `{ revoked: boolean }`
+
+---
+
+## Express Middleware
+
+Protect routes with automatic token verification:
+
+```typescript
+import { ICAMiddleware } from '@iglobals/auth-client';
+
+app.use(ICAMiddleware({
+  baseUrl: 'https://auth.yourdomain.com',
+  clientId: 'your-client-id'
+}));
+
+// Protected route
+app.get('/profile', (req, res) => {
+  // req.user contains verified user info
+  res.json({ user: req.user });
+});
+```
+
+## Error Handling
+
+```typescript
+import { ICAError } from '@iglobals/auth-client';
+
+try {
+  const tokens = await client.exchangeCode(code, verifier);
+} catch (error) {
+  if (error instanceof ICAError) {
+    console.error('OAuth error:', error.error);
+    console.error('Description:', error.description);
+    console.error('Status:', error.statusCode);
+  }
+}
+```
+
+## TypeScript Support
+
+Fully typed with TypeScript definitions included.
+
+```typescript
+import {
+  ICAClient,
+  ICAConfig,
+  TokenSet,
+  UserInfoClaims,
+  JWTPayload
+} from '@iglobals/auth-client';
+```
+
+## Security Best Practices
+
+1. **Never expose client secret in frontend code** - use backend-only
+2. **Use HTTPS** in production for `redirectUri` and `baseUrl`
+3. **Store tokens securely** - use httpOnly cookies, not localStorage
+4. **Implement proper session management** - don't store PKCE in memory for production
+5. **Validate state parameter** - prevent CSRF attacks
+6. **Use short-lived access tokens** - rely on refresh tokens for long sessions
+
+## Configuration Requirements
+
+Your ICA server must have:
+- A registered OAuth client with your `clientId` and `clientSecret`
+- Your `redirectUri` added to the client's allowed redirect URIs
+- Appropriate scopes enabled for the client
+
+## Complete Next.js Example
+
+```typescript
+// app/login/page.tsx
+'use client';
+
+export default function LoginPage() {
+  const handleLogin = () => {
+    window.location.href = '/api/auth/login';
+  };
+  
+  return <button onClick={handleLogin}>Login with ICA</button>;
+}
+
+// app/api/auth/login/route.ts
+import { ICAClient } from '@iglobals/auth-client';
+import { redirect } from 'next/navigation';
+import { cookies } from 'next/headers';
+
+const client = new ICAClient({
+  baseUrl: process.env.ICA_BASE_URL!,
+  clientId: process.env.ICA_CLIENT_ID!,
+  clientSecret: process.env.ICA_CLIENT_SECRET!,
+  redirectUri: process.env.ICA_REDIRECT_URI!,
+});
+
+export async function GET() {
+  const { codeVerifier, codeChallenge } = client.generatePKCE();
+  const state = crypto.randomUUID();
+  
+  const cookieStore = await cookies();
+  cookieStore.set('ica_state', state);
+  cookieStore.set('ica_verifier', codeVerifier);
+  
+  const authUrl = client.getAuthorizationUrl(state, codeChallenge);
+  redirect(authUrl);
+}
+
+// app/api/auth/callback/route.ts
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const code = searchParams.get('code');
+  const state = searchParams.get('state');
+  
+  const cookieStore = await cookies();
+  const savedState = cookieStore.get('ica_state')?.value;
+  const verifier = cookieStore.get('ica_verifier')?.value;
+  
+  if (!code || !verifier || state !== savedState) {
+    return new Response('Invalid request', { status: 400 });
+  }
+  
+  const tokens = await client.exchangeCode(code, verifier);
+  
+  // Store tokens securely and redirect
+  cookieStore.set('ica_access_token', tokens.access_token, {
+    httpOnly: true,
+    secure: true,
+    sameSite: 'lax'
+  });
+  
+  redirect('/dashboard');
+}
+```
+
+## Support
+
+- Documentation: [https://github.com/yourusername/iglobals-cauth](https://github.com/yourusername/iglobals-cauth)
+- Issues: [https://github.com/yourusername/iglobals-cauth/issues](https://github.com/yourusername/iglobals-cauth/issues)
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,19 @@
+import { ICAConfig, TokenSet, UserInfoClaims, JWTPayload } from './types';
+export declare class ICAClient {
+    private config;
+    private jwksService;
+    constructor(config: ICAConfig);
+    getAuthorizationUrl(state: string, codeChallenge: string): string;
+    generatePKCE(): {
+        codeVerifier: string;
+        codeChallenge: string;
+    };
+    private requestToken;
+    exchangeCode(code: string, codeVerifier: string): Promise<TokenSet>;
+    refreshAccessToken(refreshToken: string): Promise<TokenSet>;
+    getUserInfo(accessToken: string): Promise<UserInfoClaims>;
+    verifyToken(jwt: string): Promise<JWTPayload>;
+    revokeToken(refreshToken: string): Promise<{
+        revoked: boolean;
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICAClient = void 0;
+const errors_1 = require("./errors");
+const pkce_1 = require("./pkce");
+const jwks_1 = require("./jwks");
+class ICAClient {
+    config;
+    jwksService;
+    constructor(config) {
+        if (!config.clientId)
+            throw new Error('clientId is required');
+        if (!config.redirectUri)
+            throw new Error('redirectUri is required');
+        if (!config.baseUrl)
+            throw new Error('baseUrl is required');
+        this.config = {
+            ...config,
+            scopes: config.scopes || ['openid', 'profile', 'email']
+        };
+        this.jwksService = new jwks_1.JWKSService(`${this.config.baseUrl}/api/oauth/jwks`);
+    }
+    getAuthorizationUrl(state, codeChallenge) {
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            response_type: 'code',
+            scope: this.config.scopes.join(' '),
+            state: state,
+            code_challenge: codeChallenge,
+            code_challenge_method: 'S256',
+        });
+        return `${this.config.baseUrl}/api/oauth/authorize?${params.toString()}`;
+    }
+    generatePKCE() {
+        return (0, pkce_1.generatePKCE)();
+    }
+    async requestToken(body) {
+        const res = await fetch(`${this.config.baseUrl}/api/oauth/token`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                ...body,
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+            }),
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            throw new errors_1.ICAError(data.error || 'request_failed', data.error_description || 'Failed to fetch token', res.status);
+        }
+        return data;
+    }
+    async exchangeCode(code, codeVerifier) {
+        return this.requestToken({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: this.config.redirectUri,
+            code_verifier: codeVerifier,
+        });
+    }
+    async refreshAccessToken(refreshToken) {
+        return this.requestToken({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+        });
+    }
+    async getUserInfo(accessToken) {
+        const res = await fetch(`${this.config.baseUrl}/api/oauth/userinfo`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+            },
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            throw new errors_1.ICAError(data.error || 'request_failed', data.error_description || 'Failed to fetch userinfo', res.status);
+        }
+        return data;
+    }
+    async verifyToken(jwt) {
+        return this.jwksService.verifyToken(jwt, this.config.clientId, this.config.baseUrl);
+    }
+    async revokeToken(refreshToken) {
+        const res = await fetch(`${this.config.baseUrl}/api/oauth/revoke`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                token: refreshToken,
+                client_id: this.config.clientId,
+                client_secret: this.config.clientSecret,
+            }),
+        });
+        const data = await res.json();
+        if (!res.ok) {
+            throw new errors_1.ICAError(data.error || 'request_failed', data.error_description || 'Failed to revoke token', res.status);
+        }
+        return data;
+    }
+}
+exports.ICAClient = ICAClient;

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class ICAError extends Error {
+    error: string;
+    error_description: string;
+    status?: number;
+    constructor(error: string, error_description: string, status?: number);
+}

package/dist/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICAError = void 0;
+class ICAError extends Error {
+    error;
+    error_description;
+    status;
+    constructor(error, error_description, status) {
+        super(`${error}: ${error_description}`);
+        this.name = 'ICAError';
+        this.error = error;
+        this.error_description = error_description;
+        this.status = status;
+        Object.setPrototypeOf(this, ICAError.prototype);
+    }
+}
+exports.ICAError = ICAError;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { ICAClient } from './client';
+import { ICAConfig } from './types';
+import { createRequireAuth, createOptionalAuth } from './middleware';
+export * from './types';
+export * from './errors';
+export { ICAClient } from './client';
+export interface IGlobalsAuthInstance extends ICAClient {
+    requireAuth: ReturnType<typeof createRequireAuth>;
+    optionalAuth: ReturnType<typeof createOptionalAuth>;
+}
+export declare function createIGlobalsAuth(config: ICAConfig): IGlobalsAuthInstance;

package/dist/index.js

@@ -0,0 +1,31 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ICAClient = void 0;
+exports.createIGlobalsAuth = createIGlobalsAuth;
+const client_1 = require("./client");
+const middleware_1 = require("./middleware");
+__exportStar(require("./types"), exports);
+__exportStar(require("./errors"), exports);
+var client_2 = require("./client");
+Object.defineProperty(exports, "ICAClient", { enumerable: true, get: function () { return client_2.ICAClient; } });
+function createIGlobalsAuth(config) {
+    const client = new client_1.ICAClient(config);
+    const instance = client;
+    instance.requireAuth = (0, middleware_1.createRequireAuth)(client);
+    instance.optionalAuth = (0, middleware_1.createOptionalAuth)(client);
+    return instance;
+}

package/dist/jwks.d.ts

@@ -0,0 +1,7 @@
+import { JWTPayload } from './types';
+export declare class JWKSService {
+    private client;
+    constructor(jwksUri: string);
+    private getKey;
+    verifyToken(token: string, expectedAud: string, expectedIss: string): Promise<JWTPayload>;
+}

package/dist/jwks.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JWKSService = void 0;
+const jsonwebtoken_1 = __importDefault(require("jsonwebtoken"));
+const jwks_rsa_1 = __importDefault(require("jwks-rsa"));
+const errors_1 = require("./errors");
+class JWKSService {
+    client;
+    constructor(jwksUri) {
+        this.client = (0, jwks_rsa_1.default)({
+            jwksUri,
+            cache: true,
+            cacheMaxEntries: 5,
+            cacheMaxAge: 3600000, // 1 hour
+        });
+    }
+    getKey = (header, callback) => {
+        this.client.getSigningKey(header.kid, (err, key) => {
+            if (err) {
+                return callback(err);
+            }
+            const signingKey = key?.getPublicKey();
+            callback(null, signingKey);
+        });
+    };
+    verifyToken(token, expectedAud, expectedIss) {
+        return new Promise((resolve, reject) => {
+            jsonwebtoken_1.default.verify(token, this.getKey, {
+                audience: expectedAud,
+                issuer: expectedIss,
+                algorithms: ['RS256'],
+            }, (err, decoded) => {
+                if (err) {
+                    reject(new errors_1.ICAError('invalid_token', err.message, 401));
+                }
+                else {
+                    resolve(decoded);
+                }
+            });
+        });
+    }
+}
+exports.JWKSService = JWKSService;

package/dist/middleware.d.ts

@@ -0,0 +1,12 @@
+import { RequestHandler } from 'express';
+import { ICAClient } from './client';
+import { JWTPayload } from './types';
+declare global {
+    namespace Express {
+        interface Request {
+            icaUser?: JWTPayload;
+        }
+    }
+}
+export declare function createRequireAuth(ica: ICAClient): RequestHandler;
+export declare function createOptionalAuth(ica: ICAClient): RequestHandler;

package/dist/middleware.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequireAuth = createRequireAuth;
+exports.createOptionalAuth = createOptionalAuth;
+function createRequireAuth(ica) {
+    return async (req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            res.status(401).json({ error: 'unauthorized', error_description: 'Bearer token missing or malformed.', status: 401 });
+            return;
+        }
+        const token = authHeader.split(' ')[1];
+        try {
+            const payload = await ica.verifyToken(token);
+            req.icaUser = payload;
+            next();
+        }
+        catch (err) {
+            res.status(401).json({ error: 'unauthorized', error_description: err.message, status: 401 });
+        }
+    };
+}
+function createOptionalAuth(ica) {
+    return async (req, res, next) => {
+        const authHeader = req.headers.authorization;
+        if (!authHeader || !authHeader.startsWith('Bearer ')) {
+            return next();
+        }
+        const token = authHeader.split(' ')[1];
+        try {
+            const payload = await ica.verifyToken(token);
+            req.icaUser = payload;
+        }
+        catch (err) {
+            // Ignore errors for optional auth
+        }
+        next();
+    };
+}

package/dist/pkce.d.ts

@@ -0,0 +1,4 @@
+export declare function generatePKCE(): {
+    codeVerifier: string;
+    codeChallenge: string;
+};

package/dist/pkce.js

@@ -0,0 +1,15 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePKCE = generatePKCE;
+const crypto_1 = __importDefault(require("crypto"));
+function generatePKCE() {
+    const codeVerifier = crypto_1.default.randomBytes(32).toString('base64url');
+    const codeChallenge = crypto_1.default
+        .createHash('sha256')
+        .update(codeVerifier)
+        .digest('base64url');
+    return { codeVerifier, codeChallenge };
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export interface ICAConfig {
+    clientId: string;
+    clientSecret?: string;
+    redirectUri: string;
+    scopes: string[];
+    baseUrl: string;
+}
+export interface TokenSet {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token: string;
+    id_token?: string;
+    scope: string;
+}
+export interface UserInfoClaims {
+    sub: string;
+    given_name?: string;
+    family_name?: string;
+    email?: string;
+    email_verified?: boolean;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: {
+        street_address?: string;
+        locality?: string;
+        region?: string;
+        postal_code?: string;
+        country?: string;
+    };
+    [key: string]: any;
+}
+export interface JWTPayload {
+    iss: string;
+    sub: string;
+    aud: string;
+    iat: number;
+    exp: number;
+    scope?: string;
+    email?: string;
+    email_verified?: boolean;
+    given_name?: string;
+    family_name?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    [key: string]: any;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "iglobals-auth-client",
+  "version": "1.0.0",
+  "description": "iGlobals Central Auth SDK for Node.js",
+  "homepage": "https://github.com/Profeso1012/Iglobals-CAuth#readme",
+  "bugs": {
+    "url": "https://github.com/Profeso1012/Iglobals-CAuth/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Profeso1012/Iglobals-CAuth.git"
+  },
+  "license": "ISC",
+  "author": "",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2",
+    "jwks-rsa": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/express": "^4.17.21",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,117 @@
+import { ICAConfig, TokenSet, UserInfoClaims, JWTPayload } from './types';
+import { ICAError } from './errors';
+import { generatePKCE } from './pkce';
+import { JWKSService } from './jwks';
+
+export class ICAClient {
+  private config: ICAConfig;
+  private jwksService: JWKSService;
+
+  constructor(config: ICAConfig) {
+    if (!config.clientId) throw new Error('clientId is required');
+    if (!config.redirectUri) throw new Error('redirectUri is required');
+    if (!config.baseUrl) throw new Error('baseUrl is required');
+    
+    this.config = {
+      ...config,
+      scopes: config.scopes || ['openid', 'profile', 'email']
+    };
+    
+    this.jwksService = new JWKSService(`${this.config.baseUrl}/api/oauth/jwks`);
+  }
+
+  public getAuthorizationUrl(state: string, codeChallenge: string): string {
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      response_type: 'code',
+      scope: this.config.scopes.join(' '),
+      state: state,
+      code_challenge: codeChallenge,
+      code_challenge_method: 'S256',
+    });
+    return `${this.config.baseUrl}/api/oauth/authorize?${params.toString()}`;
+  }
+
+  public generatePKCE(): { codeVerifier: string; codeChallenge: string } {
+    return generatePKCE();
+  }
+
+  private async requestToken(body: Record<string, string>): Promise<TokenSet> {
+    const res = await fetch(`${this.config.baseUrl}/api/oauth/token`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        ...body,
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+      }),
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new ICAError(data.error || 'request_failed', data.error_description || 'Failed to fetch token', res.status);
+    }
+
+    return data as TokenSet;
+  }
+
+  public async exchangeCode(code: string, codeVerifier: string): Promise<TokenSet> {
+    return this.requestToken({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: this.config.redirectUri,
+      code_verifier: codeVerifier,
+    });
+  }
+
+  public async refreshAccessToken(refreshToken: string): Promise<TokenSet> {
+    return this.requestToken({
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+    });
+  }
+
+  public async getUserInfo(accessToken: string): Promise<UserInfoClaims> {
+    const res = await fetch(`${this.config.baseUrl}/api/oauth/userinfo`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new ICAError(data.error || 'request_failed', data.error_description || 'Failed to fetch userinfo', res.status);
+    }
+
+    return data as UserInfoClaims;
+  }
+
+  public async verifyToken(jwt: string): Promise<JWTPayload> {
+    return this.jwksService.verifyToken(jwt, this.config.clientId, this.config.baseUrl);
+  }
+
+  public async revokeToken(refreshToken: string): Promise<{ revoked: boolean }> {
+    const res = await fetch(`${this.config.baseUrl}/api/oauth/revoke`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        token: refreshToken,
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+      }),
+    });
+
+    const data = await res.json();
+    if (!res.ok) {
+      throw new ICAError(data.error || 'request_failed', data.error_description || 'Failed to revoke token', res.status);
+    }
+
+    return data as { revoked: boolean };
+  }
+}

package/src/errors.ts

@@ -0,0 +1,14 @@
+export class ICAError extends Error {
+  public error: string;
+  public error_description: string;
+  public status?: number;
+
+  constructor(error: string, error_description: string, status?: number) {
+    super(`${error}: ${error_description}`);
+    this.name = 'ICAError';
+    this.error = error;
+    this.error_description = error_description;
+    this.status = status;
+    Object.setPrototypeOf(this, ICAError.prototype);
+  }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { ICAClient } from './client';
+import { ICAConfig } from './types';
+import { createRequireAuth, createOptionalAuth } from './middleware';
+
+export * from './types';
+export * from './errors';
+export { ICAClient } from './client';
+
+export interface IGlobalsAuthInstance extends ICAClient {
+  requireAuth: ReturnType<typeof createRequireAuth>;
+  optionalAuth: ReturnType<typeof createOptionalAuth>;
+}
+
+export function createIGlobalsAuth(config: ICAConfig): IGlobalsAuthInstance {
+  const client = new ICAClient(config);
+  
+  const instance = client as IGlobalsAuthInstance;
+  instance.requireAuth = createRequireAuth(client);
+  instance.optionalAuth = createOptionalAuth(client);
+  
+  return instance;
+}

package/src/jwks.ts

@@ -0,0 +1,48 @@
+import jwt, { JwtHeader, SigningKeyCallback } from 'jsonwebtoken';
+import jwksClient from 'jwks-rsa';
+import { JWTPayload } from './types';
+import { ICAError } from './errors';
+
+export class JWKSService {
+  private client: jwksClient.JwksClient;
+
+  constructor(jwksUri: string) {
+    this.client = jwksClient({
+      jwksUri,
+      cache: true,
+      cacheMaxEntries: 5,
+      cacheMaxAge: 3600000, // 1 hour
+    });
+  }
+
+  private getKey = (header: JwtHeader, callback: SigningKeyCallback) => {
+    this.client.getSigningKey(header.kid, (err, key) => {
+      if (err) {
+        return callback(err);
+      }
+      const signingKey = key?.getPublicKey();
+      callback(null, signingKey);
+    });
+  };
+
+  public verifyToken(token: string, expectedAud: string, expectedIss: string): Promise<JWTPayload> {
+    return new Promise((resolve, reject) => {
+      jwt.verify(
+        token,
+        this.getKey,
+        {
+          audience: expectedAud,
+          issuer: expectedIss,
+          algorithms: ['RS256'],
+        },
+        (err, decoded) => {
+          if (err) {
+            reject(new ICAError('invalid_token', err.message, 401));
+          } else {
+            resolve(decoded as JWTPayload);
+          }
+        }
+      );
+    });
+  }
+}

package/src/middleware.ts

@@ -0,0 +1,48 @@
+import { Request, Response, NextFunction, RequestHandler } from 'express';
+import { ICAClient } from './client';
+import { JWTPayload } from './types';
+
+declare global {
+  namespace Express {
+    interface Request {
+      icaUser?: JWTPayload;
+    }
+  }
+}
+
+export function createRequireAuth(ica: ICAClient): RequestHandler {
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      res.status(401).json({ error: 'unauthorized', error_description: 'Bearer token missing or malformed.', status: 401 });
+      return;
+    }
+
+    const token = authHeader.split(' ')[1];
+    try {
+      const payload = await ica.verifyToken(token);
+      req.icaUser = payload;
+      next();
+    } catch (err: any) {
+      res.status(401).json({ error: 'unauthorized', error_description: err.message, status: 401 });
+    }
+  };
+}
+
+export function createOptionalAuth(ica: ICAClient): RequestHandler {
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return next();
+    }
+
+    const token = authHeader.split(' ')[1];
+    try {
+      const payload = await ica.verifyToken(token);
+      req.icaUser = payload;
+    } catch (err) {
+      // Ignore errors for optional auth
+    }
+    next();
+  };
+}

package/src/pkce.ts

@@ -0,0 +1,11 @@
+import crypto from 'crypto';
+
+export function generatePKCE(): { codeVerifier: string; codeChallenge: string } {
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto
+    .createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url');
+
+  return { codeVerifier, codeChallenge };
+}

package/src/types.ts

@@ -0,0 +1,50 @@
+export interface ICAConfig {
+  clientId: string;
+  clientSecret?: string;
+  redirectUri: string;
+  scopes: string[];
+  baseUrl: string;
+}
+
+export interface TokenSet {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token: string;
+  id_token?: string;
+  scope: string;
+}
+
+export interface UserInfoClaims {
+  sub: string;
+  given_name?: string;
+  family_name?: string;
+  email?: string;
+  email_verified?: boolean;
+  phone_number?: string;
+  phone_number_verified?: boolean;
+  address?: {
+    street_address?: string;
+    locality?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+  };
+  [key: string]: any;
+}
+
+export interface JWTPayload {
+  iss: string;
+  sub: string;
+  aud: string;
+  iat: number;
+  exp: number;
+  scope?: string;
+  email?: string;
+  email_verified?: boolean;
+  given_name?: string;
+  family_name?: string;
+  phone_number?: string;
+  phone_number_verified?: boolean;
+  [key: string]: any;
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}