scorezilla 0.1.0-next.1 → 0.1.0-next.3

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # 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

package/README.md

@@ -88,11 +88,11 @@ 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: {
-    id: process.env.SCOREZILLA_KEY_ID!,
-    secret: process.env.SCOREZILLA_KEY_SECRET!, // never ship to a browser
-  },
+  secretKey: process.env.SCOREZILLA_SECRET_KEY!, // never ship to a browser
 });
 
 await sz.submitScore({ boardId, playerId, score, metadata });

package/dist/{errors-Bp9ZDYqm.d.cts → errors-CUAQsaVS.d.cts}

@@ -31,6 +31,12 @@ interface BaseConfig {
     /** 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>`. */
@@ -38,14 +44,16 @@ type PublicKeyConfig = BaseConfig & {
     publicKey: string;
     secretKey?: never;
 };
-/** Secret-key auth: server-side HMAC. The pair `{ id, secret }` is what
- *  the operator dashboard issues; the SDK signs requests with `secret` and
- *  identifies them via `id`. */
+/** 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: {
-        id: string;
-        secret: string;
-    };
+    secretKey: string;
     publicKey?: never;
 };
 /** The top-level config type. The union is open for additional auth modes

package/dist/{errors-Bp9ZDYqm.d.ts → errors-CUAQsaVS.d.ts}

@@ -31,6 +31,12 @@ interface BaseConfig {
     /** 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>`. */
@@ -38,14 +44,16 @@ type PublicKeyConfig = BaseConfig & {
     publicKey: string;
     secretKey?: never;
 };
-/** Secret-key auth: server-side HMAC. The pair `{ id, secret }` is what
- *  the operator dashboard issues; the SDK signs requests with `secret` and
- *  identifies them via `id`. */
+/** 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: {
-        id: string;
-        secret: string;
-    };
+    secretKey: string;
     publicKey?: never;
 };
 /** The top-level config type. The union is open for additional auth modes

package/dist/index.cjs

@@ -32,6 +32,7 @@ function validateConfig(cfg) {
     fetch: cfg.fetch,
     timeoutMs: cfg.timeoutMs,
     maxRetries: cfg.maxRetries,
+    sleepImpl: cfg.sleepImpl,
     userAgent: cfg.userAgent,
     auth
   };
@@ -45,24 +46,25 @@ function validatePublicKeyValue(pk) {
   }
   return pk;
 }
+var SECRET_KEY_PATTERN = /^sk_live_([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})_[A-Za-z0-9]+$/;
 function validateSecretKey(cfg) {
   if (!cfg || typeof cfg !== "object") {
     throw new Error("scorezilla/server: config must be an object with a secretKey field");
   }
   const sk = cfg.secretKey;
-  if (!sk || typeof sk !== "object" || typeof sk.id !== "string" || typeof sk.secret !== "string") {
-    throw new Error("scorezilla/server: secretKey must be an object with string `id` and `secret`");
-  }
-  if (sk.id.length === 0) {
-    throw new Error("scorezilla/server: secretKey.id must be a non-empty string");
+  if (typeof sk !== "string") {
+    throw new Error(
+      `scorezilla/server: secretKey must be a single string of the shape ${SECRET_KEY_PREFIX}<keyId>_<random> (got: ${typeof sk})`
+    );
   }
-  if (!sk.secret.startsWith(SECRET_KEY_PREFIX)) {
-    const shape = `string of length ${sk.secret.length}`;
+  const match = SECRET_KEY_PATTERN.exec(sk);
+  if (!match) {
+    const shape = `string of length ${sk.length}`;
     throw new Error(
-      `scorezilla/server: secretKey.secret must start with "${SECRET_KEY_PREFIX}" (live keys only) (got: ${shape})`
+      `scorezilla/server: secretKey must match ${SECRET_KEY_PATTERN.toString()} (got: ${shape}). v0.1.0-next.2 switched to a single-token format \u2014 if you have a pre-next.2 pair, issue a fresh key in the dashboard to upgrade.`
     );
   }
-  return { keyId: sk.id, secret: sk.secret };
+  return { keyId: match[1], secret: sk };
 }
 
 // src/paths.ts
@@ -551,7 +553,7 @@ function validateMetadata(metadata) {
 }
 var Scorezilla = class _Scorezilla {
   /** The package version, injected at build time from `package.json`. */
-  static version = "0.1.0-next.1";
+  static version = "0.1.0-next.3";
   #config;
   #userAgent;
   #authHeader;
@@ -716,8 +718,11 @@ var Scorezilla = class _Scorezilla {
     if (opts.body !== void 0) requestOpts.body = opts.body;
     if (this.#config.fetch !== void 0) requestOpts.fetchImpl = this.#config.fetch;
     if (this.#config.timeoutMs !== void 0) requestOpts.timeoutMs = this.#config.timeoutMs;
-    if (this.#config.maxRetries !== void 0) {
-      requestOpts.retry = { maxRetries: this.#config.maxRetries };
+    if (this.#config.maxRetries !== void 0 || this.#config.sleepImpl !== void 0) {
+      requestOpts.retry = {
+        ...this.#config.maxRetries !== void 0 ? { maxRetries: this.#config.maxRetries } : {},
+        ...this.#config.sleepImpl !== void 0 ? { sleepImpl: this.#config.sleepImpl } : {}
+      };
     }
     return request(requestOpts);
   }
@@ -727,7 +732,7 @@ function createClient(config) {
 }
 
 // src/index.ts
-var SDK_VERSION = "0.1.0-next.1";
+var SDK_VERSION = "0.1.0-next.3";
 
 exports.SDK_VERSION = SDK_VERSION;
 exports.Scorezilla = Scorezilla;