Warp Memory

A hybrid conversation memory management system using PocketBase as the backend database with JWT authentication and comprehensive access controls.

Features

• 🔐 JWT Authentication: Secure token-based authentication with middleware validation
• 👥 User Isolation: Complete data separation between users - users can only access their own conversations
• 💬 Conversation Management: Create, read, update, and delete conversations with messages
• 🗃️ PocketBase Backend: Self-contained database with built-in access rules
• 🧪 Comprehensive Testing: Full test suite for authentication and access control
• 🚀 Express API: RESTful API endpoints for all operations

Architecture

Hybrid Approach

This project combines:

• PocketBase: Handles data storage, built-in access rules, and user management
• Express.js: Custom API layer with JWT middleware for additional security
• JWT Tokens: Stateless authentication that works with existing applications

Security Features

• JWT token validation on every request
• PocketBase access rules preventing cross-user data access
• Server-side middleware validation
• Comprehensive test coverage for security scenarios

Quick Start

Prerequisites

• Node.js (v16+)
• npm or yarn

Installation

1. Clone and install dependencies:

   git clone <your-repo-url>
   cd warp-memory
   npm install
   

2. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

3. Start PocketBase:

   npm run pocketbase
   

   • This starts PocketBase on http://localhost:8090
   • First time: Create an admin account at http://localhost:8090/_/

4. Start the API server:

   npm run dev
   

   • API runs on http://localhost:3000
   • Health check: http://localhost:3000/health

API Endpoints

Authentication

All endpoints require a valid JWT token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Conversations

Method	Endpoint	Description
POST	/api/warp-memory/conversations	Create a new conversation
GET	/api/warp-memory/conversations	Get all user's conversations
GET	/api/warp-memory/conversations/:id	Get specific conversation with messages
POST	/api/warp-memory/conversations/:id/messages	Add message to conversation
PATCH	/api/warp-memory/conversations/:id	Update conversation title
DELETE	/api/warp-memory/conversations/:id	Delete conversation

Example Usage

Create a conversation:

curl -X POST http://localhost:3000/api/warp-memory/conversations \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "My First Conversation"}'

Add a message:

curl -X POST http://localhost:3000/api/warp-memory/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role": "user", "content": "Hello, world!"}'

Testing

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

Test Coverage

The test suite covers:

• JWT token validation (valid, invalid, expired, missing)
• User authentication and PocketBase integration
• Cross-user access prevention
• Error handling scenarios
• All API endpoints with authentication

Environment Variables

# PocketBase Configuration
POCKETBASE_URL=http://localhost:8090
POCKETBASE_ADMIN_EMAIL=admin@example.com
POCKETBASE_ADMIN_PASSWORD=admin123

# JWT Configuration  
JWT_SECRET=your-jwt-secret-key-here

# Server Configuration
PORT=3000
NODE_ENV=development

# API Configuration
API_BASE_URL=http://localhost:3000

Data Models

User

• id: Unique identifier
• email: User email (authentication)
• name: Optional display name

Conversation

• id: Unique identifier
• title: Conversation title
• userId: Reference to owning user
• messages: Array of message objects
• created: Creation timestamp
• updated: Last update timestamp

Message

• role: "user" or "assistant"
• content: Message text content
• timestamp: When message was added

Access Control

PocketBase Rules

• Users: Can only read/update their own profile
• Conversations: Complete isolation - users can only access their own conversations
• Authentication: Required for all operations

API Middleware

• JWT validation on every request
• User existence verification
• Token expiration checking
• Comprehensive error handling

Development

Project Structure

warp-memory/
├── src/
│   ├── middleware/     # Authentication middleware
│   ├── routes/         # API route handlers
│   ├── services/       # PocketBase integration
│   └── server.js       # Express server setup
├── tests/              # Test suite
├── pb/                 # PocketBase binary and data
│   ├── pocketbase      # PocketBase executable
│   ├── pb_data/        # Database files (included in git)
│   └── pb_migrations/  # Database migrations
└── package.json

Available Scripts

• npm run dev: Start development server
• npm run start: Start production server
• npm test: Run test suite
• npm run test:watch: Run tests in watch mode
• npm run pocketbase: Start PocketBase server

Integration with Existing Apps

To integrate with an existing application that already uses JWT tokens:

1. Use the same JWT secret in your .env file
2. Make API calls with existing user tokens:

   const response = await fetch('/api/warp-memory/conversations', {
     headers: {
       'Authorization': `Bearer ${existingJwtToken}`,
       'Content-Type': 'application/json'
     }
   })
   

3. User isolation is automatic - each user only sees their own data

Production Deployment

1. Set environment variables in production
2. Build and start:

   npm run build
   npm start
   

3. PocketBase data is included in the repository for easy deployment
4. Consider setting up backups for the pb/pb_data/ directory

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details