scorezilla 0.3.0-next.0 → 0.3.0-next.2

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,75 @@ 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.
+
 ## Advanced
 
 ### Custom fetch / polyfills

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## 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
+
+- [#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.
+
 ## 0.3.0-next.0
 
 ### Minor Changes

package/README.md

@@ -122,6 +122,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,186 @@
+# 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
+  };
+},
+```
+
+## 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-CtXMAHtJ.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 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 };

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