@intelicity/gates-sdk 0.1.5 → 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,364 +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
-- 🎨 Custom error classes for better error handling
-- 🔐 Group-based access control
+- 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
-
-The `UserService` provides user management capabilities:
+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.
 
-```typescript
-import { UserService } from "@intelicity/gates-sdk";
-
-const userService = new UserService(
-  "https://api.example.com", // Backend API URL
-  "your-system-name" // System identifier
-);
+### Middleware
 
-// 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);
-}
+Framework-agnostic functions for request authentication:
 
-// 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);
-}
+```typescript
+import { handleAuth, AuthService } from "@intelicity/gates-sdk";
+
+const service = new AuthService(region, userPoolId, clientId);
+
+// Fastify
+app.addHook("preHandler", async (req) => {
+  req.user = await handleAuth(req.headers.authorization, {
+    service,
+    requiredGroups: "GAIA",
+  });
+});
+
+// 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 } 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!
-    );
-  }
+import { extractToken, authenticate, authorize } from "@intelicity/gates-sdk";
 
-  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) {
-      throw new Error(`Operation failed: ${error.message}`);
-    }
-  }
-}
+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 custom error classes for better error handling:
-
 ```typescript
 import {
-  AuthService,
-  UserService,
-  AuthenticationError,
   TokenExpiredError,
   InvalidTokenError,
-  MissingAuthorizationError,
+  UnauthorizedGroupError,
+  GatesError,
 } from "@intelicity/gates-sdk";
 
-const authService = new AuthService(region, userPoolId, audience);
-
 try {
-  const user = await authService.verifyToken(token);
+  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 provided");
-  } else if (error instanceof MissingAuthorizationError) {
-    console.error("No authorization token provided");
-  } else {
-    console.error("Authentication failed:", error.message);
-  }
-}
-
-// Error handling with User Service
-try {
-  const users = await userService.getAllUsers(token);
-} catch (error) {
-  if (error.message.includes("HTTP 401")) {
-    console.error("Unauthorized - check your token");
-  } else if (error.message.includes("HTTP 403")) {
-    console.error("Forbidden - insufficient permissions");
-  } else {
-    console.error("Failed to fetch users:", error.message);
+    // error.code === "INVALID_TOKEN"
+  } else if (error instanceof UnauthorizedGroupError) {
+    // error.code === "UNAUTHORIZED_GROUP"
+    // error.requiredGroups: string[]
+  } else if (error instanceof GatesError) {
+    // 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?)
+import { GatesAdminService } from "@intelicity/gates-sdk";
+
+const admin = new GatesAdminService({
+  baseUrl: "https://abc123.execute-api.sa-east-1.amazonaws.com/prod",
+});
+
+// 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",
+});
+
+// Later: add/remove user access to other systems
+await admin.updateUser(adminIdToken, {
+  user_id: sub,
+  clients_to_add: ["RECAPE"],
+  clients_to_remove: ["INFORMS"],
+});
 ```
 
-**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
-
-##### `verifyToken(token: string): Promise<GatesUser>`
-
-Verifies a JWT token and returns the authenticated user.
-
-##### `isMemberOf(groups: string[]): boolean`
-
-Checks if the user groups match the required groups.
-
-### `UserService`
-
-Service for managing users through a backend API.
+## API Reference
 
-#### Constructor
+### `AuthService`
 
 ```typescript
-new UserService(baseUrl, system);
+new AuthService(region: string, userPoolId: string, clientId: string)
 ```
 
-**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
-};
-```
+- `verifyToken(token: string): Promise<GatesUser>` — Verifies JWT, returns user
 
-#### `Profile`
+### `GatesAdminService`
 
 ```typescript
-type Profile = {
-  user_id: string;
-  email: string;
-  name: string;
-  enabled: boolean;
-  profile_attributes: ProfileAttribute[];
-};
-
-type ProfileAttribute = {
-  attribute_name: string;
-  value: string | boolean | number;
-};
+new GatesAdminService({ baseUrl: string })
 ```
 
-#### `UserListResponse`
-
-```typescript
-type UserListResponse = {
-  profiles: Profile[];
-  total?: number;
-  page?: number;
-  limit?: number;
-  nextToken?: string;
-};
-```
+- `createUser(idToken: string, params: CreateUserParams): Promise<CreateUserResponse>` — Creates user in Gates
+- `updateUser(idToken: string, params: UpdateUserParams): Promise<void>` — Manages user's system access
 
-#### `VerifyOptions`
+### Types
 
 ```typescript
-type VerifyOptions = {
-  region: string;
-  userPoolId: string;
-  audience: string;
-  requiredGroup?: string | string[];
+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;
 };
-```
-
-#### Custom Errors
-
-- `AuthenticationError`: Base authentication error class
-- `TokenExpiredError`: Token has expired
-- `InvalidTokenError`: Token is invalid or malformed
-- `MissingAuthorizationError`: Authorization header is missing
-
-## Environment Variables
-
-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:
 
-```typescript
-import { AuthService, UserService } from "@intelicity/gates-sdk";
-
-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
-
-### 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)
+### Error Codes
 
-```typescript
-// Good: Secure error handling
-try {
-  const user = await authService.verifyToken(token);
-} catch (error) {
-  // Log for monitoring (server-side only)
-  console.error('Auth failed:', error.constructor.name);
-
-  // Return generic error to client
-  throw new Error('Authentication failed');
-}
-
-// Bad: Exposing sensitive information
-catch (error) {
-  throw new Error(`Auth failed: ${error.message}`); // May expose internal details
-}
-```
+| 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"}

package/dist/auth/middleware.js

@@ -1,40 +1,31 @@
-// // src/auth/middleware.ts
-// import type { FastifyRequest, FastifyReply } from "fastify";
-// import { verifyToken, type VerifyOptions } from "./verifier.js";
-// import {
-//   MissingAuthorizationError,
-//   InvalidTokenError,
-//   TokenExpiredError,
-// } from "../errors/error.js";
-// import type { GatesUser } from "../models/user.js";
-export {};
-// // Extend FastifyRequest to include user
-// declare module "fastify" {
-//   interface FastifyRequest {
-//     user?: GatesUser;
-//   }
-// }
-// export type GatesMiddlewareConfig = VerifyOptions;
-// /**
-//  * Fastify middleware to verify JWT tokens from AWS Cognito
-//  * @param config Configuration with region, userPoolId, and optional audience
-//  * @returns Fastify preHandler hook
-//  */
-// export function gatesMiddleware(config: GatesMiddlewareConfig) {
-//   return async (request: FastifyRequest, reply: FastifyReply) => {
-//     const authHeader = request.headers.authorization;
-//     if (!authHeader) {
-//       throw new MissingAuthorizationError();
-//     }
-//     const token = authHeader.replace(/^Bearer\s+/i, "");
-//     try {
-//       const user = await verifyToken(token, config);
-//       request.user = user;
-//     } catch (err) {
-//       if (err instanceof Error && err.message.includes("expired")) {
-//         throw new TokenExpiredError();
-//       }
-//       throw new InvalidTokenError();
-//     }
-//   };
-// }
+import { MissingAuthorizationError, UnauthorizedGroupError, } from "../errors/error.js";
+export function extractToken(authorizationHeader) {
+    if (!authorizationHeader) {
+        throw new MissingAuthorizationError();
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(authorizationHeader);
+    if (!match) {
+        throw new MissingAuthorizationError("Authorization header must use Bearer scheme");
+    }
+    return match[1];
+}
+export async function authenticate(token, service) {
+    return service.verifyToken(token);
+}
+export function authorize(user, requiredGroups) {
+    const groups = Array.isArray(requiredGroups)
+        ? requiredGroups
+        : [requiredGroups];
+    const hasGroup = user.groups.some((g) => groups.includes(g));
+    if (!hasGroup) {
+        throw new UnauthorizedGroupError(`User must be a member of one of the following groups: ${groups.join(", ")}`, groups);
+    }
+}
+export async function handleAuth(authorizationHeader, config) {
+    const token = extractToken(authorizationHeader);
+    const user = await authenticate(token, config.service);
+    if (config.requiredGroups) {
+        authorize(user, config.requiredGroups);
+    }
+    return user;
+}

package/dist/errors/error.d.ts

@@ -1,26 +1,34 @@
-/**
- * Base error class for authentication-related errors
- */
-export declare class AuthenticationError extends Error {
+export declare class GatesError extends Error {
     readonly code?: string | undefined;
     constructor(message: string, code?: string | undefined);
 }
-/**
- * Error thrown when a token has expired
- */
+export declare class AuthenticationError extends GatesError {
+    constructor(message: string, code?: string);
+}
 export declare class TokenExpiredError extends AuthenticationError {
     constructor(message?: string);
 }
-/**
- * Error thrown when a token is invalid
- */
 export declare class InvalidTokenError extends AuthenticationError {
     constructor(message?: string);
 }
-/**
- * Error thrown when authorization header is missing
- */
 export declare class MissingAuthorizationError extends AuthenticationError {
     constructor(message?: string);
 }
+export declare class UnauthorizedGroupError extends AuthenticationError {
+    readonly requiredGroups: string[];
+    constructor(message: string, requiredGroups: string[]);
+}
+export declare class ApiError extends GatesError {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined, code?: string);
+}
+export declare class ApiRequestError extends ApiError {
+    constructor(message: string, statusCode?: number);
+}
+export declare class MissingParameterError extends GatesError {
+    constructor(parameterName: string);
+}
+export declare class InvalidParameterError extends GatesError {
+    constructor(parameterName: string, reason?: string);
+}
 //# sourceMappingURL=error.d.ts.map

package/dist/errors/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/errors/error.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aACC,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAK3D;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,mBAAmB;gBAC5C,OAAO,SAAsB;CAK1C;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,mBAAmB;gBAC5C,OAAO,SAAkB;CAKtC;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,mBAAmB;gBACpD,OAAO,SAAiC;CAKrD"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/errors/error.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAW,SAAQ,KAAK;aACU,IAAI,CAAC,EAAE,MAAM;gBAA9C,OAAO,EAAE,MAAM,EAAkB,IAAI,CAAC,EAAE,MAAM,YAAA;CAK3D;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAK3C;AAED,qBAAa,iBAAkB,SAAQ,mBAAmB;gBAC5C,OAAO,SAAsB;CAK1C;AAED,qBAAa,iBAAkB,SAAQ,mBAAmB;gBAC5C,OAAO,SAAkB;CAKtC;AAED,qBAAa,yBAA0B,SAAQ,mBAAmB;gBACpD,OAAO,SAAoC;CAKxD;AAED,qBAAa,sBAAuB,SAAQ,mBAAmB;aAChB,cAAc,EAAE,MAAM,EAAE;gBAAzD,OAAO,EAAE,MAAM,EAAkB,cAAc,EAAE,MAAM,EAAE;CAKtE;AAED,qBAAa,QAAS,SAAQ,UAAU;aAGpB,UAAU,CAAC,EAAE,MAAM;gBADnC,OAAO,EAAE,MAAM,EACC,UAAU,CAAC,EAAE,MAAM,YAAA,EACnC,IAAI,CAAC,EAAE,MAAM;CAMhB;AAED,qBAAa,eAAgB,SAAQ,QAAQ;gBAC/B,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAKjD;AAED,qBAAa,qBAAsB,SAAQ,UAAU;gBACvC,aAAa,EAAE,MAAM;CAKlC;AAED,qBAAa,qBAAsB,SAAQ,UAAU;gBACvC,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAQnD"}