AWS Helpers

AWS helper utilities and functions for common AWS operations including DynamoDB, Cognito, and SES.

Installation

npm install ditwaru-aws-helpers

Features

• DynamoDB: CRUD operations, table management, and query utilities
• Cognito: User management, authentication, and OAuth flows
• SES: Email sending and template management

Cognito OAuth Usage

Basic OAuth Flow

import { 
  getCognitoOAuthUrl, 
  exchangeCodeForTokens,
  refreshTokens,
  revokeToken,
  decodeJWT,
  getUserInfoFromToken 
} from 'ditwaru-aws-helpers';

// 1. Generate OAuth URL for user to visit
const oauthUrl = getCognitoOAuthUrl(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  'http://localhost:3000/auth/callback',
  'openid email profile'
);

// 2. After user authenticates, exchange the code for tokens
const tokens = await exchangeCodeForTokens(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  'authorization-code-from-callback',
  'http://localhost:3000/auth/callback'
  // clientSecret is optional - defaults to empty string for public clients
);

// 3. Use the tokens
const accessToken = tokens.access_token;
const idToken = tokens.id_token;
const refreshToken = tokens.refresh_token;

// 4. Decode and use the ID token
const userInfo = getUserInfoFromToken(idToken);
console.log('User email:', userInfo.email);
console.log('User name:', userInfo.name);

// 5. Refresh tokens when they expire
const newTokens = await refreshTokens(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  refreshToken
);

// 6. Revoke tokens when user signs out
await revokeToken(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  accessToken
);

Identity Provider Specific URLs

import { 
  getGoogleOAuthUrl, 
  getFacebookOAuthUrl, 
  getAppleOAuthUrl 
} from 'ditwaru-aws-helpers';

// Google OAuth
const googleUrl = getGoogleOAuthUrl(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  'http://localhost:3000/auth/callback'
);

// Facebook OAuth
const facebookUrl = getFacebookOAuthUrl(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  'http://localhost:3000/auth/callback'
);

// Apple OAuth
const appleUrl = getAppleOAuthUrl(
  'https://your-domain.auth.region.amazoncognito.com',
  'your-client-id',
  'http://localhost:3000/auth/callback'
);

Token Utilities

import { decodeJWT, isTokenExpired } from 'ditwaru-aws-helpers';

// Check if token is expired
if (isTokenExpired(accessToken)) {
  // Token is expired, need to refresh
  const newTokens = await refreshTokens(/* ... */);
}

// Decode JWT manually
const decoded = decodeJWT(idToken);
console.log('Token expires at:', new Date(decoded.exp * 1000));

DynamoDB Usage

import { 
  get, 
  put, 
  update, 
  delete: deleteItem,
  listApplications 
} from 'ditwaru-aws-helpers';

// Get a page
const page = await get('table-name', 'page-id');

// Put a page
await put('table-name', 'page-id', { content: 'Hello World' });

// Update a page
await update('table-name', 'page-id', { content: 'Updated content' });

// Delete a page
await deleteItem('table-name', 'page-id');

// List all applications (tables)
const apps = await listApplications();

SES Usage

import { sendEmail } from 'ditwaru-aws-helpers';

await sendEmail({
  to: '[email protected]',
  subject: 'Hello',
  text: 'Hello world',
  html: '<h1>Hello world</h1>'
});

Configuration

Set these environment variables:

AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=us-east-1

Important Notes

OAuth Configuration

• Cognito Domain: Use the actual domain from your Cognito User Pool, not the User Pool ID
• Client Secret: For public clients, the functions automatically include an empty client_secret
• Redirect URI: Must match exactly what's configured in your Cognito App Client

Security

• Always validate tokens on the server side
• Store refresh tokens securely
• Use HTTPS in production
• Implement proper CSRF protection with state parameters

Changelog

v1.1.1

• FIXED: OAuth implementation completely rewritten
• ADDED: Proper token exchange with client_secret handling
• ADDED: Token refresh and revocation functions
• ADDED: JWT decoding utilities
• ADDED: Identity provider specific OAuth URLs
• REMOVED: Broken initiateOAuthAuth function
• IMPROVED: Better error handling and TypeScript types

v1.0.2

• Initial release with basic DynamoDB and Cognito functions