Backend Setup

Prerequisites

Bun runtime (v1.0+)
SQLite database
OAuth client credentials from providers (optional for testing)

Installation

Clone the repository and install dependencies:

git clone <repository-url>
cd proof-of-spend
bun install

Database Setup

Initialize the SQLite database with Drizzle ORM:

# Generate migrations
bun run drizzle-kit generate

# Run migrations
bun run drizzle-kit migrate

Environment Configuration

Create a .env file in the project root:

# Server Configuration
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL=./data/proof-of-spend.db

# JWT Secrets
JWT_ACCESS_SECRET=your-secret-key-here
JWT_REFRESH_SECRET=your-refresh-secret-here

# OAuth Provider Credentials (optional for testing)
OPENAI_CLIENT_ID=your-openai-client-id
OPENAI_CLIENT_SECRET=your-openai-client-secret

ANTHROPIC_CLIENT_ID=your-anthropic-client-id
ANTHROPIC_CLIENT_SECRET=your-anthropic-client-secret

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

Register OAuth Clients

curl -X POST http://localhost:3000/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Annotation App",
    "redirectUris": ["http://localhost:3001/callback"],
    "grantTypes": ["authorization_code", "refresh_token"]
  }'

Save the client_id and client_secret from the response.

Start the Server

bun run dev

The OAuth server will be available at http://localhost:3000.

OAuth Endpoints

GET /oauth/authorize - Authorization endpoint
POST /oauth/token - Token endpoint
POST /oauth/token/verify - Token introspection
POST /oauth/token/revoke - Token revocation
POST /oauth/register - Client registration
GET /oauth/clients - List clients
PUT /oauth/clients/:id - Update client
DELETE /oauth/clients/:id - Delete client

Testing

Run the comprehensive test suite:

# Backend tests (OAuth flow and admin)
bun test tests/integration/oauth-flow.test.ts
bun test tests/integration/oauth-admin.test.ts

Security Considerations

Always use HTTPS in production
Rotate JWT secrets regularly
Implement rate limiting on auth endpoints
Store client secrets securely (use bcrypt hashing)
Enable CORS only for trusted origins
Set appropriate token expiration times