Security Guide

1. Token Validation

ALWAYS validate token transfers server-side:

// WRONG - Client-side only
async function buyItem(price: number) {
    await sdk.triggerAction("transferTokens", {
        recipient: gameWalletAddress,
        amount: price
    });
    // DON'T update game state here!
}

// RIGHT - Server-side validation
app.post('/validate', async (req, res) => {
    const { sender, recipient, amount, validatedTransfer } = req.body;
    
    // 1. Check Games.fun validation
    if (!validatedTransfer) {
        return res.json({ error: 'Transfer not validated' });
    }
    
    // 2. Verify recipient is your game wallet
    if (recipient !== gameWalletAddress) {
        return res.json({ error: 'Invalid recipient' });
    }
    
    // 3. Verify token mint
    if (validatedTransfer.token !== process.env.GAME_TOKEN_MINT) {
        return res.json({ error: 'Invalid token' });
    }
    
    // 4. Only NOW update game state
    await updatePlayerBalance(sender, amount * 10);
});

2. JWT Authentication

NEVER skip JWT verification:

// WRONG - No JWT check
ws.on('message', (data) => {
    const { type, itemId } = JSON.parse(data);
    if (type === 'purchase') {
        handlePurchase(itemId); // UNSAFE!
    }
});

// RIGHT - Always verify JWT
ws.on('message', async (data) => {
    const { type, itemId, jwt } = JSON.parse(data);
    
    // 1. Verify JWT first
    const jwtResult = await verifyJWT(jwt);
    if (!jwtResult.valid) {
        ws.send(JSON.stringify({
            type: 'error',
            error: 'Authentication required'
        }));
        return;
    }
    
    // 2. Verify player matches token
    const tokenPlayerId = jwtResult.payload.sub;
    if (playerId !== tokenPlayerId) {
        ws.send(JSON.stringify({
            type: 'error',
            error: 'Invalid authentication'
        }));
        return;
    }
    
    // 3. Only NOW handle action
    if (type === 'purchase') {
        handlePurchase(itemId);
    }
});

Key Points

1. Token Security

• Games.fun validates transfers on-chain

• Your server MUST verify the validation

• Only update state after validation

• Check token mint address

1. Authentication Security

• Always verify JWT tokens

• Check token expiration

• Verify player matches token

• Keep tokens in memory only

1. Common Mistakes

• Updating state before validation

• Skipping JWT verification

• Not checking token mint

• Storing JWT in localStorage

1. Best Practices

• Use environment variables

• Log security events

• Rate limit requests

• Keep dependencies updated