@intelicity/gates-sdk 0.1.6 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # Gates SDK
 
-Simple SDK for authenticating users with AWS Cognito JWT tokens and managing user data.
+Node.js SDK for the Gates authentication system (AWS Cognito). Provides JWT token verification, group-based access control, admin user management, and framework-agnostic middleware.
 
 ## Installation
 
@@ -10,563 +10,182 @@ npm install @intelicity/gates-sdk
 
 ## Features
 
-- 🔒 JWT token verification with AWS Cognito
-- 👥 User management service with backend integration
-- 🎯 TypeScript support with full type definitions
-- 💾 Built-in JWKS caching for better performance
-- 🎨 Comprehensive error hierarchy with specific error types
-- 🔐 Group-based access control
-- ⚡ Detailed error messages with status codes and error codes
+- JWT verification for both access and id tokens
+- Admin user management (create + assign to client/group)
+- Framework-agnostic middleware (works with Fastify, Express, etc.)
+- Built-in JWKS caching (1h TTL)
+- Group-based access control (Cognito Groups)
+- Comprehensive error hierarchy
 
 ## Usage
 
-### Authentication Service
-
-The `AuthService` provides JWT token verification with AWS Cognito:
+### Token Verification
 
 ```typescript
 import { AuthService } from "@intelicity/gates-sdk";
 
-const authService = new AuthService(
-  "sa-east-1", // AWS region
+const auth = new AuthService(
+  "sa-east-1",           // AWS region
   "sa-east-1_xxxxxxxxx", // User Pool ID
-  "your-client-id", // Audience (client ID)
-  ["admin", "user"] // Optional: required groups
+  "your-client-id"       // Cognito App Client ID
 );
 
-// Verify a token
-try {
-  const user = await authService.verifyToken(token);
-  console.log("Authenticated user:", user);
-
-  // Check group membership
-  const isAdmin = authService.isMemberOf(user.groups || []);
-  console.log("Has required group:", isAdmin);
-} catch (error) {
-  console.error("Authentication failed:", error.message);
-}
+const user = await auth.verifyToken(accessToken);
+// user.user_id, user.groups, user.token_use, user.email?, user.name?
 ```
 
-### User Service
+Supports both `access_token` (validates `client_id` claim) and `id_token` (validates `aud` claim). The `token_use` field on the returned user indicates which type was verified.
 
-The `UserService` provides user management capabilities:
+### Middleware
+
+Framework-agnostic functions for request authentication:
 
 ```typescript
-import { UserService } from "@intelicity/gates-sdk";
+import { handleAuth, AuthService } from "@intelicity/gates-sdk";
 
-const userService = new UserService(
-  "https://api.example.com", // Backend API URL
-  "your-system-name" // System identifier
-);
+const service = new AuthService(region, userPoolId, clientId);
 
-// Get all users from the system
-try {
-  const users = await userService.getAllUsers(idToken);
-  console.log("Users:", users.profiles);
-  console.log("Total:", users.total);
-} catch (error) {
-  console.error("Failed to fetch users:", error.message);
-}
+// Fastify
+app.addHook("preHandler", async (req) => {
+  req.user = await handleAuth(req.headers.authorization, {
+    service,
+    requiredGroups: "GAIA",
+  });
+});
 
-// Get specific user by ID
-try {
-  const user = await userService.getUserById(idToken, "user-id-123");
-  console.log("User details:", user);
-} catch (error) {
-  console.error("Failed to fetch user:", error.message);
-}
+// Express
+app.use(async (req, res, next) => {
+  try {
+    req.user = await handleAuth(req.headers.authorization, {
+      service,
+      requiredGroups: "GAIA",
+    });
+    next();
+  } catch (e) { next(e); }
+});
 ```
 
-### Complete Integration Example
+Individual functions are also available:
 
 ```typescript
-import {
-  AuthService,
-  UserService,
-  TokenExpiredError,
-  UnauthorizedGroupError,
-  ApiRequestError,
-  MissingParameterError,
-  GatesError,
-} from "@intelicity/gates-sdk";
+import { extractToken, authenticate, authorize } from "@intelicity/gates-sdk";
 
-class MyApplication {
-  private authService: AuthService;
-  private userService: UserService;
-
-  constructor() {
-    this.authService = new AuthService(
-      process.env.AWS_REGION!,
-      process.env.COGNITO_USER_POOL_ID!,
-      process.env.COGNITO_CLIENT_ID!,
-      ["admin"] // Only admins can access
-    );
-
-    this.userService = new UserService(
-      process.env.BACKEND_URL!,
-      process.env.SYSTEM_NAME!
-    );
-  }
-
-  async handleRequest(authToken: string) {
-    try {
-      // 1. Authenticate user
-      const user = await this.authService.verifyToken(authToken);
-      console.log(`User ${user.name} authenticated successfully`);
-
-      // 2. Get user list if authorized
-      const users = await this.userService.getAllUsers(authToken);
-
-      return {
-        currentUser: user,
-        allUsers: users.profiles,
-        total: users.total,
-      };
-    } catch (error) {
-      // Handle specific error types
-      if (error instanceof TokenExpiredError) {
-        return { error: "Session expired", code: 401 };
-      }
-
-      if (error instanceof UnauthorizedGroupError) {
-        return {
-          error: "Access denied",
-          code: 403,
-          requiredGroups: error.requiredGroups,
-        };
-      }
-
-      if (error instanceof ApiRequestError) {
-        return {
-          error: "Service unavailable",
-          code: error.statusCode || 500,
-          details: error.message,
-        };
-      }
-
-      if (error instanceof MissingParameterError) {
-        return { error: "Invalid request", code: 400 };
-      }
-
-      if (error instanceof GatesError) {
-        return {
-          error: "Operation failed",
-          code: 500,
-          errorCode: error.code,
-        };
-      }
-
-      // Unknown error
-      throw error;
-    }
-  }
-}
+const token = extractToken(req.headers.authorization); // Bearer token extraction
+const user = await authenticate(token, service);        // JWT verification
+authorize(user, ["GAIA", "RECAPE"]);                    // Group check (throws if unauthorized)
 ```
 
 ### Error Handling
 
-The SDK provides a comprehensive error hierarchy for better error handling:
-
 ```typescript
 import {
-  AuthService,
-  UserService,
-  // Base errors
-  GatesError,
-  // Authentication errors
-  AuthenticationError,
   TokenExpiredError,
   InvalidTokenError,
-  MissingAuthorizationError,
   UnauthorizedGroupError,
-  // API errors
-  ApiError,
-  ApiRequestError,
-  InvalidResponseError,
-  // Parameter errors
-  MissingParameterError,
-  InvalidParameterError,
+  GatesError,
 } from "@intelicity/gates-sdk";
 
-const authService = new AuthService(region, userPoolId, audience, ["admin"]);
-
-// Authentication Error Handling
 try {
-  const user = await authService.verifyToken(token);
-  console.log("User authenticated:", user);
+  const user = await auth.verifyToken(token);
 } catch (error) {
   if (error instanceof TokenExpiredError) {
-    console.error("Token expired, please login again");
     // error.code === "TOKEN_EXPIRED"
   } else if (error instanceof InvalidTokenError) {
-    console.error("Invalid token:", error.message);
     // error.code === "INVALID_TOKEN"
   } else if (error instanceof UnauthorizedGroupError) {
-    console.error("Access denied:", error.message);
-    console.error("Required groups:", error.requiredGroups);
     // error.code === "UNAUTHORIZED_GROUP"
-  } else if (error instanceof MissingParameterError) {
-    console.error("Missing parameter:", error.message);
-    // error.code === "MISSING_PARAMETER"
-  } else if (error instanceof AuthenticationError) {
-    console.error("Authentication failed:", error.message);
-  }
-}
-
-// User Service Error Handling
-const userService = new UserService(backendUrl, systemName);
-
-try {
-  const users = await userService.getAllUsers(token);
-  console.log("Users fetched:", users.profiles.length);
-} catch (error) {
-  if (error instanceof ApiRequestError) {
-    console.error(`API request failed [${error.statusCode}]:`, error.message);
-    // error.code === "API_REQUEST_ERROR"
-    // error.statusCode contains HTTP status code
-
-    if (error.statusCode === 401) {
-      console.error("Unauthorized - check your token");
-    } else if (error.statusCode === 403) {
-      console.error("Forbidden - insufficient permissions");
-    } else if (error.statusCode === 404) {
-      console.error("Resource not found");
-    }
-  } else if (error instanceof InvalidResponseError) {
-    console.error("Invalid API response:", error.message);
-    // error.code === "INVALID_RESPONSE"
-  } else if (error instanceof MissingParameterError) {
-    console.error("Missing required parameter:", error.message);
+    // error.requiredGroups: string[]
   } else if (error instanceof GatesError) {
-    console.error("Gates SDK error:", error.message, error.code);
-  }
-}
-
-// Catch all Gates errors
-try {
-  const profile = await userService.getProfile(token);
-} catch (error) {
-  if (error instanceof GatesError) {
-    // All SDK errors inherit from GatesError
-    console.error(`Error [${error.code}]:`, error.message);
-
-    // You can check specific properties based on error type
-    if (error instanceof ApiRequestError && error.statusCode) {
-      console.error(`HTTP Status: ${error.statusCode}`);
-    }
-    if (error instanceof UnauthorizedGroupError) {
-      console.error(`Required groups: ${error.requiredGroups.join(", ")}`);
-    }
+    // error.code, error.message
   }
 }
 ```
 
-## API Reference
-
-### `AuthService`
-
-Main service for JWT token verification with AWS Cognito.
+### Admin Service (User Management)
 
-#### Constructor
+For creating users and managing system access (requires admin id_token):
 
 ```typescript
-new AuthService(region, userPoolId, audience, requiredGroup?)
-```
-
-**Parameters:**
-
-- `region` (string): AWS region (e.g., 'sa-east-1')
-- `userPoolId` (string): Cognito User Pool ID
-- `audience` (string): Expected audience claim (client ID)
-- `requiredGroup` (string | string[], optional): Required Cognito groups
-
-#### Methods
+import { GatesAdminService } from "@intelicity/gates-sdk";
 
-##### `verifyToken(token: string): Promise<GatesUser>`
+const admin = new GatesAdminService({
+  baseUrl: "https://abc123.execute-api.sa-east-1.amazonaws.com/prod",
+});
 
-Verifies a JWT token and returns the authenticated user.
+// Create a new user and add to a client (group)
+// Internally calls POST /create-user then PUT /update-user
+const { sub } = await admin.createUser(adminIdToken, {
+  email: "newuser@company.com",
+  name: "New User",
+  role: "CLIENT_USER",
+  client: "GAIA",
+});
 
-##### `isMemberOf(groups: string[]): boolean`
-
-Checks if the user groups match the required groups.
-
-### `UserService`
-
-Service for managing users through a backend API.
-
-#### Constructor
-
-```typescript
-new UserService(baseUrl, system);
+// Later: add/remove user access to other systems
+await admin.updateUser(adminIdToken, {
+  user_id: sub,
+  clients_to_add: ["RECAPE"],
+  clients_to_remove: ["INFORMS"],
+});
 ```
 
-**Parameters:**
-
-- `baseUrl` (string): Backend API base URL
-- `system` (string): System identifier
-
-#### Methods
-
-##### `getAllUsers(idToken: string): Promise<UserListResponse>`
-
-Retrieves all users from the system.
-
-##### `getUserById(idToken: string, userId: string): Promise<Profile>`
-
-Retrieves a specific user by ID.
-
-### Types
-
-#### `GatesUser`
-
-```typescript
-type GatesUser = {
-  user_id: string; // Mapped from 'sub' claim
-  email: string; // User email
-  name: string; // User display name
-  role: string; // Mapped from 'custom:general_role'
-  exp: number; // Token expiration timestamp
-  iat: number; // Token issued at timestamp
-};
-```
-
-#### `Profile`
-
-```typescript
-type Profile = {
-  user_id: string;
-  email: string;
-  name: string;
-  enabled: boolean;
-  profile_attributes: ProfileAttribute[];
-};
-
-type ProfileAttribute = {
-  attribute_name: string;
-  value: string | boolean | number;
-};
-```
-
-#### `UserListResponse`
-
-```typescript
-type UserListResponse = {
-  profiles: Profile[];
-  total?: number;
-  page?: number;
-  limit?: number;
-  nextToken?: string;
-};
-```
+## API Reference
 
-#### `VerifyOptions`
+### `AuthService`
 
 ```typescript
-type VerifyOptions = {
-  region: string;
-  userPoolId: string;
-  audience: string;
-  requiredGroup?: string | string[];
-};
+new AuthService(region: string, userPoolId: string, clientId: string)
 ```
 
-#### Custom Errors
-
-All errors inherit from `GatesError` and include a `code` property for easy error identification.
-
-**Base Errors:**
-
-- `GatesError`: Base error class for all SDK errors
-  - Properties: `message`, `code`
-
-**Authentication Errors:**
-
-- `AuthenticationError`: Base authentication error (extends `GatesError`)
-- `TokenExpiredError`: Token has expired
-  - Code: `TOKEN_EXPIRED`
-- `InvalidTokenError`: Token is invalid or malformed
-  - Code: `INVALID_TOKEN`
-- `MissingAuthorizationError`: Authorization header is missing
-  - Code: `MISSING_AUTHORIZATION`
-- `UnauthorizedGroupError`: User is not a member of required group
-  - Code: `UNAUTHORIZED_GROUP`
-  - Properties: `message`, `code`, `requiredGroups: string[]`
-
-**API Errors:**
-
-- `ApiError`: Base API error (extends `GatesError`)
-  - Properties: `message`, `code`, `statusCode?: number`
-- `ApiRequestError`: API request failed
-  - Code: `API_REQUEST_ERROR`
-  - Properties: `message`, `code`, `statusCode?: number`
-- `InvalidResponseError`: API response format is invalid
-  - Code: `INVALID_RESPONSE`
-
-**Parameter Errors:**
-
-- `MissingParameterError`: Required parameter is missing
-  - Code: `MISSING_PARAMETER`
-- `InvalidParameterError`: Parameter has an invalid value
-  - Code: `INVALID_PARAMETER`
+- `verifyToken(token: string): Promise<GatesUser>` — Verifies JWT, returns user
 
-### Error Codes Reference
-
-All SDK errors include a `code` property for programmatic error handling:
-
-| Error Code              | Error Class                 | Description                          |
-| ----------------------- | --------------------------- | ------------------------------------ |
-| `TOKEN_EXPIRED`         | `TokenExpiredError`         | JWT token has expired                |
-| `INVALID_TOKEN`         | `InvalidTokenError`         | Token is invalid or malformed        |
-| `MISSING_AUTHORIZATION` | `MissingAuthorizationError` | Authorization header is missing      |
-| `UNAUTHORIZED_GROUP`    | `UnauthorizedGroupError`    | User lacks required group membership |
-| `API_REQUEST_ERROR`     | `ApiRequestError`           | API request failed                   |
-| `INVALID_RESPONSE`      | `InvalidResponseError`      | API response format is invalid       |
-| `MISSING_PARAMETER`     | `MissingParameterError`     | Required parameter is missing        |
-| `INVALID_PARAMETER`     | `InvalidParameterError`     | Parameter has invalid value          |
-
-**Usage Example:**
+### `GatesAdminService`
 
 ```typescript
-try {
-  const user = await authService.verifyToken(token);
-} catch (error) {
-  if (error instanceof GatesError) {
-    switch (error.code) {
-      case "TOKEN_EXPIRED":
-        // Redirect to login
-        break;
-      case "UNAUTHORIZED_GROUP":
-        // Show access denied page
-        break;
-      case "API_REQUEST_ERROR":
-        // Show error message with retry option
-        break;
-      default:
-        // Generic error handling
-        console.error(error.message);
-    }
-  }
-}
+new GatesAdminService({ baseUrl: string })
 ```
 
-## Environment Variables
+- `createUser(idToken: string, params: CreateUserParams): Promise<CreateUserResponse>` — Creates user in Gates
+- `updateUser(idToken: string, params: UpdateUserParams): Promise<void>` — Manages user's system access
 
-You can configure the SDK using environment variables:
-
-```bash
-# .env file
-GATES_REGION=sa-east-1
-GATES_USER_POOL_ID=sa-east-1_xxxxxxxxx
-GATES_CLIENT_ID=your-cognito-client-id
-GATES_BACKEND_URL=https://your-backend-api.com
-GATES_SYSTEM_NAME=your-system-name
-```
-
-Example usage with environment variables:
+### Types
 
 ```typescript
-import { AuthService, UserService } from "@intelicity/gates-sdk";
+type GatesUser = {
+  user_id: string;              // from 'sub'
+  email?: string;               // only in id_tokens
+  name?: string;                // only in id_tokens
+  role?: string;                // from 'custom:general_role'
+  groups: string[];             // from 'cognito:groups'
+  token_use: "access" | "id";
+  exp: number;
+  iat: number;
+};
 
-const authService = new AuthService(
-  process.env.GATES_REGION!,
-  process.env.GATES_USER_POOL_ID!,
-  process.env.GATES_CLIENT_ID!
-);
+type GatesRole = "INTERNAL_ADMIN" | "INTERNAL_USER" | "CLIENT_ADMIN" | "CLIENT_USER";
 
-const userService = new UserService(
-  process.env.GATES_BACKEND_URL!,
-  process.env.GATES_SYSTEM_NAME!
-);
 ```
 
-**Note:** The application is responsible for loading the `.env` file (e.g., using `dotenv` package). The SDK reads from `process.env`.
-
-## Security Best Practices
+### Error Codes
 
-### Token Handling
-
-- Never log or expose JWT tokens in production
-- Always use HTTPS in production environments
-- Implement proper token refresh mechanisms
-- Store tokens securely on the client side
-
-### Error Handling
-
-- Don't expose sensitive error details to end users
-- Log authentication failures for security monitoring
-- Implement rate limiting for authentication endpoints
-
-### Configuration
-
-- Use environment variables for sensitive configuration
-- Validate all configuration parameters at startup
-- Use strong, unique audience values (client IDs)
-
-```typescript
-import {
-  GatesError,
-  TokenExpiredError,
-  UnauthorizedGroupError,
-} from "@intelicity/gates-sdk";
-
-// Good: Secure error handling
-try {
-  const user = await authService.verifyToken(token);
-} catch (error) {
-  // Log for monitoring (server-side only)
-  if (error instanceof GatesError) {
-    console.error('Auth failed:', error.code, error.constructor.name);
-  }
-
-  // Return appropriate error to client based on type
-  if (error instanceof TokenExpiredError) {
-    throw new Error('Session expired');
-  }
-  if (error instanceof UnauthorizedGroupError) {
-    throw new Error('Access denied');
-  }
-
-  // Generic error for other cases
-  throw new Error('Authentication failed');
-}
-
-// Bad: Exposing sensitive information
-catch (error) {
-  throw new Error(`Auth failed: ${error.message}`); // May expose internal details
-}
-
-// Good: Check error codes for routing logic
-try {
-  const users = await userService.getAllUsers(token);
-} catch (error) {
-  if (error instanceof GatesError) {
-    // Safe to use error codes for client-side logic
-    if (error.code === 'TOKEN_EXPIRED') {
-      redirectToLogin();
-    } else if (error.code === 'UNAUTHORIZED_GROUP') {
-      showAccessDenied();
-    }
-  }
-}
-```
+| Code                       | Class                       | Description                     |
+| -------------------------- | --------------------------- | ------------------------------- |
+| `TOKEN_EXPIRED`            | `TokenExpiredError`         | JWT has expired                 |
+| `INVALID_TOKEN`            | `InvalidTokenError`         | Invalid or malformed token      |
+| `MISSING_AUTHORIZATION`    | `MissingAuthorizationError` | Authorization header missing    |
+| `UNAUTHORIZED_GROUP`       | `UnauthorizedGroupError`    | User not in required group      |
+| `API_REQUEST_ERROR`        | `ApiRequestError`           | Gates API request failed        |
+| `MISSING_PARAMETER`        | `MissingParameterError`     | Required parameter missing      |
+| `INVALID_PARAMETER`        | `InvalidParameterError`     | Parameter has invalid value     |
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build
-npm run build
-
-# Lint
-npm run lint
-
-# Type check
-npm run typecheck
-
-# Run tests
-npm test
+npm run build       # tsc && tsc-alias → dist/
+npm run typecheck   # tsc --noEmit
+npm test            # vitest run
+npm run test:watch  # vitest (watch mode)
 ```
 
 ## License

package/dist/auth/middleware.d.ts

@@ -1,2 +1,11 @@
-export {};
+import { AuthService } from "../services/auth-service.js";
+import { GatesUser } from "../models/user.js";
+export declare function extractToken(authorizationHeader: string | undefined): string;
+export declare function authenticate(token: string, service: AuthService): Promise<GatesUser>;
+export declare function authorize(user: GatesUser, requiredGroups: string | string[]): void;
+export type AuthHandlerConfig = {
+    service: AuthService;
+    requiredGroups?: string | string[];
+};
+export declare function handleAuth(authorizationHeader: string | undefined, config: AuthHandlerConfig): Promise<GatesUser>;
 //# sourceMappingURL=middleware.d.ts.map

package/dist/auth/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":""}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAM9C,wBAAgB,YAAY,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAa5E;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,CAAC,CAEpB;AAED,wBAAgB,SAAS,CACvB,IAAI,EAAE,SAAS,EACf,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,GAChC,IAAI,CAaN;AAED,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACpC,CAAC;AAEF,wBAAsB,UAAU,CAC9B,mBAAmB,EAAE,MAAM,GAAG,SAAS,EACvC,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,SAAS,CAAC,CASpB"}