keeperboard 2.1.1 → 2.2.1

package/README.md

@@ -233,6 +233,81 @@ try {
 
 ---
 
+## Anti-Cheat Protection
+
+KeeperBoard provides optional anti-cheat measures to prevent casual leaderboard hacking:
+
+### 1. HMAC Signing
+
+When enabled, all requests are cryptographically signed to prevent tampering.
+
+```typescript
+const session = new KeeperBoardSession({
+  apiKey: 'kb_prod_xxx',
+  leaderboard: 'main',
+  signingSecret: process.env.KEEPERBOARD_SIGNING_SECRET, // From dashboard
+});
+```
+
+**Setup:**
+1. Enable "HMAC Signing" in KeeperBoard dashboard
+2. Copy the signing secret
+3. Add to your game's environment variables
+4. Pass to SDK constructor
+
+### 2. Run Tokens
+
+For stronger protection, use run tokens to bind scores to game sessions:
+
+```typescript
+// When game starts
+await session.startRun();
+
+// ... player plays the game ...
+
+// When game ends (instead of submitScore)
+const result = await session.finishRun(score);
+if (result.isNewHighScore) {
+  console.log('New high score!');
+}
+```
+
+**Server validates:**
+- Run token exists and hasn't been used
+- Minimum elapsed time passed (e.g., 5+ seconds)
+- Score is within cap (if configured)
+- Signature is valid (if signing enabled)
+
+### 3. Build Obfuscation
+
+For browser games, obfuscate your production build to make reverse-engineering harder:
+
+```javascript
+// vite.config.js
+import obfuscatorPlugin from 'vite-plugin-javascript-obfuscator';
+
+export default {
+  plugins: [
+    obfuscatorPlugin({
+      include: ['src/**/*.ts'],
+      apply: 'build',
+      options: {
+        compact: true,
+        controlFlowFlattening: true,
+        stringArray: true,
+        stringArrayEncoding: ['base64'],
+      },
+    }),
+  ],
+};
+```
+
+### Security Model
+
+These measures stop **casual cheaters** (DevTools interception, simple replay attacks). Determined reverse-engineers with time and skill may still find ways around them. This is an acceptable tradeoff for most indie games.
+
+---
+
 ## Phaser.js Integration
 
 ```typescript
@@ -242,6 +317,7 @@ import { KeeperBoardSession } from 'keeperboard';
 const leaderboard = new KeeperBoardSession({
   apiKey: import.meta.env.VITE_KEEPERBOARD_API_KEY,
   leaderboard: 'main',
+  signingSecret: import.meta.env.VITE_KEEPERBOARD_SIGNING_SECRET, // Optional
   cache: { ttlMs: 30000 },
   retry: { maxAgeMs: 86400000 },
 });
@@ -255,11 +331,20 @@ class BootScene extends Phaser.Scene {
   }
 }
 
-// In GameOverScene
+// In GameScene - start run for anti-cheat
+class GameScene extends Phaser.Scene {
+  async create() {
+    await leaderboard.startRun(); // Optional: enables run token validation
+    // ... game logic ...
+  }
+}
+
+// In GameOverScene - use finishRun if run was started
 class GameOverScene extends Phaser.Scene {
   async create() {
-    const result = await leaderboard.submitScore(this.score);
-    if (result.success) {
+    // finishRun() uses run token if active, falls back to submitScore()
+    const result = await leaderboard.finishRun(this.score);
+    if (result.isNewHighScore) {
       this.showRank(result.rank, result.isNewHighScore);
     }
 

package/dist/index.d.mts

@@ -10,6 +10,8 @@ interface KeeperBoardConfig {
     apiKey: string;
     /** Default leaderboard name — used when no leaderboard is specified in method calls */
     defaultLeaderboard?: string;
+    /** Signing secret for HMAC request signing (get from dashboard when signing is enabled) */
+    signingSecret?: string;
     /** @internal Base URL override for testing. Do not use in production. */
     apiUrl?: string;
 }
@@ -48,6 +50,20 @@ interface ClaimScoreOptions {
     /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
     leaderboard?: string;
 }
+interface StartRunOptions {
+    playerGuid: string;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+}
+interface FinishRunOptions {
+    runId: string;
+    playerGuid: string;
+    playerName: string;
+    score: number;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+    metadata?: Record<string, unknown>;
+}
 interface ScoreResult {
     id: string;
     playerGuid: string;
@@ -93,6 +109,16 @@ interface HealthResult {
     version: string;
     timestamp: string;
 }
+interface StartRunResult {
+    runId: string;
+    startedAt: string;
+    expiresAt: string;
+}
+interface FinishRunResult {
+    scoreId: string;
+    rank: number;
+    isNewHighScore: boolean;
+}
 type ErrorCode = 'PROFANITY_DETECTED' | 'RATE_LIMITED' | 'INVALID_REQUEST' | 'NOT_FOUND' | 'INTERNAL_ERROR';
 interface SessionConfig {
     /** API key from the KeeperBoard dashboard */
@@ -111,6 +137,8 @@ interface SessionConfig {
     retry?: {
         maxAgeMs?: number;
     };
+    /** Signing secret for HMAC request signing (get from dashboard when signing is enabled) */
+    signingSecret?: string;
     /** @internal Base URL override for testing. */
     apiUrl?: string;
 }
@@ -233,6 +261,7 @@ declare class KeeperBoardClient {
     private readonly apiUrl;
     private readonly apiKey;
     private readonly defaultLeaderboard?;
+    private readonly signingSecret?;
     constructor(config: KeeperBoardConfig);
     /**
      * Submit a score. Only updates if the new score is higher than the existing one.
@@ -288,10 +317,41 @@ declare class KeeperBoardClient {
      * Check if the API is healthy. Does not require an API key.
      */
     healthCheck(): Promise<HealthResult>;
+    /**
+     * Start a game run. Use this when the leaderboard requires run tokens.
+     * Returns a run ID that must be passed to finishRun() when submitting the score.
+     *
+     * @example
+     * const run = await client.startRun({ playerGuid: 'abc-123' });
+     * // ... play game ...
+     * const result = await client.finishRun({
+     *   runId: run.runId,
+     *   playerGuid: 'abc-123',
+     *   playerName: 'ACE',
+     *   score: 1500,
+     * });
+     */
+    startRun(options: StartRunOptions): Promise<StartRunResult>;
+    /**
+     * Finish a game run and submit the score.
+     * The run must have been started with startRun() first.
+     *
+     * @example
+     * const result = await client.finishRun({
+     *   runId: run.runId,
+     *   playerGuid: 'abc-123',
+     *   playerName: 'ACE',
+     *   score: 1500,
+     * });
+     * console.log(result.rank, result.isNewHighScore);
+     */
+    finishRun(options: FinishRunOptions): Promise<FinishRunResult>;
     private mapScoreResponse;
     private mapLeaderboardResponse;
     private mapPlayerResponse;
     private mapClaimResponse;
+    private mapStartRunResponse;
+    private mapFinishRunResponse;
     private request;
 }
 
@@ -312,6 +372,7 @@ declare class KeeperBoardSession {
     private readonly retryQueue;
     private cachedLimit;
     private isSubmitting;
+    private currentRunId;
     constructor(config: SessionConfig);
     /** Get or create a persistent player GUID. */
     getPlayerGuid(): string;
@@ -331,6 +392,31 @@ declare class KeeperBoardSession {
      * Prevents concurrent double-submissions.
      */
     submitScore(score: number, metadata?: Record<string, unknown>): Promise<SessionScoreResult>;
+    /**
+     * Start a game run. Call this when a game session begins.
+     * For leaderboards with `require_run_token` enabled, scores must be submitted via finishRun().
+     *
+     * The run ID is stored internally and used automatically by finishRun().
+     *
+     * @example
+     * await session.startRun();
+     * // ... play game ...
+     * const result = await session.finishRun(1500);
+     */
+    startRun(): Promise<StartRunResult>;
+    /**
+     * Finish a game run and submit the score.
+     * Must be called after startRun(). Uses the stored run ID automatically.
+     *
+     * @example
+     * const result = await session.finishRun(1500);
+     * if (result.isNewHighScore) console.log('New high score!');
+     */
+    finishRun(score: number, metadata?: Record<string, unknown>): Promise<FinishRunResult>;
+    /** Check if there's an active run in progress. */
+    hasActiveRun(): boolean;
+    /** Get the current run ID, or null if no run is active. */
+    getCurrentRunId(): string | null;
     /**
      * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
      * plus the current player's rank if they're outside the top N.
@@ -519,4 +605,4 @@ declare class RetryQueue {
     clear(): void;
 }
 
-export { Cache, type ClaimResponse, type ClaimResult, type ClaimScoreOptions, type ErrorCode, type GetLeaderboardOptions, type GetPlayerRankOptions, type HealthResponse, type HealthResult, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, KeeperBoardSession, type LeaderboardEntry, type LeaderboardResponse, type LeaderboardResult, type NameValidationOptions, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type PlayerResult, type ResetSchedule, RetryQueue, type ScoreResponse, type ScoreResult, type ScoreSubmission, type SessionConfig, type SessionScoreResult, type SnapshotEntry, type SnapshotResult, type SubmitScoreOptions, type UpdateNameResult, type UpdatePlayerNameOptions, generatePlayerName, validateName };
+export { Cache, type ClaimResponse, type ClaimResult, type ClaimScoreOptions, type ErrorCode, type FinishRunOptions, type FinishRunResult, type GetLeaderboardOptions, type GetPlayerRankOptions, type HealthResponse, type HealthResult, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, KeeperBoardSession, type LeaderboardEntry, type LeaderboardResponse, type LeaderboardResult, type NameValidationOptions, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type PlayerResult, type ResetSchedule, RetryQueue, type ScoreResponse, type ScoreResult, type ScoreSubmission, type SessionConfig, type SessionScoreResult, type SnapshotEntry, type SnapshotResult, type StartRunOptions, type StartRunResult, type SubmitScoreOptions, type UpdateNameResult, type UpdatePlayerNameOptions, generatePlayerName, validateName };

package/dist/index.d.ts

@@ -10,6 +10,8 @@ interface KeeperBoardConfig {
     apiKey: string;
     /** Default leaderboard name — used when no leaderboard is specified in method calls */
     defaultLeaderboard?: string;
+    /** Signing secret for HMAC request signing (get from dashboard when signing is enabled) */
+    signingSecret?: string;
     /** @internal Base URL override for testing. Do not use in production. */
     apiUrl?: string;
 }
@@ -48,6 +50,20 @@ interface ClaimScoreOptions {
     /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
     leaderboard?: string;
 }
+interface StartRunOptions {
+    playerGuid: string;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+}
+interface FinishRunOptions {
+    runId: string;
+    playerGuid: string;
+    playerName: string;
+    score: number;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+    metadata?: Record<string, unknown>;
+}
 interface ScoreResult {
     id: string;
     playerGuid: string;
@@ -93,6 +109,16 @@ interface HealthResult {
     version: string;
     timestamp: string;
 }
+interface StartRunResult {
+    runId: string;
+    startedAt: string;
+    expiresAt: string;
+}
+interface FinishRunResult {
+    scoreId: string;
+    rank: number;
+    isNewHighScore: boolean;
+}
 type ErrorCode = 'PROFANITY_DETECTED' | 'RATE_LIMITED' | 'INVALID_REQUEST' | 'NOT_FOUND' | 'INTERNAL_ERROR';
 interface SessionConfig {
     /** API key from the KeeperBoard dashboard */
@@ -111,6 +137,8 @@ interface SessionConfig {
     retry?: {
         maxAgeMs?: number;
     };
+    /** Signing secret for HMAC request signing (get from dashboard when signing is enabled) */
+    signingSecret?: string;
     /** @internal Base URL override for testing. */
     apiUrl?: string;
 }
@@ -233,6 +261,7 @@ declare class KeeperBoardClient {
     private readonly apiUrl;
     private readonly apiKey;
     private readonly defaultLeaderboard?;
+    private readonly signingSecret?;
     constructor(config: KeeperBoardConfig);
     /**
      * Submit a score. Only updates if the new score is higher than the existing one.
@@ -288,10 +317,41 @@ declare class KeeperBoardClient {
      * Check if the API is healthy. Does not require an API key.
      */
     healthCheck(): Promise<HealthResult>;
+    /**
+     * Start a game run. Use this when the leaderboard requires run tokens.
+     * Returns a run ID that must be passed to finishRun() when submitting the score.
+     *
+     * @example
+     * const run = await client.startRun({ playerGuid: 'abc-123' });
+     * // ... play game ...
+     * const result = await client.finishRun({
+     *   runId: run.runId,
+     *   playerGuid: 'abc-123',
+     *   playerName: 'ACE',
+     *   score: 1500,
+     * });
+     */
+    startRun(options: StartRunOptions): Promise<StartRunResult>;
+    /**
+     * Finish a game run and submit the score.
+     * The run must have been started with startRun() first.
+     *
+     * @example
+     * const result = await client.finishRun({
+     *   runId: run.runId,
+     *   playerGuid: 'abc-123',
+     *   playerName: 'ACE',
+     *   score: 1500,
+     * });
+     * console.log(result.rank, result.isNewHighScore);
+     */
+    finishRun(options: FinishRunOptions): Promise<FinishRunResult>;
     private mapScoreResponse;
     private mapLeaderboardResponse;
     private mapPlayerResponse;
     private mapClaimResponse;
+    private mapStartRunResponse;
+    private mapFinishRunResponse;
     private request;
 }
 
@@ -312,6 +372,7 @@ declare class KeeperBoardSession {
     private readonly retryQueue;
     private cachedLimit;
     private isSubmitting;
+    private currentRunId;
     constructor(config: SessionConfig);
     /** Get or create a persistent player GUID. */
     getPlayerGuid(): string;
@@ -331,6 +392,31 @@ declare class KeeperBoardSession {
      * Prevents concurrent double-submissions.
      */
     submitScore(score: number, metadata?: Record<string, unknown>): Promise<SessionScoreResult>;
+    /**
+     * Start a game run. Call this when a game session begins.
+     * For leaderboards with `require_run_token` enabled, scores must be submitted via finishRun().
+     *
+     * The run ID is stored internally and used automatically by finishRun().
+     *
+     * @example
+     * await session.startRun();
+     * // ... play game ...
+     * const result = await session.finishRun(1500);
+     */
+    startRun(): Promise<StartRunResult>;
+    /**
+     * Finish a game run and submit the score.
+     * Must be called after startRun(). Uses the stored run ID automatically.
+     *
+     * @example
+     * const result = await session.finishRun(1500);
+     * if (result.isNewHighScore) console.log('New high score!');
+     */
+    finishRun(score: number, metadata?: Record<string, unknown>): Promise<FinishRunResult>;
+    /** Check if there's an active run in progress. */
+    hasActiveRun(): boolean;
+    /** Get the current run ID, or null if no run is active. */
+    getCurrentRunId(): string | null;
     /**
      * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
      * plus the current player's rank if they're outside the top N.
@@ -519,4 +605,4 @@ declare class RetryQueue {
     clear(): void;
 }
 
-export { Cache, type ClaimResponse, type ClaimResult, type ClaimScoreOptions, type ErrorCode, type GetLeaderboardOptions, type GetPlayerRankOptions, type HealthResponse, type HealthResult, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, KeeperBoardSession, type LeaderboardEntry, type LeaderboardResponse, type LeaderboardResult, type NameValidationOptions, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type PlayerResult, type ResetSchedule, RetryQueue, type ScoreResponse, type ScoreResult, type ScoreSubmission, type SessionConfig, type SessionScoreResult, type SnapshotEntry, type SnapshotResult, type SubmitScoreOptions, type UpdateNameResult, type UpdatePlayerNameOptions, generatePlayerName, validateName };
+export { Cache, type ClaimResponse, type ClaimResult, type ClaimScoreOptions, type ErrorCode, type FinishRunOptions, type FinishRunResult, type GetLeaderboardOptions, type GetPlayerRankOptions, type HealthResponse, type HealthResult, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, KeeperBoardSession, type LeaderboardEntry, type LeaderboardResponse, type LeaderboardResult, type NameValidationOptions, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type PlayerResult, type ResetSchedule, RetryQueue, type ScoreResponse, type ScoreResult, type ScoreSubmission, type SessionConfig, type SessionScoreResult, type SnapshotEntry, type SnapshotResult, type StartRunOptions, type StartRunResult, type SubmitScoreOptions, type UpdateNameResult, type UpdatePlayerNameOptions, generatePlayerName, validateName };