ze-preguica-services

A collection of utility services and helpers for the Ze-Preguica platform, designed to be easily imported and used across different projects.

📋 Description

This package provides essential utility services including AWS Secrets Manager integration and JWT authentication helpers. It's built with TypeScript and optimized for AWS Lambda environments.

✨ Available Services

🔐 AWS Secrets Manager

• Secure secret retrieval with built-in caching
• TypeScript support with full type definitions
• Error handling for missing or invalid secrets

🔑 JWT Authentication

• Token verification for API Gateway requests
• Request authentication helpers
• AWS Lambda integration ready

🚀 Installation

npm install ze-preguica-services

📦 Dependencies

Production

• aws-sdk: ^2.1692.0 - AWS SDK for cloud services
• jsonwebtoken: ^9.0.2 - JWT token handling
• aws-lambda: ^1.0.7 - AWS Lambda types

Development

• typescript: ^5.8.3 - TypeScript compiler
• @types/node: ^24.0.10 - Node.js type definitions
• @types/jsonwebtoken: ^9.0.10 - JWT type definitions
• @types/aws-lambda: ^8.10.150 - Lambda type definitions

💻 Usage

AWS Secrets Manager

import { getSecretValue } from 'ze-preguica-services';

// Retrieve a secret from AWS Secrets Manager
async function getApiKey() {
  try {
    const apiKey = await getSecretValue({
      secretId: 'my-api-key',
      region: 'us-east-1'
    });
    
    console.log('Secret retrieved:', apiKey);
    return apiKey;
  } catch (error) {
    console.error('Error retrieving secret:', error);
    throw error;
  }
}

JWT Authentication

import { authenticateRequest, verifyJwt } from 'ze-preguica-services';
import { APIGatewayProxyEvent } from 'aws-lambda';

// Authenticate API Gateway request
export async function handler(event: APIGatewayProxyEvent) {
  const jwtSecret = process.env.JWT_SECRET || 'your-secret-key';
  
  const authResult = authenticateRequest(event, jwtSecret);
  
  if (authResult.statusCode) {
    // Authentication failed
    return authResult;
  }
  
  // Authentication successful
  const { token, payload } = authResult;
  console.log('Authenticated user:', payload);
  
  // Your business logic here
  return {
    statusCode: 200,
    body: JSON.stringify({ message: 'Authenticated successfully' })
  };
}

// Verify JWT token directly
function verifyToken(token: string) {
  const secret = process.env.JWT_SECRET || 'your-secret-key';
  const decoded = verifyJwt(token, secret);
  
  if (typeof decoded === 'object' && decoded.statusCode) {
    // Token verification failed
    return null;
  }
  
  return decoded;
}

🔧 Configuration

AWS Secrets Manager

Make sure your AWS credentials are properly configured:

# AWS CLI
aws configure

# Or environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

JWT Authentication

Set your JWT secret in environment variables:

export JWT_SECRET=your-super-secret-jwt-key

📁 Project Structure

src/
├── index.ts              # Main exports
├── getSecretOptions/     # AWS Secrets Manager utilities
│   └── index.ts         # getSecretValue function
├── auth-jwt/            # JWT authentication utilities
│   └── index.ts         # Authentication functions
└── types/               # TypeScript type definitions
    └── types.ts         # Shared types

🏗️ Development

Build

npm run build

Publishing

npm publish

The package automatically builds before publishing thanks to the prepublishOnly script.

📝 API Reference

getSecretValue(options: GetSecretOptions): Promise

Retrieves a secret from AWS Secrets Manager with caching.

Parameters:

• options.secretId (string): The name or ARN of the secret
• options.region (string): The AWS region

Returns: Promise - The secret value

authenticateRequest(event: APIGatewayProxyEvent, secret: string)

Authenticates an API Gateway request using JWT.

Parameters:

• event (APIGatewayProxyEvent): The API Gateway event
• secret (string): The JWT secret key

Returns:

• Success: { token: string, payload: any }
• Failure: { statusCode: 401, body: string }

verifyJwt(token: string, secret: string)

Verifies a JWT token.

Parameters:

• token (string): The JWT token to verify
• secret (string): The JWT secret key

Returns:

• Success: The decoded token payload
• Failure: { statusCode: 401, body: string }

🔒 Security Features

• In-memory caching for AWS Secrets Manager (performance optimization)
• JWT token validation with proper error handling
• Authorization header parsing for Bearer tokens
• Type-safe operations with TypeScript

⚠️ Important Notes

• Cache behavior: Secrets are cached in memory and persist for the lifetime of the process
• JWT format: Expects Bearer tokens in the format Bearer <token>
• AWS permissions: Requires secretsmanager:GetSecretValue permission
• Environment: Optimized for AWS Lambda but works in any Node.js environment

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-utility)
3. Add your utility service
4. Update the main index.ts to export your new service
5. Add tests and documentation
6. Submit a pull request

📝 License

MIT - see LICENSE file for details.

👨‍💻 Author

Matheus Mangueira

Built with ❤️ for the Ze-Preguica platform