playe-developer-sdk 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -18,9 +18,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Live leaderboards with player rankings
   - Player attempt history and statistics
 - Anti-cheat and validation systems
-  - Game session validation
+  - Game session validation with integrity verification
   - Score validation with basic cheat detection
   - Device fingerprinting and information collection
+  - Cryptographic session integrity with SHA-256 hashing
+  - Automatic game state verification and tampering detection
 - Developer tools and utilities
   - Test game session creation for development
   - Debug mode with comprehensive logging
@@ -44,7 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Game Session Management**: Complete lifecycle management of game sessions from initialization to completion
 - **Campaign Integration**: Support for all campaign styles (SingleWinner, FixedPool, Leaderboard, RewardForAll)
 - **Real-time Updates**: Live progress tracking and leaderboard updates
-- **Anti-cheat Protection**: Built-in validation mechanisms and heartbeat monitoring
+- **Anti-cheat Protection**: Advanced integrity verification, cryptographic validation, and heartbeat monitoring
 - **Device Detection**: Automatic device information gathering and fingerprinting
 - **Error Handling**: Comprehensive error types with context and debugging information
 - **Browser Events**: Custom DOM events for game lifecycle tracking

package/README.md

@@ -5,16 +5,18 @@ A comprehensive browser-based SDK for integrating games with the Playe platform.
 ## Features
 
 - 🎮 **Game Session Management** - Initialize, start, update, and complete game sessions
+- 🛡️ **Integrity Verification** - Built-in session integrity with cryptographic hashing and validation
 - 🏆 **Campaign Integration** - Access campaign information, leaderboards, and player attempts
-- 🛡️ **Anti-Cheat Protection** - Built-in validation and heartbeat mechanisms
+- 🔄 **Anti-Cheat Protection** - Advanced validation, heartbeat mechanisms, and session monitoring
 - 📱 **Device Detection** - Automatic device information and fingerprinting
-- 🔧 **Developer Tools** - Test game sessions and debugging utilities
+- 🔧 **Developer Tools** - Test game sessions and comprehensive debugging utilities
 - 📊 **Real-time Updates** - Progress tracking and live leaderboards
-- ⚡ **Browser Optimized** - Lightweight and fast for web games
+- ⚡ **Browser Optimized** - Lightweight and fast for web games with automatic retry logic
 
 ## Installation
 
 ### NPM (Recommended)
+
 ```bash
 npm install playe-developer-sdk
 # or
@@ -24,6 +26,7 @@ pnpm add playe-developer-sdk
 ```
 
 ### CDN (No build tools required)
+
 ```html
 <!-- For production -->
 <script src="https://unpkg.com/playe-developer-sdk@latest/dist/playe-sdk.umd.min.js"></script>
@@ -33,6 +36,7 @@ pnpm add playe-developer-sdk
 ```
 
 ### Workspace (Internal development)
+
 ```json
 {
   "dependencies": {
@@ -44,46 +48,67 @@ pnpm add playe-developer-sdk
 ## Quick Start
 
 ### NPM Usage
+
 ```typescript
-import { createPlayeSDK } from 'playe-developer-sdk';
+import { createPlayeSDK } from "playe-developer-sdk";
 
 // Initialize the SDK
 const sdk = createPlayeSDK({
-  apiBaseUrl: 'https://api.playe.com',
-  apiKey: 'your-api-key',
+  apiBaseUrl: "https://api.playe.com",
+  apiKey: "your-api-key",
   enableDebugMode: true, // Enable for development
 });
 
-// Initialize a game session
-const session = await sdk.initializeGameSession({
-  campaignId: 'campaign-123',
-  gameId: 'game-456',
-  playerFingerprint: 'unique-player-fingerprint',
-  playerEmail: 'player@example.com',
+// Initialize a game session (gets sessionId from URL query parameter)
+const session = await sdk.initializeGameSession();
+
+console.log("Game session initialized:", {
+  sessionId: session.sessionId,
+  campaignId: session.campaign.id,
+  playerId: session.player.id,
 });
 
 // Start the game
-await sdk.startGameSession(session.sessionId);
+await sdk.startGameSession({
+  difficulty: "normal",
+  mode: "classic",
+});
 
-// Update progress during gameplay
-await sdk.updateGameProgress(session.sessionId, {
+// Update progress during gameplay (includes automatic integrity verification)
+await sdk.updateGameProgress({
   currentScore: 1500,
   elapsedTime: 120, // seconds
-  gameState: { level: 3, lives: 2 },
+  gameState: {
+    level: 3,
+    lives: 2,
+    powerUps: ["speed", "shield"],
+  },
+  achievements: [
+    {
+      id: "level-3",
+      name: "Level 3 Complete",
+      unlockedAt: new Date().toISOString(),
+    },
+  ],
 });
 
-// Complete the game
-const result = await sdk.completeGame(session.sessionId, {
+// Complete the game (includes integrity verification)
+const result = await sdk.completeGame({
   finalScore: 2500,
+  validationChecksum: "client-checksum",
   gameMetrics: {
     totalPlayTime: 300,
     actionsPerformed: 150,
     powerUpsUsed: 5,
     levelsCompleted: 5,
   },
+  finalGameState: {
+    level: 5,
+    finalLives: 1,
+  },
 });
 
-console.log('Game completed!', {
+console.log("Game completed!", {
   isWinner: result.isWinner,
   finalRank: result.finalRank,
   prizeAmount: result.prizeAmount,
@@ -91,25 +116,24 @@ console.log('Game completed!', {
 ```
 
 ### CDN Usage
+
 ```html
 <script src="https://unpkg.com/playe-developer-sdk@latest/dist/playe-sdk.umd.min.js"></script>
 <script>
-// SDK is available as global PlayeSDK
-const sdk = PlayeSDK.createPlayeSDK({
-  apiBaseUrl: 'https://api.playe.com',
-  apiKey: 'your-api-key',
-  enableDebugMode: true,
-});
+  // SDK is available as global PlayeSDK
+  const sdk = PlayeSDK.createPlayeSDK({
+    apiBaseUrl: 'https://api.playe.com',
+    apiKey: 'your-api-key',
+    enableDebugMode: true,
+  });
 
-// All utilities are available
-const fingerprint = PlayeSDK.DeviceUtils.generateFingerprint();
+  // All utilities are available
+  const fingerprint = PlayeSDK.DeviceUtils.generateFingerprint();
 
-// Same API as NPM version
-const session = await sdk.initializeGameSession({
-  campaignId: 'campaign-123',
-  gameId: 'game-456',
-  playerFingerprint: fingerprint,
-});
+  // Same API as NPM version
+  const session = await sdk.initializeGameSession(); // Gets sessionId from URL
+
+  console.log('Session initialized:', session.sessionId);
 </script>
 ```
 
@@ -119,11 +143,11 @@ const session = await sdk.initializeGameSession({
 
 ```typescript
 interface SDKConfig {
-  apiBaseUrl: string;           // Required: API base URL
-  apiKey?: string;             // Optional: API key for authentication
-  enableDebugMode?: boolean;   // Optional: Enable debug logging
-  retryAttempts?: number;      // Optional: Number of retry attempts (default: 3)
-  timeoutMs?: number;          // Optional: Request timeout in ms (default: 30000)
+  apiBaseUrl: string; // Required: API base URL
+  apiKey?: string; // Optional: API key for authentication
+  enableDebugMode?: boolean; // Optional: Enable debug logging
+  retryAttempts?: number; // Optional: Number of retry attempts (default: 3)
+  timeoutMs?: number; // Optional: Request timeout in ms (default: 30000)
   enableOfflineMode?: boolean; // Optional: Enable offline mode (default: false)
 }
 ```
@@ -133,85 +157,108 @@ interface SDKConfig {
 #### Game Session Management
 
 ```typescript
-// Initialize a new game session
-await sdk.initializeGameSession({
-  campaignId: string;
-  gameId: string;
-  playerFingerprint: string;
-  playerEmail?: string;
-  deviceInfo?: DeviceInfo;
-  receiptImage?: string;        // Base64 encoded
-  geolocationData?: GeolocationData;
-});
+// Initialize game session (gets sessionId from URL query parameter)
+const session = await sdk.initializeGameSession(): Promise<GameSessionResponse>;
 
 // Start the game session
-await sdk.startGameSession(sessionId: string, config?: Record<string, any>);
+await sdk.startGameSession(config?: Record<string, any>): Promise<GameSessionResponse>;
 
-// Update game progress
-await sdk.updateGameProgress(sessionId: string, {
+// Update game progress with integrity verification
+await sdk.updateGameProgress({
   currentScore: number;
-  gameState?: Record<string, any>;
+  gameState?: Record<string, any>;  // Automatically hashed for integrity
   elapsedTime: number;
   achievements?: Achievement[];
   clientTimestamp?: string;
-});
+}): Promise<ProgressUpdateResponse>;
 
-// Complete the game
-await sdk.completeGame(sessionId: string, {
+// Complete the game with integrity verification
+await sdk.completeGame({
   finalScore: number;
+  validationChecksum: string;
   gameMetrics?: GameMetrics;
-  finalGameState?: Record<string, any>;
-});
+  finalGameState?: Record<string, any>;  // Automatically hashed for integrity
+}): Promise<GameCompletionResponse>;
 
 // Abandon the game
-await sdk.abandonGame(sessionId: string, reason?: string, lastKnownScore?: number);
+await sdk.abandonGame(reason?: string, lastKnownScore?: number): Promise<AbandonGameResponse>;
 ```
 
 #### Campaign Information
 
 ```typescript
 // Get campaign status
-await sdk.getCampaignStatus(campaignId: string, playerId?: string);
+await sdk.getCampaignStatus(campaignId: string, playerId?: string): Promise<CampaignStatusResponse>;
 
 // Get leaderboard
-await sdk.getLeaderboard(campaignId: string, limit?: number, playerId?: string);
+await sdk.getLeaderboard(campaignId: string, limit?: number, playerId?: string): Promise<LeaderboardResponse>;
 
 // Get player attempts
-await sdk.getPlayerAttempts(campaignId: string, playerId: string);
+await sdk.getPlayerAttempts(campaignId: string, playerId: string): Promise<PlayerAttemptsResponse>;
 ```
 
 #### Validation & Anti-Cheat
 
 ```typescript
-// Validate game session
-await sdk.validateGameSession(sessionId: string, validationData?: Record<string, any>);
+// Validate game session with integrity verification
+await sdk.validateGameSession({
+  clientChecksum: string;
+  stateSnapshot?: Record<string, unknown>;  // Automatically hashed
+  timingData?: unknown;
+  behaviorMetrics?: unknown;
+}): Promise<ValidationResponse>;
 
 // Send heartbeat (usually handled automatically)
-await sdk.sendHeartbeat(sessionId: string, currentScore?: number);
+await sdk.sendHeartbeat(currentScore?: number): Promise<HeartbeatResponse>;
+```
+
+#### Developer Tools
+
+```typescript
+// Create test game session for development
+await sdk.createTestGameSession(testConfig?: Record<string, any>): Promise<TestGameResponse>;
 ```
 
 ### Utility Methods
 
 ```typescript
 // Test SDK functionality
-sdk.test('Custom test message');
+sdk.test('Custom test message'): void;
 
 // Check if running in demo mode
-const isDemoMode = sdk.isDemo();
+const isDemoMode = sdk.isDemo(): boolean;
 
 // Game lifecycle events
-sdk.gameLoadingStart();
-sdk.gameLoadingFinished();
-sdk.gamePlayStop();
+sdk.gameLoadingStart(): void;     // Emit loading start event
+sdk.gameLoadingFinished(): void;  // Emit loading finished event
+sdk.gamePlayStop(): void;         // Stop heartbeat and emit stop event
 
 // Clean up resources
-sdk.destroy();
+sdk.destroy(): void;              // Clean up session artifacts and stop heartbeat
+```
+
+### Integrity Verification Utilities
+
+```typescript
+import { canonicalStringify, sha256Hex, buildIntegrityHeaders, computeGameStateHash } from "playe-developer-sdk";
+
+// Canonical JSON stringification (deterministic)
+const canonical = canonicalStringify({ b: 1, a: 2 }); // '{"a":2,"b":1}'
+
+// SHA-256 hashing
+const hash = await sha256Hex("data to hash");
+
+// Build integrity headers (used internally)
+const headers = buildIntegrityHeaders(sessionToken);
+
+// Compute game state hash with session salt
+const gameStateHash = await computeGameStateHash(gameState, sessionSalt);
 ```
 
 ### Device Utilities
 
 ```typescript
-import { DeviceUtils } from '@workspace/playe-developer-sdk';
+import { DeviceUtils } from "@workspace/playe-developer-sdk";
 
 // Get device information
 const deviceInfo = DeviceUtils.getDeviceInfo();
@@ -230,25 +277,25 @@ const features = DeviceUtils.getFeatureSupport();
 ### Error Handling
 
 ```typescript
-import { 
-  PlayeSDKError, 
-  ValidationError, 
-  NetworkError, 
+import {
+  PlayeSDKError,
+  ValidationError,
+  NetworkError,
   AuthenticationError,
-  GameSessionError 
-} from '@workspace/playe-developer-sdk';
+  GameSessionError,
+} from "@workspace/playe-developer-sdk";
 
 try {
   await sdk.initializeGameSession(params);
 } catch (error) {
   if (error instanceof ValidationError) {
-    console.error('Validation failed:', error.message);
+    console.error("Validation failed:", error.message);
   } else if (error instanceof NetworkError) {
-    console.error('Network error:', error.message);
+    console.error("Network error:", error.message);
   } else if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', error.message);
+    console.error("Authentication failed:", error.message);
   } else if (error instanceof PlayeSDKError) {
-    console.error('SDK error:', error.toJSON());
+    console.error("SDK error:", error.toJSON());
   }
 }
 ```
@@ -268,17 +315,51 @@ The SDK emits custom browser events for tracking:
 
 ```typescript
 // Listen for SDK events
-window.addEventListener('playe:game-loading-start', () => {
-  console.log('Game loading started');
+window.addEventListener("playe:game-loading-start", () => {
+  console.log("Game loading started");
+});
+
+window.addEventListener("playe:game-loading-finished", () => {
+  console.log("Game loading finished");
 });
 
-window.addEventListener('playe:game-loading-finished', () => {
-  console.log('Game loading finished');
+window.addEventListener("playe:game-play-stop", () => {
+  console.log("Game play stopped");
 });
+```
+
+## Integrity Verification
+
+The SDK includes built-in integrity verification to prevent cheating and ensure fair play:
+
+### Automatic Features
+
+- **Session Integrity**: Each game session includes a unique session token and salt
+- **Game State Hashing**: Game states are automatically hashed using SHA-256 with session salt
+- **Integrity Headers**: All authenticated requests include cryptographic integrity headers
+- **Retry Logic**: Failed requests due to integrity issues are automatically retried with fresh headers
+
+### How It Works
+
+1. **Session Initialization**: SDK receives session token and salt from server
+2. **State Hashing**: Game states are canonicalized and hashed with session salt
+3. **Request Signing**: Integrity headers are built with timestamp, nonce, and session token
+4. **Server Validation**: Server verifies hashes and headers to detect tampering
+
+### Manual Verification (Advanced)
 
-window.addEventListener('playe:game-play-stop', () => {
-  console.log('Game play stopped');
+```typescript
+// Manually validate game session
+const validation = await sdk.validateGameSession({
+  clientChecksum: "calculated-checksum",
+  stateSnapshot: currentGameState,
+  timingData: { avgResponseTime: 250 },
+  behaviorMetrics: { clicksPerSecond: 5.2 },
 });
+
+if (!validation.isValid) {
+  console.log("Validation issues:", validation.validationIssues);
+}
 ```
 
 ## Development
@@ -288,10 +369,14 @@ window.addEventListener('playe:game-play-stop', () => {
 ```typescript
 // Create a test game session for development
 const testSession = await sdk.createTestGameSession({
-  mockCampaign: true,
-  mockPlayers: 10,
-  testScenario: 'leaderboard',
+  testConfig: {
+    mockCampaign: true,
+    mockPlayers: 10,
+    testScenario: "leaderboard",
+  },
 });
+
+console.log("Test session created:", testSession.testSessionId);
 ```
 
 ### Debug Mode
@@ -300,11 +385,21 @@ Enable debug mode to see detailed logging:
 
 ```typescript
 const sdk = createPlayeSDK({
-  apiBaseUrl: 'https://api.playe.com',
-  enableDebugMode: true, // This will log all API calls and responses
+  apiBaseUrl: "https://api.playe.com",
+  enableDebugMode: true, // This will log all API calls, integrity operations, and responses
 });
 ```
 
+### URL Requirements
+
+For `initializeGameSession()` to work, the page URL must include a `sessionId` query parameter:
+
+```
+https://yourgame.com/play?sessionId=abc123-def456-ghi789
+```
+
+The SDK will automatically extract this sessionId and initialize the session.
+
 ## Browser Compatibility
 
 - Chrome 60+
@@ -321,8 +416,9 @@ The SDK is available in multiple formats:
 - **Workspace**: `@workspace/playe-developer-sdk` (internal development)
 
 ### Bundle Sizes
+
 - ESM: 27.3KB (8KB gzipped)
-- CommonJS: 27.6KB (8KB gzipped)  
+- CommonJS: 27.6KB (8KB gzipped)
 - UMD: 30.8KB (9KB gzipped)
 - UMD Minified: 13.7KB (5KB gzipped)