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

package/dist/server.d.cts

@@ -1,5 +1,187 @@
-import { S as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-B7hyC-C5.cjs';
-export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-B7hyC-C5.cjs';
+import { F as FetchImpl, g as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-CWTmormh.cjs';
+export { R as RankedEntry, e as ScorezillaError, f as ScorezillaErrorCode } from './errors-CWTmormh.cjs';
+
+/**
+ * Built-in request verifiers for {@link createScoreSubmitHandler} (#211).
+ *
+ * These turn the common "verify a JWT, derive the player id from a claim"
+ * shape into a one-liner. They produce a function with the same signature as
+ * the handler's `verify` callback, so they drop straight in:
+ *
+ * ```ts
+ * import { createScoreSubmitHandler, verifySupabaseJwt } from 'scorezilla/server';
+ *
+ * createScoreSubmitHandler({
+ *   secretKey, boardId,
+ *   verify: verifySupabaseJwt({ supabaseUrl: process.env.SUPABASE_URL! }),
+ * });
+ * ```
+ *
+ * **`jose` is an optional peer dependency.** Only these verifiers use it, and
+ * only via a lazy `import('jose')` — so consumers who use the public-key
+ * client, the factory with their own `verify`, or a provider backend SDK never
+ * install or load it. If you call a built-in verifier without `jose` present,
+ * it throws a clear "install jose" error.
+ */
+
+/** Same shape as the handler's `verify` callback. */
+type RequestVerifier = (req: Request) => Promise<VerifiedIdentity | null>;
+/** Options for the generic JWKS verifier {@link verifyJwt}. */
+interface VerifyJwtOptions {
+    /** JWKS endpoint, e.g. `https://issuer/.well-known/jwks.json`. */
+    readonly jwksUrl: string | URL;
+    /** Expected `iss` claim — strongly recommended. */
+    readonly issuer?: string | string[];
+    /** Expected `aud` claim — strongly recommended. */
+    readonly audience?: string | string[];
+    /** Which claim becomes the `playerId`. Default `'sub'`. */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/** Options for the Supabase preset {@link verifySupabaseJwt}. */
+interface VerifySupabaseJwtOptions {
+    /** Your Supabase project URL, e.g. `https://abcd.supabase.co`. */
+    readonly supabaseUrl: string;
+    /** Which claim becomes the `playerId`. Default `'sub'`. */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Generic JWKS-backed JWT verifier. Verifies a `Bearer` token against the
+ * given JWKS and returns `{ playerId }` from the configured claim (default
+ * `sub`), or `null` if there's no token or verification fails.
+ *
+ * Covers the modern provider majority (Supabase, Clerk, Auth0, Firebase,
+ * WorkOS, …) — they differ only by `jwksUrl` / `issuer` / `audience`.
+ *
+ * @since 0.3.0
+ */
+declare function verifyJwt(options: VerifyJwtOptions): RequestVerifier;
+/**
+ * Supabase preset over {@link verifyJwt}. Verifies a Supabase user JWT via the
+ * project's JWKS and derives the `playerId` from `sub`.
+ *
+ * ```ts
+ * verify: verifySupabaseJwt({ supabaseUrl: process.env.SUPABASE_URL! })
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function verifySupabaseJwt(options: VerifySupabaseJwtOptions): RequestVerifier;
+/** Options for the Clerk preset {@link verifyClerkJwt}. */
+interface VerifyClerkJwtOptions {
+    /**
+     * Your Clerk instance issuer (the token's `iss`), e.g.
+     * `https://clerk.your-app.com` or `https://<slug>.clerk.accounts.dev`. The
+     * JWKS URL is derived from it.
+     */
+    readonly issuer: string;
+    /**
+     * Expected `aud`. Clerk session tokens have **no** `aud` by default, so leave
+     * this unset unless you added one via a custom JWT template.
+     */
+    readonly audience?: string | string[];
+    /** Which claim becomes the `playerId`. Default `'sub'` (the Clerk user id). */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Clerk preset over {@link verifyJwt}. Verifies a Clerk session JWT against the
+ * instance JWKS and derives the `playerId` from `sub` (the Clerk user id).
+ *
+ * @since 0.3.0
+ */
+declare function verifyClerkJwt(options: VerifyClerkJwtOptions): RequestVerifier;
+/** Options for the Auth0 preset {@link verifyAuth0Jwt}. */
+interface VerifyAuth0JwtOptions {
+    /** Your Auth0 domain, e.g. `your-tenant.us.auth0.com` (scheme optional). */
+    readonly domain: string;
+    /** Your API identifier — the access token's `aud`. */
+    readonly audience: string | string[];
+    /** Which claim becomes the `playerId`. Default `'sub'`. */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Auth0 preset over {@link verifyJwt}. Note Auth0's issuer carries a trailing
+ * slash (`https://<domain>/`) — the preset adds it for you.
+ *
+ * @since 0.3.0
+ */
+declare function verifyAuth0Jwt(options: VerifyAuth0JwtOptions): RequestVerifier;
+/** Options for the Firebase preset {@link verifyFirebaseIdToken}. */
+interface VerifyFirebaseIdTokenOptions {
+    /** Your Firebase project id — both the token's `aud` and the issuer suffix. */
+    readonly projectId: string;
+    /** Which claim becomes the `playerId`. Default `'sub'` (the Firebase uid). */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Firebase Authentication preset over {@link verifyJwt}. Verifies a Firebase ID
+ * token (`iss = https://securetoken.google.com/<projectId>`, `aud = projectId`)
+ * and derives the `playerId` from `sub` (the Firebase uid).
+ *
+ * @since 0.3.0
+ */
+declare function verifyFirebaseIdToken(options: VerifyFirebaseIdTokenOptions): RequestVerifier;
+
+/**
+ * `createGitHubOAuthHandler` — the server-side callback leg of the GitHub
+ * identity provider (`useAuthProvider({ provider: 'github' })`, ADR 0009).
+ *
+ * GitHub redirects the sign-in popup here with `?code=&state=`. This handler:
+ *   1. validates the query strictly (formats are pinned — anything else is a
+ *      400, never reflected);
+ *   2. exchanges the code at GitHub's token endpoint — the client secret
+ *      stays on this server, and the resulting access token is used for ONE
+ *      `/user` lookup and then discarded;
+ *   3. responds with a tiny HTML page that `postMessage`s
+ *      `{ source: 'scorezilla:github-oauth', state, id }` to `window.opener`,
+ *      pinned to `allowedOrigin`, and closes the popup.
+ *
+ * The browser side (`scorezilla/identity`) accepts the message only when the
+ * origin matches its `exchangeUrl` and the `state` echoes the one it
+ * generated — this page is the only party that can complete a sign-in.
+ *
+ * Returns a standard `(Request) => Promise<Response>`: deploy it on any web
+ * runtime (a Next.js route handler, Hono, Deno, Bun, a Cloudflare Worker).
+ * Configure the deployed URL as the OAuth app's callback URL on GitHub.
+ *
+ * @since 0.3.0
+ */
+
+interface CreateGitHubOAuthHandlerConfig {
+    /** Your GitHub OAuth app client ID. */
+    readonly clientId: string;
+    /** Your GitHub OAuth app client secret. Server-only — never ships to a browser. */
+    readonly clientSecret: string;
+    /**
+     * The exact origin of the GAME page that opens the sign-in popup, e.g.
+     * `https://mygame.example`. Used as the `postMessage` target origin so the
+     * sign-in result can only be delivered to your page — never `*`.
+     */
+    readonly allowedOrigin: string;
+    /** Inject a `fetch` (testing / custom transport). */
+    readonly fetch?: FetchImpl;
+}
+/** The web-standard request handler returned by {@link createGitHubOAuthHandler}. */
+type GitHubOAuthHandler = (req: Request) => Promise<Response>;
+/**
+ * Build the GitHub OAuth callback endpoint. See module docs for the flow;
+ * see `GitHubAuthProviderOptions` in `scorezilla/identity` for the matching
+ * client half.
+ *
+ * **Construction patterns.** In Node/Next, secrets are in `process.env`, so
+ * build the handler once at module scope. In Cloudflare Workers, secrets
+ * live on the per-request `env` binding, so build it inside `fetch`.
+ */
+declare function createGitHubOAuthHandler(config: CreateGitHubOAuthHandlerConfig): GitHubOAuthHandler;
 
 /**
  * `scorezilla/server` — HMAC-signed adapter for game backends (#17, v0.2.0).
@@ -144,5 +326,121 @@ declare class Scorezilla {
     /** Fetch the slice of entries surrounding a player. */
     getWindowAround(input: GetWindowAroundInput): Promise<ApiSuccess<WindowAroundResponse>>;
 }
+/** A value or a promise of it. */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * The trusted identity produced by your `verify` callback. `playerId` is what
+ * gets submitted — derived from the *verified* request, never the request body.
+ */
+interface VerifiedIdentity {
+    /** Stable, trusted per-player id (e.g. your auth user id). Avoid PII. */
+    readonly playerId: string;
+    /** Optional trusted metadata merged into the submission (wins over the body). */
+    readonly metadata?: Record<string, unknown> | undefined;
+}
+/** The score payload extracted from the request body. */
+interface ParsedScoreSubmission {
+    readonly score: number;
+    readonly metadata?: Record<string, unknown> | undefined;
+}
+/** Decision returned by an optional pre-verify rate-limit gate. */
+interface RateLimitDecision {
+    readonly ok: boolean;
+    readonly retryAfterSeconds?: number | undefined;
+}
+/** CORS config for the handler. Omit entirely for same-origin endpoints. */
+interface ScoreSubmitCorsOptions {
+    /**
+     * Allowed origin(s): an exact string, an array of strings, a predicate, or
+     * `true` to reflect any `Origin`. `false` disables reflection.
+     */
+    readonly origin: string | readonly string[] | boolean | ((origin: string | null) => boolean);
+    /** Methods for the preflight. Default `['POST', 'OPTIONS']`. */
+    readonly methods?: readonly string[];
+    /** Request headers for the preflight. Default `['content-type', 'authorization']`. */
+    readonly headers?: readonly string[];
+    /** `Access-Control-Max-Age` seconds. Default `600`. */
+    readonly maxAgeSeconds?: number;
+}
+/** Configuration for {@link createScoreSubmitHandler}. */
+interface CreateScoreSubmitHandlerConfig {
+    /** Your `sk_live_*` secret. Server-only — never ship to a browser. */
+    readonly secretKey: string;
+    /** The board UUID this handler submits to. */
+    readonly boardId: string;
+    /**
+     * Authenticate the request and return the **trusted** `playerId` (and any
+     * trusted metadata). Return `null` to reject (→ 401); throwing also rejects.
+     * Read identity from headers/cookies — the request **body** is reserved for
+     * the score payload (see `parseSubmission`). This callback is the universal
+     * seam: wire any auth (provider SDK, JWT verify, DB session lookup) here.
+     */
+    readonly verify: (req: Request) => Awaitable<VerifiedIdentity | null>;
+    /**
+     * Extract the score (+ optional client metadata) from the request. Defaults
+     * to JSON `{ score: number, metadata?: object }`. Return `null` (or throw)
+     * to reject as a bad request (→ 400). Note: a `playerId` in the body is
+     * always ignored — identity comes only from `verify`.
+     */
+    readonly parseSubmission?: (req: Request) => Awaitable<ParsedScoreSubmission | null>;
+    /**
+     * Optional gate that runs **before** `verify` (cheap defense — e.g. a per-IP
+     * rate limit, so unauthenticated spam can't drive auth/crypto work). Return
+     * `{ ok: false }` to reject with 429. Per-user limits belong inside `verify`.
+     */
+    readonly rateLimit?: (req: Request) => Awaitable<RateLimitDecision>;
+    /** Optional CORS handling (OPTIONS preflight + reflected `Access-Control-Allow-Origin`). */
+    readonly cors?: ScoreSubmitCorsOptions;
+    /** Override the API base URL (self-host / testing). */
+    readonly baseUrl?: string;
+    /** Inject a `fetch` (testing / custom transport). */
+    readonly fetch?: FetchImpl;
+    /** Max transport retries (default SDK policy). Set `0` to disable. */
+    readonly maxRetries?: number;
+    /** Per-attempt timeout in ms. */
+    readonly timeoutMs?: number;
+}
+/** The web-standard request handler returned by {@link createScoreSubmitHandler}. */
+type ScoreSubmitHandler = (req: Request) => Promise<Response>;
+/**
+ * Build a turnkey, framework-agnostic secure score-submit endpoint.
+ *
+ * Returns a standard `(Request) => Promise<Response>` handler — drop it into a
+ * Cloudflare Worker, a Next.js route handler, Hono, Deno, Bun, or any runtime
+ * that speaks web `Request`/`Response`. You supply only what's app-specific:
+ * the `secretKey`, the `boardId`, and a `verify` callback that proves identity
+ * and returns the trusted `playerId`. The handler owns parsing/validation, the
+ * "playerId comes from `verify`, never the body" guarantee, signing via the
+ * HMAC server client, and error → HTTP mapping.
+ *
+ * **Construction patterns.** In Node/Next, secrets are in `process.env`, so
+ * build the handler once at module scope. In Cloudflare Workers, secrets live
+ * on the per-request `env` binding, so build it inside `fetch` (closing over
+ * `env`) — the construction is cheap (no I/O).
+ *
+ * @example Cloudflare Worker
+ * ```ts
+ * import { createScoreSubmitHandler } from 'scorezilla/server';
+ *
+ * export default {
+ *   fetch(req, env) {
+ *     const handler = createScoreSubmitHandler({
+ *       secretKey: env.SCOREZILLA_SECRET_KEY,
+ *       boardId: env.SCOREZILLA_BOARD_ID,
+ *       verify: async (r) => {
+ *         const user = await verifyMyAuth(r, env); // your auth: SDK / JWT / DB
+ *         return user ? { playerId: user.id } : null;
+ *       },
+ *       cors: { origin: 'https://mygame.example' },
+ *     });
+ *     return handler(req);
+ *   },
+ * };
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function createScoreSubmitHandler(config: CreateScoreSubmitHandlerConfig): ScoreSubmitHandler;
 
-export { ApiSuccess, type CancellableInput, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, LeaderboardResponse, PlayerRankResponse, Scorezilla, type SubmitScoreInput, SubmitScoreResponse, WindowAroundResponse };
+export { ApiSuccess, type CancellableInput, type CreateGitHubOAuthHandlerConfig, type CreateScoreSubmitHandlerConfig, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, type GitHubOAuthHandler, LeaderboardResponse, type ParsedScoreSubmission, PlayerRankResponse, type RateLimitDecision, type RequestVerifier, type ScoreSubmitCorsOptions, type ScoreSubmitHandler, Scorezilla, type SubmitScoreInput, SubmitScoreResponse, type VerifiedIdentity, type VerifyAuth0JwtOptions, type VerifyClerkJwtOptions, type VerifyFirebaseIdTokenOptions, type VerifyJwtOptions, type VerifySupabaseJwtOptions, WindowAroundResponse, createGitHubOAuthHandler, createScoreSubmitHandler, verifyAuth0Jwt, verifyClerkJwt, verifyFirebaseIdToken, verifyJwt, verifySupabaseJwt };

package/dist/server.d.ts

@@ -1,5 +1,187 @@
-import { S as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-B7hyC-C5.js';
-export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-B7hyC-C5.js';
+import { F as FetchImpl, g as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-CWTmormh.js';
+export { R as RankedEntry, e as ScorezillaError, f as ScorezillaErrorCode } from './errors-CWTmormh.js';
+
+/**
+ * Built-in request verifiers for {@link createScoreSubmitHandler} (#211).
+ *
+ * These turn the common "verify a JWT, derive the player id from a claim"
+ * shape into a one-liner. They produce a function with the same signature as
+ * the handler's `verify` callback, so they drop straight in:
+ *
+ * ```ts
+ * import { createScoreSubmitHandler, verifySupabaseJwt } from 'scorezilla/server';
+ *
+ * createScoreSubmitHandler({
+ *   secretKey, boardId,
+ *   verify: verifySupabaseJwt({ supabaseUrl: process.env.SUPABASE_URL! }),
+ * });
+ * ```
+ *
+ * **`jose` is an optional peer dependency.** Only these verifiers use it, and
+ * only via a lazy `import('jose')` — so consumers who use the public-key
+ * client, the factory with their own `verify`, or a provider backend SDK never
+ * install or load it. If you call a built-in verifier without `jose` present,
+ * it throws a clear "install jose" error.
+ */
+
+/** Same shape as the handler's `verify` callback. */
+type RequestVerifier = (req: Request) => Promise<VerifiedIdentity | null>;
+/** Options for the generic JWKS verifier {@link verifyJwt}. */
+interface VerifyJwtOptions {
+    /** JWKS endpoint, e.g. `https://issuer/.well-known/jwks.json`. */
+    readonly jwksUrl: string | URL;
+    /** Expected `iss` claim — strongly recommended. */
+    readonly issuer?: string | string[];
+    /** Expected `aud` claim — strongly recommended. */
+    readonly audience?: string | string[];
+    /** Which claim becomes the `playerId`. Default `'sub'`. */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/** Options for the Supabase preset {@link verifySupabaseJwt}. */
+interface VerifySupabaseJwtOptions {
+    /** Your Supabase project URL, e.g. `https://abcd.supabase.co`. */
+    readonly supabaseUrl: string;
+    /** Which claim becomes the `playerId`. Default `'sub'`. */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Generic JWKS-backed JWT verifier. Verifies a `Bearer` token against the
+ * given JWKS and returns `{ playerId }` from the configured claim (default
+ * `sub`), or `null` if there's no token or verification fails.
+ *
+ * Covers the modern provider majority (Supabase, Clerk, Auth0, Firebase,
+ * WorkOS, …) — they differ only by `jwksUrl` / `issuer` / `audience`.
+ *
+ * @since 0.3.0
+ */
+declare function verifyJwt(options: VerifyJwtOptions): RequestVerifier;
+/**
+ * Supabase preset over {@link verifyJwt}. Verifies a Supabase user JWT via the
+ * project's JWKS and derives the `playerId` from `sub`.
+ *
+ * ```ts
+ * verify: verifySupabaseJwt({ supabaseUrl: process.env.SUPABASE_URL! })
+ * ```
+ *
+ * @since 0.3.0
+ */
+declare function verifySupabaseJwt(options: VerifySupabaseJwtOptions): RequestVerifier;
+/** Options for the Clerk preset {@link verifyClerkJwt}. */
+interface VerifyClerkJwtOptions {
+    /**
+     * Your Clerk instance issuer (the token's `iss`), e.g.
+     * `https://clerk.your-app.com` or `https://<slug>.clerk.accounts.dev`. The
+     * JWKS URL is derived from it.
+     */
+    readonly issuer: string;
+    /**
+     * Expected `aud`. Clerk session tokens have **no** `aud` by default, so leave
+     * this unset unless you added one via a custom JWT template.
+     */
+    readonly audience?: string | string[];
+    /** Which claim becomes the `playerId`. Default `'sub'` (the Clerk user id). */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Clerk preset over {@link verifyJwt}. Verifies a Clerk session JWT against the
+ * instance JWKS and derives the `playerId` from `sub` (the Clerk user id).
+ *
+ * @since 0.3.0
+ */
+declare function verifyClerkJwt(options: VerifyClerkJwtOptions): RequestVerifier;
+/** Options for the Auth0 preset {@link verifyAuth0Jwt}. */
+interface VerifyAuth0JwtOptions {
+    /** Your Auth0 domain, e.g. `your-tenant.us.auth0.com` (scheme optional). */
+    readonly domain: string;
+    /** Your API identifier — the access token's `aud`. */
+    readonly audience: string | string[];
+    /** Which claim becomes the `playerId`. Default `'sub'`. */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Auth0 preset over {@link verifyJwt}. Note Auth0's issuer carries a trailing
+ * slash (`https://<domain>/`) — the preset adds it for you.
+ *
+ * @since 0.3.0
+ */
+declare function verifyAuth0Jwt(options: VerifyAuth0JwtOptions): RequestVerifier;
+/** Options for the Firebase preset {@link verifyFirebaseIdToken}. */
+interface VerifyFirebaseIdTokenOptions {
+    /** Your Firebase project id — both the token's `aud` and the issuer suffix. */
+    readonly projectId: string;
+    /** Which claim becomes the `playerId`. Default `'sub'` (the Firebase uid). */
+    readonly claim?: string;
+    /** Custom `fetch` for retrieving the JWKS (proxy / self-host / testing). */
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Firebase Authentication preset over {@link verifyJwt}. Verifies a Firebase ID
+ * token (`iss = https://securetoken.google.com/<projectId>`, `aud = projectId`)
+ * and derives the `playerId` from `sub` (the Firebase uid).
+ *
+ * @since 0.3.0
+ */
+declare function verifyFirebaseIdToken(options: VerifyFirebaseIdTokenOptions): RequestVerifier;
+
+/**
+ * `createGitHubOAuthHandler` — the server-side callback leg of the GitHub
+ * identity provider (`useAuthProvider({ provider: 'github' })`, ADR 0009).
+ *
+ * GitHub redirects the sign-in popup here with `?code=&state=`. This handler:
+ *   1. validates the query strictly (formats are pinned — anything else is a
+ *      400, never reflected);
+ *   2. exchanges the code at GitHub's token endpoint — the client secret
+ *      stays on this server, and the resulting access token is used for ONE
+ *      `/user` lookup and then discarded;
+ *   3. responds with a tiny HTML page that `postMessage`s
+ *      `{ source: 'scorezilla:github-oauth', state, id }` to `window.opener`,
+ *      pinned to `allowedOrigin`, and closes the popup.
+ *
+ * The browser side (`scorezilla/identity`) accepts the message only when the
+ * origin matches its `exchangeUrl` and the `state` echoes the one it
+ * generated — this page is the only party that can complete a sign-in.
+ *
+ * Returns a standard `(Request) => Promise<Response>`: deploy it on any web
+ * runtime (a Next.js route handler, Hono, Deno, Bun, a Cloudflare Worker).
+ * Configure the deployed URL as the OAuth app's callback URL on GitHub.
+ *
+ * @since 0.3.0
+ */
+
+interface CreateGitHubOAuthHandlerConfig {
+    /** Your GitHub OAuth app client ID. */
+    readonly clientId: string;
+    /** Your GitHub OAuth app client secret. Server-only — never ships to a browser. */
+    readonly clientSecret: string;
+    /**
+     * The exact origin of the GAME page that opens the sign-in popup, e.g.
+     * `https://mygame.example`. Used as the `postMessage` target origin so the
+     * sign-in result can only be delivered to your page — never `*`.
+     */
+    readonly allowedOrigin: string;
+    /** Inject a `fetch` (testing / custom transport). */
+    readonly fetch?: FetchImpl;
+}
+/** The web-standard request handler returned by {@link createGitHubOAuthHandler}. */
+type GitHubOAuthHandler = (req: Request) => Promise<Response>;
+/**
+ * Build the GitHub OAuth callback endpoint. See module docs for the flow;
+ * see `GitHubAuthProviderOptions` in `scorezilla/identity` for the matching
+ * client half.
+ *
+ * **Construction patterns.** In Node/Next, secrets are in `process.env`, so
+ * build the handler once at module scope. In Cloudflare Workers, secrets
+ * live on the per-request `env` binding, so build it inside `fetch`.
+ */
+declare function createGitHubOAuthHandler(config: CreateGitHubOAuthHandlerConfig): GitHubOAuthHandler;
 
 /**
  * `scorezilla/server` — HMAC-signed adapter for game backends (#17, v0.2.0).
@@ -144,5 +326,121 @@ declare class Scorezilla {
     /** Fetch the slice of entries surrounding a player. */
     getWindowAround(input: GetWindowAroundInput): Promise<ApiSuccess<WindowAroundResponse>>;
 }
+/** A value or a promise of it. */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * The trusted identity produced by your `verify` callback. `playerId` is what
+ * gets submitted — derived from the *verified* request, never the request body.
+ */
+interface VerifiedIdentity {
+    /** Stable, trusted per-player id (e.g. your auth user id). Avoid PII. */
+    readonly playerId: string;
+    /** Optional trusted metadata merged into the submission (wins over the body). */
+    readonly metadata?: Record<string, unknown> | undefined;
+}
+/** The score payload extracted from the request body. */
+interface ParsedScoreSubmission {
+    readonly score: number;
+    readonly metadata?: Record<string, unknown> | undefined;
+}
+/** Decision returned by an optional pre-verify rate-limit gate. */
+interface RateLimitDecision {
+    readonly ok: boolean;
+    readonly retryAfterSeconds?: number | undefined;
+}
+/** CORS config for the handler. Omit entirely for same-origin endpoints. */
+interface ScoreSubmitCorsOptions {
+    /**
+     * Allowed origin(s): an exact string, an array of strings, a predicate, or
+     * `true` to reflect any `Origin`. `false` disables reflection.
+     */
+    readonly origin: string | readonly string[] | boolean | ((origin: string | null) => boolean);
+    /** Methods for the preflight. Default `['POST', 'OPTIONS']`. */
+    readonly methods?: readonly string[];
+    /** Request headers for the preflight. Default `['content-type', 'authorization']`. */
+    readonly headers?: readonly string[];
+    /** `Access-Control-Max-Age` seconds. Default `600`. */
+    readonly maxAgeSeconds?: number;
+}
+/** Configuration for {@link createScoreSubmitHandler}. */
+interface CreateScoreSubmitHandlerConfig {
+    /** Your `sk_live_*` secret. Server-only — never ship to a browser. */
+    readonly secretKey: string;
+    /** The board UUID this handler submits to. */
+    readonly boardId: string;
+    /**
+     * Authenticate the request and return the **trusted** `playerId` (and any
+     * trusted metadata). Return `null` to reject (→ 401); throwing also rejects.
+     * Read identity from headers/cookies — the request **body** is reserved for
+     * the score payload (see `parseSubmission`). This callback is the universal
+     * seam: wire any auth (provider SDK, JWT verify, DB session lookup) here.
+     */
+    readonly verify: (req: Request) => Awaitable<VerifiedIdentity | null>;
+    /**
+     * Extract the score (+ optional client metadata) from the request. Defaults
+     * to JSON `{ score: number, metadata?: object }`. Return `null` (or throw)
+     * to reject as a bad request (→ 400). Note: a `playerId` in the body is
+     * always ignored — identity comes only from `verify`.
+     */
+    readonly parseSubmission?: (req: Request) => Awaitable<ParsedScoreSubmission | null>;
+    /**
+     * Optional gate that runs **before** `verify` (cheap defense — e.g. a per-IP
+     * rate limit, so unauthenticated spam can't drive auth/crypto work). Return
+     * `{ ok: false }` to reject with 429. Per-user limits belong inside `verify`.
+     */
+    readonly rateLimit?: (req: Request) => Awaitable<RateLimitDecision>;
+    /** Optional CORS handling (OPTIONS preflight + reflected `Access-Control-Allow-Origin`). */
+    readonly cors?: ScoreSubmitCorsOptions;
+    /** Override the API base URL (self-host / testing). */
+    readonly baseUrl?: string;
+    /** Inject a `fetch` (testing / custom transport). */
+    readonly fetch?: FetchImpl;
+    /** Max transport retries (default SDK policy). Set `0` to disable. */
+    readonly maxRetries?: number;
+    /** Per-attempt timeout in ms. */
+    readonly timeoutMs?: number;
+}
+/** The web-standard request handler returned by {@link createScoreSubmitHandler}. */
+type ScoreSubmitHandler = (req: Request) => Promise<Response>;
+/**
+ * Build a turnkey, framework-agnostic secure score-submit endpoint.
+ *
+ * Returns a standard `(Request) => Promise<Response>` handler — drop it into a
+ * Cloudflare Worker, a Next.js route handler, Hono, Deno, Bun, or any runtime
+ * that speaks web `Request`/`Response`. You supply only what's app-specific:
+ * the `secretKey`, the `boardId`, and a `verify` callback that proves identity
+ * and returns the trusted `playerId`. The handler owns parsing/validation, the
+ * "playerId comes from `verify`, never the body" guarantee, signing via the
+ * HMAC server client, and error → HTTP mapping.
+ *
+ * **Construction patterns.** In Node/Next, secrets are in `process.env`, so
+ * build the handler once at module scope. In Cloudflare Workers, secrets live
+ * on the per-request `env` binding, so build it inside `fetch` (closing over
+ * `env`) — the construction is cheap (no I/O).
+ *
+ * @example Cloudflare Worker
+ * ```ts
+ * import { createScoreSubmitHandler } from 'scorezilla/server';
+ *
+ * export default {
+ *   fetch(req, env) {
+ *     const handler = createScoreSubmitHandler({
+ *       secretKey: env.SCOREZILLA_SECRET_KEY,
+ *       boardId: env.SCOREZILLA_BOARD_ID,
+ *       verify: async (r) => {
+ *         const user = await verifyMyAuth(r, env); // your auth: SDK / JWT / DB
+ *         return user ? { playerId: user.id } : null;
+ *       },
+ *       cors: { origin: 'https://mygame.example' },
+ *     });
+ *     return handler(req);
+ *   },
+ * };
+ * ```
+ *
+ * @since 0.3.0
+ * @stability stable
+ */
+declare function createScoreSubmitHandler(config: CreateScoreSubmitHandlerConfig): ScoreSubmitHandler;
 
-export { ApiSuccess, type CancellableInput, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, LeaderboardResponse, PlayerRankResponse, Scorezilla, type SubmitScoreInput, SubmitScoreResponse, WindowAroundResponse };
+export { ApiSuccess, type CancellableInput, type CreateGitHubOAuthHandlerConfig, type CreateScoreSubmitHandlerConfig, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, type GitHubOAuthHandler, LeaderboardResponse, type ParsedScoreSubmission, PlayerRankResponse, type RateLimitDecision, type RequestVerifier, type ScoreSubmitCorsOptions, type ScoreSubmitHandler, Scorezilla, type SubmitScoreInput, SubmitScoreResponse, type VerifiedIdentity, type VerifyAuth0JwtOptions, type VerifyClerkJwtOptions, type VerifyFirebaseIdTokenOptions, type VerifyJwtOptions, type VerifySupabaseJwtOptions, WindowAroundResponse, createGitHubOAuthHandler, createScoreSubmitHandler, verifyAuth0Jwt, verifyClerkJwt, verifyFirebaseIdToken, verifyJwt, verifySupabaseJwt };