startgg-oauth2-full 0.2.0 → 0.2.1

package/CONTRIBUTING.md

@@ -1,36 +0,0 @@
-# Contributing to startgg-oauth2-full
-
-## Prerequisites
-- Node 18+ and npm 9+
-- Git
-
-## Layout
-- `src` — library (TypeScript)
-- `__tests__` — unit tests
-- `examples` — browser + node demos (includes local redirect catcher)
-- `.github/workflows/ci.yml` — CI (build + tests)
-
-## Setup
-```bash
-npm i
-npm run build
-npm test
-```
-
-## Run examples
-```bash
-npm run dev:browser
-npm run dev:node
-STARTGG_CLIENT_ID=your_id \
-STARTGG_AUTH_URL=https://api.start.gg/oauth/authorize \
-STARTGG_TOKEN_URL=https://api.start.gg/oauth/token \
-npm run dev:node:server
-```
-
-## Branch & PR
-- Branch naming: `feat/*`, `fix/*`, `docs/*`, `chore/*`
-- Before PR:
-  - [ ] `npm run build` passes
-  - [ ] `npm test` passes
-  - [ ] Tests added/updated when changing behavior
-  - [ ] README/docs updated if API or flows changed

package/STARTGG_OAUTH_SETUP.md

@@ -1,41 +0,0 @@
-# Start.gg OAuth Setup
-
-## 1) Create an OAuth app
-- In Start.gg developer console, create a **Public** OAuth app (PKCE).
-- Copy **Client ID**.
-
-## 2) Register redirect URIs
-Add exact matches you will use:
-- Browser demo: `http://localhost:5174/index.html` (or the exact URL you open)
-- Node catcher: `http://localhost:3000/callback`
-
-> Redirect URIs must match exactly (scheme/host/port/path).
-
-## 3) Scopes
-Common scopes:
-- `user.identity`
-- `user.email` (requires `user.identity`)
-- `tournament.manager`
-- `tournament.reporter`
-
-## 4) Environment variables (Node catcher)
-```bash
-export STARTGG_CLIENT_ID=your_client_id
-export STARTGG_AUTH_URL=https://api.start.gg/oauth/authorize
-export STARTGG_TOKEN_URL=https://api.start.gg/oauth/token
-npm run dev:node:server
-```
-
-## 5) Test the flow
-1. Ensure `http://localhost:3000/callback` is registered.
-2. Run the server script above.
-3. Browser opens Start.gg consent.
-4. Approve; you’re redirected to `/callback`.
-5. Terminal prints masked tokens + `Authorization` header.
-
-## 6) Production notes
-- Always HTTPS for redirects.
-- Persist and validate `state` (CSRF).
-- Keep `code_verifier` private (session/server).
-- Never log raw tokens in prod.
-- Plan for refresh token storage/rotation.

package/__tests__/authorize-url.test.ts

@@ -1,62 +0,0 @@
-import { buildAuthorizeUrl, StartGGScope } from '../src/auth/StartGGOAuth2';
-
-describe('Authorize URL', () => {
-  test('includes required params and scopes', async () => {
-    const cfg = {
-      clientId: 'abc',
-      authEndpoint: 'https://example.com/authorize',
-      redirectUri: 'https://app/callback',
-    };
-    const { url, codeVerifier, codeChallenge } = await buildAuthorizeUrl(cfg, {
-      scopes: [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL],
-      state: 'xyz',
-      prompt: 'consent',
-      extras: { access_type: 'offline' },
-    });
-
-    const u = new URL(url);
-    expect(u.searchParams.get('response_type')).toBe('code');
-    expect(u.searchParams.get('client_id')).toBe('abc');
-    expect(u.searchParams.get('redirect_uri')).toBe('https://app/callback');
-    expect(u.searchParams.get('scope')).toContain('user.identity');
-    expect(u.searchParams.get('scope')).toContain('user.email');
-    expect(u.searchParams.get('state')).toBe('xyz');
-    expect(u.searchParams.get('prompt')).toBe('consent');
-    expect(u.searchParams.get('access_type')).toBe('offline');
-    expect(u.searchParams.get('code_challenge_method')).toBe('S256');
-    expect(codeVerifier.length).toBeGreaterThanOrEqual(43);
-    expect(codeChallenge.length).toBeGreaterThan(20);
-  });
-
-  test('throws when codeChallenge provided without matching codeVerifier', async () => {
-    const cfg = {
-      clientId: 'abc',
-      authEndpoint: 'https://example.com/authorize',
-      redirectUri: 'https://app/callback',
-    };
-    await expect(
-      buildAuthorizeUrl(cfg, {
-        scopes: [],
-        codeChallenge: 'custom-challenge',
-      })
-    ).rejects.toThrow(/codeVerifier is required/);
-  });
-
-  test('accepts externally provided PKCE pair when consistent', async () => {
-    const cfg = {
-      clientId: 'abc',
-      authEndpoint: 'https://example.com/authorize',
-      redirectUri: 'https://app/callback',
-    };
-    const verifier = 'test-verifier-1234567890_-=.~';
-    const expectedChallenge = 'xPCddgBLJpr4TYXpjK5OM51rAX0xrMyIOiVyy18DPQ8';
-    const result = await buildAuthorizeUrl(cfg, {
-      scopes: [],
-      codeVerifier: verifier,
-      codeChallenge: expectedChallenge,
-    });
-
-    expect(result.codeVerifier).toBe(verifier);
-    expect(result.codeChallenge).toBe(expectedChallenge);
-  });
-});

package/__tests__/bearer-token.test.ts

@@ -1,21 +0,0 @@
-import { BearerToken } from '../src/auth/StartGGOAuth2';
-
-describe('BearerToken', () => {
-  test('applies skew and expiry checks', () => {
-    const now = 1_000_000;
-    const res = {
-      access_token: 'at',
-      token_type: 'Bearer',
-      expires_in: 120,
-    };
-    const token = BearerToken.fromOAuthResponse(res as any, now, 60);
-    expect(token.isExpired(now)).toBe(false);
-    expect(token.willExpireWithin(120, now)).toBe(true);
-    expect(token.toAuthHeader()).toEqual({ Authorization: 'Bearer at' });
-  });
-
-  test('non-expiring when expires_in absent', () => {
-    const token = BearerToken.fromOAuthResponse({ access_token: 'at', token_type: 'Bearer' } as any, 0, 60);
-    expect(token.isExpired()).toBe(false);
-  });
-});

package/__tests__/handler.test.ts

@@ -1,111 +0,0 @@
-import {
-  createStartGGAuth2Handler,
-  StartGGScope,
-  OAuth2Error,
-} from '../src/auth/StartGGOAuth2';
-
-describe('StartGGOAuth2Handler', () => {
-  const cfg = {
-    clientId: 'client',
-    redirectUri: 'https://app/callback',
-    authEndpoint: 'https://example.com/authorize',
-    tokenEndpoint: 'https://example.com/token',
-  };
-
-  beforeEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  test('exchangeToken success with scope present', async () => {
-    const mockBody = {
-      access_token: 'at',
-      token_type: 'Bearer',
-      expires_in: 3600,
-      scope: 'user.identity user.email',
-      refresh_token: 'rt',
-    };
-    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
-      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
-    );
-
-    const handler = createStartGGAuth2Handler(cfg);
-    const res = await handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL]);
-    expect(res.access_token).toBe('at');
-    expect(res.refresh_token).toBe('rt');
-  });
-
-  test('exchangeToken accepts missing scope (assume unchanged)', async () => {
-    const mockBody = {
-      access_token: 'at',
-      token_type: 'Bearer',
-      expires_in: 3600,
-      refresh_token: 'rt',
-    };
-    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
-      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
-    );
-
-    const handler = createStartGGAuth2Handler(cfg);
-    const res = await handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY]);
-    expect(res.access_token).toBe('at');
-  });
-
-  test('exchangeToken fails when token_type not Bearer', async () => {
-    const mockBody = {
-      access_token: 'at',
-      token_type: 'MAC',
-      expires_in: 3600,
-      scope: 'user.identity',
-    };
-    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
-      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
-    );
-
-    const handler = createStartGGAuth2Handler(cfg);
-    await expect(handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY]))
-      .rejects.toThrow(OAuth2Error);
-  });
-
-  test('refreshToken preserves previous refresh_token when omitted', async () => {
-    const mockBody = {
-      access_token: 'at2',
-      token_type: 'Bearer',
-      expires_in: 3600,
-      scope: 'user.identity',
-    };
-    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
-      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
-    );
-
-    const handler = createStartGGAuth2Handler(cfg);
-    const res = await handler.refreshToken('rt-old', [StartGGScope.USER_IDENTITY]);
-    expect(res.refresh_token).toBe('rt-old');
-  });
-
-  test('refreshToken throws when scope reduced', async () => {
-    const mockBody = {
-      access_token: 'at3',
-      token_type: 'Bearer',
-      scope: 'user.identity',
-    };
-    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
-      new Response(JSON.stringify(mockBody), { status: 200, headers: { 'Content-Type': 'application/json' } })
-    );
-
-    const handler = createStartGGAuth2Handler(cfg);
-    await expect(
-      handler.refreshToken('rt', [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL])
-    ).rejects.toThrow('Missing required scopes: user.email');
-  });
-
-  test('handles non-JSON error body safely', async () => {
-    jest.spyOn(global, 'fetch' as any).mockResolvedValueOnce(
-      // @ts-ignore
-      new Response('<html>bad request</html>', { status: 400, headers: { 'Content-Type': 'text/html' } })
-    );
-
-    const handler = createStartGGAuth2Handler(cfg);
-    await expect(handler.exchangeToken('code', 'verifier', [StartGGScope.USER_IDENTITY]))
-      .rejects.toThrow('Token exchange failed');
-  });
-});

package/__tests__/pkce.test.ts

@@ -1,17 +0,0 @@
-import { computeCodeChallengeS256, generateCodeVerifier } from '../src/auth/StartGGOAuth2';
-
-describe('PKCE helpers', () => {
-  test('generateCodeVerifier length bounds', () => {
-    expect(generateCodeVerifier(10).length).toBeGreaterThanOrEqual(43);
-    expect(generateCodeVerifier(200).length).toBeLessThanOrEqual(128);
-  });
-
-  test('computeCodeChallengeS256 deterministic', async () => {
-    const verifier = 'test-verifier-1234567890_-=.~';
-    const ch1 = await computeCodeChallengeS256(verifier);
-    const ch2 = await computeCodeChallengeS256(verifier);
-    expect(ch1).toEqual(ch2);
-    expect(typeof ch1).toBe('string');
-    expect(ch1.length).toBeGreaterThan(20);
-  });
-});

package/examples/browser/README.md

@@ -1,20 +0,0 @@
-# Browser Demo
-
-This example runs the Start.gg OAuth helpers in a plain browser application with no framework. It uses Vite for bundling and serves a single page that builds PKCE authorize URLs, displays the verifier/challenge pair, and exchanges the authorization code after Start.gg redirects back.
-
-## Getting Started
-```bash
-cd examples/browser
-npm install
-npm run dev
-```
-
-The dev server opens at `http://localhost:5173`. Fill in your Start.gg OAuth client details and click **Generate Authorize URL**. Inspect the generated verifier/challenge values, open the authorize link in a new tab, and complete the Start.gg flow. When Start.gg redirects back, the page exchanges the code and prints a token summary.
-
-## Production Build
-```bash
-npm run build
-npm run preview
-```
-
-`npm run build` writes static assets to `dist/`, and `npm run preview` serves them locally.

package/examples/browser/index.html

@@ -1,55 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Start.gg OAuth2 Browser Demo</title>
-  </head>
-  <body>
-    <main>
-      <h1>Start.gg OAuth2 (Vanilla Browser)</h1>
-      <p>
-        This demo uses the <code>startgg-oauth2-full</code> helpers to produce a PKCE authorize URL and exchange the
-        resulting authorization code inside a plain browser app.
-      </p>
-
-      <form id="config">
-        <label>
-          Client ID
-          <input name="clientId" value="YOUR_CLIENT_ID" required />
-        </label>
-        <label>
-          Auth Endpoint
-          <input name="authEndpoint" value="https://api.start.gg/oauth/authorize" required />
-        </label>
-        <label>
-          Token Endpoint
-          <input name="tokenEndpoint" value="https://api.start.gg/oauth/token" required />
-        </label>
-        <label>
-          Redirect URI
-          <input name="redirectUri" value="http://localhost:5173/" required />
-        </label>
-        <button type="submit">Generate Authorize URL</button>
-      </form>
-
-      <section>
-        <h2>Generated Values</h2>
-        <h3>Authorize URL</h3>
-        <pre id="output-url">Fill the form to generate a URL.</pre>
-        <h3>Verifier</h3>
-        <pre id="output-verifier">Verifier will be shown here.</pre>
-        <h3>Challenge</h3>
-        <pre id="output-challenge">Challenge will be shown here.</pre>
-      </section>
-
-      <section>
-        <h2>Authorization Callback</h2>
-        <p id="callback-status">Waiting for callback…</p>
-        <pre id="token-preview">Token preview appears here after callback.</pre>
-      </section>
-    </main>
-
-    <script type="module" src="/src/main.ts"></script>
-  </body>
-</html>

package/examples/browser/package.json

@@ -1,17 +0,0 @@
-{
-  "name": "startgg-oauth2-browser-example",
-  "version": "0.0.0",
-  "private": true,
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "startgg-oauth2-full": "file:../.."
-  },
-  "devDependencies": {
-    "typescript": "^5.6.3",
-    "vite": "^5.4.8"
-  }
-}

package/examples/browser/src/main.ts

@@ -1,105 +0,0 @@
-import {
-  BearerToken,
-  StartGGScope,
-  buildAuthorizeUrl,
-  createStartGGAuth2Handler,
-} from 'startgg-oauth2-full/src/auth/StartGGOAuth2';
-
-const form = document.querySelector<HTMLFormElement>('#config')!;
-const outputUrl = document.querySelector<HTMLPreElement>('#output-url')!;
-const outputVerifier = document.querySelector<HTMLPreElement>('#output-verifier')!;
-const outputChallenge = document.querySelector<HTMLPreElement>('#output-challenge')!;
-const callbackStatus = document.querySelector<HTMLParagraphElement>('#callback-status')!;
-const tokenPreview = document.querySelector<HTMLPreElement>('#token-preview')!;
-
-let lastVerifier: string | null = null;
-let lastConfig: {
-  clientId: string;
-  authEndpoint: string;
-  tokenEndpoint: string;
-  redirectUri: string;
-} | null = null;
-
-form.addEventListener('submit', async event => {
-  event.preventDefault();
-  const data = new FormData(form);
-
-  const cfg = {
-    clientId: String(data.get('clientId') ?? ''),
-    authEndpoint: String(data.get('authEndpoint') ?? ''),
-    tokenEndpoint: String(data.get('tokenEndpoint') ?? ''),
-    redirectUri: String(data.get('redirectUri') ?? ''),
-  };
-
-  try {
-    const { url, codeVerifier, codeChallenge } = await buildAuthorizeUrl(cfg, {
-      scopes: [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL],
-      state: crypto.randomUUID(),
-      prompt: 'consent',
-    });
-
-    lastVerifier = codeVerifier;
-    lastConfig = cfg;
-
-    sessionStorage.setItem('startgg:lastVerifier', codeVerifier);
-    sessionStorage.setItem('startgg:lastConfig', JSON.stringify(cfg));
-
-    outputUrl.textContent = url;
-    outputVerifier.textContent = codeVerifier;
-    outputChallenge.textContent = codeChallenge;
-    callbackStatus.textContent = 'Waiting for authorization code…';
-    tokenPreview.textContent = 'Token preview appears here after callback.';
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    outputUrl.textContent = `Failed to generate authorize URL: ${message}`;
-    outputVerifier.textContent = '—';
-    outputChallenge.textContent = '—';
-  }
-});
-
-async function handleCallbackIfPresent() {
-  const params = new URLSearchParams(window.location.search);
-  const code = params.get('code');
-  const state = params.get('state');
-  if (!code || !state) return;
-
-  if (!lastVerifier || !lastConfig) {
-    lastVerifier = sessionStorage.getItem('startgg:lastVerifier');
-    const stored = sessionStorage.getItem('startgg:lastConfig');
-    lastConfig = stored ? JSON.parse(stored) : null;
-  }
-
-  if (!lastVerifier || !lastConfig) {
-    callbackStatus.textContent = 'Missing verifier/config in session storage; restart the flow.';
-    return;
-  }
-
-  try {
-    const handler = createStartGGAuth2Handler(lastConfig);
-    const tokenResponse = await handler.exchangeToken(code, lastVerifier, [
-      StartGGScope.USER_IDENTITY,
-      StartGGScope.USER_EMAIL,
-    ]);
-
-    const bearer = BearerToken.fromOAuthResponse(tokenResponse);
-    callbackStatus.textContent = 'Authorization complete!';
-    tokenPreview.textContent = JSON.stringify(
-      {
-        accessTokenPreview: `${bearer.accessToken.slice(0, 8)}…`,
-        expiresIn: tokenResponse.expires_in ?? null,
-        scope: tokenResponse.scope ?? null,
-        refreshTokenPresent: Boolean(tokenResponse.refresh_token),
-      },
-      null,
-      2
-    );
-  } catch (error) {
-    console.error('[browser example] Token exchange failed', error);
-    const message = error instanceof Error ? error.message : String(error);
-    callbackStatus.textContent = `Token exchange failed: ${message}`;
-  }
-}
-
-handleCallbackIfPresent().catch(err => {
-  console.error('[browser example] Failed to process callback', err);
-});

package/examples/browser/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "types": ["vite/client"]
-  },
-  "include": ["src"]
-}

package/examples/browser/vite.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from 'vite';
-
-export default defineConfig({
-  server: {
-    port: 5173,
-    open: true,
-  },
-});

package/examples/discordjs/.env.example

@@ -1,9 +0,0 @@
-DISCORD_TOKEN=YOUR_DISCORD_BOT_TOKEN
-DISCORD_CLIENT_ID=YOUR_DISCORD_APPLICATION_ID
-# Optional: restrict slash command registration to a single guild for faster propagation.
-# DISCORD_GUILD_ID=YOUR_TEST_GUILD_ID
-
-STARTGG_CLIENT_ID=YOUR_STARTGG_CLIENT_ID
-# STARTGG_AUTH_ENDPOINT=https://api.start.gg/oauth/authorize
-# STARTGG_TOKEN_ENDPOINT=https://api.start.gg/oauth/token
-STARTGG_REDIRECT_URI=http://localhost:5175/oauth/callback

package/examples/discordjs/README.md

@@ -1,36 +0,0 @@
-# Discord.js Bot Demo
-
-This example shows how to generate Start.gg OAuth authorize links and exchange tokens from a Discord slash command using `discord.js` v14.
-
-## Prerequisites
-- Node.js 18+ (for global `fetch` and WebCrypto).
-- A Discord application with a bot token and the `applications.commands` scope.
-- A Start.gg OAuth client configured with a redirect URI like `http://localhost:5175/oauth/callback`.
-
-## Setup
-```bash
-cd examples/discordjs
-cp .env.example .env
-# Edit .env with your Discord IDs and Start.gg client info
-npm install
-```
-
-Required `.env` values:
-- `DISCORD_TOKEN` – bot token.
-- `DISCORD_CLIENT_ID` – application/client ID.
-- `STARTGG_CLIENT_ID` – Start.gg OAuth client ID.
-- Optional: `DISCORD_GUILD_ID` for faster guild-only slash command registration.
-- Optional overrides: `STARTGG_AUTH_ENDPOINT`, `STARTGG_TOKEN_ENDPOINT`, `STARTGG_REDIRECT_URI`.
-
-## Running the Bot
-```bash
-npm run dev
-```
-
-The script registers the `/startgg-auth` command, logs the bot in, and starts an Express callback server that listens on the redirect URI's port/path (defaults to `http://localhost:5175/oauth/callback`).
-
-1. Invoke `/startgg-auth` in a guild where the bot is present.
-2. Follow the generated authorize link; after approving Start.gg, the callback exchanges the code for tokens.
-3. The bot logs the full token response and DMs you a confirmation with truncated credentials for demonstration.
-
-Store tokens securely in real applications—persist them in encrypted storage instead of sending them via DM.

package/examples/discordjs/package.json

@@ -1,23 +0,0 @@
-{
-  "name": "startgg-oauth2-discordjs-example",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "tsx watch src/bot.ts",
-    "start": "tsx src/bot.ts",
-    "build": "tsc --outDir dist --project tsconfig.json && node dist/bot.js"
-  },
-  "dependencies": {
-    "discord.js": "^14.15.3",
-    "dotenv": "^16.4.5",
-    "express": "^4.19.2",
-    "startgg-oauth2-full": "file:../.."
-  },
-  "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/node": "^22.7.5",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.3"
-  }
-}