scorezilla 0.3.0-next.2 → 0.3.0

package/API.md

@@ -325,6 +325,54 @@ For non-JWKS auth (Auth.js JWE sessions, opaque sessions, provider backend
 SDKs), write your own `verify` — anything returning `{ playerId }` works. See
 [RECIPES.md](./RECIPES.md) for worked recipes.
 
+### `createGitHubOAuthHandler(config)`
+
+The server half of `useAuthProvider({ provider: 'github' })` (see the
+identity section below): a `(Request) => Promise<Response>` callback endpoint
+that exchanges GitHub's OAuth `code` (the client secret stays server-side),
+resolves the user id, and hands `{ id }` back to the sign-in popup via a
+`postMessage` pinned to your game's origin. Deploy it anywhere that speaks
+web `Request`/`Response`, and register its URL as the OAuth app's callback
+URL on GitHub.
+
+| Option          | Type     | Notes                                                               |
+| --------------- | -------- | ------------------------------------------------------------------- |
+| `clientId`      | `string` | Your GitHub OAuth app client ID. Required.                          |
+| `clientSecret`  | `string` | Server-only. Required.                                              |
+| `allowedOrigin` | `string` | Exact origin of the game page (the `postMessage` target). Required. |
+| `fetch?`        |          | Inject a fetch (testing / custom transport).                        |
+
+## Identity presets (`scorezilla/identity`)
+
+Browser-side helpers producing the `playerId` for `submitScore`. All of them
+are **client-authoritative** — see the trust-boundary note in the
+[README](./README.md#player-identity-scorezillaidentity); for spoof-proof
+identity use the secure path above.
+
+```ts
+import {
+  useAnonymousPlayer, // { storageKey } → PlayerHandle (UUID, persisted)
+  usePromptedPlayer, // { storageKey, prompt } → Promise<PlayerHandle>
+  useServerAuthoritative, // () → marker; playerId comes from your server
+  useAuthProvider, // OAuth sign-in → Promise<AuthPlayerHandle | null>
+} from 'scorezilla/identity';
+```
+
+### `useAuthProvider(options)`
+
+Discriminated on `provider`:
+
+| Provider   | Options                                 | Flow                                                                  |
+| ---------- | --------------------------------------- | --------------------------------------------------------------------- |
+| `'google'` | `clientId`, `storageKey`, `autoSelect?` | Google Identity Services One Tap, client-only                         |
+| `'github'` | `clientId`, `exchangeUrl`, `storageKey` | Popup → your deployed `createGitHubOAuthHandler` endpoint (see above) |
+
+Resolves an `AuthPlayerHandle` (`{ id, provider, source, signOut() }`) — or
+`null` when the player **declines** (dismissed One Tap, cancelled on GitHub,
+closed the popup). Throws only on genuine failures (invalid arguments, popup
+blocked, exchange endpoint failure). `source: 'restored'` means the id was
+rehydrated from `localStorage` without a fresh provider interaction.
+
 ## Advanced
 
 ### Custom fetch / polyfills

package/CHANGELOG.md

@@ -1,5 +1,194 @@
 # Changelog
 
+## 0.3.0
+
+### Minor Changes
+
+- [#45](https://github.com/isco-tec/scorezilla-js/pull/45) [`1a1e625`](https://github.com/isco-tec/scorezilla-js/commit/1a1e625cc6aff058071f922c7c5a619efa80ddc8) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(identity): ship the GitHub provider for `useAuthProvider` (scorezilla#194)
+
+  The GitHub option is real (and final, per ADR 0009): a popup OAuth web flow
+  on the client plus a turnkey server-side token exchange.
+  - `useAuthProvider({ provider: 'github', clientId, exchangeUrl, storageKey })`
+    — opens the GitHub sign-in popup, validates the callback by origin + state,
+    resolves `github:<id>` (or `null` on decline). The provisional option shape
+    is finalized: `clientId`, `exchangeUrl`, and `storageKey` are all required.
+  - `createGitHubOAuthHandler({ clientId, clientSecret, allowedOrigin })` (new
+    in `scorezilla/server`) — the deployable callback endpoint: exchanges the
+    code (secret stays server-side), resolves the user id, posts it back to the
+    game's origin, closes the popup. The access token never reaches the browser.
+  - size-limit: server caps 7 → 8 KB (documented); new tree-shaking proof pins
+    that adapter-only consumers pay for neither factory.
+
+- [#39](https://github.com/isco-tec/scorezilla-js/pull/39) [`608137f`](https://github.com/isco-tec/scorezilla-js/commit/608137f2a880fd3b9031cde8de765a5262d6c334) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(identity): ship the Google provider for `useAuthProvider`
+
+  `useAuthProvider({ provider: 'google', clientId, storageKey })` is now
+  implemented and **stable**. It wraps Google Identity Services ("One Tap"),
+  derives a stable, opaque player id from the account's `sub` claim
+  (`google:<sub>`), and persists it in `localStorage` so returning visitors are
+  recognized without signing in again.
+
+  ```ts
+  import { Scorezilla } from 'scorezilla';
+  import { useAuthProvider } from 'scorezilla/identity';
+
+  const player = await useAuthProvider({
+    provider: 'google',
+    clientId: 'YOUR_CLIENT_ID.apps.googleusercontent.com',
+    storageKey: 'mygame:player',
+  });
+
+  if (player) {
+    const sz = new Scorezilla({ publicKey: 'pk_…' });
+    await sz.submitScore({ boardId, playerId: player.id, score: 42 });
+    // player.signOut() clears the persisted id and disables Google auto-select.
+  }
+  ```
+
+  - **Resolves `null` when the player declines** or One Tap can't be shown — a
+    dismissed sign-in is not an error. It **rejects** only on genuine failures
+    (invalid args, script load failure, malformed credential).
+  - **`handle.source`** is `'signed-in'` for a fresh sign-in or `'restored'` when
+    the id was rehydrated from `localStorage` (a restored id is not a re-verified
+    live session).
+  - **Bring your own client ID.** The SDK never bundles Scorezilla-owned OAuth
+    credentials, so revocation and consent stay under your control.
+  - **Privacy.** Only the derived `sub`-based id is stored and transmitted on
+    score submission — never the Google credential, email, or profile.
+  - **Bundle.** The Google provider tree-shakes out for consumers who don't call
+    `useAuthProvider`; the Google Identity Services library is loaded at runtime
+    from `accounts.google.com`, never bundled.
+  - `useAuthProvider` is now async (replacing the `0.3.0-next.0` preview stub that
+    threw synchronously). Despite the `use*` name it is **not** a React hook.
+    Identity errors are plain `Error`/`TypeError` (not `ScorezillaError`), keeping
+    the `scorezilla/identity` subpath dependency-free. The host page's CSP must
+    allow `https://accounts.google.com`.
+  - The **GitHub** provider is not available yet — it ships in a follow-up and
+    will require a server-side token exchange (your backend or a Scorezilla
+    Workers proxy). Calling `useAuthProvider({ provider: 'github' })` rejects
+    with guidance until then.
+
+- [#36](https://github.com/isco-tec/scorezilla-js/pull/36) [`19c2dcc`](https://github.com/isco-tec/scorezilla-js/commit/19c2dcc14d2000551d80498813b075172c8f4d66) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(identity): preset helpers for `scorezilla/identity` (Phase 1)
+
+  New subpath export: `scorezilla/identity`. Three identity-strategy
+  presets ship as `stable`; one OAuth helper ships as a preview stub.
+
+  **Stable in this release:**
+  - `useAnonymousPlayer({ storageKey })` — generates a UUID, persists in
+    localStorage, same browser keeps the same id across reloads. Returns
+    `{ id, forget() }`. Privacy-safe by default (no PII).
+  - `usePromptedPlayer({ storageKey, prompt })` — `window.prompt()` on
+    first run, persists to localStorage. Returns `{ id, forget() } | null`
+    (null when SSR, no `prompt`, or user cancels).
+  - `useServerAuthoritative()` — no-op marker for snippets using the
+    HMAC-signed secure path (`scorezilla/server`). The browser SDK does
+    no identity work; the server picks the value.
+
+  **Preview stub in this release (throws on call):**
+  - `useAuthProvider({ provider: 'google' | 'github' })` — OAuth-backed
+    identity. Full implementation (Google + GitHub for v1) ships in a
+    follow-up `next` release before the 0.3.0 latest promote.
+
+  Per [ADR 0003](https://github.com/isco-tec/scorezilla/blob/main/docs/adr/0003-mcp-identity-axis.md). All helpers document where data is stored and
+  what `forget()` / `signOut()` does NOT do (server-side history is
+  retained — call admin delete-player for full erasure).
+
+  Closes upstream tracking issue isco-tec/scorezilla#125 (Phase 1).
+
+- [#41](https://github.com/isco-tec/scorezilla-js/pull/41) [`e48a5a2`](https://github.com/isco-tec/scorezilla-js/commit/e48a5a2f09cd0f098e8466b51586bd4108bb5678) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(server): `createScoreSubmitHandler()` — turnkey secure score submissions
+
+  A framework-agnostic factory in `scorezilla/server` that collapses the secure
+  (HMAC-signed) submission path from ~150 lines of boilerplate into a few. It
+  returns a standard `(Request) => Promise<Response>` handler — drop it into a
+  Cloudflare Worker, a Next.js route handler, Hono, Deno, or Bun.
+
+  ```ts
+  import { createScoreSubmitHandler } from 'scorezilla/server';
+
+  export const POST = createScoreSubmitHandler({
+    secretKey: process.env.SCOREZILLA_SECRET_KEY!,
+    boardId: process.env.SCOREZILLA_BOARD_ID!,
+    verify: async (req) => {
+      // your auth — any provider; return the trusted playerId
+      const user = await myAuth(req);
+      return user ? { playerId: user.id } : null;
+    },
+  });
+  ```
+
+  - The submitted `playerId` always comes from `verify` (the verified request),
+    never the request body — so ranking-sensitive boards aren't subject to the
+    client-authoritative submission of the public-key path.
+  - Owns body parsing/validation, HMAC signing, and `ScorezillaError` → HTTP
+    status mapping. Optional `cors` (OPTIONS preflight + reflected origin) and a
+    pre-verify `rateLimit` gate.
+  - Works with **any** auth via the `verify` callback (Supabase / Clerk / Auth0 /
+    Firebase JWTs, Lucia / opaque sessions, or a provider backend SDK). First-class
+    one-line verifiers (`verifySupabaseJwt`, `verifyJwt`) follow.
+
+- [#42](https://github.com/isco-tec/scorezilla-js/pull/42) [`7ca5976`](https://github.com/isco-tec/scorezilla-js/commit/7ca5976857cfff44cc3a3c155181cd9f6276aea0) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(server): built-in `verifyJwt` + `verifySupabaseJwt` for `createScoreSubmitHandler`
+
+  Turn the common "verify a JWT, derive the player id" step into a one-liner.
+  Both return a `verify` function you drop straight into `createScoreSubmitHandler`.
+
+  ```ts
+  import { createScoreSubmitHandler, verifySupabaseJwt } from 'scorezilla/server';
+
+  export const POST = createScoreSubmitHandler({
+    secretKey: process.env.SCOREZILLA_SECRET_KEY!,
+    boardId: process.env.SCOREZILLA_BOARD_ID!,
+    verify: verifySupabaseJwt({ supabaseUrl: process.env.SUPABASE_URL! }),
+  });
+  ```
+
+  - `verifyJwt({ jwksUrl, issuer, audience, claim? })` — generic JWKS verifier,
+    plus first-class presets for the popular providers: `verifySupabaseJwt({
+supabaseUrl })`, `verifyClerkJwt({ issuer })`, `verifyAuth0Jwt({ domain,
+audience })`, and `verifyFirebaseIdToken({ projectId })`.
+  - **`jose` is an optional peer dependency**, loaded lazily via dynamic
+    `import()` — consumers who use the public-key client, the factory with their
+    own `verify`, or a provider backend SDK never install or load it.
+
+### Patch Changes
+
+- [#44](https://github.com/isco-tec/scorezilla-js/pull/44) [`e7fcc42`](https://github.com/isco-tec/scorezilla-js/commit/e7fcc4262b5d0a706d29f05333335f746307cb47) Thanks [@isco-tec](https://github.com/isco-tec)! - docs: make the `useAuthProvider` trust boundary explicit (scorezilla#213)
+
+  Client OAuth identity is sign-in convenience, not anti-forgery — the derived
+  id is computed client-side and submitted with the public key. New
+  trust-boundary notes on the `useAuthProvider` JSDoc and `AuthPlayerHandle`, a
+  "Player identity" section in the README, and a RECIPES.md recipe ("OAuth
+  identity and the secure path") routing ranking-sensitive boards to
+  `createScoreSubmitHandler` with a server-verified identity.
+
+## 0.3.0-next.3
+
+### Minor Changes
+
+- [#45](https://github.com/isco-tec/scorezilla-js/pull/45) [`1a1e625`](https://github.com/isco-tec/scorezilla-js/commit/1a1e625cc6aff058071f922c7c5a619efa80ddc8) Thanks [@isco-tec](https://github.com/isco-tec)! - feat(identity): ship the GitHub provider for `useAuthProvider` (scorezilla#194)
+
+  The GitHub option is real (and final, per ADR 0009): a popup OAuth web flow
+  on the client plus a turnkey server-side token exchange.
+  - `useAuthProvider({ provider: 'github', clientId, exchangeUrl, storageKey })`
+    — opens the GitHub sign-in popup, validates the callback by origin + state,
+    resolves `github:<id>` (or `null` on decline). The provisional option shape
+    is finalized: `clientId`, `exchangeUrl`, and `storageKey` are all required.
+  - `createGitHubOAuthHandler({ clientId, clientSecret, allowedOrigin })` (new
+    in `scorezilla/server`) — the deployable callback endpoint: exchanges the
+    code (secret stays server-side), resolves the user id, posts it back to the
+    game's origin, closes the popup. The access token never reaches the browser.
+  - size-limit: server caps 7 → 8 KB (documented); new tree-shaking proof pins
+    that adapter-only consumers pay for neither factory.
+
+### Patch Changes
+
+- [#44](https://github.com/isco-tec/scorezilla-js/pull/44) [`e7fcc42`](https://github.com/isco-tec/scorezilla-js/commit/e7fcc4262b5d0a706d29f05333335f746307cb47) Thanks [@isco-tec](https://github.com/isco-tec)! - docs: make the `useAuthProvider` trust boundary explicit (scorezilla#213)
+
+  Client OAuth identity is sign-in convenience, not anti-forgery — the derived
+  id is computed client-side and submitted with the public key. New
+  trust-boundary notes on the `useAuthProvider` JSDoc and `AuthPlayerHandle`, a
+  "Player identity" section in the README, and a RECIPES.md recipe ("OAuth
+  identity and the secure path") routing ranking-sensitive boards to
+  `createScoreSubmitHandler` with a server-verified identity.
+
 ## 0.3.0-next.2
 
 ### Minor Changes

package/README.md

@@ -92,6 +92,60 @@ await sz.getWindowAround({ boardId, playerId, before?, after? });
 See [**API.md**](./API.md) for the full reference, including every response
 field, every error code, and advanced patterns.
 
+## Player identity (`scorezilla/identity`)
+
+Browser-side helpers that produce the `playerId` you pass to `submitScore`:
+
+```ts
+import {
+  useAnonymousPlayer, // mints a UUID, persists in localStorage — no prompt
+  usePromptedPlayer, // asks once for a nickname, saves it, silent thereafter
+  useAuthProvider, // OAuth sign-in (Google + GitHub)
+} from 'scorezilla/identity';
+
+const player = await useAuthProvider({
+  provider: 'google',
+  clientId: 'YOUR_GOOGLE_CLIENT_ID.apps.googleusercontent.com',
+  storageKey: 'mygame:player',
+});
+if (player) await sz.submitScore({ boardId, playerId: player.id, score: 9001 });
+```
+
+**GitHub** needs one extra ingredient: GitHub's token exchange requires your
+OAuth app's client secret, so you deploy a one-line exchange endpoint
+(`createGitHubOAuthHandler` from `scorezilla/server`) and point the client at
+it:
+
+```ts
+// Client — opens a GitHub sign-in popup; resolves github:<id> (or null on decline).
+const player = await useAuthProvider({
+  provider: 'github',
+  clientId: 'YOUR_GITHUB_OAUTH_CLIENT_ID',
+  exchangeUrl: '/api/github-oauth',
+  storageKey: 'mygame:player',
+});
+
+// Server — deploy at /api/github-oauth and register that URL as the OAuth
+// app's callback URL on GitHub. The secret + access token never reach the browser.
+import { createGitHubOAuthHandler } from 'scorezilla/server';
+
+export const GET = createGitHubOAuthHandler({
+  clientId: process.env.GITHUB_CLIENT_ID!,
+  clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+  allowedOrigin: 'https://mygame.example', // your game page's origin
+});
+```
+
+> **Trust boundary — all of these are client-authoritative.** `useAuthProvider`
+> proves the player's identity _to the browser_, not to the leaderboard: the
+> derived id is computed client-side and submitted with the public key, so it
+> is exactly as forgeable as any other public-key write. OAuth identity is
+> sign-in convenience for casual/vanity boards — **not anti-forgery**. For
+> competitive or ranking-sensitive boards, submit through the secure path
+> below (`createScoreSubmitHandler` + a server-verified identity); see
+> [RECIPES.md](./RECIPES.md) for the combined "OAuth identity + secure
+> submission" recipe.
+
 ## Server-side HMAC (`scorezilla/server`)
 
 Public-key submissions are client-authoritative — anyone with your `pk_` can

package/RECIPES.md

@@ -173,6 +173,47 @@ verify: async (req) => {
 },
 ```
 
+## OAuth identity and the secure path
+
+`useAuthProvider` (from `scorezilla/identity`) is **client-authoritative**: it
+proves the player's identity to the browser, not to your endpoint — the
+`google:<sub>` / `github:<id>` ids arrive at your endpoint from the client,
+with no credential attached for `verify` to check. (Yes, the GitHub flow's
+exchange endpoint verifies identity — but only inside the sign-in popup; at
+score-submit time the id is still client-asserted.) Combining `useAuthProvider`
+with the secure path looks like one of these:
+
+**Your app has real auth (recommended).** Trust comes from your auth platform;
+the OAuth handle is just sign-in UX. Verify the platform session as usual —
+the verified user id is the `playerId`:
+
+```ts
+// Identity for TRUST: the verified Supabase/Clerk/Auth0/Firebase session.
+verify: verifySupabaseJwt({ supabaseUrl: process.env.SUPABASE_URL! }),
+```
+
+If you want the OAuth display identity alongside, send it in the request
+body's `metadata` — it's treated as untrusted client data, which is exactly
+what it is.
+
+**OAuth-only, no backend auth.** You can still route submissions through
+`createScoreSubmitHandler` to keep `sk_*` off the client and gain payload
+validation + rate limiting — but identity stays client-asserted, and the
+endpoint should say so:
+
+```ts
+// ⚠️ Client-asserted: any client can claim any id. Acceptable for casual
+// boards; NOT for ranking-sensitive ones — add real auth for that.
+verify: async (req) => {
+  const playerId = req.headers.get('x-player-id'); // e.g. the google:<sub> id
+  return playerId ? { playerId } : null;
+},
+```
+
+There is no middle option: an id that arrives from the browser without a
+verifiable credential cannot be promoted to trusted server-side, no matter
+which OAuth provider produced it.
+
 ## Hardening checklist
 
 - **Never** derive `playerId` from the request body or an unverified header —

package/dist/{errors-CtXMAHtJ.d.cts → errors-CWTmormh.d.cts}

@@ -363,4 +363,4 @@ declare class ScorezillaError extends Error {
     static timeout(timeoutMs: number): ScorezillaError;
 }
 
-export { type ApiSuccess as A, type BaseConfig as B, type FetchImpl as F, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type SecretKeyConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, ScorezillaError as b, type ScorezillaErrorCode as c, type ScorezillaConfig as d, type ApiError as e, type ApiResponse as f, type PublicKeyConfig as g };
+export { type ApiSuccess as A, type BaseConfig as B, type FetchImpl as F, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type ScorezillaConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, type ApiError as b, type ApiResponse as c, type PublicKeyConfig as d, ScorezillaError as e, type ScorezillaErrorCode as f, type SecretKeyConfig as g };

package/dist/{errors-CtXMAHtJ.d.ts → errors-CWTmormh.d.ts}

@@ -363,4 +363,4 @@ declare class ScorezillaError extends Error {
     static timeout(timeoutMs: number): ScorezillaError;
 }
 
-export { type ApiSuccess as A, type BaseConfig as B, type FetchImpl as F, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type SecretKeyConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, ScorezillaError as b, type ScorezillaErrorCode as c, type ScorezillaConfig as d, type ApiError as e, type ApiResponse as f, type PublicKeyConfig as g };
+export { type ApiSuccess as A, type BaseConfig as B, type FetchImpl as F, type LeaderboardResponse as L, type OutOfBoundsReason as O, type PlayerRankResponse as P, type RankedEntry as R, type ScorezillaConfig as S, type WindowAroundResponse as W, type SubmitScoreResponse as a, type ApiError as b, type ApiResponse as c, type PublicKeyConfig as d, ScorezillaError as e, type ScorezillaErrorCode as f, type SecretKeyConfig as g };

package/dist/identity.cjs

@@ -143,6 +143,94 @@ async function signInWithGoogle(params) {
   return credential === null ? null : decodeSubFromIdToken(credential);
 }
 
+// src/identity/github.ts
+var GITHUB_AUTHORIZE_URL = "https://github.com/login/oauth/authorize";
+var GITHUB_MESSAGE_SOURCE = "scorezilla:github-oauth";
+var POPUP_CLOSED_POLL_MS = 500;
+var SIGN_IN_TIMEOUT_MS = 10 * 60 * 1e3;
+var KNOWN_ERRORS = /* @__PURE__ */ new Set(["access_denied", "exchange_failed"]);
+var ID_RE = /^\d{1,20}$/;
+function randomState() {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let out = "";
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+  for (const b of bytes) out += alphabet[b & 63];
+  return out;
+}
+async function signInWithGitHub(params) {
+  const exchangeUrl = new URL(params.exchangeUrl, window.location.href);
+  const state = randomState();
+  const authorize = new URL(GITHUB_AUTHORIZE_URL);
+  authorize.searchParams.set("client_id", params.clientId);
+  authorize.searchParams.set("redirect_uri", exchangeUrl.toString());
+  authorize.searchParams.set("state", state);
+  const popup = window.open(
+    authorize.toString(),
+    "scorezilla-github-oauth",
+    "popup,width=600,height=700"
+  );
+  if (popup === null) {
+    throw new Error(
+      "useAuthProvider: the GitHub sign-in popup was blocked. Call useAuthProvider from a user gesture (e.g. a click handler), or allow popups for this site."
+    );
+  }
+  return new Promise((resolve, reject) => {
+    const pollTimer = setInterval(() => {
+      if (popup.closed) settle(() => resolve(null));
+    }, POPUP_CLOSED_POLL_MS);
+    const timeoutTimer = setTimeout(() => {
+      settle(
+        () => reject(
+          new Error(
+            "useAuthProvider: GitHub sign-in timed out. If this recurs, check that exchangeUrl is deployed and reachable."
+          )
+        )
+      );
+    }, SIGN_IN_TIMEOUT_MS);
+    const settle = (action) => {
+      window.removeEventListener("message", onMessage);
+      clearInterval(pollTimer);
+      clearTimeout(timeoutTimer);
+      if (!popup.closed) popup.close();
+      action();
+    };
+    const onMessage = (event) => {
+      if (event.origin !== exchangeUrl.origin) return;
+      const data = event.data;
+      if (data === null || typeof data !== "object") return;
+      if (data.source !== GITHUB_MESSAGE_SOURCE) return;
+      if (data.state !== state) return;
+      if (typeof data.error === "string" && data.error.length > 0) {
+        if (data.error === "access_denied") {
+          settle(() => resolve(null));
+          return;
+        }
+        const safeError = KNOWN_ERRORS.has(data.error) ? data.error : "exchange_failed";
+        settle(
+          () => reject(
+            new Error(
+              `useAuthProvider: GitHub token exchange failed (${safeError}). Check the exchange endpoint logs and its GitHub OAuth app credentials.`
+            )
+          )
+        );
+        return;
+      }
+      if (typeof data.id === "string" && ID_RE.test(data.id)) {
+        settle(() => resolve(data.id));
+        return;
+      }
+      settle(
+        () => reject(
+          new Error(
+            "useAuthProvider: the GitHub exchange endpoint posted a malformed callback message (missing or non-numeric id). Is exchangeUrl pointing at createGitHubOAuthHandler (or an equivalent implementation)?"
+          )
+        )
+      );
+    };
+    window.addEventListener("message", onMessage);
+  });
+}
+
 // src/identity.ts
 var isBrowser = () => typeof window !== "undefined";
 function readPersisted(key) {
@@ -227,9 +315,7 @@ async function useAuthProvider(options) {
     case "google":
       return signInWithGoogleProvider(options);
     case "github":
-      throw new Error(
-        'useAuthProvider: the GitHub provider is not available yet. It ships in scorezilla@0.3.0-next.2 and will require a server-side token exchange (your backend or a Scorezilla Workers proxy), because GitHub OAuth cannot be completed securely in the browser alone. Until then use provider: "google", or drive your own GitHub OAuth flow and pass the resulting id to submitScore.'
-      );
+      return signInWithGitHubProvider(options);
     default:
       throw new TypeError(
         `useAuthProvider: unknown provider ${JSON.stringify(
@@ -268,6 +354,32 @@ async function signInWithGoogleProvider(options) {
   googleSignInInFlight.set(storageKey, run);
   return run;
 }
+var githubSignInInFlight = /* @__PURE__ */ new Map();
+async function signInWithGitHubProvider(options) {
+  const clientId = requireNonEmptyString("useAuthProvider", "clientId", options.clientId);
+  const exchangeUrl = requireNonEmptyString("useAuthProvider", "exchangeUrl", options.exchangeUrl);
+  const storageKey = requireNonEmptyString("useAuthProvider", "storageKey", options.storageKey);
+  const persisted = readPersisted(storageKey);
+  if (persisted !== null && persisted.length > 0) {
+    return makeAuthHandle(persisted, "github", storageKey, "restored");
+  }
+  if (!isBrowser()) {
+    throw new Error("useAuthProvider: GitHub sign-in requires a browser environment.");
+  }
+  const existing = githubSignInInFlight.get(storageKey);
+  if (existing) return existing;
+  const run = (async () => {
+    const userId = await signInWithGitHub({ clientId, exchangeUrl });
+    if (userId === null) return null;
+    const id = `github:${userId}`;
+    writePersisted(storageKey, id);
+    return makeAuthHandle(id, "github", storageKey, "signed-in");
+  })().finally(() => {
+    githubSignInInFlight.delete(storageKey);
+  });
+  githubSignInInFlight.set(storageKey, run);
+  return run;
+}
 function makeAuthHandle(id, provider, storageKey, source) {
   return {
     id,
@@ -275,7 +387,7 @@ function makeAuthHandle(id, provider, storageKey, source) {
     source,
     signOut: () => {
       removePersisted(storageKey);
-      disableGoogleAutoSelect();
+      if (provider === "google") disableGoogleAutoSelect();
     }
   };
 }