Local Development with OAuth#

AT Protocol OAuth requires HTTPS URLs for security. For local development, you have two options:

Option 1: Use ngrok (Recommended)#

1. Install ngrok#

# Using Homebrew (macOS)
brew install ngrok

# Or download from https://ngrok.com/download

2. Start your dev server#

npm run dev

3. In a new terminal, start ngrok#

ngrok http 5173

You'll see output like:

Forwarding  https://abc123.ngrok-free.app -> http://localhost:5173

4. Update your .env file#

Copy the HTTPS URL from ngrok and update .env:

PUBLIC_BASE_URL=https://abc123.ngrok-free.app

5. Restart your dev server#

Stop and restart the dev server to pick up the new URL:

# Ctrl+C to stop, then:
npm run dev

6. Access your app via the ngrok URL#

Open https://abc123.ngrok-free.app in your browser and try logging in!

Note: The ngrok URL changes each time you restart it (unless you have a paid account). You'll need to update .env each time.

Option 2: Local HTTPS with mkcert#

This creates a permanent local HTTPS setup.

1. Install mkcert#

# macOS
brew install mkcert

# Then install the local CA
mkcert -install

2. Generate certificates#

cd /Users/dan/Documents/Coding/atprotogo
mkdir -p .cert
mkcert -key-file .cert/key.pem -cert-file .cert/cert.pem localhost

3. Update vite.config.ts#

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
import fs from 'fs';

export default defineConfig({
  plugins: [sveltekit()],
  server: {
    port: 5173,
    https: {
      key: fs.readFileSync('.cert/key.pem'),
      cert: fs.readFileSync('.cert/cert.pem'),
    },
  },
});

4. Update .env#

PUBLIC_BASE_URL=https://localhost:5173

5. Restart dev server#

npm run dev

Access at https://localhost:5173

Note: AT Protocol servers may still reject localhost URLs. In that case, use ngrok.

Option 3: Use a Custom Domain (Advanced)#

If you have a domain, you can:

1. Set up a subdomain (e.g., dev.yourdomain.com)
2. Point it to your local machine via /etc/hosts
3. Use Caddy or nginx for HTTPS reverse proxy
4. Update PUBLIC_BASE_URL to your subdomain

Quick Start Script (ngrok)#

Create a helper script for easy development:

scripts/dev-with-ngrok.sh:

#!/bin/bash

# Start dev server in background
npm run dev &
DEV_PID=$!

# Wait for server to start
sleep 3

# Start ngrok
echo "Starting ngrok tunnel..."
ngrok http 5173

# Cleanup on exit
trap "kill $DEV_PID" EXIT

Make it executable:

chmod +x scripts/dev-with-ngrok.sh

Then run:

./scripts/dev-with-ngrok.sh

Remember to update PUBLIC_BASE_URL in .env with the ngrok URL before testing!

Testing Without OAuth (Alternative)#

If you want to skip OAuth for now and test the game functionality:

1. Comment out the OAuth check in protected endpoints
2. Manually set a test session in your browser console
3. Use the API directly with a test DID

Not recommended for production, but useful for testing game logic.

Production Deployment#

For production:

• Deploy to a hosting service (Vercel, Netlify, Railway, etc.)
• Use your production domain in PUBLIC_BASE_URL
• Ensure HTTPS is enabled (automatic on most platforms)
• Regenerate PRIVATE_KEY_JWK for production

Example production .env:

PUBLIC_BASE_URL=https://atprotogo.yourdomain.com
PRIVATE_KEY_JWK={"kty":"EC"...}
DATABASE_PATH=/var/data/app.db
SESSION_SECRET=long-random-production-secret