startgg-oauth2-full 0.2.0 → 0.2.1

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,7 +36,10 @@ 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
+┬─[playerone@fedora:~/d/startgg-oauth2-full]─[21:08:50]─[G:main =]
+╰─>$ npm test -- pkce
+
+> startgg-oauth2-full@0.2.0 test
 > jest --runInBand pkce
 
  PASS  __tests__/pkce.test.ts
@@ -44,8 +50,11 @@ startgg-oauth2-full@0.1.0 test
 Test Suites: 1 passed, 1 total
 Tests:       2 passed, 2 total
 Snapshots:   0 total
-Time:        1.121 s, estimated 2 s
+Time:        0.641 s, estimated 1 s
 Ran all test suites matching /pkce/i.
+┬─[playerone@fedora:~/d/startgg-oauth2-full]─[21:10:09]─[G:main =]
+╰─>$ 
+[0] 0:fish*                                                                  "~/d/startgg-oauth2-fu" 21:10 30-lis-25
 ```
 
 ## Installation
@@ -83,7 +92,7 @@ import { buildAuthorizeUrl, StartGGScope } from 'startgg-oauth2-full';
 const cfg = {
   clientId: '<client-id>',
   authEndpoint: 'https://api.start.gg/oauth/authorize',
-  redirectUri: 'https://your.app/callback',
+  redirectUri: 'https://your.app/api/startgg/callback',
 };
 
 const { url, codeVerifier } = await buildAuthorizeUrl(cfg, {
@@ -108,7 +117,7 @@ if (state !== sessionStorage.getItem('oauth:state')) throw new Error('State mism
 
 const handler = createStartGGAuth2Handler({
   clientId: '<client-id>',
-  redirectUri: 'https://your.app/callback',
+  redirectUri: 'https://your.app/api/startgg/callback',
   authEndpoint: 'https://api.start.gg/oauth/authorize',
   tokenEndpoint: 'https://api.start.gg/oauth/token',
 });
@@ -249,7 +258,7 @@ startgg-oauth2-full/
 ## 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,84 @@
+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. */
+    refreshToken(refreshToken: string, originalScopes: StartGGScope[]): Promise<OAuth2TokenResponse>;
+}
+/** Factory */
+export declare function createStartGGAuth2Handler(params: {
+    clientId: string;
+    redirectUri: string;
+    authEndpoint: string;
+    tokenEndpoint: string;
+    fetchTimeoutMs?: number;
+}): StartGGOAuth2Handler;

package/dist/auth/StartGGOAuth2.js

@@ -0,0 +1,291 @@
+// 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!
+// (c) 2026 0xabadbabe (jet'aime), Inc. (MIT License)
+// Happy coding! <3
+export var StartGGScope;
+(function (StartGGScope) {
+    StartGGScope["USER_IDENTITY"] = "user.identity";
+    StartGGScope["USER_EMAIL"] = "user.email";
+    StartGGScope["TOURNAMENT_MANAGER"] = "tournament.manager";
+    StartGGScope["TOURNAMENT_REPORTER"] = "tournament.reporter";
+})(StartGGScope || (StartGGScope = {}));
+export class OAuth2Error extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = 'OAuth2Error';
+        this.code = code;
+        this.details = details;
+    }
+}
+export class ScopeValidationError extends OAuth2Error {
+    requestedScopes;
+    grantedScopes;
+    constructor(message, requestedScopes, grantedScopes) {
+        super(message, 'SCOPE_VALIDATION_FAILED');
+        this.requestedScopes = requestedScopes;
+        this.grantedScopes = grantedScopes;
+    }
+}
+/** WebCrypto subtle (browser + Node >=18). */
+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');
+}
+/** 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 = '';
+    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');
+    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, '');
+}
+/** Random bytes using WebCrypto. */
+function getRandomBytes(length) {
+    const g = globalThis;
+    if (!g.crypto?.getRandomValues)
+        throw new OAuth2Error('crypto.getRandomValues unavailable', 'RNG_UNAVAILABLE');
+    const bytes = new Uint8Array(length);
+    g.crypto.getRandomValues(bytes);
+    return bytes;
+}
+/** x-www-form-urlencoded body. */
+function formBody(params) {
+    const sp = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        sp.set(k, v);
+    return sp.toString();
+}
+/** Parse non-JSON error bodies safely. */
+async function parseJsonSafe(res) {
+    const txt = await res.text();
+    try {
+        return JSON.parse(txt);
+    }
+    catch {
+        return { raw: txt };
+    }
+}
+/** 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.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);
+    }
+}
+/** If scope omitted, assume unchanged (RFC 6749). */
+function validateScopesOrAssumePrevious(responseScope, requiredScopes) {
+    if (!requiredScopes.length)
+        return;
+    if (responseScope == null)
+        return;
+    const granted = new Set(responseScope.split(/\s+/).filter(Boolean));
+    const missing = requiredScopes.filter(s => !granted.has(s));
+    if (missing.length > 0) {
+        throw new ScopeValidationError(`Missing required scopes: ${missing.join(', ')}`, requiredScopes, Array.from(granted));
+    }
+}
+/** Fetch with timeout to avoid hangs. */
+async function fetchWithTimeout(input, init = {}) {
+    const { timeoutMs = 15000, ...rest } = init;
+    const ac = new AbortController();
+    const id = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        return await fetch(input, { ...rest, signal: ac.signal });
+    }
+    finally {
+        clearTimeout(id);
+    }
+}
+// -------- PKCE (RFC 7636) --------
+const PKCE_VERIFIER_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+export function generateCodeVerifier(length = 64) {
+    const len = Math.min(Math.max(length, 43), 128);
+    const alphabet = PKCE_VERIFIER_CHARS;
+    const alphabetLength = alphabet.length;
+    const maxValue = Math.floor(256 / alphabetLength) * alphabetLength;
+    const result = [];
+    while (result.length < len) {
+        const randomBytes = getRandomBytes(len - result.length);
+        for (const byte of randomBytes) {
+            if (byte >= maxValue)
+                continue; // Skip to avoid modulo bias.
+            result.push(alphabet.charAt(byte % alphabetLength));
+            if (result.length === len)
+                break;
+        }
+    }
+    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));
+    return base64Url(hash);
+}
+/** Build an authorization URL with PKCE (S256). */
+export async function buildAuthorizeUrl(cfg, opts) {
+    let codeVerifier;
+    let codeChallenge;
+    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');
+        }
+        codeVerifier = opts.codeVerifier;
+        codeChallenge = opts.codeChallenge;
+    }
+    else if (opts.codeVerifier) {
+        codeVerifier = opts.codeVerifier;
+        codeChallenge = await computeCodeChallengeS256(codeVerifier);
+    }
+    else if (opts.codeChallenge) {
+        throw new OAuth2Error('codeVerifier is required when providing codeChallenge', 'INVALID_PKCE_PAIR');
+    }
+    else {
+        codeVerifier = generateCodeVerifier();
+        codeChallenge = await computeCodeChallengeS256(codeVerifier);
+    }
+    const u = new URL(cfg.authEndpoint);
+    const params = {
+        response_type: 'code',
+        client_id: cfg.clientId,
+        redirect_uri: cfg.redirectUri,
+        scope: opts.scopes.map(String).join(' '),
+        code_challenge: codeChallenge,
+        code_challenge_method: 'S256',
+    };
+    if (opts.state)
+        params.state = opts.state;
+    if (opts.prompt)
+        params.prompt = opts.prompt;
+    if (opts.extras) {
+        for (const [k, v] of Object.entries(opts.extras))
+            if (v != null)
+                params[k] = String(v);
+    }
+    for (const [k, v] of Object.entries(params))
+        u.searchParams.set(k, v);
+    return { url: u.toString(), codeVerifier, codeChallenge };
+}
+// -------- Bearer Token Helper (RFC 6750) --------
+export class BearerToken {
+    accessToken;
+    tokenType;
+    refreshToken;
+    expiresAt; // epoch ms
+    constructor(init) {
+        this.accessToken = init.accessToken;
+        this.tokenType = init.tokenType;
+        this.refreshToken = init.refreshToken;
+        this.expiresAt = init.expiresAt;
+    }
+    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)
+            : undefined;
+        return new BearerToken({
+            accessToken: res.access_token,
+            tokenType: 'Bearer',
+            refreshToken: res.refresh_token,
+            expiresAt,
+        });
+    }
+    isExpired(nowMs = Date.now()) {
+        if (this.expiresAt == null)
+            return false; // unknown → treat as non-expiring
+        return nowMs >= this.expiresAt;
+    }
+    willExpireWithin(seconds, nowMs = Date.now()) {
+        if (this.expiresAt == null)
+            return false;
+        return this.expiresAt - nowMs <= seconds * 1000;
+    }
+    toAuthHeader() {
+        return { Authorization: `Bearer ${this.accessToken}` };
+    }
+    assertUsable(nowMs = Date.now()) {
+        if (this.isExpired(nowMs))
+            throw new OAuth2Error('Access token expired', 'TOKEN_EXPIRED');
+    }
+}
+// -------- Handler (RFC 6749 §4.1.3, §6) --------
+export class StartGGOAuth2Handler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Exchange authorization code for tokens (PKCE). */
+    async exchangeToken(code, codeVerifier, expectedScopes) {
+        const tokenRequest = {
+            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' },
+            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);
+        }
+        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. */
+    async refreshToken(refreshToken, originalScopes) {
+        const refreshRequest = {
+            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' },
+            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);
+        }
+        const tokenResponse = (await res.json());
+        validateTokenResponse(tokenResponse);
+        validateScopesOrAssumePrevious(tokenResponse.scope, originalScopes.map(String));
+        if (!tokenResponse.refresh_token)
+            tokenResponse.refresh_token = refreshToken;
+        return tokenResponse;
+    }
+}
+/** Factory */
+export function createStartGGAuth2Handler(params) {
+    return new StartGGOAuth2Handler(params);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './auth/StartGGOAuth2.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './auth/StartGGOAuth2.js';

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "startgg-oauth2-full",
-  "version": "0.2.0",
+  "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",
@@ -15,7 +28,7 @@
     "@types/node": "^22.7.5",
     "jest": "^29.7.0",
     "node-fetch": "^3.3.2",
-    "serve": "^14.2.1",
+    "serve": "^14.2.6",
     "ts-jest": "^29.2.5",
     "ts-node": "10.9.2",
     "tsx": "^4.19.0",

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,18 +0,0 @@
----
-name: Bug report
-about: Report a bug
----
-
-**Describe the bug**
-…
-
-**Repro**
-1. …
-2. …
-
-**Expected**
-…
-
-**Env**
-- Node:
-- Browser:

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,13 +0,0 @@
----
-name: Feature request
-about: Suggest an idea
----
-
-**Problem**
-…
-
-**Proposal**
-…
-
-**Alternatives**
-…

package/.github/pull_request_template.md

@@ -1,30 +0,0 @@
-# Pull Request
-
-## Summary
-Explain the change concisely. What does this PR do and why?
-
-## Type
-- [ ] feat (new feature)
-- [ ] fix (bug fix)
-- [ ] refactor (no functional change)
-- [ ] docs (docs only)
-- [ ] test (tests only)
-- [ ] chore (infrastructure/CI/build)
-
-## Checklist
-- [ ] I ran `npm run build` successfully.
-- [ ] I ran `npm test` successfully and added/updated tests where behavior changed.
-- [ ] I updated README/docs if public API or flows changed.
-- [ ] I did not commit secrets/tokens and scrubbed logs.
-
-## Breaking Changes
-- [ ] Yes — describe impact and migration steps below
-- [ ] No
-
-If **Yes**, detail migration notes:
-
-## Screenshots / Demos (if applicable)
-Paste or link minimal repro or demo outputs.
-
-## Related Issues
-Link to issues (e.g., #123).

package/.github/workflows/ci.yml

@@ -1,23 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [ main, master ]
-  pull_request:
-    branches: [ main, master ]
-
-jobs:
-  build-and-test:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-      - run: npm ci
-      - run: npm run build
-      - run: npm test -- --ci

package/.github/workflows/release.yml

@@ -1,60 +0,0 @@
-name: Release Publish
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch:
-
-jobs:
-  publish:
-    name: Publish to npm
-    if: github.event.release.draft == false && github.event.release.prerelease == false || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Verify tag matches package version
-        if: github.event_name == 'release'
-        run: |
-          TAG="${{ github.event.release.tag_name }}"
-          PKG_VERSION=$(node -p "require('./package.json').version")
-          if [ "$TAG" != "v$PKG_VERSION" ]; then
-            echo "Release tag $TAG does not match package version $PKG_VERSION"
-            exit 1
-          fi
-
-      - name: Build
-        run: npm run build
-
-      - name: Test
-        run: npm test -- --ci
-
-      - name: Publish
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Publish to GitHub Packages
-        env:
-          NODE_AUTH_TOKEN: ${{ github.token }}
-        run: |
-          ORIGINAL_NAME=$(node -p "require('./package.json').name")
-          OWNER_SCOPE=$(echo "${GITHUB_REPOSITORY_OWNER}" | tr '[:upper:]' '[:lower:]')
-          SCOPED_NAME="@${OWNER_SCOPE}/startgg-oauth2-full"
-          npm pkg set name="$SCOPED_NAME"
-          npm publish --registry https://npm.pkg.github.com
-          npm pkg set name="$ORIGINAL_NAME"

package/AGENTS.md

@@ -1,46 +0,0 @@
-# Repository Guidelines
-
-## Project Structure & Module Organization
-- `src/` contains the TypeScript OAuth2 helpers (PKCE generation, token exchange, authorize URL builder).
-- `__tests__/` mirrors the source with Jest specs (e.g., `pkce.test.ts`, `authorize-url.test.ts`).
-- `examples/` includes Node, server, and browser demos; use them to validate end-to-end flows.
-- Root config (`tsconfig.json`, `jest.config.ts`, `package.json`) defines tooling standards—change only with consensus.
-
-## Build, Test, and Development Commands
-- `npm run build` compiles TypeScript via `tsc`; run before opening a PR.
-- `npm test` runs the full Jest suite; add `-- pkce` (or similar) to target individual specs.
-- `npm run dev:node`, `npm run dev:node:server`, and `npm run dev:browser` start interactive demos for manual OAuth verification.
-
-## Coding Style & Naming Conventions
-- Write modern TypeScript (ES2022 target) with strict null checks enabled in `tsconfig.json`.
-- Use two-space indentation, semicolons, and single quotes to match the existing codebase.
-- Functions and variables use `camelCase`, classes and enums use `PascalCase`, constants use `SCREAMING_SNAKE_CASE` where appropriate.
-- Prefer small, self-documenting helpers; add concise comments only when logic is non-obvious.
-
-## Testing Guidelines
-- Jest with `ts-jest` handles unit tests; new behaviour requires corresponding specs in `__tests__/`.
-- Name test files after the module under test (e.g., `foo.test.ts`); keep describe blocks aligned with exported functions.
-- Ensure deterministic randomness in tests (stub RNGs) and cover error cases like PKCE validation failures.
-
-## Commit & Pull Request Guidelines
-- Craft commits in the form `type(scope): summary` (examples in history: `fix(pkce): cap verifier length`).
-- Each PR should explain the change, list validation steps (e.g., `npm test` output), and link related issues or tickets.
-- Include screenshots or curl transcripts when work affects interactive flows or API responses.
-
-## Security & Configuration Tips
-- PKCE relies on WebCrypto; document fallbacks if new runtimes lack `crypto.subtle`.
-- Never log tokens or verifiers in examples; scrub debug statements before merging.
-- Keep secrets out of version control and reference sample env files instead.
-
-## Agent Workflow Checklist
-- Sync `main`, install modules (`npm install`), and confirm `npm run build` passes.
-- Add focused Jest coverage for new logic and ensure `npm test` is green.
-- Update docs (`README.md`, `AGENTS.md`) when behaviour or workflows shift.
-- Capture manual verification steps (demo URLs, curl output) in the PR description.
-
-## Release Process
-- Bump `package.json` version and update changelog/notes as needed.
-- Commit and tag in `vX.Y.Z` form, then push the tag (`git push origin vX.Y.Z`).
-- Create a GitHub release using that tag; the `Release Publish` workflow runs automatically (or run it manually via **Run workflow**).
-- Ensure `NPM_TOKEN` is configured as a repository secret with publish rights to npm.
-- The workflow also publishes to GitHub Packages using `GITHUB_TOKEN`; consumers can install via `npm install @${repo_owner}/startgg-oauth2-full`.