scorezilla 0.1.0-next.0 → 0.1.0-next.3

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## 0.1.0-next.3
+
+### Minor Changes
+
+- [#25](https://github.com/isco-tec/scorezilla-js/pull/25) [`5f7025b`](https://github.com/isco-tec/scorezilla-js/commit/5f7025b7b06dded92b3e710316454eb8c891d053) Thanks [@isco-tec](https://github.com/isco-tec)! - **`scorezilla/server`: HMAC requests now bind to the target host (v=2).**
+
+  The canonical signing string includes the host of the request URL, so a signature minted against staging cannot be replayed against prod (or any other origin that happens to share key material). SigV4 has had this since day one; closing the gap before MCP locks the format.
+
+  Wire format change:
+
+  ```
+  Authorization: Scorezilla-HMAC-SHA256 keyId=…, ts=…, nonce=…, signature=…, v=2
+  ```
+
+  The `v=2` parameter is new. The canonical signing string now has six lines instead of five — `host` is inserted between `METHOD` and `pathAndQuery`, lowercased per RFC 9110 §4.2.4.
+
+  **Backward compatibility.** The API verifier still accepts v=1 (no `v=` field, no host binding) during the rollout window — your existing pre-next.3 SDK builds will keep working until v=1 is deprecated. The SDK itself, however, emits v=2 unconditionally from next.3 onwards. If you've forked or wrapped `buildHmacAuthHeader` / `buildSigningString`, you'll need to thread a `host` parameter through.
+
+  **For consumers of `Scorezilla` from `scorezilla/server`:** no API changes. The constructor derives `host` from `baseUrl` automatically. As an added safety net, an invalid `baseUrl` now throws at construction time rather than producing 401 mismatches at every request.
+
+  **For low-level consumers of `buildSigningString` / `buildHmacAuthHeader`:** a new `host` parameter is now required. The latter also accepts an optional `version: 1 | 2` for explicit backward-compat scenarios.
+
+### Patch Changes
+
+- [#28](https://github.com/isco-tec/scorezilla-js/pull/28) [`94b39d2`](https://github.com/isco-tec/scorezilla-js/commit/94b39d2e67ec7bba2681145560529f058acfc633) Thanks [@isco-tec](https://github.com/isco-tec)! - **Pre-release security hardening pass.** Three issues surfaced by a focused security review before the first public release of `scorezilla/server`:
+  - **HIGH — nonce injection.** `buildHmacAuthHeader` now requires injected nonces to be at least 16 characters. The default path (`crypto.randomUUID()`) is unaffected. Previously a misconfigured caller could pass `nonce: ''` and silently sign a header with no replay protection — the server has no minimum-length check, so the API would accept it. Now caught at SDK build-time with a clear error.
+  - **HIGH — server policy disclosure.** `HMAC_TIMESTAMP_WINDOW_SECONDS = 300` was previously exported as documentation of the API's clock-skew tolerance. Removed from the public API — publishing the server's replay-protection window in the SDK's types was unnecessary information disclosure and narrowed the pre-computation window for any future timestamp-forgery work. The SDK has no behavioral dependency on the value (it always emits a fresh `ts = floor(Date.now() / 1000)`).
+  - **MEDIUM — `EdgeRuntime` polyfill bypass.** The server adapter's runtime browser-guard previously trusted `globalThis.EdgeRuntime` as a "this is a server" signal. A browser extension or bundler misconfig setting that global would have bypassed the guard. Removed from the trusted set — the package's `exports.browser` condition remains the primary gate, and the runtime check now refuses to trust globals that can be polyfilled from a browser context. Real Vercel Edge runtimes still pass the guard because they don't have `window`/`document`.
+
+  No external-attack surface was exploitable; all three are self-inflicted/defense-in-depth issues caught before the first stable release. Tests added: 4 for nonce validation (rejects empty / too-short, accepts at-floor / default UUID), 1 for the EdgeRuntime polyfill scenario.
+
+## 0.1.0-next.2
+
+### Minor Changes
+
+- [#23](https://github.com/isco-tec/scorezilla-js/pull/23) [`5163e31`](https://github.com/isco-tec/scorezilla-js/commit/5163e3130ac208d591b026d66870ce5a194f90b6) Thanks [@isco-tec](https://github.com/isco-tec)! - **`scorezilla/server` adopts a single-token secret-key format.** Breaking
+  change vs. v0.1.0-next.1; we're still in pre-release so this is permitted.
+
+  Before (v0.1.0-next.1):
+
+  ```ts
+  new Scorezilla({
+    secretKey: { id: 'sk-id-uuid', secret: 'sk_live_xxxxx' },
+  });
+  ```
+
+  After (v0.1.0-next.2):
+
+  ```ts
+  new Scorezilla({
+    secretKey: 'sk_live_<keyId>_xxxxx', // one self-contained token
+  });
+  ```
+
+  The keyId is embedded in the secret string itself; the SDK parses it
+  out via `/^sk_live_([0-9a-f]{8}-...)_/` before signing. The HMAC key
+  remains the WHOLE plaintext. Wire format on the Authorization header
+  is unchanged. API verification is unchanged.
+
+  Rationale: matches Stripe's design and the public-key client's
+  single-string shape. One value to copy from the dashboard, one to
+  manage in env config, one to pass into the constructor. Previously
+  users had to manage two distinct values (`id` AND `secret`) which
+  created confusion — they're functionally one credential.
+
+  **To upgrade**: issue (or rotate) a fresh secret key in the dashboard.
+  Old-format keys (no embedded keyId) are rejected by the SDK with a
+  clear error message pointing at the migration path.
+
+## 0.1.0-next.1
+
+### Minor Changes
+
+- [#18](https://github.com/isco-tec/scorezilla-js/pull/18) [`a02b07a`](https://github.com/isco-tec/scorezilla-js/commit/a02b07a116a9d15c2928ad4f98a9cfa3a8dceffd) Thanks [@isco-tec](https://github.com/isco-tec)! - **v0.2.0 — HMAC server adapter (`scorezilla/server`).** Closes [#17](https://github.com/isco-tec/scorezilla-js/issues/17).
+
+  The new `scorezilla/server` subpath ships an HMAC-SHA256 signing client for
+  game backends that need cheat-resistant submissions. The browser-side
+  public-key client (`scorezilla`) is unchanged.
+
+  ```ts
+  import { Scorezilla } from 'scorezilla/server';
+
+  const sz = new Scorezilla({
+    secretKey: {
+      id: process.env.SCOREZILLA_KEY_ID,
+      secret: process.env.SCOREZILLA_KEY_SECRET, // never ship to a browser
+    },
+  });
+
+  await sz.submitScore({ boardId, playerId, score, metadata });
+  await sz.getLeaderboard({ boardId, top });
+  await sz.getPlayerRank({ boardId, playerId });
+  await sz.getWindowAround({ boardId, playerId, before, after });
+  ```
+
+  Behavior:
+  - Each request is signed with HMAC-SHA256 over a canonical
+    `{ts}\n{nonce}\n{METHOD}\n{path?query}\n{sha256_hex(body)}` string and
+    delivered via `Authorization: Scorezilla-HMAC-SHA256 keyId=…, ts=…,
+nonce=…, signature=…`. Matches the API's verifier byte-for-byte.
+  - `submitScore` posts to `/v1/secure/scores` (the boardId moves into the
+    body — the public-key endpoint at `/v1/boards/:id/scores` is unchanged).
+  - Read methods (`getLeaderboard` / `getPlayerRank` / `getWindowAround`)
+    hit the same paths as the public-key client.
+  - Every retry attempt regenerates `(ts, nonce)` so server-side replay
+    protection (10-minute nonce window) doesn't trip.
+  - Importing `scorezilla/server` from a browser bundle throws at module
+    evaluation — the `sk_live_*` secret never reaches client-side code.
+
+  Same `ScorezillaError` surface (`isRateLimited()`, `isAuth()`,
+  `isTransient()`, `code`, `requestId`, etc.) — typed catch patterns
+  written for v0.1 work unchanged.
+
+  Bundle: ~3.84 KB ESM gzipped, ~4.04 KB CJS gzipped — well under the
+  6 KB per-entry cap.
+
 ## 0.1.0-next.0
 
 ### Minor Changes

package/README.md

@@ -18,10 +18,13 @@ AI-vibe-coded games.
 - **Private.** No cookies, no `localStorage`, no fingerprinting beyond runtime
   detection — see [COMPATIBILITY.md](./COMPATIBILITY.md).
 
-> **Status:** v0.1.0 ships the **public-key client** (browser-safe). The HMAC
-> server adapter (`scorezilla/server`) lands in v0.2.0; React
-> (`scorezilla/react`) in v0.3.0; Phaser (`scorezilla/phaser`) in v0.4.0. See
-> [CHANGELOG.md](./CHANGELOG.md) and [VERSIONING.md](./VERSIONING.md).
+> **Status:** v0.1.0 ships the **public-key client** (browser-safe).
+> v0.2.0 ships the **HMAC server adapter** (`scorezilla/server`) for
+> game backends that need cheat-resistant submissions. React
+> (`scorezilla/react`) lands in v0.3.0; Phaser (`scorezilla/phaser`) in
+> v0.4.0. The first preview is on the `next` dist-tag — install with
+> `npm install scorezilla@next`. See [CHANGELOG.md](./CHANGELOG.md) and
+> [VERSIONING.md](./VERSIONING.md).
 
 > **Commercial context.** Scorezilla is a hosted leaderboard service with free
 > and paid tiers — see [scorezilla.dev/pricing](https://scorezilla.dev/pricing).
@@ -76,6 +79,36 @@ 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.
 
+## Server-side HMAC (`scorezilla/server`)
+
+Public-key submissions are client-authoritative — anyone with your `pk_` can
+submit any score from devtools. For games where ranking matters, sign each
+submission server-side with a `sk_live_*` secret:
+
+```ts
+import { Scorezilla, ScorezillaError } from 'scorezilla/server';
+
+// Single self-contained token from the dashboard. Format:
+//   sk_live_<keyId>_<random>
+// The SDK parses the keyId out internally; you only manage one value.
+const sz = new Scorezilla({
+  secretKey: process.env.SCOREZILLA_SECRET_KEY!, // never ship to a browser
+});
+
+await sz.submitScore({ boardId, playerId, score, metadata });
+```
+
+Same method shape as the public-key client — `submitScore`, `getLeaderboard`,
+`getPlayerRank`, `getWindowAround`. The adapter signs every request with
+**HMAC-SHA256** over a canonical string (method + path + ts + nonce +
+sha256(body)), and the API verifies before any state change. Replay
+protection is enforced server-side via a 10-minute nonce window.
+
+The `scorezilla/server` subpath is server-only — importing it from the
+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.
+
 ## Error handling
 
 Every failure path — HTTP non-2xx, network error, timeout, abort, JSON parse

package/dist/errors-CUAQsaVS.d.cts

@@ -0,0 +1,292 @@
+/** Minimal fetch shape — broader than `typeof fetch` so polyfills and
+ *  test stubs (`vi.fn()`, `node-fetch`, etc.) typecheck cleanly. */
+type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * SDK configuration.
+ *
+ * The `ScorezillaConfig` is a TypeScript-level discriminated union of
+ * `PublicKeyConfig` and `SecretKeyConfig`. The mutual-exclusivity (you may
+ * pass `publicKey` OR `secretKey`, never both) is enforced at compile time:
+ * passing both fields fails type-checking before the runtime check fires.
+ *
+ * The runtime check in {@link validateConfig} is the second line of defense
+ * for consumers using plain JS or `as any` casts.
+ */
+
+/** Shared options across both auth modes. */
+interface BaseConfig {
+    /** API base URL (no trailing slash required). Defaults to {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Custom fetch implementation — defaults to `globalThis.fetch`. Pass
+     *  `node-fetch`, `undici`, or a mock here. The explicit signature
+     *  (`(RequestInfo | URL, init?) => Promise<Response>`) is broader than
+     *  `typeof fetch` so common polyfills typecheck cleanly. */
+    fetch?: FetchImpl;
+    /** Per-request timeout in milliseconds. Defaults to 30 s. */
+    timeoutMs?: number;
+    /** Maximum retry attempts on transient failures. Defaults to 2 (so the
+     *  worst-case total request count is 3). */
+    maxRetries?: number;
+    /** Override the default `User-Agent` header (Node/Workers/Bun/Deno —
+     *  browsers silently ignore the value). */
+    userAgent?: string;
+    /** Injectable sleep implementation for the retry loop's inter-attempt
+     *  pause. Exists for tests that need deterministic, zero-delay retries
+     *  rather than real wall-clock backoff. Production code should leave
+     *  this unset to use the default exponential backoff with jitter.
+     *  @internal */
+    sleepImpl?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** Public-key auth: browser-safe path. The key is fingerprinted to a game
+ *  on the server side via `pk_<gameSlug>_<base62>`. */
+type PublicKeyConfig = BaseConfig & {
+    publicKey: string;
+    secretKey?: never;
+};
+/** Secret-key auth: server-side HMAC. A single self-contained token of the
+ *  shape `sk_live_<keyId>_<random>`. The SDK parses the keyId out and uses
+ *  the whole string as the HMAC key. One value to copy, one to manage —
+ *  matches Stripe's design and the public-key client's single-string shape.
+ *
+ *  Past versions of the SDK took `{ id, secret }` separately. That was an
+ *  unnecessary cognitive tax — the id was always derivable from a properly-
+ *  formatted secret. v0.1.0-next.2+ takes the single-string form. */
+type SecretKeyConfig = BaseConfig & {
+    secretKey: string;
+    publicKey?: never;
+};
+/** The top-level config type. The union is open for additional auth modes
+ *  in future major releases. */
+type ScorezillaConfig = PublicKeyConfig | SecretKeyConfig;
+
+/**
+ * Wire types for the Scorezilla API at /v1.
+ *
+ * Mirrors the documented response shapes. TypeScript's structural typing
+ * means additional fields the server adds in a minor release won't break
+ * consumers — see VERSIONING.md for the full SemVer contract.
+ *
+ * No Zod or other runtime validators in v0.1.0 — keeps the bundle small.
+ * Narrow untrusted input with the {@link isApiSuccess} / {@link isApiError}
+ * type guards exported below.
+ */
+/**
+ * Machine-stable error codes returned by the API.
+ *
+ * Consumers MUST branch on this `code` rather than the human-readable
+ * `message` — message text is English-only and explicitly NOT part of the
+ * SemVer contract.
+ *
+ * The union is intentionally open (`| (string & {})`) so unknown future
+ * codes from a server-side minor release don't compile-error against the
+ * SDK. The trick preserves autocomplete on the known set while permitting
+ * arbitrary strings at runtime — see
+ * https://github.com/microsoft/TypeScript/issues/29729 for the pattern.
+ *
+ * @stable v0.1.0
+ */
+type ScorezillaErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid_input' | 'invalid_json' | 'out_of_bounds' | 'rate_limited' | 'conflict' | 'internal_error' | (string & {});
+/** Reason sub-classifier on `out_of_bounds` errors. Open union — see {@link ScorezillaErrorCode}. */
+type OutOfBoundsReason = 'below_min' | 'above_max' | (string & {});
+/** Successful API response envelope. The `T` is the per-route payload. */
+type ApiSuccess<T> = {
+    ok: true;
+} & T;
+/** Failure response envelope. The server returns this on every non-2xx response. */
+interface ApiError {
+    ok: false;
+    error: ScorezillaErrorCode;
+    /** Human-readable, English only. Not machine-stable — branch on `error` and `reason`. */
+    message?: string;
+    /** Sub-classifier — used by `out_of_bounds` (`'below_min' | 'above_max'`). */
+    reason?: string;
+    /** Seconds — present on `rate_limited`. Also mirrored in the HTTP `Retry-After` header. */
+    retryAfter?: number;
+    /** Which rate-limit layer fired — present on `rate_limited`. */
+    layer?: string;
+    /** The limit value that was crossed — present on `out_of_bounds`. */
+    bound?: number;
+}
+/** Discriminated envelope: every API response is one of these two shapes. */
+type ApiResponse<T> = ApiSuccess<T> | ApiError;
+/**
+ * A single ranked entry on a leaderboard.
+ *
+ * Returned as an array on `leaderboard` and `window-around` responses, and
+ * inline on `playerRank` (without the `rank` wrapper — see
+ * {@link PlayerRankResponse}).
+ */
+interface RankedEntry {
+    /** 1-based rank. */
+    rank: number;
+    playerId: string;
+    score: number;
+    /** Milliseconds since epoch. */
+    submittedAt: number;
+    metadata?: Record<string, unknown>;
+}
+/** Payload from `POST /v1/boards/:boardId/scores`. */
+interface SubmitScoreResponse {
+    boardId: string;
+    /** The key ID that authorized the submission. Useful for consumer-side audit. */
+    keyId: string;
+    /** 1-based rank after the submit settled. */
+    rank: number;
+    totalEntries: number;
+    isPersonalBest: boolean;
+}
+/** Payload from `GET /v1/boards/:boardId/leaderboard`. */
+interface LeaderboardResponse {
+    boardId: string;
+    offset: number;
+    limit: number;
+    entries: RankedEntry[];
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/rank`. */
+interface PlayerRankResponse {
+    boardId: string;
+    playerId: string;
+    rank: number;
+    score: number;
+    submittedAt: number;
+    totalEntries: number;
+}
+/** Payload from `GET /v1/boards/:boardId/players/:playerId/window`. */
+interface WindowAroundResponse {
+    boardId: string;
+    playerId: string;
+    before: number;
+    after: number;
+    entries: RankedEntry[];
+}
+
+/**
+ * SDK error type.
+ *
+ * Every non-2xx API response is normalized into a `ScorezillaError` instance
+ * by the transport layer. Network failures and timeouts surface as the same
+ * class (with `status: 0`) so callers have a single error type to catch.
+ *
+ * **Invariant — consumers MUST branch on `code` (and optionally `reason`),
+ * never on `message`.** The English-language `message` is for operator
+ * logging only and is explicitly **not** part of the SemVer contract; a
+ * minor release MAY reword any message. Machine logic that depends on
+ * message text will break silently across upgrades.
+ */
+
+/**
+ * Options for {@link ScorezillaError.from}.
+ *
+ * The fields mirror what's available after a fetch round-trip: the HTTP
+ * status, the parsed JSON body (if any), the request ID from
+ * `X-Request-Id`, and an optional `cause` for the underlying
+ * network/abort error.
+ */
+interface ScorezillaErrorFromInit {
+    status: number;
+    body?: ApiError | undefined;
+    requestId?: string | undefined;
+    cause?: unknown;
+}
+/**
+ * Thrown by the SDK for every failure path — non-2xx responses, network
+ * errors, aborts, and timeouts.
+ *
+ * Cross-realm `instanceof` is guaranteed: the class sets `Error.prototype`
+ * explicitly so checks survive iframe / worker boundaries.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sz.submitScore({ boardId, playerId, score });
+ * } catch (e) {
+ *   if (!(e instanceof ScorezillaError)) throw e;
+ *
+ *   if (e.isRateLimited()) {
+ *     await sleep((e.retryAfter ?? 30) * 1000);
+ *     return retry();
+ *   }
+ *   if (e.code === 'out_of_bounds') {
+ *     console.warn(`Score crosses ${e.reason} bound (limit ${e.bound})`);
+ *     return;
+ *   }
+ *   if (e.isAuth()) throw new Error('SDK misconfigured — bad publicKey');
+ *
+ *   // Anything else: surface to your reporter with requestId for support.
+ *   console.error(`Scorezilla ${e.code} (${e.status}) — request ${e.requestId}`);
+ *   throw e;
+ * }
+ * ```
+ *
+ * @since 0.1.0
+ * @stability stable
+ */
+declare class ScorezillaError extends Error {
+    /** HTTP status of the response, or {@link STATUS_NETWORK_ERROR} (0) for
+     *  network / abort / timeout. */
+    readonly status: number;
+    /** Machine-stable error code from the API. Open union — see
+     *  {@link ScorezillaErrorCode}. For network errors, this is `'network_error'`;
+     *  for aborts, `'aborted'`; for timeouts, `'timeout'`. */
+    readonly code: ScorezillaErrorCode;
+    /** Sub-classifier — present on `out_of_bounds` (`'below_min' | 'above_max'`)
+     *  and possibly other codes in future minor releases. */
+    readonly reason: OutOfBoundsReason | string | undefined;
+    /** Seconds — present on `rate_limited`. Honored by the transport's retry
+     *  policy (Step 2.4). */
+    readonly retryAfter: number | undefined;
+    /** Server-issued request ID, lifted from the `X-Request-Id` response
+     *  header. Pass this to support when filing bugs. */
+    readonly requestId: string | undefined;
+    /** The bound value crossed on `out_of_bounds`. */
+    readonly bound: number | undefined;
+    /** Which rate-limit layer fired on `rate_limited`. */
+    readonly layer: string | undefined;
+    /** The underlying cause (e.g., a `TypeError: fetch failed`) for
+     *  network/abort/timeout paths. `undefined` when the error came from a
+     *  successfully-parsed API error body. */
+    readonly cause: unknown;
+    constructor(message: string, init: {
+        status: number;
+        code: ScorezillaErrorCode;
+        reason?: string | undefined;
+        retryAfter?: number | undefined;
+        requestId?: string | undefined;
+        bound?: number | undefined;
+        layer?: string | undefined;
+        cause?: unknown;
+    });
+    /** `true` when this error is a 429 / `rate_limited`. */
+    isRateLimited(): boolean;
+    /** `true` when this error is a 401 / `unauthorized` (or 403 / `forbidden`). */
+    isAuth(): boolean;
+    /** `true` when this error is a 404 / `not_found`. */
+    isNotFound(): boolean;
+    /** `true` when this error is a 422 / `out_of_bounds` (score below/above board limit). */
+    isOutOfBounds(): boolean;
+    /** `true` for transient / retryable conditions: network errors, timeouts,
+     *  5xx, and 429. The transport layer relies on this for its retry policy. */
+    isTransient(): boolean;
+    /**
+     * Build a `ScorezillaError` from a fetch round-trip outcome.
+     *
+     * Prefer this over `new ScorezillaError(...)` from the transport layer —
+     * it does the mapping from API response shape to error fields in one
+     * place, so future fields like `correlationId` get added once here.
+     *
+     * @param init - status, optional parsed body, optional requestId, optional cause
+     */
+    static from(init: ScorezillaErrorFromInit): ScorezillaError;
+    /**
+     * Build a `ScorezillaError` for a transport-level failure (no HTTP
+     * response received): network error, abort, or timeout.
+     */
+    static network(message: string, cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for an `AbortSignal`-triggered cancellation. */
+    static aborted(cause: unknown): ScorezillaError;
+    /** Build a `ScorezillaError` for a request that exceeded its timeout budget. */
+    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 };