Quick Start

What you need

• Bun (v1.0+) because Node.js is fine but Bun is faster
• Git (obviously)
• A text editor (VSCode, probably)
• 10 minutes and some terminal patience

Step 1: Clone and install things

The usual ceremony:

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

# Widget has its own deps because monorepos are still terrible
cd proof-of-spend-widget
bun install
cd ..

Step 2: Database setup

SQLite because Postgres is overkill for local dev:

bun run drizzle-kit generate
bun run drizzle-kit migrate

If this fails, congratulations, you found a bug. File an issue.

Step 3: Environment variables

Create .env in the root. Generate actual secrets for production, but for local testing:

PORT=3000
NODE_ENV=development
DATABASE_URL=./data/proof-of-spend.db
JWT_ACCESS_SECRET=make-this-long-and-random-in-production
JWT_REFRESH_SECRET=seriously-dont-use-this-in-production

Step 4: Start the OAuth server

bun run dev

OAuth server runs at http://localhost:3000. If you see errors, read them. They’re usually helpful.

Step 5: Register an OAuth client

Your widget needs credentials to talk to the OAuth server:

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

This returns client_id and client_secret. Write them down or scroll up in your terminal later.

Step 6: Start the widget

New terminal because the server is blocking the first one:

cd proof-of-spend-widget
bun run dev

Widget runs at http://localhost:3001. Open it in a browser.

Step 7: Actually test it

1. Go to http://localhost:3001
2. Click a provider button (OpenAI, Anthropic, whatever)
3. OAuth flow happens (you’ll need real API credentials for this part)
4. Get an annotation task
5. Paste an API response
6. Watch it verify

If it works, you’re done. If it doesn’t, check the console. Error messages are there for a reason.

What’s next?

Backend Setup has the details I skipped here.

Widget Integration if you want to embed this in your own app.

OAuth API Reference if you’re the “read the spec” type.

Run the tests (you should)

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

# Widget tests
cd proof-of-spend-widget
bun test

200+ tests, >85% coverage. If they don’t pass, something’s broken (probably your environment, but maybe the code).