Speakeasy Services

A collection of microservices for the Speakeasy platform enabling Bluesky users to share posts with trusted followers only, built with post-quantum encryption and user convenience in mind.

Quickstart

You will need Docker installed

# First time
pnpm install
pnpm build
pnpm dev:setup

# Launch dev environment
pnpm dev

# Or to launch just one service
pnpm dev:private-sessions

To add an invite code in prod:

SSH into spkeasy_services_prod

docker exec -it <container-id> npm run invite:add -- <code> <key> [value] [totalUses]

If you've borked your database pnpm dev:setup will wipe and reinitialise it

Database ER Diagrams

Project Structure

/
├── packages/                      # Shared packages/libraries
│   ├── common/                   # Shared code, types, and utilities
│   │   ├── src/
│   │   │   ├── types/           # Shared TypeScript interfaces
│   │   │   ├── constants/       # Shared constants
│   │   │   └── utils/           # Shared utility functions
│   └── crypto/                  # Shared cryptographic operations
│       ├── src/
│       │   ├── kyber/          # CRYSTALS-Kyber implementation
│       │   ├── aes/            # AES-256-GCM operations
│       │   └── dilithium/      # CRYSTALS-Dilithium signatures
├── services/                     # Individual microservices
│   ├── user-profiles/          # User profile and preferences management
│   ├── user-keys/              # User encryption key management
│   ├── trusted-users/          # Trust relationship management
│   ├── private-sessions/       # Encryption session and private post management
│   ├── group-sessions/         # (Future)
│   └── group-members/          # (Future)
├── docker/                      # Docker configuration
│   ├── development/
│   └── production/
├── scripts/                     # Build and deployment scripts
├── tests/                       # Integration tests
├── .github/                     # GitHub Actions workflows
├── package.json                 # Root package.json for workspace
├── tsconfig.json               # Base TypeScript configuration
└── docker-compose.yml          # Local development setup

Architecture Overview

A set of microservices handling:

• User profiles and preferences (user-profiles)
• User encryption keys (user-keys)
• Trust relationships (trusted-users)
• Encryption sessions and private posts (private-sessions)

Technical Stack

• TypeScript
• XRPC (@atproto/xrpc-server)
• PostgreSQL with Prisma ORM
• Authentication using AT Protocol JWT tokens
• Post-quantum encryption (CRYSTALS-Kyber)
• Symmetric encryption (AES-256-GCM)

Key Features

• Completely out-of-band from Bluesky PDS
• No modifications to user's Bluesky data
• Staff access for moderation
• Multi-device support
• Key rotation and revocation
• Forward secrecy through session management

Architecture

The services are built as a collection of microservices that share a common development environment. Each service has its own:

• Database schema
• API endpoints
• Job processing (via PgBoss)
• Prisma models and migrations

Services

1. User Profiles Service

   • Manages user keys and profiles
   • Schema: user_profiles
   • Port: 3001

2. Private Sessions Service

   • Handles private session creation and management
   • Schema: private_sessions
   • Port: 3002
   • Processes session-related jobs

3. Trusted Users Service

   • Manages trusted user relationships
   • Schema: trusted_users
   • Port: 3003
   • Schedules session recipient additions

Shared Infrastructure

• PostgreSQL Database

  • Single database instance
  • Separate schemas for each service
  • Shared PgBoss schema for job processing
  • Environment-based database names:
    • Development: speakeasy database
    • Test: speakeasy_test database
    • Production: Uses production database URLs
  • Default credentials:
    • User: speakeasy
    • Password: speakeasy
    • Database: speakeasy (development) or speakeasy_test (test)

• PgBoss

  • Centralized job processing
  • Single schema (pgboss)
  • Job names partition processing by service
  • Web UI available at http://localhost:8080

Development Environment Setup

Prerequisites

• Node.js (v18 or later)
• Docker and Docker Compose
• pnpm

Initial Setup

1. Install dependencies:

   pnpm install

2. Start the development environment:

   pnpm dev:setup

   This will:

   • Create a .env file from .env.example if it doesn't exist
   • Replace placeholder Stripe API secret key (Test environment!) in .env if relevant to your work
   • Start all services in Docker
   • Run database migrations
   • Build and start the services

Environment Support

The application supports multiple environments:

• Development (default): Uses speakeasy database
• Test: Uses speakeasy_test database

Development Environment

# Default development setup
pnpm dev:setup

# Or explicitly set environment
NODE_ENV=development pnpm dev:setup

Test Environment

# Test environment setup
pnpm test:setup

# Or explicitly set environment
NODE_ENV=test pnpm dev:setup

The environment is determined by the NODE_ENV environment variable:

• NODE_ENV=development (or unset) → uses speakeasy database
• NODE_ENV=test → uses speakeasy_test database (or modifies existing environment variables to use test database)
• NODE_ENV=production → requires explicit service-specific environment variables (e.g., PRIVATE_SESSIONS_DATABASE_URL, TRUSTED_USERS_DATABASE_URL, etc.)

Common Issues

Database Migrations

If you see errors about database migrations:

• Check that your .env file has the correct database URLs
• Each service has its own database URL (e.g. PRIVATE_SESSIONS_DATABASE_URL, TRUSTED_USERS_DATABASE_URL)
• The main DATABASE_URL is used for migrations
• Database URLs are automatically derived based on NODE_ENV:
  • Development: postgresql://speakeasy:speakeasy@localhost:5496/speakeasy?schema=<service_schema>
  • Test: postgresql://speakeasy:speakeasy@localhost:5496/speakeasy_test?schema=<service_schema> (or modifies existing environment variables to use test database)
  • Production: Requires explicit service-specific environment variables (e.g., PRIVATE_SESSIONS_DATABASE_URL, TRUSTED_USERS_DATABASE_URL, etc.)

TypeScript Build Errors

If you see TypeScript errors:

• Make sure all dependencies are installed
• Check that the common package is built
• Run pnpm build in the common package if needed

Service Dependencies

Services depend on each other in this order:

1. user-keys - Provides key management
2. trusted-users - Manages trust relationships
3. private-sessions - Handles private sessions
4. private-posts - Manages private posts

If a service fails to start, check its dependencies are running first.

Development Workflow

1. Make changes to the code
2. Run pnpm build to rebuild affected packages
3. Restart services as needed with pnpm dev

Testing

Run tests with:

pnpm test

Contributing

1. Create a new branch for your feature
2. Make your changes
3. Run tests and ensure everything builds
4. Submit a pull request

License

[License details here]

See REFERENCE.md for detailed technical documentation.