OGS API Server

A Cloudflare Workers implementation of the Open Game System (OGS) API specification

This repository contains the reference implementation of the OGS API server, built as a Cloudflare Workers application. It handles authentication, push notifications, and TV casting protocols as defined in the OGS Specification.

Table of Contents

• Overview
• Architecture
• Getting Started
• API Endpoints
• Development
• Deployment
• Testing
• Contributing

Overview

The OGS API Server implements the server-side components of the Open Game System, enabling web games to access native capabilities like push notifications and TV casting. This implementation uses Cloudflare Workers for global distribution, high reliability, and low latency.

Key Features

• Account Linking: Implements the Account Linking Protocol for connecting game accounts with OGS
• Web Auth Token: Provides single sign-on capabilities between OGS and games
• Push Notifications: Handles notification delivery to registered devices
• TV Casting: Manages cast sessions between games and Chromecast devices
• API Key Management: Secure generation and validation of game API keys
• Domain Verification: Automated verification of game domains

Architecture

graph TD
    subgraph "Cloudflare Workers"
        Router[Request Router]
        Auth[Auth Service]
        Notification[Notification Service]
        Cast[Cast Service]
        Verification[Verification Service]
    end
    
    subgraph "Cloudflare Storage"
        KV[KV Storage]
        D1[D1 Database]
        R2[R2 Storage]
    end
    
    subgraph "External Services"
        FCM[Firebase Cloud Messaging]
        APNS[Apple Push Notification Service]
    end
    
    Router --> Auth
    Router --> Notification
    Router --> Cast
    Router --> Verification
    
    Auth -.-> KV
    Auth -.-> D1
    
    Notification -.-> KV
    Notification -.-> D1
    Notification --> FCM
    Notification --> APNS
    
    Cast -.-> D1
    Cast -.-> R2
    
    Verification -.-> KV
    Verification -.-> D1

Loading

The API server is structured as a collection of modular services, each handling a specific aspect of the OGS specification:

• Request Router: Routes incoming requests to the appropriate service
• Auth Service: Handles account linking, web auth tokens, and token refresh
• Notification Service: Manages device registration and notification delivery
• Cast Service: Coordinates casting sessions between games and devices
• Verification Service: Manages domain verification and API key generation

Data storage leverages Cloudflare's built-in storage solutions:

• KV: For high-performance key-value storage of tokens and session data
• D1: For relational data like user accounts and game registrations
• R2: For storing larger objects like game assets for casting

Getting Started

Prerequisites

• Node.js (v18 or later)
• Wrangler (Cloudflare Workers CLI)
• Cloudflare account with Workers, KV, D1, and R2 access

Installation

1. Clone the repository:

   git clone https://github.com/open-game-collective/opengame-api.git
   cd opengame-api

2. Install dependencies:

   npm install

3. Copy the example environment variables:

   cp .env.example .env

4. Update the environment variables with your Cloudflare account information and service credentials.

5. Initialize Wrangler configuration:

   wrangler login

API Endpoints

The API server implements all endpoints defined in the OGS Specification. Here's a summary of the key endpoints:

Authentication Endpoints

• POST /api/v1/auth/account-link-token: Generate account link token
• POST /api/v1/auth/verify-link-token: Verify account link token
• POST /api/v1/auth/web-code: Generate web auth code
• POST /api/v1/auth/verify-token: Verify web auth token
• POST /api/v1/auth/refresh: Refresh session token

Notification Endpoints

• POST /api/v1/notifications/send: Send notification to user
• GET /api/v1/notifications/status/:id: Get notification status
• POST /api/v1/notifications/register: Register device for notifications
• POST /api/v1/notifications/unregister: Unregister device

Cast Endpoints

• POST /api/v1/cast/session: Create cast session
• GET /api/v1/cast/session/:id: Get session status
• POST /api/v1/cast/input: Send input to cast session
• DELETE /api/v1/cast/session/:id: End cast session

Verification Endpoints

• GET /api/v1/verify: Verify game domain
• POST /api/v1/keys/generate: Generate API key for verified domain

Development

Local Development

Start the development server:

npm run dev

This runs the API server using Wrangler's local development environment. The server will be accessible at http://localhost:8787.

Project Structure

opengame-api/
├── src/
│   ├── index.ts              # Entry point
│   ├── router.ts             # Request router
│   ├── middleware/           # Shared middleware
│   │   ├── auth.ts           # Auth middleware
│   │   ├── cors.ts           # CORS handling
│   │   └── ...
│   ├── services/             # Core service modules
│   │   ├── auth/             # Auth service
│   │   ├── notification/     # Notification service
│   │   ├── cast/             # Cast service
│   │   └── verification/     # Verification service
│   ├── models/               # Data models and schemas
│   ├── utils/                # Utility functions
│   └── types/                # TypeScript type definitions
├── test/                     # Unit and integration tests
├── wrangler.toml             # Wrangler configuration
├── package.json
└── README.md

Database Setup

Initialize the D1 database:

wrangler d1 create opengame-db

Update your wrangler.toml with the database binding:

[[d1_databases]]
binding = "DB"
database_name = "opengame-db"
database_id = "your-database-id"

Create KV namespaces:

wrangler kv:namespace create "TOKENS"
wrangler kv:namespace create "SESSIONS"

Update your wrangler.toml with the KV bindings:

[[kv_namespaces]]
binding = "TOKENS"
id = "your-tokens-namespace-id"

[[kv_namespaces]]
binding = "SESSIONS"
id = "your-sessions-namespace-id"

Deployment

Deploy to Cloudflare Workers

Deploy to production:

npm run deploy

This script compiles the TypeScript code, bundles the application, and deploys it to Cloudflare Workers.

Environment Variables

The following environment variables must be configured in your Cloudflare Workers environment:

• JWT_SECRET: Secret key for signing JWTs
• CORS_ORIGINS: Allowed origins for CORS
• FIREBASE_CREDENTIALS: Firebase credentials for push notifications
• APPLE_CERTS: Apple certificates for iOS push notifications

Testing

Running Tests

Run the test suite:

npm test

This executes Jest tests for the entire application, including unit and integration tests.

Test Coverage

Generate test coverage report:

npm run test:coverage

Security Considerations

The OGS API Server implements several security measures:

• JWT Authentication: Secure token-based authentication for all protected endpoints
• API Key Validation: Rigorous validation of game API keys
• CORS Protection: Strict CORS policy to prevent unauthorized access
• Rate Limiting: Protection against abuse and DDoS attacks
• Input Validation: Thorough validation of all incoming requests
• Secret Management: Secure storage of sensitive credentials

Monitoring and Logging

The API server includes comprehensive logging and monitoring:

• Structured Logging: JSON-formatted logs for easy parsing
• Error Tracking: Detailed error reporting with stack traces
• Performance Metrics: Response time and throughput monitoring
• Usage Analytics: Tracking of API usage patterns

CI/CD Pipeline

The repository includes GitHub Actions workflows for continuous integration and deployment:

• CI Workflow: Runs tests and checks code quality on pull requests
• CD Workflow: Automatically deploys changes to staging/production environments

Contributing

Contributions are welcome! Please check out our contributing guidelines for details on how to submit changes.

Development Workflow

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

License

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

Contact

• Website: opengame.org
• Email: hello@opengame.org
• GitHub: open-game-collective