Friend Verify Frame

✨ Try it live: https://friend-verify.vercel.app

A Farcaster Mini App that enables secure, cryptographically-verified friendship confirmations between users. Built with Next.js, Neynar API, and Upstash Redis.

Security Features

• Cryptographic Signature Verification: All frame interactions are validated using Farcaster's native signature mechanism via Neynar API
• Identity Authentication: Real FID (Farcaster ID) extraction and username validation
• Authorization Controls: Only intended users can verify their friendship
• Collision-Safe Storage: Redis keys use sorted FIDs to prevent duplicate records
• Rate Limiting: Built-in protection against abuse with 5 requests per 10 seconds per IP
• Error Handling: Robust protection against invalid payloads, forgery attempts, and edge cases

Architecture

Framework Choice: Next.js App Router

• Why Next.js: Better integration with Vercel, built-in API routes, superior TypeScript support, and seamless deployment
• App Router: Modern React patterns with server components and improved performance
• API Routes: Serverless functions with automatic scaling

Project Structure

├── app/
│   ├── api/frame/route.ts      # Main Frame API endpoint
│   ├── layout.tsx              # Root layout with metadata
│   ├── page.tsx                # Main page component
│   └── globals.css             # Global styles
├── components/
│   ├── FrameWrapper.tsx        # Frame preview component
│   └── Generator.tsx           # URL generation interface
├── lib/
│   ├── types.ts                # TypeScript definitions
│   ├── neynar.ts               # Neynar API client
│   ├── redis.ts                # Upstash Redis client
│   ├── username-resolver.ts    # Username to FID resolution
│   └── errors.ts               # Error handling utilities
└── Configuration files...

Quick Start

Prerequisites

• Node.js 18+
• Neynar API account (free tier available)
• Upstash Redis database (free tier available)

1. Clone and Install

git clone https://github.com/logiccrafterdz/friend-verify-frame.git
cd friend-verify-frame
npm install

2. Environment Setup

Copy the example environment file:

cp .env.example .env.local

3. Get Required API Keys

Neynar API Key:

1. Visit neynar.com
2. Sign up for a free account
3. Navigate to API Keys section
4. Generate a new API key

Upstash Redis:

1. Visit upstash.com
2. Create a free account
3. Create a new Redis database
4. Copy the REST URL and Token from database details

4. Configure Environment Variables

Edit .env.local with your actual values:

NEYNAR_API_KEY=your_actual_neynar_api_key
UPSTASH_REDIS_REST_URL=https://your-actual-redis.upstash.io
UPSTASH_REDIS_REST_TOKEN=your_actual_redis_token

⚠️ Warning: Never commit .env.local to Git. It contains sensitive credentials.

5. Run Development Server

npm run dev

Visit http://localhost:3000 to see the application.

6. Test the Build

npm run build

Deployment to Vercel

Prerequisites

• GitHub repository with your code
• Vercel account (free tier available)
• Environment variables ready (from setup above)

Steps

1. Connect Repository

   • Push your code to GitHub
   • Visit vercel.com and sign in
   • Click "New Project" and import your repository

2. Configure Environment Variables

   • In Vercel dashboard, go to Project Settings → Environment Variables
   • Add the following variables:

     NEYNAR_API_KEY=your_actual_neynar_api_key
     UPSTASH_REDIS_REST_URL=https://your-actual-redis.upstash.io
     UPSTASH_REDIS_REST_TOKEN=your_actual_redis_token
     

3. Deploy

   • Click "Deploy" - Vercel will automatically build and deploy
   • Your app will be available at https://your-project.vercel.app

4. Automatic Deployments

   • Future pushes to main branch will auto-deploy
   • Preview deployments created for pull requests

Testing

Test Case 1: Valid Mutual Confirmation

Objective: Verify successful friendship confirmation between two real Farcaster accounts

Steps:

1. Generate frame URL with both usernames
2. Share frame URL in Farcaster (Warpcast recommended)
3. Have one user click "Yes, we're friends!" button
4. Verify success message appears
5. Attempt to click again - should show "Already Verified"

Expected Results:

• ✅ First click: "Friendship Verified!" message
• ℹ️ Second click: "Already Verified!" message
• 🔒 Friendship record stored in Redis

Test Case 2: Forgery Attempt Prevention

Objective: Ensure unauthorized users cannot verify friendships

Steps:

1. Generate frame URL for userA and userB
2. Have userC (different account) attempt to click the button
3. Verify rejection message

Expected Results:

• ❌ "Unauthorized - Only userA or userB can verify this friendship"
• 🚫 No friendship record created

Test Case 3: Invalid Username Handling

Objective: Test behavior with non-existent Farcaster usernames

Steps:

1. Generate frame URL with invalid username
2. Attempt to interact with frame

Expected Results:

• ❌ "User(s) not found: nonexistentuser123"
• 🔍 Username resolution fails gracefully

Test Case 4: Malformed Request Handling

Objective: Verify API robustness against invalid payloads

Steps:

1. Send POST request to /api/frame with invalid JSON
2. Send request with missing required fields
3. Send request with invalid content-type

Expected Results:

• ❌ Appropriate error frames for each scenario
• 🛡️ No server crashes or security vulnerabilities
• 📊 Proper HTTP status codes (400, 401, 405, 500)

API Reference

POST /api/frame

Handles Farcaster Frame Action payloads for friendship verification.

Request Body: Farcaster Frame Action Payload

{
  untrustedData: {
    fid: number,
    url: string,
    messageHash: string,
    timestamp: number,
    network: number,
    buttonIndex: number
  },
  trustedData: {
    messageBytes: string
  }
}

Response: Frame Response

{
  image: string,      // URL to frame image
  buttons: string[]   // Array of button labels (empty for final states)
}

Error Handling:

• 400: Invalid request format or missing parameters
• 401: Invalid cryptographic signature
• 403: Unauthorized user attempting verification
• 405: Invalid HTTP method
• 429: Rate limit exceeded
• 500: Internal server error

Security Best Practices

Cryptographic Verification

• Never trust client data: All user identity claims are verified via Neynar's signature validation
• Farcaster-native signatures: Uses Frame Action signatures, not wallet signatures
• Real-time validation: Every interaction is cryptographically verified before processing

Data Privacy

• Minimal data collection: Only stores FIDs, usernames, and timestamps
• No PII storage: No personal information beyond public Farcaster data
• Collision-safe keys: Consistent friendship keys prevent duplicate records

Error Security

• No information leakage: Error messages don't expose internal system details
• Graceful degradation: Invalid requests return user-friendly error frames
• Rate limiting: Protection against abuse and spam

Global Considerations

• English-only interface: Aligned with Farcaster ecosystem standards
• No geographic restrictions: Works globally where Farcaster is accessible
• Timezone-agnostic: All timestamps stored in ISO 8601 UTC format
• Unicode support: Handles international usernames correctly

Production Checklist

• Environment variables configured
• Neynar API key valid and active
• Upstash Redis database accessible
• All test cases passing
• Error handling implemented
• Security measures active
• Documentation complete
• Deployment successful

Monitoring & Maintenance

Key Metrics to Monitor

• API response times
• Neynar API rate limits
• Redis connection health
• Error rates by type
• Successful verification count

Regular Maintenance

• Monitor Neynar API usage (free tier limits)
• Check Upstash Redis storage usage
• Review error logs for patterns
• Update dependencies for security patches

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure all contributions maintain the security-first approach and error handling standards.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Farcaster for the decentralized social protocol
• Neynar for the robust API infrastructure
• Upstash for serverless Redis hosting
• Vercel for seamless deployment platform

📬 Connect with the Developer

Developer: LogicCrafterDZ
Email: logiccrafterdz@gmail.com
Twitter: @Arana_lib
Telegram: https://t.me/LogicCrafterDZ