Vote return URL guide

<?php
// vote-callback.php: the page your Vote Return URL points to.
// Ranked Private Servers sends the player here after a counted vote.

const VOTE_KEY  = 'YOUR_SERVER_KEY'; // your server's key: Dashboard > Promo tools > Vote return
const MY_SERVER = '123';             // your server ID, the number in your vote link

session_start();

function vote_param(string $name): string
{
    return isset($_GET[$name]) && is_string($_GET[$name]) ? $_GET[$name] : '';
}

function vote_refuse(int $status, string $message): void
{
    http_response_code($status);
    exit($message);
}

$server_id = vote_param('server_id');
$vote_id   = vote_param('vote_id');
$timestamp = vote_param('timestamp');
$ip        = vote_param('ip');
$signature = vote_param('signature_v2');

// 1. The signature: HMAC-SHA256 of v2|server_id|vote_id|timestamp|ip with your key
$expected = hash_hmac('sha256', "v2|$server_id|$vote_id|$timestamp|$ip", VOTE_KEY);
if (!hash_equals($expected, $signature)) {
    vote_refuse(403, 'This vote link is not valid.');
}

// 2. It must be for your server
if ($server_id !== MY_SERVER) {
    vote_refuse(403, 'This vote is for another server.');
}

// 3. It must be fresh: at most an hour old, at most 5 minutes ahead of your clock
$age = time() - (int) $timestamp;
if ($age > 3600 || $age < -300) {
    vote_refuse(403, 'This vote link has expired.');
}

// 4. Reward the account that is logged in on your site
$account_id = $_SESSION['account_id'] ?? null; // use your own login's session value
if (!$account_id) {
    vote_refuse(401, 'Please log in, then open this link again.');
}

$db = new PDO('mysql:host=localhost;dbname=YOUR_DATABASE;charset=utf8mb4',
              'YOUR_DB_USER', 'YOUR_DB_PASSWORD', [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);

// 5. Optional: one reward per account a day
$recent = $db->prepare('SELECT 1 FROM vote_rewards
                         WHERE account_id = ? AND rewarded_at > NOW() - INTERVAL 23 HOUR');
$recent->execute([$account_id]);
if ($recent->fetchColumn()) {
    vote_refuse(409, 'You already had a vote reward today.');
}

// 6. Each vote pays once: vote_id is the table's primary key
try {
    $db->prepare('INSERT INTO vote_rewards (vote_id, account_id, rewarded_at) VALUES (?, ?, NOW())')
       ->execute([$vote_id, $account_id]);
} catch (PDOException $e) {
    if ((int) ($e->errorInfo[1] ?? 0) === 1062) { // duplicate key: this vote was paid before
        vote_refuse(409, 'This vote has already been rewarded.');
    }
    throw $e;
}

// 7. Give the reward to $account_id here, for example vote points.
echo 'Thank you for voting! Your reward has been added.';

// Node.js with Express and mysql2: the route your Vote Return URL points to.
// Ranked Private Servers sends the player here after a counted vote.
// Add it to your own Express app (app = express()), after the session
// middleware your site's login uses: req.session must say who is logged in.
const crypto = require('crypto');
const mysql = require('mysql2/promise');

const VOTE_KEY = 'YOUR_SERVER_KEY'; // your server's key: Dashboard > Promo tools > Vote return
const MY_SERVER = '123';            // your server ID, the number in your vote link
const db = mysql.createPool({
  host: 'localhost', user: 'YOUR_DB_USER', password: 'YOUR_DB_PASSWORD', database: 'YOUR_DATABASE',
});

app.get('/vote-callback', async (req, res) => {
  const param = (name) => (typeof req.query[name] === 'string' ? req.query[name] : '');
  const serverId = param('server_id');
  const voteId = param('vote_id');
  const timestamp = param('timestamp');
  const ip = param('ip');
  const signature = param('signature_v2');

  // 1. The signature: HMAC-SHA256 of v2|server_id|vote_id|timestamp|ip with your key
  const expected = Buffer.from(crypto.createHmac('sha256', VOTE_KEY)
    .update(`v2|${serverId}|${voteId}|${timestamp}|${ip}`)
    .digest('hex'));
  const received = Buffer.from(signature);
  if (received.length !== expected.length || !crypto.timingSafeEqual(received, expected)) {
    return res.status(403).send('This vote link is not valid.');
  }

  // 2. It must be for your server
  if (serverId !== MY_SERVER) {
    return res.status(403).send('This vote is for another server.');
  }

  // 3. It must be fresh: at most an hour old, at most 5 minutes ahead of your clock
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (age > 3600 || age < -300) {
    return res.status(403).send('This vote link has expired.');
  }

  // 4. Reward the account that is logged in on your site
  const accountId = req.session && req.session.accountId; // use your own login's session value
  if (!accountId) {
    return res.status(401).send('Please log in, then open this link again.');
  }

  try {
    // 5. Optional: one reward per account a day
    const [recent] = await db.execute(
      'SELECT 1 FROM vote_rewards WHERE account_id = ? AND rewarded_at > NOW() - INTERVAL 23 HOUR',
      [accountId]);
    if (recent.length > 0) {
      return res.status(409).send('You already had a vote reward today.');
    }
    // 6. Each vote pays once: vote_id is the table's primary key
    await db.execute('INSERT INTO vote_rewards (vote_id, account_id, rewarded_at) VALUES (?, ?, NOW())',
      [voteId, accountId]);
  } catch (err) {
    if (err.code === 'ER_DUP_ENTRY') { // duplicate key: this vote was paid before
      return res.status(409).send('This vote has already been rewarded.');
    }
    console.error(err);
    return res.status(500).send('Something went wrong. Please try again later.');
  }

  // 7. Give the reward to accountId here, for example vote points.
  res.send('Thank you for voting! Your reward has been added.');
});

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.SQLIntegrityConstraintViolationException;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

/** Checks the values Ranked Private Servers adds to your Vote Return URL. */
public final class VoteReturn {
    private static final String VOTE_KEY = "YOUR_SERVER_KEY"; // your server's key: Dashboard > Promo tools > Vote return
    private static final String MY_SERVER = "123";            // your server ID, the number in your vote link

    /** Null when the link is genuine, for your server and fresh; otherwise why it is refused. */
    public static String check(String serverId, String voteId, String timestamp, String ip, String signatureV2) {
        if (serverId == null || voteId == null || timestamp == null || ip == null || signatureV2 == null) {
            return "This vote link is not valid.";
        }
        // 1. The signature: HMAC-SHA256 of v2|server_id|vote_id|timestamp|ip with your key
        StringBuilder expected = new StringBuilder();
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(VOTE_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            byte[] raw = mac.doFinal(("v2|" + serverId + "|" + voteId + "|" + timestamp + "|" + ip)
                    .getBytes(StandardCharsets.UTF_8));
            for (byte b : raw) {
                expected.append(String.format("%02x", b));
            }
        } catch (Exception e) {
            return "This vote link is not valid.";
        }
        if (!MessageDigest.isEqual(expected.toString().getBytes(StandardCharsets.UTF_8),
                                   signatureV2.getBytes(StandardCharsets.UTF_8))) {
            return "This vote link is not valid.";
        }
        // 2. It must be for your server
        if (!serverId.equals(MY_SERVER)) {
            return "This vote is for another server.";
        }
        // 3. It must be fresh: at most an hour old, at most 5 minutes ahead of your clock
        long age = System.currentTimeMillis() / 1000L - Long.parseLong(timestamp);
        if (age > 3600 || age < -300) {
            return "This vote link has expired.";
        }
        return null;
    }

    /** Records the reward. Null when you may give it; otherwise why not. */
    public static String claim(Connection db, String voteId, long accountId) throws SQLException {
        // 5. Optional: one reward per account a day
        try (PreparedStatement recent = db.prepareStatement(
                "SELECT 1 FROM vote_rewards WHERE account_id = ? AND rewarded_at > NOW() - INTERVAL 23 HOUR")) {
            recent.setLong(1, accountId);
            try (ResultSet rs = recent.executeQuery()) {
                if (rs.next()) {
                    return "You already had a vote reward today.";
                }
            }
        }
        // 6. Each vote pays once: vote_id is the table's primary key
        try (PreparedStatement insert = db.prepareStatement(
                "INSERT INTO vote_rewards (vote_id, account_id, rewarded_at) VALUES (?, ?, NOW())")) {
            insert.setLong(1, Long.parseLong(voteId));
            insert.setLong(2, accountId);
            insert.executeUpdate();
        } catch (SQLIntegrityConstraintViolationException duplicate) {
            return "This vote has already been rewarded.";
        }
        return null;
    }
}

// In the servlet your Vote Return URL points to (doGet), after
// 4. taking accountId from your own login (send a logged-out player to log in first):
//
//     String problem = VoteReturn.check(request.getParameter("server_id"), request.getParameter("vote_id"),
//             request.getParameter("timestamp"), request.getParameter("ip"), request.getParameter("signature_v2"));
//     if (problem != null) {
//         response.sendError(403, problem);
//         return;
//     }
//     problem = VoteReturn.claim(db, request.getParameter("vote_id"), accountId);
//     if (problem != null) {
//         response.sendError(409, problem);
//         return;
//     }
//     // 7. Give the reward to accountId here, for example vote points.