Setup Guide

Prerequisites

• AWS CLI configured with zooly profile
• .env.local file with AWS credentials:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION

AWS Resources Setup

AWS resources (Cognito User Pool, App Client, and DynamoDB table) are created using the setup script.

Running the Setup Script

set -a && source .env.local && ./scripts/setup-aws-auth.sh

The script:

• Uses AWS profile zooly for all CLI commands
• Checks for existing resources (idempotent)
• Creates Cognito User Pool, App Client, and DynamoDB table if they don't exist
• Outputs environment variables to add to .env.local

Environment Variables

After running the setup script, add these to your .env.local:

# Cognito
COGNITO_USER_POOL_ID=us-east-1_tvlpQoJAn
COGNITO_CLIENT_ID=2i28c7h1cpm6od29o7vatlncv9
COGNITO_REGION=us-east-1

# DynamoDB
DYNAMODB_IDENTITIES_TABLE=zooly-auth-identities
DYNAMODB_REGION=us-east-1

Cognito User Pool Configuration

Current Setup

• User Pool ID: us-east-1_tvlpQoJAn
• Pool Name: zooly-auth-pool
• Region: us-east-1

Configuration Details

• Username Attribute: Email
• Email Verification: Via code
• Password Policy:
  • Minimum 8 characters
  • Requires uppercase, lowercase, and numbers
• Self-Sign-Up: Enabled
• Account Recovery: Via verified email

App Client Configuration

• Client ID: 2i28c7h1cpm6od29o7vatlncv9
• Client Name: zooly-auth-client
• Auth Flows:
  • ALLOW_USER_PASSWORD_AUTH
  • ALLOW_REFRESH_TOKEN_AUTH
• Client Type: Public client (no secret)
• Token Settings:
  • Refresh token validity: 90 days
  • ID/Access token validity: 60 minutes

Important Notes

• Single app client for all environments (prod and dev)
• Auth is centralized at auth.zooly.ai
• Prod and dev use the same login flow
• Same roles, claims, and security rules apply everywhere
• All apps redirect to auth.zooly.ai and use returnTo

Trade-off accepted:

• Same token audience for prod & dev
• Same session settings for both
• Environment separation happens in API domains (api.zooly.ai vs api.dev.zooly.ai) and data/infrastructure, not auth

Identity Providers

Currently Configured:

• Cognito native user/password

Planned (Phase 2):

• Google
• Apple

DynamoDB Table Configuration

Table Details

• Table Name: zooly-auth-identities
• Primary Key: user_id (string)
  • Cognito sub for linked users
  • Generated UUID for email-only users
• Billing Mode: Pay-per-request (on-demand)
• Region: us-east-1

Table Schema

Primary Key:

• user_id (string) - Primary key

Attributes:

• guest_email (string) - Email for guest checkout users before linking
• display_name (string) - User's display name
• avatar_url (string) - User's avatar URL
• roles (string[]) - Array of role strings
• cognito_sub (string, nullable) - Cognito user ID for linked users
• created_at (number) - Unix timestamp
• updated_at (number) - Unix timestamp

Important Notes

• Email is NOT stored in DynamoDB
• For Cognito-linked users, email comes from Cognito ID token (source of truth)
• Only guest_email is stored for guest checkout users before linking
• Currently uses Scan for findIdentityByEmail. Consider adding GSI on guest_email for better performance at scale.

Access Patterns

• GetItem on every /api/me request (by user_id)
• PutItem / UpdateItem on profile change
• Scan for findIdentityByEmail (consider GSI optimization)

Verification

After setup, verify the resources:

Check Cognito User Pool

aws cognito-idp describe-user-pool \
  --user-pool-id us-east-1_tvlpQoJAn \
  --profile zooly

Check Cognito App Client

aws cognito-idp describe-user-pool-client \
  --user-pool-id us-east-1_tvlpQoJAn \
  --client-id 2i28c7h1cpm6od29o7vatlncv9 \
  --profile zooly

Check DynamoDB Table

aws dynamodb describe-table \
  --table-name zooly-auth-identities \
  --profile zooly

Next Steps

After setup is complete:

1. Configure environment variables in your apps
2. Test authentication flow locally
3. Set up production domains
4. Configure social login providers (Phase 2)