scorezilla 0.3.0-next.1 → 0.3.0-next.3

package/API.md

@@ -1,10 +1,10 @@
 # Scorezilla SDK — API Reference
 
-> **Status:** v0.1.0 (public-key client). The HMAC server adapter
-> (`scorezilla/server`) ships in v0.2.0; React adapter in v0.3.0; Phaser in
-> v0.4.0. See [CHANGELOG.md](./CHANGELOG.md) and
-> [VERSIONING.md](./VERSIONING.md) for the release timeline and stability
-> guarantees.
+> **Status:** The public-key client and the HMAC server adapter
+> (`scorezilla/server` — incl. `createScoreSubmitHandler` + JWT verifiers) are
+> stable; the `scorezilla/identity` presets ship in 0.3.0. See
+> [CHANGELOG.md](./CHANGELOG.md) and [VERSIONING.md](./VERSIONING.md) for the
+> release timeline and stability guarantees.
 
 ## Quick start
 
@@ -50,8 +50,9 @@ type ScorezillaConfig = PublicKeyConfig /* | SecretKeyConfig — v0.2.0 */;
 
 - `publicKey`: `pk_<game-slug>_<base62-suffix>`. Issued by the operator
   dashboard. Safe to embed in browser code.
-- `secretKey` (v0.2.0+): `{ id: string, secret: 'sk_live_…' }`. Server-side
-  only. Used to compute HMAC signatures for the secure path.
+- `secretKey`: a single `sk_live_<keyId>_<random>` token (the keyId is embedded,
+  so you manage one value). Server-side only — used by the `scorezilla/server`
+  adapter to HMAC-sign the secure path. Never embed it in client code.
 
 ### Mutual exclusivity
 
@@ -255,6 +256,123 @@ try {
 }
 ```
 
+## Server adapter (`scorezilla/server`)
+
+The public-key client is client-authoritative — any player can submit any score
+from devtools. For ranking-sensitive boards, sign submissions server-side with a
+`sk_live_*` secret. Full recipes are in the
+[README](./README.md#server-side-hmac-scorezillaserver); the surface:
+
+### `Scorezilla` (server client)
+
+```ts
+import { Scorezilla } from 'scorezilla/server';
+
+const sz = new Scorezilla({
+  secretKey: process.env.SCOREZILLA_SECRET_KEY!, // sk_live_<keyId>_<random>
+});
+await sz.submitScore({ boardId, playerId, score, metadata });
+```
+
+Same methods as the public-key client (`submitScore`, `getLeaderboard`,
+`getPlayerRank`, `getWindowAround`); each request is HMAC-SHA256 signed and
+verified server-side. Server-only — importing it in a browser throws.
+
+### `createScoreSubmitHandler(config)`
+
+A framework-agnostic factory returning a `(Request) => Promise<Response>`
+handler (Cloudflare Workers, Next route handlers, Hono, Deno, Bun). You supply
+your auth via `verify`; it owns parsing/validation, signing, and error → HTTP
+mapping.
+
+```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! }),
+});
+```
+
+| Option                                               | Type                                             | Notes                                                                               |
+| ---------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `secretKey`                                          | `string`                                         | `sk_live_*`. Required.                                                              |
+| `boardId`                                            | `string`                                         | Required.                                                                           |
+| `verify`                                             | `(req) => { playerId, metadata? } \| null`       | Required. The submitted `playerId` always comes from here — never the request body. |
+| `parseSubmission?`                                   | `(req) => { score, metadata? } \| null`          | Defaults to JSON `{ score, metadata? }`.                                            |
+| `rateLimit?`                                         | `(req) => { ok, retryAfterSeconds? }`            | Runs **before** `verify`.                                                           |
+| `cors?`                                              | `{ origin, methods?, headers?, maxAgeSeconds? }` | OPTIONS preflight + reflected `Access-Control-Allow-Origin`.                        |
+| `baseUrl?` · `fetch?` · `maxRetries?` · `timeoutMs?` |                                                  | Pass-through to the server client.                                                  |
+
+### JWT verifiers
+
+Built-in `verify` helpers — each returns `(req) => Promise<{ playerId } | null>`.
+They require the optional peer dependency `jose` (loaded lazily; only consumers
+of a verifier install it).
+
+```ts
+import {
+  verifyJwt, // generic JWKS: { jwksUrl, issuer, audience, claim? }
+  verifySupabaseJwt, // { supabaseUrl }
+  verifyClerkJwt, // { issuer }
+  verifyAuth0Jwt, // { domain, audience }
+  verifyFirebaseIdToken, // { projectId }
+} from 'scorezilla/server';
+```
+
+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,93 @@
 # Changelog
 
+## 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
+
+- [#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.
+
 ## 0.3.0-next.1
 
 ### 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
@@ -122,6 +176,83 @@ browser throws at module evaluation. Use environment variables (or your
 secret manager) to load the `sk_live_*` value; never embed it in a build
 that ships to clients.
 
+### Turnkey endpoint: `createScoreSubmitHandler`
+
+Wiring the secure path by hand means verifying your auth, deriving the player
+id from it, validating the body, signing, and mapping errors.
+`createScoreSubmitHandler` does all of that — you supply only your auth. It
+returns a standard `(Request) => Promise<Response>`, so it drops 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!,
+  // The one app-specific bit: prove identity, return the TRUSTED playerId.
+  // The submitted playerId comes from here — never from the request body.
+  verify: async (req) => {
+    const user = await myAuth(req);
+    return user ? { playerId: user.id } : null;
+  },
+  cors: { origin: 'https://mygame.example' }, // omit for same-origin
+});
+```
+
+Your client just POSTs `{ score, metadata? }` (plus its auth header) to the
+endpoint; the handler signs and forwards it.
+
+**Supabase? One line.** Built-in verifiers do the JWKS verification for you.
+(`jose` is an optional peer dependency, loaded only when you use a built-in
+verifier — `npm i jose`.)
+
+```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! }),
+});
+```
+
+**Clerk, Auth0, and Firebase have presets too:**
+
+```ts
+import { verifyClerkJwt, verifyAuth0Jwt, verifyFirebaseIdToken } from 'scorezilla/server';
+
+verify: verifyClerkJwt({ issuer: 'https://clerk.your-app.com' });
+verify: verifyAuth0Jwt({ domain: 'you.us.auth0.com', audience: 'your-api' });
+verify: verifyFirebaseIdToken({ projectId: 'your-firebase-project' });
+```
+
+**Any other JWKS provider** uses the generic `verifyJwt`:
+
+```ts
+import { verifyJwt } from 'scorezilla/server';
+
+verify: verifyJwt({
+  jwksUrl: 'https://your-issuer/.well-known/jwks.json',
+  issuer: 'https://your-issuer',
+  audience: 'your-api', // claim: 'sub' (default) → playerId
+});
+```
+
+**Anything else** — the `verify` callback is the universal seam. For
+Auth.js/NextAuth (encrypted JWE sessions), Better Auth, opaque session
+cookies, or a provider backend SDK, anything that returns `{ playerId }`
+works:
+
+```ts
+verify: async (req) => {
+  const session = await validateSession(req); // your DB / SDK
+  return session ? { playerId: session.userId } : null;
+};
+```
+
+Worked recipes for each of those live in [RECIPES.md](./RECIPES.md).
+
 ## Error handling
 
 Every failure path — HTTP non-2xx, network error, timeout, abort, JSON parse

package/RECIPES.md

@@ -0,0 +1,227 @@
+# Auth recipes — `createScoreSubmitHandler`
+
+The built-in verifiers ([README](./README.md#turnkey-endpoint-createscoresubmithandler))
+cover auth systems that issue **JWKS-verifiable bearer tokens** — Supabase,
+Clerk, Auth0, Firebase, and any other provider via the generic `verifyJwt`.
+
+This doc covers everything else: sessions that **cannot** be verified against a
+public key set — encrypted session cookies (Auth.js), database-backed sessions
+(Better Auth, roll-your-own), and provider backend SDKs. They all plug into the
+same seam: the `verify` callback.
+
+## The `verify` contract
+
+```ts
+verify: (req: Request) => Promise<{ playerId: string; metadata?: object } | null>;
+```
+
+- Return `{ playerId }` on success. The submitted `playerId` **always** comes
+  from `verify` — a `playerId` in the request body is ignored.
+- Return `null` to reject (→ `401 unauthorized`). Throwing also rejects with
+  401; the error message is never surfaced to the client (it may carry token
+  internals), so prefer returning `null` explicitly.
+- Read identity from **headers/cookies only**. The request body is reserved for
+  the score payload (`parseSubmission` consumes it).
+- Optional `metadata` you return is trusted and **wins over** body metadata on
+  key conflicts — use it for server-verified fields like a display name.
+- The optional `rateLimit` gate runs **before** `verify`, so unauthenticated
+  spam can't drive your auth/crypto work. Per-user limits belong inside
+  `verify` (after you know who the user is).
+
+## Auth.js / NextAuth — encrypted JWE sessions
+
+Auth.js does not expose a JWKS: its session cookie is a **JWE** — encrypted
+with a key derived from `AUTH_SECRET` — so only your server can read it. Two
+ways to wire it:
+
+### In a Next.js App Router route handler
+
+Call your Auth.js instance's `auth()` inside `verify` — it reads the session
+from the ambient request context:
+
+```ts
+// app/api/submit-score/route.ts
+import { createScoreSubmitHandler } from 'scorezilla/server';
+import { auth } from '@/auth'; // your Auth.js config
+
+export const POST = createScoreSubmitHandler({
+  secretKey: process.env.SCOREZILLA_SECRET_KEY!,
+  boardId: process.env.SCOREZILLA_BOARD_ID!,
+  verify: async () => {
+    const session = await auth();
+    return session?.user?.id ? { playerId: session.user.id } : null;
+  },
+});
+```
+
+> **Note:** `session.user.id` is not populated by default with the JWT session
+> strategy — expose it in your Auth.js config's `session` callback
+> (`session.user.id = token.sub`), or use the `getToken` recipe below, where
+> `sub` is always present.
+
+### Anywhere else (framework-agnostic)
+
+`getToken` decrypts the session cookie (or `Authorization` header) directly
+from the `Request` — no Next context needed, so it works in the handler's
+`verify` on any runtime:
+
+```ts
+import { createScoreSubmitHandler } from 'scorezilla/server';
+import { getToken } from 'next-auth/jwt'; // or '@auth/core/jwt' outside Next
+
+export const handler = createScoreSubmitHandler({
+  secretKey: process.env.SCOREZILLA_SECRET_KEY!,
+  boardId: process.env.SCOREZILLA_BOARD_ID!,
+  verify: async (req) => {
+    const token = await getToken({
+      req,
+      secret: process.env.AUTH_SECRET!,
+      // The cookie name carries a __Secure- prefix on https. Auth.js infers
+      // this from AUTH_URL; set it explicitly where AUTH_URL isn't available.
+      secureCookie: true,
+    });
+    return token?.sub ? { playerId: token.sub } : null;
+  },
+});
+```
+
+NextAuth **v4** uses a different default cookie name — add
+`cookieName: 'next-auth.session-token'` (or its `__Secure-` variant) to the
+`getToken` call.
+
+## Better Auth — database-backed sessions
+
+Better Auth sessions are opaque tokens looked up server-side. Its server API
+takes the request headers directly:
+
+```ts
+import { createScoreSubmitHandler } from 'scorezilla/server';
+import { auth } from './auth'; // your Better Auth instance
+
+export const handler = createScoreSubmitHandler({
+  secretKey: process.env.SCOREZILLA_SECRET_KEY!,
+  boardId: process.env.SCOREZILLA_BOARD_ID!,
+  verify: async (req) => {
+    const session = await auth.api.getSession({ headers: req.headers });
+    return session ? { playerId: session.user.id } : null;
+  },
+});
+```
+
+## Any opaque session cookie
+
+For roll-your-own sessions (or anything storing a session id in a cookie and
+the session itself in a DB/KV/Redis), `verify` is a cookie parse + store
+lookup:
+
+```ts
+const SESSION_COOKIE = 'sid';
+
+verify: async (req) => {
+  const cookies = req.headers.get('cookie') ?? '';
+  const match = new RegExp(`(?:^|;\\s*)${SESSION_COOKIE}=([^;]+)`).exec(cookies);
+  if (!match) return null;
+
+  const session = await sessionStore.get(match[1]); // your DB / KV / Redis
+  if (!session || session.expiresAt < now()) return null;
+
+  return { playerId: session.userId };
+},
+```
+
+Encrypted-cookie systems (e.g. iron-session) are the same shape — replace the
+store lookup with the library's unseal/decrypt call and read the user id from
+the decrypted payload.
+
+## Provider backend SDKs
+
+Already shipping a provider's admin SDK? Wrap it instead of re-verifying
+tokens yourself. For example, Firebase Admin (alternative to the
+`verifyFirebaseIdToken` JWKS preset):
+
+```ts
+import { getAuth } from 'firebase-admin/auth';
+
+verify: async (req) => {
+  const token = req.headers.get('authorization')?.replace(/^Bearer\s+/i, '');
+  if (!token) return null;
+  try {
+    const decoded = await getAuth().verifyIdToken(token);
+    return { playerId: decoded.uid };
+  } catch {
+    return null; // bad signature / expired / wrong project
+  }
+},
+```
+
+The same pattern fits any backend SDK that authenticates a request or token
+and hands back a stable user id.
+
+## Returning trusted metadata
+
+Anything your session already proves can ride along as trusted metadata — it
+overrides whatever the client put in the body for the same keys:
+
+```ts
+verify: async (req) => {
+  const session = await auth.api.getSession({ headers: req.headers });
+  if (!session) return null;
+  return {
+    playerId: session.user.id,
+    metadata: { displayName: session.user.name }, // server-verified, wins over body
+  };
+},
+```
+
+## 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 —
+  only from the verified session/token. (The handler enforces the body half of
+  this for you.)
+- Use a stable, non-PII user id as `playerId` (auth user id, not an email).
+- Add a cheap per-IP `rateLimit` gate; do per-user limits inside `verify`.
+- Keep secrets (`SCOREZILLA_SECRET_KEY`, `AUTH_SECRET`, session-store
+  credentials) in env vars or a secret manager — never in client builds.
+- Set `cors` only if the game is served from a different origin than the
+  endpoint; omit it for same-origin.

package/dist/{errors-B7hyC-C5.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 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-B7hyC-C5.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 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 };