startgg-oauth2-full 0.2.1 → 0.2.2

package/README.md

@@ -37,24 +37,25 @@ Cooked for *you* by 0xabadbabe - using a lot of 💜 and few lines of code.
 
 ```fish
 ┬─[playerone@fedora:~/d/startgg-oauth2-full]─[21:08:50]─[G:main =]
-╰─>$ npm test -- pkce
+╰─>$ npm test
 
-> startgg-oauth2-full@0.2.0 test
-> jest --runInBand pkce
+> 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:        0.641 s, estimated 1 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 30-lis-25
+╰─>$
+[0] 0:fish*                                                                  "~/d/startgg-oauth2-fu" 21:10 26-wrz-26
 ```
 
 ## Installation
@@ -82,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',
+  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/api/startgg/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
 });
+```
 
-const res = await handler.exchangeToken(code, sessionStorage.getItem('pkce:verifier')!, [
-  StartGGScope.USER_IDENTITY,
-  StartGGScope.USER_EMAIL,
-]);
+### Server-Side (Node/Next.js) with Secure State Store
 
-const bearer = BearerToken.fromOAuthResponse(res);
-fetch('https://api.start.gg/your-endpoint', { headers: bearer.toAuthHeader() });
+```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 { data } = await response.json();
+```
+
+### Error Handling
+
+```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
+  },
+};
 ```
 
 ---
@@ -136,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`
@@ -161,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
 
@@ -177,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.
 
@@ -190,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.
 
 ---
 
@@ -216,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
@@ -252,6 +510,13 @@ 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).
 
 ---
 

package/dist/auth/StartGGOAuth2.d.ts

@@ -50,7 +50,7 @@ export declare function buildAuthorizeUrl(cfg: {
 }, opts: AuthorizeUrlOptions): Promise<BuiltAuthorizeUrl>;
 export declare class BearerToken {
     readonly accessToken: string;
-    readonly tokenType: 'Bearer';
+    readonly tokenType: "Bearer";
     readonly refreshToken?: string;
     readonly expiresAt?: number;
     private constructor();
@@ -71,14 +71,15 @@ export declare class StartGGOAuth2Handler implements IOAuth2HandlerWithPKCE {
     });
     /** 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. */
+    /** 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;
+    authEndpoint?: string;
+    tokenEndpoint?: string;
     fetchTimeoutMs?: number;
 }): StartGGOAuth2Handler;

package/dist/auth/StartGGOAuth2.js

@@ -1,4 +1,5 @@
-// Full RFC-compliant implementation 
+import { STARTGG_ENDPOINTS } from "../constants";
+// Full RFC-compliant implementation
 // of OAuth2 Authorization Code Flow with PKCE (RFC 6749, RFC 7636)
 // for Start.gg API (https://start.gg/docs/oauth2).
 // Happy to accept PRs for improvements or fixes!
@@ -16,7 +17,7 @@ export class OAuth2Error extends Error {
     details;
     constructor(message, code, details) {
         super(message);
-        this.name = 'OAuth2Error';
+        this.name = "OAuth2Error";
         this.code = code;
         this.details = details;
     }
@@ -25,7 +26,7 @@ export class ScopeValidationError extends OAuth2Error {
     requestedScopes;
     grantedScopes;
     constructor(message, requestedScopes, grantedScopes) {
-        super(message, 'SCOPE_VALIDATION_FAILED');
+        super(message, "SCOPE_VALIDATION_FAILED");
         this.requestedScopes = requestedScopes;
         this.grantedScopes = grantedScopes;
     }
@@ -35,31 +36,34 @@ async function getSubtleCrypto() {
     const g = globalThis;
     if (g.crypto?.subtle)
         return g.crypto.subtle;
-    throw new OAuth2Error('WebCrypto subtle not available; required for PKCE S256', 'CRYPTO_UNAVAILABLE');
+    throw new OAuth2Error("WebCrypto subtle not available; required for PKCE S256", "CRYPTO_UNAVAILABLE");
 }
 /** Base64 (Buffer if available, else btoa path). */
 function base64Encode(bytes) {
     const g = globalThis;
-    if (typeof g.Buffer?.from === 'function')
-        return g.Buffer.from(bytes).toString('base64');
-    let binary = '';
+    if (typeof g.Buffer?.from === "function")
+        return g.Buffer.from(bytes).toString("base64");
+    let binary = "";
     const chunk = 0x8000;
     for (let i = 0; i < bytes.length; i += chunk)
         binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
-    if (typeof g.btoa !== 'function')
-        throw new OAuth2Error('btoa not available for base64 encoding', 'B64_UNAVAILABLE');
+    if (typeof g.btoa !== "function")
+        throw new OAuth2Error("btoa not available for base64 encoding", "B64_UNAVAILABLE");
     return g.btoa(binary);
 }
 /** URL-safe Base64 (no padding). */
 function base64Url(bytes) {
     const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-    return base64Encode(u8).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+    return base64Encode(u8)
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
 }
 /** Random bytes using WebCrypto. */
 function getRandomBytes(length) {
     const g = globalThis;
     if (!g.crypto?.getRandomValues)
-        throw new OAuth2Error('crypto.getRandomValues unavailable', 'RNG_UNAVAILABLE');
+        throw new OAuth2Error("crypto.getRandomValues unavailable", "RNG_UNAVAILABLE");
     const bytes = new Uint8Array(length);
     g.crypto.getRandomValues(bytes);
     return bytes;
@@ -83,12 +87,12 @@ async function parseJsonSafe(res) {
 }
 /** Validate token response + Bearer type. */
 function validateTokenResponse(tr) {
-    if (!tr || typeof tr !== 'object')
-        throw new OAuth2Error('Invalid token response shape', 'INVALID_TOKEN_RESPONSE', tr);
+    if (!tr || typeof tr !== "object")
+        throw new OAuth2Error("Invalid token response shape", "INVALID_TOKEN_RESPONSE", tr);
     if (!tr.access_token)
-        throw new OAuth2Error('Missing access_token', 'INVALID_TOKEN_RESPONSE', tr);
-    if (!tr.token_type || tr.token_type.toLowerCase() !== 'bearer') {
-        throw new OAuth2Error('Unsupported token_type', 'UNSUPPORTED_TOKEN_TYPE', tr);
+        throw new OAuth2Error("Missing access_token", "INVALID_TOKEN_RESPONSE", tr);
+    if (!tr.token_type || tr.token_type.toLowerCase() !== "bearer") {
+        throw new OAuth2Error("Unsupported token_type", "UNSUPPORTED_TOKEN_TYPE", tr);
     }
 }
 /** If scope omitted, assume unchanged (RFC 6749). */
@@ -98,9 +102,9 @@ function validateScopesOrAssumePrevious(responseScope, requiredScopes) {
     if (responseScope == null)
         return;
     const granted = new Set(responseScope.split(/\s+/).filter(Boolean));
-    const missing = requiredScopes.filter(s => !granted.has(s));
+    const missing = requiredScopes.filter((s) => !granted.has(s));
     if (missing.length > 0) {
-        throw new ScopeValidationError(`Missing required scopes: ${missing.join(', ')}`, requiredScopes, Array.from(granted));
+        throw new ScopeValidationError(`Missing required scopes: ${missing.join(", ")}`, requiredScopes, Array.from(granted));
     }
 }
 /** Fetch with timeout to avoid hangs. */
@@ -116,7 +120,7 @@ async function fetchWithTimeout(input, init = {}) {
     }
 }
 // -------- PKCE (RFC 7636) --------
-const PKCE_VERIFIER_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+const PKCE_VERIFIER_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
 export function generateCodeVerifier(length = 64) {
     const len = Math.min(Math.max(length, 43), 128);
     const alphabet = PKCE_VERIFIER_CHARS;
@@ -133,13 +137,13 @@ export function generateCodeVerifier(length = 64) {
                 break;
         }
     }
-    return result.join('');
+    return result.join("");
 }
 /** S256 challenge for a verifier. */
 export async function computeCodeChallengeS256(codeVerifier) {
     const enc = new TextEncoder();
     const subtle = await getSubtleCrypto();
-    const hash = await subtle.digest('SHA-256', enc.encode(codeVerifier));
+    const hash = await subtle.digest("SHA-256", enc.encode(codeVerifier));
     return base64Url(hash);
 }
 /** Build an authorization URL with PKCE (S256). */
@@ -149,7 +153,7 @@ export async function buildAuthorizeUrl(cfg, opts) {
     if (opts.codeVerifier && opts.codeChallenge) {
         const expectedChallenge = await computeCodeChallengeS256(opts.codeVerifier);
         if (expectedChallenge !== opts.codeChallenge) {
-            throw new OAuth2Error('Provided codeChallenge does not match codeVerifier', 'INVALID_PKCE_PAIR');
+            throw new OAuth2Error("Provided codeChallenge does not match codeVerifier", "INVALID_PKCE_PAIR");
         }
         codeVerifier = opts.codeVerifier;
         codeChallenge = opts.codeChallenge;
@@ -159,7 +163,7 @@ export async function buildAuthorizeUrl(cfg, opts) {
         codeChallenge = await computeCodeChallengeS256(codeVerifier);
     }
     else if (opts.codeChallenge) {
-        throw new OAuth2Error('codeVerifier is required when providing codeChallenge', 'INVALID_PKCE_PAIR');
+        throw new OAuth2Error("codeVerifier is required when providing codeChallenge", "INVALID_PKCE_PAIR");
     }
     else {
         codeVerifier = generateCodeVerifier();
@@ -167,12 +171,12 @@ export async function buildAuthorizeUrl(cfg, opts) {
     }
     const u = new URL(cfg.authEndpoint);
     const params = {
-        response_type: 'code',
+        response_type: "code",
         client_id: cfg.clientId,
         redirect_uri: cfg.redirectUri,
-        scope: opts.scopes.map(String).join(' '),
+        scope: opts.scopes.map(String).join(" "),
         code_challenge: codeChallenge,
-        code_challenge_method: 'S256',
+        code_challenge_method: "S256",
     };
     if (opts.state)
         params.state = opts.state;
@@ -201,12 +205,13 @@ export class BearerToken {
     }
     static fromOAuthResponse(res, nowMs = Date.now(), skewSeconds = 60) {
         validateTokenResponse(res);
-        const expiresAt = typeof res.expires_in === 'number'
-            ? nowMs + Math.max(0, (res.expires_in - Math.max(0, skewSeconds)) * 1000)
+        const expiresAt = typeof res.expires_in === "number"
+            ? nowMs +
+                Math.max(0, (res.expires_in - Math.max(0, skewSeconds)) * 1000)
             : undefined;
         return new BearerToken({
             accessToken: res.access_token,
-            tokenType: 'Bearer',
+            tokenType: "Bearer",
             refreshToken: res.refresh_token,
             expiresAt,
         });
@@ -226,7 +231,7 @@ export class BearerToken {
     }
     assertUsable(nowMs = Date.now()) {
         if (this.isExpired(nowMs))
-            throw new OAuth2Error('Access token expired', 'TOKEN_EXPIRED');
+            throw new OAuth2Error("Access token expired", "TOKEN_EXPIRED");
     }
 }
 // -------- Handler (RFC 6749 §4.1.3, §6) --------
@@ -238,44 +243,50 @@ export class StartGGOAuth2Handler {
     /** Exchange authorization code for tokens (PKCE). */
     async exchangeToken(code, codeVerifier, expectedScopes) {
         const tokenRequest = {
-            grant_type: 'authorization_code',
+            grant_type: "authorization_code",
             code,
             redirect_uri: this.config.redirectUri,
             code_verifier: codeVerifier,
             client_id: this.config.clientId,
         };
         const res = await fetchWithTimeout(this.config.tokenEndpoint, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
             body: formBody(tokenRequest),
             timeoutMs: this.config.fetchTimeoutMs ?? 15000,
         });
         if (!res.ok) {
             const details = await parseJsonSafe(res);
-            throw new OAuth2Error('Token exchange failed', 'TOKEN_EXCHANGE_FAILED', details);
+            throw new OAuth2Error("Token exchange failed", "TOKEN_EXCHANGE_FAILED", details);
         }
         const tokenResponse = (await res.json());
         validateTokenResponse(tokenResponse);
         validateScopesOrAssumePrevious(tokenResponse.scope, expectedScopes.map(String));
         return tokenResponse;
     }
-    /** Refresh access token; preserve prior refresh token if server omits rotation. */
+    /** 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. */
     async refreshToken(refreshToken, originalScopes) {
         const refreshRequest = {
-            grant_type: 'refresh_token',
+            grant_type: "refresh_token",
             refresh_token: refreshToken,
             client_id: this.config.clientId,
-            scope: originalScopes.length ? originalScopes.join(' ') : undefined,
         };
         const res = await fetchWithTimeout(this.config.tokenEndpoint, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/x-www-form-urlencoded', 'Accept': 'application/json' },
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
             body: formBody(Object.fromEntries(Object.entries(refreshRequest).filter(([, v]) => v != null))),
             timeoutMs: this.config.fetchTimeoutMs ?? 15000,
         });
         if (!res.ok) {
             const details = await parseJsonSafe(res);
-            throw new OAuth2Error('Token refresh failed', 'TOKEN_REFRESH_FAILED', details);
+            throw new OAuth2Error("Token refresh failed", "TOKEN_REFRESH_FAILED", details);
         }
         const tokenResponse = (await res.json());
         validateTokenResponse(tokenResponse);
@@ -287,5 +298,9 @@ export class StartGGOAuth2Handler {
 }
 /** Factory */
 export function createStartGGAuth2Handler(params) {
-    return new StartGGOAuth2Handler(params);
+    return new StartGGOAuth2Handler({
+        ...params,
+        authEndpoint: params.authEndpoint ?? STARTGG_ENDPOINTS.authorize,
+        tokenEndpoint: params.tokenEndpoint ?? STARTGG_ENDPOINTS.token,
+    });
 }

package/dist/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const STARTGG_ENDPOINTS: {
+    readonly authorize: "https://api.start.gg/oauth/authorize";
+    readonly token: "https://api.start.gg/oauth/access_token";
+    readonly refresh: "https://api.start.gg/oauth/refresh";
+    readonly gql: "https://api.start.gg/gql/alpha";
+};
+export declare const STARTGG_SCOPES: readonly ["user.identity", "user.email", "tournament.manager", "tournament.reporter"];
+export declare const STARTGG_GQL_AUTH_HEADER: "Bearer";
+export type StartGGScopeValue = (typeof STARTGG_SCOPES)[number];
+export declare function isValidStartGGScope(scope: string): scope is StartGGScopeValue;

package/dist/constants.js

@@ -0,0 +1,16 @@
+export const STARTGG_ENDPOINTS = {
+    authorize: "https://api.start.gg/oauth/authorize",
+    token: "https://api.start.gg/oauth/access_token",
+    refresh: "https://api.start.gg/oauth/refresh",
+    gql: "https://api.start.gg/gql/alpha",
+};
+export const STARTGG_SCOPES = [
+    "user.identity",
+    "user.email",
+    "tournament.manager",
+    "tournament.reporter",
+];
+export const STARTGG_GQL_AUTH_HEADER = "Bearer";
+export function isValidStartGGScope(scope) {
+    return STARTGG_SCOPES.includes(scope);
+}

package/dist/index.d.ts

@@ -1 +1,2 @@
-export * from './auth/StartGGOAuth2.js';
+export * from "./auth/StartGGOAuth2.js";
+export * from "./constants.js";

package/dist/index.js

@@ -1 +1,2 @@
-export * from './auth/StartGGOAuth2.js';
+export * from "./auth/StartGGOAuth2.js";
+export * from "./constants.js";

package/package.json

@@ -1,37 +1,65 @@
 {
-  "name": "startgg-oauth2-full",
-  "version": "0.2.1",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE"
-  ],
-  "license": "MIT",
-  "scripts": {
-    "dev:browser": "serve examples/browser -p 5174",
-    "dev:node": "tsx examples/node/index.ts",
-    "dev:node:server": "tsx examples/node/server.ts",
-    "test": "jest --runInBand",
-    "build": "tsc -p tsconfig.json"
-  },
-  "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "@types/node": "^22.7.5",
-    "jest": "^29.7.0",
-    "node-fetch": "^3.3.2",
-    "serve": "^14.2.6",
-    "ts-jest": "^29.2.5",
-    "ts-node": "10.9.2",
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.3"
-  }
+	"name": "startgg-oauth2-full",
+	"version": "0.2.2",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./auth": {
+			"types": "./dist/auth/StartGGOAuth2.d.ts",
+			"import": "./dist/auth/StartGGOAuth2.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/0xABADBABE-ops/startgg-oauth2-full.git"
+	},
+	"scripts": {
+		"dev:browser": "serve examples/browser -p 5174",
+		"dev:node": "tsx examples/node/src/index.ts",
+		"dev:node:server": "tsx examples/node/src/server.ts",
+		"dev:vite": "cd examples/vite && npm run dev",
+		"dev:nextjs": "cd examples/nextjs && npm run dev",
+		"dev:discord": "cd examples/discordjs && npm run dev",
+		"build:vercel-connect": "cd packages/startgg-vercel-connect && npm run build",
+		"test": "jest --runInBand",
+		"test:watch": "jest --watch",
+		"test:coverage": "jest --coverage",
+		"lint": "tsc --noEmit",
+		"build": "tsc -p tsconfig.json",
+		"prepare": "npm run build"
+	},
+	"devDependencies": {
+		"@types/jest": "^29.5.12",
+		"@types/node": "^22.7.5",
+		"jest": "^29.7.0",
+		"lantern": "0.1.2",
+		"node-fetch": "^3.3.2",
+		"serve": "^14.2.6",
+		"ts-jest": "^29.2.5",
+		"ts-node": "10.9.2",
+		"tsx": "^4.19.0",
+		"typescript": "^5.6.3"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"allowScripts": {
+		"esbuild@0.25.11": true
+	}
 }