scorezilla 0.3.0-next.2 → 0.3.0-next.3

package/dist/server.d.cts

@@ -1,5 +1,5 @@
-import { F as FetchImpl, S as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-CtXMAHtJ.cjs';
-export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-CtXMAHtJ.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).
@@ -131,6 +131,58 @@ interface VerifyFirebaseIdTokenOptions {
  */
 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).
  *
@@ -391,4 +443,4 @@ type ScoreSubmitHandler = (req: Request) => Promise<Response>;
  */
 declare function createScoreSubmitHandler(config: CreateScoreSubmitHandlerConfig): ScoreSubmitHandler;
 
-export { ApiSuccess, type CancellableInput, type CreateScoreSubmitHandlerConfig, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, 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, createScoreSubmitHandler, verifyAuth0Jwt, verifyClerkJwt, verifyFirebaseIdToken, verifyJwt, verifySupabaseJwt };
+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,5 @@
-import { F as FetchImpl, S as SecretKeyConfig, A as ApiSuccess, a as SubmitScoreResponse, L as LeaderboardResponse, P as PlayerRankResponse, W as WindowAroundResponse } from './errors-CtXMAHtJ.js';
-export { R as RankedEntry, b as ScorezillaError, c as ScorezillaErrorCode } from './errors-CtXMAHtJ.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).
@@ -131,6 +131,58 @@ interface VerifyFirebaseIdTokenOptions {
  */
 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).
  *
@@ -391,4 +443,4 @@ type ScoreSubmitHandler = (req: Request) => Promise<Response>;
  */
 declare function createScoreSubmitHandler(config: CreateScoreSubmitHandlerConfig): ScoreSubmitHandler;
 
-export { ApiSuccess, type CancellableInput, type CreateScoreSubmitHandlerConfig, type GetLeaderboardInput, type GetPlayerRankInput, type GetWindowAroundInput, 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, createScoreSubmitHandler, verifyAuth0Jwt, verifyClerkJwt, verifyFirebaseIdToken, verifyJwt, verifySupabaseJwt };
+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.js

@@ -706,13 +706,141 @@ function verifyFirebaseIdToken(options) {
   });
 }
 
+// src/github-oauth.ts
+var GITHUB_TOKEN_URL = "https://github.com/login/oauth/access_token";
+var GITHUB_USER_URL = "https://api.github.com/user";
+var MESSAGE_SOURCE = "scorezilla:github-oauth";
+var USER_AGENT = "scorezilla-sdk-github-oauth";
+var STATE_RE = /^[A-Za-z0-9_-]{8,128}$/;
+var CODE_RE = /^[A-Za-z0-9_-]{1,128}$/;
+function createGitHubOAuthHandler(config) {
+  if (typeof config.clientId !== "string" || config.clientId.length === 0) {
+    throw new TypeError("createGitHubOAuthHandler: clientId is required.");
+  }
+  if (typeof config.clientSecret !== "string" || config.clientSecret.length === 0) {
+    throw new TypeError("createGitHubOAuthHandler: clientSecret is required.");
+  }
+  let allowedOrigin;
+  try {
+    const parsed = new URL(config.allowedOrigin);
+    allowedOrigin = parsed.origin;
+    if (allowedOrigin === "null") throw new Error("opaque origin");
+  } catch {
+    throw new TypeError(
+      "createGitHubOAuthHandler: allowedOrigin must be an absolute origin, e.g. 'https://mygame.example' (got " + JSON.stringify(config.allowedOrigin) + ")."
+    );
+  }
+  const fetchImpl = config.fetch ?? fetch;
+  return async (req) => {
+    if (req.method !== "GET") {
+      return new Response("method not allowed", { status: 405, headers: { allow: "GET" } });
+    }
+    const url = new URL(req.url);
+    const state = url.searchParams.get("state") ?? "";
+    const code = url.searchParams.get("code");
+    const ghError = url.searchParams.get("error");
+    if (!STATE_RE.test(state)) {
+      return new Response("invalid or missing state parameter", { status: 400 });
+    }
+    if (ghError !== null) {
+      return callbackPage(
+        { state, error: ghError === "access_denied" ? "access_denied" : "exchange_failed" },
+        allowedOrigin
+      );
+    }
+    if (code === null || !CODE_RE.test(code)) {
+      return new Response("invalid or missing code parameter", { status: 400 });
+    }
+    let accessToken;
+    try {
+      const tokenRes = await fetchImpl(GITHUB_TOKEN_URL, {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          "content-type": "application/x-www-form-urlencoded",
+          "user-agent": USER_AGENT
+        },
+        body: new URLSearchParams({
+          client_id: config.clientId,
+          client_secret: config.clientSecret,
+          code
+        }).toString()
+      });
+      const tokenBody = await tokenRes.json();
+      if (!tokenRes.ok || typeof tokenBody.access_token !== "string") {
+        return callbackPage({ state, error: "exchange_failed" }, allowedOrigin);
+      }
+      accessToken = tokenBody.access_token;
+    } catch {
+      return callbackPage({ state, error: "exchange_failed" }, allowedOrigin);
+    }
+    try {
+      const userRes = await fetchImpl(GITHUB_USER_URL, {
+        method: "GET",
+        headers: {
+          authorization: `Bearer ${accessToken}`,
+          accept: "application/vnd.github+json",
+          "user-agent": USER_AGENT
+        }
+      });
+      if (!userRes.ok) {
+        return callbackPage({ state, error: "exchange_failed" }, allowedOrigin);
+      }
+      const user = await userRes.json();
+      if (typeof user.id !== "number" || !Number.isSafeInteger(user.id)) {
+        return callbackPage({ state, error: "exchange_failed" }, allowedOrigin);
+      }
+      return callbackPage({ state, id: String(user.id) }, allowedOrigin);
+    } catch {
+      return callbackPage({ state, error: "exchange_failed" }, allowedOrigin);
+    }
+  };
+}
+function callbackPage(payload, allowedOrigin) {
+  const message = JSON.stringify({ source: MESSAGE_SOURCE, ...payload });
+  const target = JSON.stringify(allowedOrigin);
+  const html = `<!doctype html>
+<html>
+<head><meta charset="utf-8"><title>Signing in\u2026</title></head>
+<body>
+<script>
+(function () {
+  if (window.opener) {
+    window.opener.postMessage(${message}, ${target});
+    window.close();
+  } else {
+    document.body.textContent =
+      'Sign-in handled \u2014 you can close this window. (If this keeps appearing, ' +
+      'the game page may be setting Cross-Origin-Opener-Policy: same-origin, ' +
+      'which severs the popup link; use same-origin-allow-popups.)';
+  }
+})();
+</script>
+</body>
+</html>`;
+  return new Response(html, {
+    status: 200,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      // One-shot page embedding a one-shot state — never cache it.
+      "cache-control": "no-store",
+      // The URL carried the OAuth `code`; nothing on this page may leak it.
+      "referrer-policy": "no-referrer",
+      // Defense in depth for the inline script: nothing else may load or
+      // run on this page even if a future regression reflected input here.
+      "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'",
+      "x-content-type-options": "nosniff"
+    }
+  });
+}
+
 // src/server.ts
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`.
    *  Mirrors the static on the public-key client so consumers can log
    *  the running SDK build the same way regardless of which surface
    *  they imported. */
-  static version = "0.3.0-next.2";
+  static version = "0.3.0-next.3";
   #keyId;
   #secret;
   #baseUrl;
@@ -979,6 +1107,6 @@ function isCorsOriginAllowed(rule, origin) {
   return rule.includes(origin);
 }
 
-export { Scorezilla, ScorezillaError, createScoreSubmitHandler, verifyAuth0Jwt, verifyClerkJwt, verifyFirebaseIdToken, verifyJwt, verifySupabaseJwt };
+export { Scorezilla, ScorezillaError, createGitHubOAuthHandler, createScoreSubmitHandler, verifyAuth0Jwt, verifyClerkJwt, verifyFirebaseIdToken, verifyJwt, verifySupabaseJwt };
 //# sourceMappingURL=server.js.map
 //# sourceMappingURL=server.js.map