@intelicity/gates-sdk 0.1.0

package/README.md

@@ -0,0 +1,375 @@
+# Gates SDK
+
+Simple SDK for authenticating users with AWS Cognito JWT tokens and managing user data.
+
+## Installation
+
+```bash
+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
+
+## Usage
+
+### Authentication Service
+
+The `AuthService` provides JWT token verification with AWS Cognito:
+
+```typescript
+import { AuthService } from "@intelicity/gates-sdk";
+
+const authService = 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
+);
+
+// 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);
+}
+```
+
+### User Service
+
+The `UserService` provides user management capabilities:
+
+```typescript
+import { UserService } from "@intelicity/gates-sdk";
+
+const userService = new UserService(
+  "https://api.example.com", // Backend API URL
+  "your-system-name" // System identifier
+);
+
+// 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);
+}
+
+// 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);
+}
+```
+
+### Complete Integration Example
+
+```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!
+    );
+  }
+
+  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}`);
+    }
+  }
+}
+```
+
+### Error Handling
+
+The SDK provides custom error classes for better error handling:
+
+```typescript
+import {
+  AuthService,
+  UserService,
+  AuthenticationError,
+  TokenExpiredError,
+  InvalidTokenError,
+  MissingAuthorizationError,
+} from "@intelicity/gates-sdk";
+
+const authService = new AuthService(region, userPoolId, audience);
+
+try {
+  const user = await authService.verifyToken(token);
+} catch (error) {
+  if (error instanceof TokenExpiredError) {
+    console.error("Token expired, please login again");
+  } 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);
+  }
+}
+```
+
+## API Reference
+
+### `AuthService`
+
+Main service for JWT token verification with AWS Cognito.
+
+#### Constructor
+
+```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
+
+##### `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.
+
+#### Constructor
+
+```typescript
+new UserService(baseUrl, system);
+```
+
+**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;
+};
+```
+
+#### `VerifyOptions`
+
+```typescript
+type VerifyOptions = {
+  region: string;
+  userPoolId: string;
+  audience: string;
+  requiredGroup?: string | string[];
+};
+```
+
+#### 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!
+);
+
+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)
+
+```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
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+```
+
+## License
+
+MIT

package/dist/auth/middleware.js

@@ -0,0 +1,40 @@
+// // 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();
+//     }
+//   };
+// }

package/dist/auth/verifier.js

@@ -0,0 +1,37 @@
+import { jwtVerify } from "jose";
+import { getJwks } from "../cache/jwks-cache.js";
+export async function verifyToken(token, { region, userPoolId, audience, requiredGroup }) {
+    if (!token) {
+        throw new Error("Token não fornecido");
+    }
+    const jwks = getJwks(region, userPoolId);
+    const issuer = `https://cognito-idp.${region}.amazonaws.com/${userPoolId}`;
+    const { payload } = await jwtVerify(token, jwks, {
+        issuer,
+        audience,
+    });
+    if (requiredGroup) {
+        const userGroups = payload["cognito:groups"];
+        if (!userGroups || !Array.isArray(userGroups)) {
+            throw new Error("Usuário não pertence ao sistema");
+        }
+        const requiredGroups = Array.isArray(requiredGroup)
+            ? requiredGroup
+            : [requiredGroup];
+        // Verifica se o usuário tem pelo menos um dos grupos obrigatórios
+        const hasRequiredGroup = requiredGroups.some((group) => userGroups.includes(group));
+        if (!hasRequiredGroup) {
+            throw new Error(`Usuário deve ser membro de um dos seguintes sistemas: ${requiredGroups.join(", ")}`);
+        }
+    }
+    // Mapear o payload do Cognito para o formato do GatesUser
+    const user = {
+        user_id: payload.sub,
+        email: payload.email,
+        name: payload.name,
+        role: payload["custom:general_role"],
+        exp: payload.exp,
+        iat: payload.iat,
+    };
+    return user;
+}

package/dist/cache/jwks-cache.js

@@ -0,0 +1,21 @@
+// src/cache/jwks-cache.ts
+import { createRemoteJWKSet } from "jose";
+const CACHE = {};
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 1 hora
+export function jwksUrl(region, userPoolId) {
+    return `https://cognito-idp.${region}.amazonaws.com/${userPoolId}/.well-known/jwks.json`;
+}
+/**
+ * Retorna um RemoteJWKSet cacheado por (region + userPoolId).
+ */
+export function getJwks(region, userPoolId, ttlMs = DEFAULT_TTL_MS) {
+    const key = `${region}::${userPoolId}`;
+    const now = Date.now();
+    if (CACHE[key] && now - CACHE[key].timestamp < ttlMs) {
+        return CACHE[key].jwks;
+    }
+    const url = jwksUrl(region, userPoolId);
+    const remote = createRemoteJWKSet(new URL(url));
+    CACHE[key] = { jwks: remote, timestamp: now };
+    return remote;
+}

package/dist/config/env.js

@@ -0,0 +1,20 @@
+// src/config/env.ts
+/**
+ * Helper to load environment variables for Gates SDK
+ * The client application should load their own .env file before importing this SDK
+ */
+export const getEnvConfig = () => ({
+    region: process.env.GATES_REGION || "sa-east-1",
+    userPoolId: process.env.GATES_USER_POOL_ID || "",
+    audience: process.env.GATES_AUDIENCE,
+});
+/**
+ * Validates that required environment variables are set
+ */
+export const validateEnvConfig = () => {
+    const config = getEnvConfig();
+    if (!config.userPoolId) {
+        throw new Error("GATES_USER_POOL_ID is required. Please set it in your .env file or environment variables.");
+    }
+    return config;
+};

package/dist/errors/error.js

@@ -0,0 +1,43 @@
+// src/errors/error.ts
+/**
+ * Base error class for authentication-related errors
+ */
+export class AuthenticationError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "AuthenticationError";
+        Object.setPrototypeOf(this, AuthenticationError.prototype);
+    }
+}
+/**
+ * Error thrown when a token has expired
+ */
+export class TokenExpiredError extends AuthenticationError {
+    constructor(message = "Token has expired") {
+        super(message, "TOKEN_EXPIRED");
+        this.name = "TokenExpiredError";
+        Object.setPrototypeOf(this, TokenExpiredError.prototype);
+    }
+}
+/**
+ * Error thrown when a token is invalid
+ */
+export class InvalidTokenError extends AuthenticationError {
+    constructor(message = "Invalid token") {
+        super(message, "INVALID_TOKEN");
+        this.name = "InvalidTokenError";
+        Object.setPrototypeOf(this, InvalidTokenError.prototype);
+    }
+}
+/**
+ * Error thrown when authorization header is missing
+ */
+export class MissingAuthorizationError extends AuthenticationError {
+    constructor(message = "Missing Authorization header") {
+        super(message, "MISSING_AUTHORIZATION");
+        this.name = "MissingAuthorizationError";
+        Object.setPrototypeOf(this, MissingAuthorizationError.prototype);
+    }
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { UserService, } from "./services/user-service.js";
+export { AuthService } from "./services/auth-service.js";
+export { AuthenticationError, TokenExpiredError, InvalidTokenError, MissingAuthorizationError, } from "./errors/error.js";

package/dist/models/user.js

@@ -0,0 +1 @@
+export {};

package/dist/services/auth-service.js

@@ -0,0 +1,80 @@
+import { jwtVerify } from "jose";
+import { getJwks } from "../cache/jwks-cache.js";
+export class AuthService {
+    region;
+    userPoolId;
+    audience;
+    requiredGroup;
+    constructor(region, userPoolId, audience, requiredGroup) {
+        if (!region || typeof region !== "string" || region.trim().length === 0) {
+            throw new Error("Region é obrigatória e deve ser uma string válida");
+        }
+        if (!userPoolId ||
+            typeof userPoolId !== "string" ||
+            userPoolId.trim().length === 0) {
+            throw new Error("UserPoolId é obrigatório e deve ser uma string válida");
+        }
+        if (!audience ||
+            typeof audience !== "string" ||
+            audience.trim().length === 0) {
+            throw new Error("Audience é obrigatória e deve ser uma string válida");
+        }
+        // Validar formato do userPoolId (deve seguir padrão AWS)
+        if (!/^[a-zA-Z0-9_-]+$/.test(userPoolId)) {
+            throw new Error("UserPoolId possui formato inválido");
+        }
+        this.region = region;
+        this.userPoolId = userPoolId;
+        this.audience = audience;
+        this.requiredGroup = requiredGroup;
+    }
+    get issuer() {
+        return `https://cognito-idp.${this.region}.amazonaws.com/${this.userPoolId}`;
+    }
+    isMemberOf(groups = []) {
+        if (!Array.isArray(groups)) {
+            return false;
+        }
+        if (!this.requiredGroup) {
+            return true;
+        }
+        const requiredGroups = Array.isArray(this.requiredGroup)
+            ? this.requiredGroup
+            : [this.requiredGroup];
+        return groups.some((g) => requiredGroups.includes(g));
+    }
+    async verifyToken(token) {
+        if (!token) {
+            throw new Error("Token não fornecido");
+        }
+        const jwks = getJwks(this.region, this.userPoolId);
+        const { payload } = await jwtVerify(token, jwks, {
+            issuer: this.issuer,
+            audience: this.audience,
+        });
+        if (this.requiredGroup) {
+            const userGroups = payload["cognito:groups"];
+            if (!userGroups || !Array.isArray(userGroups)) {
+                throw new Error("Usuário não pertence ao sistema");
+            }
+            const requiredGroups = Array.isArray(this.requiredGroup)
+                ? this.requiredGroup
+                : [this.requiredGroup];
+            // Verifica se o usuário tem pelo menos um dos grupos obrigatórios
+            const hasRequiredGroup = requiredGroups.some((group) => userGroups.includes(group));
+            if (!hasRequiredGroup) {
+                throw new Error(`Usuário deve ser membro de um dos seguintes sistemas: ${requiredGroups.join(", ")}`);
+            }
+        }
+        // Mapear o payload do Cognito para o formato do GatesUser
+        const user = {
+            user_id: payload.sub,
+            email: payload.email,
+            name: payload.name,
+            role: payload["custom:general_role"],
+            exp: payload.exp,
+            iat: payload.iat,
+        };
+        return user;
+    }
+}

package/dist/services/user-service.js

@@ -0,0 +1,97 @@
+export class UserService {
+    baseUrl;
+    system;
+    defaultHeaders;
+    constructor(baseUrl, system) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.system = system;
+        this.defaultHeaders = {
+            "Content-Type": "application/json",
+        };
+    }
+    endpoints = {
+        all: "/get-all-profiles-from-system",
+    };
+    /**
+     * Busca todos os usuários do Cognito através do backend
+     * @param idToken Token de autenticação (ID Token do Cognito)
+     * @param options Opções de paginação e filtro
+     * @returns Lista de usuários
+     */
+    async getAllUsers(idToken
+    // options: GetAllUsersOptions = {}
+    ) {
+        if (!idToken) {
+            throw new Error("ID Token is required");
+        }
+        try {
+            const queryParams = new URLSearchParams();
+            //   if (options.page) queryParams.append("page", options.page.toString());
+            //   if (options.limit) queryParams.append("limit", options.limit.toString());
+            //   if (options.filter) queryParams.append("filter", options.filter);
+            //   if (options.group) queryParams.append("group", options.group);
+            const url = `${this.baseUrl}/${this.endpoints.all}${queryParams.toString() ? `?${queryParams.toString()}` : ""}`;
+            const response = await fetch(url, {
+                method: "POST",
+                headers: {
+                    ...this.defaultHeaders,
+                    Authorization: `Bearer ${idToken}`,
+                },
+                body: JSON.stringify({
+                    system_name: this.system,
+                }),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const data = (await response.json());
+            // Adicionar total baseado no length se não vier da API
+            if (!data.total && data.profiles) {
+                data.total = data.profiles.length;
+            }
+            return data;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to fetch users: ${error.message}`);
+            }
+            throw new Error("Failed to fetch users: Unknown error");
+        }
+    }
+    /**
+     * Busca um usuário específico por ID
+     * @param idToken Token de autenticação
+     * @param userId ID do usuário
+     * @returns Dados do usuário
+     */
+    async getUserById(idToken, userId) {
+        if (!idToken) {
+            throw new Error("ID Token is required");
+        }
+        if (!userId) {
+            throw new Error("User ID is required");
+        }
+        try {
+            const response = await fetch(`${this.baseUrl}/users/${userId}`, {
+                method: "GET",
+                headers: {
+                    ...this.defaultHeaders,
+                    Authorization: `Bearer ${idToken}`,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const user = (await response.json());
+            return user;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to fetch user: ${error.message}`);
+            }
+            throw new Error("Failed to fetch user: Unknown error");
+        }
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@intelicity/gates-sdk",
+  "version": "0.1.0",
+  "description": "Simple SDK for authenticating users with AWS Cognito JWT tokens",
+  "type": "module",
+  "exports": "./dist/index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "typecheck": "tsc --noEmit",
+    "test:token": "tsx scripts/test-token.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "aws",
+    "cognito",
+    "jwt",
+    "authentication"
+  ],
+  "author": "Gabriel Godoy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/inteli-city/gates-sdk.git"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "jose": "^6.1.1"
+  }
+}