GitHub Token Pool

A service that collects and manages GitHub API tokens from contributors to distribute rate limits across a shared pool. Inspired by Shields.io's token pool.

1. Contributors authenticate via GitHub OAuth (read-only public data access)
2. Tokens are encrypted (AES-256-GCM) and stored in SQLite
3. Consumer vals import getToken() to get a healthy token rotation
4. Rate limits are tracked per-token; exhausted tokens are quarantined until reset

This pool powers GitHub API calls in:

• github-zip-api — Fetch GitHub repo contents as zip
• claude-plugins-registry — Plugin registry for Claude Code

Go to https://github.com/settings/developers and create a new OAuth App:

• Application name: Token Pool (or whatever)
• Homepage URL: Your val endpoint
• Callback URL: https://<your-endpoint>/callback
• Scopes: None needed (public data only)

Add these to your val:

GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret
TOKEN_ENCRYPTION_KEY=<32 hex chars>

Generate encryption key: openssl rand -hex 32

Import directly from the pool library — no HTTP API needed (SQLite is shared across your vals and you must set TOKEN_ENCRYPTION_KEY env in the Val):

import {
  getToken,
  syncTokenHealth,
} from "https://esm.town/v/kamalnrf/token-pool/lib/pool.ts";

// Get a healthy token (LRU selection)
const t = await getToken();

if (t) {
  const res = await fetch("https://api.github.com/repos/owner/repo", {
    headers: {
      Authorization: `Bearer ${t.token}`,
      "User-Agent": "my-val",
    },
  });

  // Updates rate limits, or removes token if revoked (401)
  await syncTokenHealth(t.id, res);
}

Returns the least-recently-used healthy token, or null if pool is empty/exhausted.

interface TokenWithSecret {
  id: number;
  github_user_id: string;
  github_username: string | null;
  token: string; // Decrypted, ready to use
  rate_limit_remaining: number;
  rate_limit_reset_at: number | null;
  // ...
}

Call after every GitHub API request. Handles:

• 401: Removes revoked/invalid token from pool
• Other: Updates rate limit tracking from response headers

Lower-level function to update token health. Prefer handleResponse for most cases.

Helper to extract rate limit info from GitHub response headers.