startgg-oauth2-full 0.2.0 → 0.2.2

package/README.md

@@ -7,6 +7,9 @@
   <a href="https://www.npmjs.com/package/startgg-oauth2-full">
     <img alt="npm" src="https://img.shields.io/npm/v/startgg-oauth2-full">
   </a>
+  <a href="https://github.com/0xabadbabe-ops/startgg-oauth2-full/pkgs/npm/startgg-oauth2-full">
+    <img alt="GitHub Packages" src="https://img.shields.io/github/package-json/v/0xabadbabe-ops/startgg-oauth2-full?label=github%20pkg">
+  </a>
   <a href="./LICENSE">
     <img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg">
   </a>
@@ -33,19 +36,26 @@ Cooked for *you* by 0xabadbabe - using a lot of 💜 and few lines of code.
 ... with hope tha this would help for any dev struggling with oauth2 start.gg specific.
 
 ```fish
-startgg-oauth2-full@0.1.0 test
-> jest --runInBand pkce
+┬─[playerone@fedora:~/d/startgg-oauth2-full]─[21:08:50]─[G:main =]
+╰─>$ npm test
+
+> startgg-oauth2-full@0.2.2 test
+> jest --runInBand
 
- PASS  __tests__/pkce.test.ts
-  PKCE helpers
-    ✓ generateCodeVerifier length bounds (4 ms)
-    ✓ computeCodeChallengeS256 deterministic (3 ms)
+PASS __tests__/pkce.test.ts
+PASS __tests__/handler.test.ts
+PASS __tests__/authorize-url.test.ts
+PASS __tests__/constants.test.ts
+PASS __tests__/bearer-token.test.ts
 
-Test Suites: 1 passed, 1 total
-Tests:       2 passed, 2 total
+Test Suites: 5 passed, 5 total
+Tests:       28 passed, 28 total
 Snapshots:   0 total
-Time:        1.121 s, estimated 2 s
-Ran all test suites matching /pkce/i.
+Time:        0.859 s, estimated 1 s
+Ran all test suites.
+┬─[playerone@fedora:~/d/startgg-oauth2-full]─[21:10:09]─[G:main =]
+╰─>$
+[0] 0:fish*                                                                  "~/d/startgg-oauth2-fu" 21:10 26-wrz-26
 ```
 
 ## Installation
@@ -73,53 +83,245 @@ npm install @0xabadbabe-ops/startgg-oauth2-full
 
 ---
 
+## Start.gg Specifics
+
+The library itself is spec-pure PKCE (RFC 7636) and never touches a client secret. Start.gg's deployment deviates from that spec in ways you must plan for:
+
+- **`client_secret` is required at the token endpoint — even with PKCE.** Every Start.gg OAuth app is a confidential client. Keep the secret server-side and add it to the token request where you run the exchange. Every example in this repo shows the pattern (a small `exchangeTokenWithSecret` helper or a same-origin dev relay).
+- **The token endpoint sends no CORS headers.** A browser page can never exchange the code directly against `api.start.gg`. Exchange on your server (Node, Next.js route handler, bot backend) or through a same-origin relay — see `examples/browser` for the relay approach.
+- **Redirect URIs must match the registered callback exactly** — scheme, host, port, and path.
+- **Authorize host.** The constants use `https://api.start.gg/oauth/authorize`. If that host ever answers the authorize request with a JSON login 404, issue the identical request (same parameters) against `https://start.gg/oauth/authorize` — it renders the login/consent screen and completes the same flow.
+
+See [STARTGG_OAUTH_SETUP.md](./STARTGG_OAUTH_SETUP.md) for app registration, per-example redirect URIs, and environment variables.
+
+---
+
 ## Quick Start
 
-### Browser (PKCE → Exchange)
+### 1. Build the authorize URL (browser or server)
 
 ```ts
-import { buildAuthorizeUrl, StartGGScope } from 'startgg-oauth2-full';
+import { buildAuthorizeUrl, StartGGScope, STARTGG_ENDPOINTS } from 'startgg-oauth2-full';
 
 const cfg = {
   clientId: '<client-id>',
-  authEndpoint: 'https://api.start.gg/oauth/authorize',
-  redirectUri: 'https://your.app/callback',
+  authEndpoint: STARTGG_ENDPOINTS.authorize,
+  redirectUri: 'https://your.app/api/startgg/callback',
 };
 
+const state = crypto.randomUUID();
 const { url, codeVerifier } = await buildAuthorizeUrl(cfg, {
   scopes: [StartGGScope.USER_IDENTITY, StartGGScope.USER_EMAIL],
-  state: crypto.randomUUID(),
+  state,
 });
 
+// Keep both tied together for the callback (session, or a server-side state store)
 sessionStorage.setItem('pkce:verifier', codeVerifier);
-sessionStorage.setItem('oauth:state', '<same-state>');
+sessionStorage.setItem('oauth:state', state);
 location.href = url;
 ```
 
-### Callback (Exchange + Bearer)
+### 2. Exchange the code server-side
+
+Start.gg requires `client_secret` and sends no CORS headers, so the exchange happens on your server (the snippet every example in this repo uses):
+
+```ts
+// e.g. app/api/startgg/callback — Node / Next.js route handler
+import { BearerToken } from 'startgg-oauth2-full';
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const code = searchParams.get('code')!;
+  // verify `state`, then load the code_verifier you stored for it
+
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: process.env.STARTGG_REDIRECT_URI!,
+    code_verifier: storedVerifier,
+    client_id: process.env.STARTGG_CLIENT_ID!,
+    client_secret: process.env.STARTGG_CLIENT_SECRET!, // required by Start.gg even with PKCE
+  });
+
+  const res = await fetch('https://api.start.gg/oauth/access_token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body,
+  });
+  if (!res.ok) return new Response(`Token exchange failed: HTTP ${res.status}`, { status: 502 });
+
+  const bearer = BearerToken.fromOAuthResponse(await res.json());
+  // store bearer per user; never expose the raw token or your secret to the page
+}
+```
+
+Against a provider *without* Start.gg's secret requirement, `createStartGGAuth2Handler(cfg).exchangeToken(code, codeVerifier, scopes)` performs the same spec-pure POST for you — see [Advanced Usage](#advanced-usage).
+
+### Using Constants for Start.gg Endpoints & Scopes
+
+```ts
+import { STARTGG_ENDPOINTS, STARTGG_SCOPES, STARTGG_GQL_AUTH_HEADER, isValidStartGGScope } from 'startgg-oauth2-full';
+
+// All official Start.gg endpoints
+console.log(STARTGG_ENDPOINTS.authorize);   // https://api.start.gg/oauth/authorize
+console.log(STARTGG_ENDPOINTS.token);       // https://api.start.gg/oauth/access_token
+console.log(STARTGG_ENDPOINTS.gql);         // https://api.start.gg/gql/alpha
+
+// Valid scopes
+console.log(STARTGG_SCOPES);                // ['user.identity', 'user.email', 'tournament.manager', 'tournament.reporter']
+console.log(STARTGG_GQL_AUTH_HEADER);       // 'Bearer'
+
+// Scope validation helper
+const userInput = 'user.identity';
+if (isValidStartGGScope(userInput)) {
+  // TypeScript narrows to StartGGScopeValue
+}
+```
+
+---
+
+## Advanced Usage
+
+### Refresh Token Rotation
 
 ```ts
 import { createStartGGAuth2Handler, BearerToken, StartGGScope } from 'startgg-oauth2-full';
 
-const params = new URLSearchParams(location.search);
-const code = params.get('code')!;
-const state = params.get('state')!;
-if (state !== sessionStorage.getItem('oauth:state')) throw new Error('State mismatch');
+const handler = createStartGGAuth2Handler({ clientId, redirectUri });
 
-const handler = createStartGGAuth2Handler({
-  clientId: '<client-id>',
-  redirectUri: 'https://your.app/callback',
-  authEndpoint: 'https://api.start.gg/oauth/authorize',
-  tokenEndpoint: 'https://api.start.gg/oauth/token',
+// Initial exchange
+const res = await handler.exchangeToken(code, codeVerifier, [StartGGScope.USER_IDENTITY]);
+let bearer = BearerToken.fromOAuthResponse(res);
+
+// Later: refresh when expired (skew-aware)
+if (bearer.willExpireWithin(60)) { // expires within 60s
+  const newRes = await handler.refreshToken(bearer.refreshToken!, [StartGGScope.USER_IDENTITY]);
+  bearer = BearerToken.fromOAuthResponse(newRes); // preserves refresh_token if server omits
+}
+```
+
+### Custom PKCE Pair (Pre-generated Verifier/Challenge)
+
+```ts
+import { buildAuthorizeUrl, computeCodeChallengeS256, generateCodeVerifier } from 'startgg-oauth2-full';
+
+// Generate once, store securely
+const codeVerifier = generateCodeVerifier(64);
+const codeChallenge = await computeCodeChallengeS256(codeVerifier);
+
+// Later: build URL with pre-computed pair
+const { url } = await buildAuthorizeUrl(cfg, {
+  scopes: [StartGGScope.USER_IDENTITY],
+  state: crypto.randomUUID(),
+  codeVerifier,
+  codeChallenge, // validated against verifier
+});
+```
+
+### Server-Side (Node/Next.js) with Secure State Store
+
+```ts
+// lib/startgg.ts (Next.js example)
+import { createStartGGAuth2Handler } from 'startgg-oauth2-full';
+
+export function getStartggHandler() {
+  return createStartGGAuth2Handler({
+    clientId: process.env.STARTGG_CLIENT_ID!,
+    redirectUri: process.env.STARTGG_REDIRECT_URI!,
+    // authEndpoint and tokenEndpoint default to STARTGG_ENDPOINTS
+  });
+}
+
+// app/api/startgg/callback/route.ts
+import { getStartggHandler } from '@/lib/startgg';
+import { consumePending } from '@/lib/pendingStore'; // your secure store
+
+export async function GET(req: Request) {
+  const { searchParams } = new URL(req.url);
+  const code = searchParams.get('code')!;
+  const state = searchParams.get('state')!;
+
+  const pending = consumePending(state); // delete after use
+  if (!pending) return new Response('Invalid state', { status: 400 });
+
+  const res = await getStartggHandler().exchangeToken(code, pending.codeVerifier, pending.scopes);
+  return Response.json({ ok: true, scope: res.scope });
+}
+```
+
+### GraphQL Calls with Bearer Token
+
+```ts
+import { BearerToken, STARTGG_ENDPOINTS, STARTGG_GQL_AUTH_HEADER } from 'startgg-oauth2-full';
+
+const bearer = BearerToken.fromOAuthResponse(tokenResponse);
+
+const query = `
+  query GetUser { user { id, name, email } }
+`;
+
+const response = await fetch(STARTGG_ENDPOINTS.gql, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    [STARTGG_GQL_AUTH_HEADER]: bearer.toAuthHeader().Authorization,
+  },
+  body: JSON.stringify({ query }),
 });
 
-const res = await handler.exchangeToken(code, sessionStorage.getItem('pkce:verifier')!, [
-  StartGGScope.USER_IDENTITY,
-  StartGGScope.USER_EMAIL,
-]);
+const { data } = await response.json();
+```
+
+### Error Handling
 
-const bearer = BearerToken.fromOAuthResponse(res);
-fetch('https://api.start.gg/your-endpoint', { headers: bearer.toAuthHeader() });
+```ts
+import { createStartGGAuth2Handler, OAuth2Error, ScopeValidationError, StartGGScope } from 'startgg-oauth2-full';
+
+const handler = createStartGGAuth2Handler(cfg);
+
+try {
+  const res = await handler.exchangeToken(code, verifier, [StartGGScope.USER_IDENTITY]);
+} catch (err) {
+  if (err instanceof ScopeValidationError) {
+    console.error('Requested scopes:', err.requestedScopes); // ['user.identity', 'user.email']
+    console.error('Granted scopes:', err.grantedScopes);     // ['user.identity'] (present when server returned scope)
+  } else if (err instanceof OAuth2Error) {
+    console.error('OAuth error:', err.code); // TOKEN_EXCHANGE_FAILED, INVALID_PKCE_PAIR, etc.
+    console.error('Details:', err.details); // parsed JSON or { raw: '...' }
+  } else {
+    throw err;
+  }
+}
+```
+
+### Cloudflare Workers / Edge Runtime
+
+```ts
+// Works in Cloudflare Workers, Vercel Edge, Deno, Bun
+import { createStartGGAuth2Handler, StartGGScope } from 'startgg-oauth2-full';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const handler = createStartGGAuth2Handler({
+      clientId: env.STARTGG_CLIENT_ID,
+      redirectUri: new URL('/callback', request.url).href,
+    });
+
+    const url = new URL(request.url);
+    if (url.pathname === '/callback') {
+      const code = url.searchParams.get('code')!;
+      const state = url.searchParams.get('state')!;
+      // validate state from your KV/D1 store...
+      const res = await handler.exchangeToken(code, storedVerifier, [StartGGScope.USER_IDENTITY]);
+      return Response.redirect('/dashboard');
+    }
+
+    // ... rest of handler
+  },
+};
 ```
 
 ---
@@ -127,11 +329,12 @@ fetch('https://api.start.gg/your-endpoint', { headers: bearer.toAuthHeader() });
 ## Scripts
 
 ```bash
-npm run build      # tsc build
-npm test           # Jest tests (needs ts-node installed)
+npm run build      # compile TypeScript (tsc)
+npm test           # full Jest suite (ts-jest)
+npm test -- pkce   # target a single spec
 ```
 
-Examples ship as their own workspaces—hop into each folder, install once, then use the local scripts:
+Examples ship as their own workspaces — hop into each folder, install once, then use the local scripts. Every example performs a real user login against Start.gg:
 
 - Browser (Vite): `cd examples/browser && npm install && npm run dev`
 - Node CLI/server: `cd examples/node && npm install && npm run dev`
@@ -152,6 +355,8 @@ Examples ship as their own workspaces—hop into each folder, install once, then
 - `BearerToken`
   - `fromOAuthResponse(res, nowMs?, skewSeconds?)`
   - `isExpired()`, `willExpireWithin()`, `toAuthHeader()`, `assertUsable()`
+- `STARTGG_ENDPOINTS`, `STARTGG_SCOPES`, `STARTGG_GQL_AUTH_HEADER`
+- `isValidStartGGScope(value): boolean`
 
 ### Scopes
 
@@ -168,7 +373,7 @@ enum StartGGScope {
 
 ## Scope Semantics
 
-- If response **includes** `scope`, it’s validated; missing required → `ScopeValidationError`.
+- If response **includes** `scope`, it's validated; missing required → `ScopeValidationError`.
 - If response **omits** `scope`, treat as unchanged (RFC 6749).
 - Refresh: preserve prior `refresh_token` if omitted by server.
 
@@ -181,17 +386,73 @@ class OAuth2Error extends Error {
   code?: string;     // e.g., TOKEN_EXCHANGE_FAILED
   details?: unknown; // parsed JSON or { raw: string }
 }
+
+class ScopeValidationError extends Error {
+  requestedScopes: string[];   // what you asked for
+  grantedScopes?: string[];    // what the server granted (when it returned scope)
+}
 ```
 
 ---
 
 ## Examples
 
-- Browser (Vite SPA): `examples/browser/`
-- Node CLI + redirect catcher: `examples/node/`
-- Discord bot (discord.js v14): `examples/discordjs/`
-- Next.js (App Router): `examples/nextjs/`
-- Frontend Vite scaffold: `examples/vite/`
+| Example | Stack | Token exchange |
+| --- | --- | --- |
+| [`examples/node/`](./examples/node) | Node CLI + local redirect server | Server-side POST with `client_secret` |
+| [`examples/nextjs/`](./examples/nextjs) | Next.js App Router | Route handler POST with `client_secret` |
+| [`examples/discordjs/`](./examples/discordjs) | discord.js v14 bot | Bot backend POST with `client_secret` |
+| [`examples/browser/`](./examples/browser) | Vite SPA | Same-origin dev relay (`/startgg/token`) injects the secret |
+| [`examples/vite/`](./examples/vite) | Minimal Vite scaffold | Same-origin dev relay (`/startgg/token`) injects the secret |
+
+Each example documents its redirect URI and environment variables in its own README.
+
+---
+
+## Vercel Connect Integration
+
+Use Start.gg with [Vercel Connect](https://vercel.com/docs/connect) for secure, short-lived tokens without storing credentials in your environment.
+
+### Quick Setup
+
+```bash
+# 1. Create Start.gg OAuth app (redirect: https://connect.vercel.com/callback)
+# 2. Create Custom OAuth connector in Vercel Connect
+vercel connect create https://api.start.gg/oauth/authorize --name startgg
+# 3. Attach to your project
+vercel connect attach oauth/startgg
+```
+
+### Use in Your Code
+
+```bash
+npm install @vercel/connect startgg-vercel-connect
+```
+
+```ts
+import { getConnectorUid, getLoginScopes, createTokenParams } from 'startgg-vercel-connect';
+import { getTokenResponse, UserAuthorizationRequiredError } from '@vercel/connect';
+
+const token = await getTokenResponse(
+  getConnectorUid(),
+  createTokenParams({
+    subject: { type: 'user', id: 'user_123' },
+    scopes: getLoginScopes(true),
+  })
+);
+
+// Use with Start.gg GraphQL API
+const response = await fetch('https://api.start.gg/gql/alpha', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'Authorization': `Bearer ${token.token}`,
+  },
+  body: JSON.stringify({ query: '{ viewer { id name } }' }),
+});
+```
+
+See [VERCEL_CONNECT_STARTGG.md](./VERCEL_CONNECT_STARTGG.md) for the complete guide and [packages/startgg-vercel-connect](./packages/startgg-vercel-connect) for the helper package.
 
 ---
 
@@ -207,27 +468,33 @@ GitHub Actions runs TypeScript build + Jest on push/PR (Node 18 & 20). See `.git
 startgg-oauth2-full/
 ├── README.md
 ├── AGENTS.md
+├── CONTRIBUTING.md
 ├── LICENSE
+├── STARTGG_OAUTH_SETUP.md     # Start.gg app registration & env vars
+├── VERCEL_CONNECT_STARTGG.md  # Vercel Connect guide
 ├── package.json
 ├── tsconfig.json
 ├── jest.config.ts
 ├── jest.setup.ts
-├── .gitignore
-├── .npmrc
 ├── src/
-│   └── auth/
-│       └── StartGGOAuth2.ts
+│   ├── auth/
+│   │   └── StartGGOAuth2.ts   # PKCE + handler + BearerToken
+│   ├── constants.ts           # STARTGG_ENDPOINTS, scopes
+│   └── index.ts
 ├── __tests__/
 │   ├── authorize-url.test.ts
 │   ├── bearer-token.test.ts
+│   ├── constants.test.ts
 │   ├── handler.test.ts
 │   └── pkce.test.ts
 ├── examples/
-│   ├── browser/      # Vanilla browser Vite demo
-│   ├── node/         # CLI + local redirect server
-│   ├── discordjs/    # Discord bot OAuth flow
-│   ├── nextjs/       # Next.js App Router example
-│   └── vite/         # Minimal Vite SPA scaffold
+│   ├── browser/               # Vite SPA — dev relay exchange
+│   ├── node/                  # CLI + local redirect server
+│   ├── discordjs/             # Discord bot OAuth flow
+│   ├── nextjs/                # Next.js App Router example
+│   └── vite/                  # Minimal Vite SPA scaffold
+├── packages/
+│   └── startgg-vercel-connect/
 └── .github/
     ├── ISSUE_TEMPLATE/
     │   ├── bug_report.md
@@ -243,13 +510,20 @@ startgg-oauth2-full/
 - Use and verify `state`.
 - Keep `code_verifier` private.
 - Never log tokens; always HTTPS.
+- Never ship `client_secret` to the browser — Start.gg requires it, so the exchange belongs on a server you control.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). PRs should include Jest coverage for new behaviour and list validation steps (`npm test`, demo transcripts for interactive flows).
 
 ---
 
 ## License
 
 **MIT License**
-Copyright © 2025 0xABADBABE-ops
+Copyright © 2026 0xABADBABE-ops
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/auth/StartGGOAuth2.d.ts

@@ -0,0 +1,85 @@
+export declare enum StartGGScope {
+    USER_IDENTITY = "user.identity",
+    USER_EMAIL = "user.email",
+    TOURNAMENT_MANAGER = "tournament.manager",
+    TOURNAMENT_REPORTER = "tournament.reporter"
+}
+export interface IOAuth2HandlerWithPKCE {
+    exchangeToken(code: string, codeVerifier: string, expectedScopes: StartGGScope[]): Promise<OAuth2TokenResponse>;
+    refreshToken(refreshToken: string, originalScopes: StartGGScope[]): Promise<OAuth2TokenResponse>;
+}
+export declare class OAuth2Error extends Error {
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(message: string, code?: string, details?: unknown);
+}
+export interface OAuth2TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    [k: string]: unknown;
+}
+export declare class ScopeValidationError extends OAuth2Error {
+    readonly requestedScopes: string[];
+    readonly grantedScopes?: string[] | undefined;
+    constructor(message: string, requestedScopes: string[], grantedScopes?: string[] | undefined);
+}
+export declare function generateCodeVerifier(length?: number): string;
+/** S256 challenge for a verifier. */
+export declare function computeCodeChallengeS256(codeVerifier: string): Promise<string>;
+export type AuthorizeUrlOptions = {
+    scopes: (StartGGScope | string)[];
+    state?: string;
+    prompt?: string;
+    codeVerifier?: string;
+    codeChallenge?: string;
+    extras?: Record<string, string | number | boolean | undefined>;
+};
+export type BuiltAuthorizeUrl = {
+    url: string;
+    codeVerifier: string;
+    codeChallenge: string;
+};
+/** Build an authorization URL with PKCE (S256). */
+export declare function buildAuthorizeUrl(cfg: {
+    clientId: string;
+    authEndpoint: string;
+    redirectUri: string;
+}, opts: AuthorizeUrlOptions): Promise<BuiltAuthorizeUrl>;
+export declare class BearerToken {
+    readonly accessToken: string;
+    readonly tokenType: "Bearer";
+    readonly refreshToken?: string;
+    readonly expiresAt?: number;
+    private constructor();
+    static fromOAuthResponse(res: OAuth2TokenResponse, nowMs?: number, skewSeconds?: number): BearerToken;
+    isExpired(nowMs?: number): boolean;
+    willExpireWithin(seconds: number, nowMs?: number): boolean;
+    toAuthHeader(): Record<string, string>;
+    assertUsable(nowMs?: number): void;
+}
+export declare class StartGGOAuth2Handler implements IOAuth2HandlerWithPKCE {
+    private readonly config;
+    constructor(config: {
+        clientId: string;
+        redirectUri: string;
+        authEndpoint: string;
+        tokenEndpoint: string;
+        fetchTimeoutMs?: number;
+    });
+    /** Exchange authorization code for tokens (PKCE). */
+    exchangeToken(code: string, codeVerifier: string, expectedScopes: StartGGScope[]): Promise<OAuth2TokenResponse>;
+    /** Refresh access token; preserve prior refresh token if server omits rotation.
+     * Per RFC 6749, scope should only be included when requesting a subset of original scopes. */
+    refreshToken(refreshToken: string, originalScopes: StartGGScope[]): Promise<OAuth2TokenResponse>;
+}
+/** Factory */
+export declare function createStartGGAuth2Handler(params: {
+    clientId: string;
+    redirectUri: string;
+    authEndpoint?: string;
+    tokenEndpoint?: string;
+    fetchTimeoutMs?: number;
+}): StartGGOAuth2Handler;