feat: add SBPP_BanPlayerBySteamId native for offline player bans (#1511)

* feat: add SBPP_BanPlayerBySteamId native for offline player bans

SBPP_BanPlayer requires an in-game client index, making it impossible
to ban players who disconnect before an automated ban fires. The new
native accepts a SteamID string and player name directly, allowing
plugins to record a ban in the SBPP database for players who are no
longer connected.

Implementation:
- Checks for an existing active ban first (duplicate-prevention SELECT)
- Inserts into sb_bans with length in seconds (iTime * 60) and the
  IFNULL admin-lookup subquery, matching the pattern used by CommandAddBan
- Uses a server-lookup subquery when serverID == -1 (unregistered), or
  the cached serverID directly
- Fires SBPP_OnBanPlayer with iTarget = -1 to signal an offline ban

sourcebanspp.inc:
- Declares the new native with full doc comment
- Adds MarkNativeAsOptional in __pl_sourcebanspp_SetNTVOptional

* fix: validate SteamID2 format before inserting ban

SBPP enforces bans on connect using AuthId_Steam2. If a caller passed
a SteamID64 or SteamID3 the ban would be stored but never fire.
Now throws a native error immediately if the steamId argument does not
start with 'STEAM_'.

Addresses review comment from rumblefrog on PR #1511.

* fix: only fire SBPP_OnBanPlayer after the ban INSERT succeeds

Addresses review nit on PR #1511 (rumblefrog): the forward was fired
synchronously right after issuing the async duplicate-check SELECT,
before the ban row was ever written. It now fires from
DB_OnBanBySteamIdInsert only when the INSERT query succeeds.

* fix: harden offline SteamID ban native

---------

Co-authored-by: rumblefrog <contact@zhenyangli.me>

Author: Sigibert

CHANGELOG.md

@@ -116,6 +116,9 @@ Legend:
         `SBPP_OnClientPostAdminCheck` (#1431). Plugins that only call
         existing SBPP ban/report forwards/natives can usually keep their
         existing `.smx`. ([#1114](https://github.com/sbpp/sourcebans-pp/issues/1114))
+37. * `SBPP_BanPlayerBySteamId` SourceMod native for adding a ban after
+        the target disconnects. This raises `SOURCEBANSPP_VERSION_MINOR`
+        to `1` (#1511).
 ```
 
 ### Privacy

game/addons/sourcemod/scripting/include/sbpp_version.inc

@@ -11,7 +11,7 @@
 #define _sbpp_version_included
 
 #define MAJOR_REVISION                    2
-#define MINOR_REVISION                    0
+#define MINOR_REVISION                    1
 
 #define SOURCEBANSPP_VERSION_MAJOR        MAJOR_REVISION
 #define SOURCEBANSPP_VERSION_MINOR        MINOR_REVISION

game/addons/sourcemod/scripting/include/sourcebanspp.inc

@@ -41,6 +41,7 @@
 // 2.0 epoch (this header):
 //   sourcebanspp.inc — library "sourcebans++" (sbpp_main.smx)
 //     Additive: forward SBPP_OnClientPostAdminCheck (#1431).
+//     Additive: native SBPP_BanPlayerBySteamId (#1511).
 //     Unchanged: SBPP_BanPlayer; SBBanPlayer remains deprecated.
 //     Existing third-party .smx that only use prior natives/forwards
 //     generally keep working without a rebuild.
@@ -81,6 +82,7 @@ public void __pl_sourcebanspp_SetNTVOptional()
 {
 	MarkNativeAsOptional("SBBanPlayer");
 	MarkNativeAsOptional("SBPP_BanPlayer");
+	MarkNativeAsOptional("SBPP_BanPlayerBySteamId");
 	MarkNativeAsOptional("SBPP_ReportPlayer");
 }
 #endif
@@ -109,6 +111,20 @@ native void SBBanPlayer(int iAdmin, int iTarget, int iTime, const char[] sReason
  *********************************************************/
 native void SBPP_BanPlayer(int iAdmin, int iTarget, int iTime, const char[] sReason);
 
+/*********************************************************
+ * Ban a player by SteamID — supports offline/disconnected players.
+ * Inserts the ban directly into the SourceBans++ database.
+ * Fires SBPP_OnBanPlayer with iTarget = -1 to indicate an offline ban.
+ *
+ * @param iAdmin	Client index of the admin (0 = server / automated)
+ * @param steamId	SteamID string, e.g. "STEAM_0:0:12345"
+ * @param name		Player name; may be empty string if unknown
+ * @param iTime		Ban duration in minutes (0 = permanent)
+ * @param sReason	Reason for the ban
+ * @noreturn
+ *********************************************************/
+native void SBPP_BanPlayerBySteamId(int iAdmin, const char[] steamId, const char[] name, int iTime, const char[] sReason);
+
 /*********************************************************
  * Reports a player
  *
@@ -123,7 +139,7 @@ native void SBPP_ReportPlayer(int iReporter, int iTarget, const char[] sReason);
  * Called when the admin banning the player.
  *
  * @param iAdmin	The client index of the admin who is banning the client
- * @param iTarget    The client index of the player to ban
+ * @param iTarget	The client index of the player to ban (-1 for an offline SteamID ban)
  * @param iTime      The time to ban the player for (in minutes, 0 = permanent)
  * @param sReason    The reason to ban the player from the server
  *********************************************************/

game/addons/sourcemod/scripting/sbpp_main.sp

@@ -148,6 +148,7 @@ public APLRes AskPluginLoad2(Handle myself, bool late, char[] error, int err_max
 
 	CreateNative("SBBanPlayer", Native_SBBanPlayer);
 	CreateNative("SBPP_BanPlayer", Native_SBBanPlayer);
+	CreateNative("SBPP_BanPlayerBySteamId", Native_SBPP_BanPlayerBySteamId);
 	CreateNative("SBPP_ReportPlayer", Native_SBReportPlayer);
 
 	g_hFwd_OnBanAdded = CreateGlobalForward("SBPP_OnBanPlayer", ET_Ignore, Param_Cell, Param_Cell, Param_Cell, Param_String);
@@ -2419,6 +2420,194 @@ public int Native_SBBanPlayer(Handle plugin, int numParams)
 	return true;
 }
 
+public int Native_SBPP_BanPlayerBySteamId(Handle plugin, int numParams)
+{
+	if (DB == INVALID_HANDLE)
+	{
+		ThrowNativeError(SP_ERROR_NATIVE, "SourceBans++ database is not available.");
+		return 0;
+	}
+
+	int admin = GetNativeCell(1);
+	int iTime = GetNativeCell(4);
+
+	if (admin < 0 || admin > MaxClients)
+	{
+		ThrowNativeError(SP_ERROR_NATIVE, "SBPP_BanPlayerBySteamId: iAdmin must be 0 or a valid client index.");
+		return 0;
+	}
+
+	if (iTime < 0)
+	{
+		ThrowNativeError(SP_ERROR_NATIVE, "SBPP_BanPlayerBySteamId: iTime cannot be negative.");
+		return 0;
+	}
+
+	if (admin != 0)
+	{
+		if (!IsClientInGame(admin))
+		{
+			ThrowNativeError(SP_ERROR_NATIVE, "Ban Error: Player is not in game.");
+			return 0;
+		}
+
+		AdminId aid = GetUserAdmin(admin);
+		if (aid == INVALID_ADMIN_ID)
+		{
+			ThrowNativeError(SP_ERROR_NATIVE, "Ban Error: Player is not an admin.");
+			return 0;
+		}
+
+		if (!aid.HasFlag(Admin_Ban))
+		{
+			ThrowNativeError(SP_ERROR_NATIVE, "Ban Error: Player does not have BAN flag.");
+			return 0;
+		}
+	}
+
+	char steamId[MAX_AUTHID_LENGTH], name[MAX_NAME_LENGTH], reason[128];
+	GetNativeString(2, steamId, sizeof(steamId));
+	GetNativeString(3, name, sizeof(name));
+	GetNativeString(5, reason, sizeof(reason));
+
+	char validatedSteam3[MAX_AUTHID_LENGTH];
+	if (!Steam2ToSteam3(steamId, validatedSteam3, sizeof(validatedSteam3)))
+	{
+		ThrowNativeError(SP_ERROR_NATIVE, "SBPP_BanPlayerBySteamId: steamId must be in SteamID2 format (STEAM_[01]:[01]:Z), got: %s", steamId);
+		return 0;
+	}
+
+	if (reason[0] == '\0')
+		strcopy(reason, sizeof(reason), "Banned by SourceBans");
+
+	char adminAuth[MAX_AUTHID_LENGTH], adminIp[16];
+	if (admin == 0)
+	{
+		strcopy(adminAuth, sizeof(adminAuth), "STEAM_ID_SERVER");
+		strcopy(adminIp, sizeof(adminIp), ServerIp);
+	}
+	else
+	{
+		strcopy(adminAuth, sizeof(adminAuth), g_sSteamIDs[admin]);
+		strcopy(adminIp, sizeof(adminIp), g_sPlayerIP[admin]);
+	}
+
+	DataPack pack = new DataPack();
+	pack.WriteCell(admin == 0 ? 0 : GetClientUserId(admin));
+	pack.WriteCell(iTime);
+	pack.WriteString(reason);
+	pack.WriteString(steamId);
+	pack.WriteString(name);
+	pack.WriteString(adminAuth);
+	pack.WriteString(adminIp);
+
+	char steamIdEscaped[MAX_AUTHID_LENGTH * 2 + 1], steamIdYzEscaped[MAX_AUTHID_LENGTH * 2 + 1];
+	DB.Escape(steamId, steamIdEscaped, sizeof(steamIdEscaped));
+	DB.Escape(steamId[8], steamIdYzEscaped, sizeof(steamIdYzEscaped));
+
+	char query[512];
+	FormatEx(query, sizeof(query), "SELECT bid FROM %s_bans WHERE type = 0 AND (authid = '%s' OR authid REGEXP '^STEAM_[0-9]:%s$') AND (length = 0 OR ends > UNIX_TIMESTAMP()) AND RemoveType IS NULL",
+		DatabasePrefix, steamIdEscaped, steamIdYzEscaped);
+
+	DB.Query(DB_OnBanBySteamIdSelect, query, pack, DBPrio_High);
+
+	return 0;
+}
+
+void DB_OnBanBySteamIdSelect(Database db, DBResultSet results, const char[] error, DataPack pack)
+{
+	if (results == null)
+	{
+		LogToFile(logFile, "[SBPP] BanPlayerBySteamId select failed: %s", error);
+		delete pack;
+		return;
+	}
+
+	pack.Reset();
+	int adminUserId = pack.ReadCell();
+	int iTime = pack.ReadCell();
+	char reason[128], steamId[MAX_AUTHID_LENGTH], name[MAX_NAME_LENGTH], adminAuth[MAX_AUTHID_LENGTH], adminIp[16];
+	pack.ReadString(reason, sizeof(reason));
+	pack.ReadString(steamId, sizeof(steamId));
+	pack.ReadString(name, sizeof(name));
+	pack.ReadString(adminAuth, sizeof(adminAuth));
+	pack.ReadString(adminIp, sizeof(adminIp));
+	delete pack;
+
+	if (results.RowCount > 0)
+	{
+		LogToFile(logFile, "[SBPP] BanPlayerBySteamId: %s is already banned, skipping.", steamId);
+		return;
+	}
+
+	char steamIdEscaped[MAX_AUTHID_LENGTH * 2 + 1], nameEscaped[MAX_NAME_LENGTH * 2 + 1], reasonEscaped[256],
+		adminAuthEscaped[MAX_AUTHID_LENGTH * 2 + 1], adminAuthYzEscaped[MAX_AUTHID_LENGTH * 2 + 1], adminIpEscaped[33];
+	if (!db.Escape(steamId, steamIdEscaped, sizeof(steamIdEscaped))
+		|| !db.Escape(name, nameEscaped, sizeof(nameEscaped))
+		|| !db.Escape(reason, reasonEscaped, sizeof(reasonEscaped))
+		|| !db.Escape(adminAuth, adminAuthEscaped, sizeof(adminAuthEscaped))
+		|| !db.Escape(adminAuth[8], adminAuthYzEscaped, sizeof(adminAuthYzEscaped))
+		|| !db.Escape(adminIp, adminIpEscaped, sizeof(adminIpEscaped)))
+	{
+		LogToFile(logFile, "[SBPP] BanPlayerBySteamId failed to escape ban data for %s", steamId);
+		return;
+	}
+
+	char query[1024];
+	if (serverID == -1)
+	{
+		FormatEx(query, sizeof(query), "INSERT INTO %s_bans (authid, name, created, ends, length, reason, aid, adminIp, sid, country) VALUES \
+			('%s', '%s', UNIX_TIMESTAMP(), UNIX_TIMESTAMP() + %d, %d, '%s', \
+			IFNULL((SELECT aid FROM %s_admins WHERE authid = '%s' OR authid REGEXP '^STEAM_[0-9]:%s$'),'0'), '%s', \
+			(SELECT sid FROM %s_servers WHERE ip = '%s' AND port = '%s' LIMIT 0,1), ' ')",
+			DatabasePrefix, steamIdEscaped, nameEscaped, (iTime * 60), (iTime * 60), reasonEscaped,
+			DatabasePrefix, adminAuthEscaped, adminAuthYzEscaped, adminIpEscaped,
+			DatabasePrefix, ServerIpEscaped, ServerPort);
+	}
+	else
+	{
+		FormatEx(query, sizeof(query), "INSERT INTO %s_bans (authid, name, created, ends, length, reason, aid, adminIp, sid, country) VALUES \
+			('%s', '%s', UNIX_TIMESTAMP(), UNIX_TIMESTAMP() + %d, %d, '%s', \
+			IFNULL((SELECT aid FROM %s_admins WHERE authid = '%s' OR authid REGEXP '^STEAM_[0-9]:%s$'),'0'), '%s', \
+			%d, ' ')",
+			DatabasePrefix, steamIdEscaped, nameEscaped, (iTime * 60), (iTime * 60), reasonEscaped,
+			DatabasePrefix, adminAuthEscaped, adminAuthYzEscaped, adminIpEscaped,
+			serverID);
+	}
+
+	DataPack fwdPack = new DataPack();
+	fwdPack.WriteCell(adminUserId);
+	fwdPack.WriteCell(iTime);
+	fwdPack.WriteString(reason);
+
+	db.Query(DB_OnBanBySteamIdInsert, query, fwdPack, DBPrio_High);
+}
+
+void DB_OnBanBySteamIdInsert(Database db, DBResultSet results, const char[] error, DataPack pack)
+{
+	pack.Reset();
+	int adminUserId = pack.ReadCell();
+	int iTime = pack.ReadCell();
+	char reason[128];
+	pack.ReadString(reason, sizeof(reason));
+	delete pack;
+
+	if (results == null)
+	{
+		LogToFile(logFile, "[SBPP] BanPlayerBySteamId insert failed: %s", error);
+		return;
+	}
+
+	int admin = adminUserId == 0 ? 0 : GetClientOfUserId(adminUserId);
+
+	Call_StartForward(g_hFwd_OnBanAdded);
+	Call_PushCell(admin);
+	Call_PushCell(-1);
+	Call_PushCell(iTime);
+	Call_PushString(reason);
+	Call_Finish();
+}
+
 public int Native_SBReportPlayer(Handle plugin, int numParams)
 {
 	if (numParams < 3)

game/addons/sourcemod/scripting/scripts/resolve-plugin-version.sh

@@ -48,7 +48,7 @@ fi
 # Native API epoch — NOT panel semver minor. Bump MINOR_REVISION manually when
 # shipping additive natives; bump MAJOR only on breaking native contract.
 api_major=2
-api_minor=0
+api_minor=1
 
 sb_major="dev"
 sb_minor="0"

web/tests/integration/PluginVersionResolveTest.php

@@ -86,7 +86,7 @@ public function testReleaseVersionWritesTagAndApiEpoch(): void
         self::assertIsString($inc);
         self::assertStringContainsString('#define SB_VERSION                        "2.0.0"', $inc);
         self::assertStringContainsString('#define MAJOR_REVISION                    2', $inc);
-        self::assertStringContainsString('#define MINOR_REVISION                    0', $inc);
+        self::assertStringContainsString('#define MINOR_REVISION                    1', $inc);
 
         @rmdir($tmp);
     }
@@ -106,8 +106,8 @@ public function testReleaseSemverMinorDoesNotBumpApiMinorRevision(): void
         self::assertIsString($inc);
         self::assertStringContainsString('#define SB_VERSION                        "2.1.0"', $inc);
         self::assertStringContainsString('#define MAJOR_REVISION                    2', $inc);
-        self::assertStringContainsString('#define MINOR_REVISION                    0', $inc);
-        self::assertStringNotContainsString('#define MINOR_REVISION                    1', $inc);
+        self::assertStringContainsString('#define MINOR_REVISION                    1', $inc);
+        self::assertStringNotContainsString('#define MINOR_REVISION                    2', $inc);
     }
 
     public function testVersionJsonTierWhenPresent(): void
@@ -149,7 +149,7 @@ public function testVersionJsonTierWritesToIsolatedOutputPath(): void
         self::assertIsString($inc);
         self::assertStringContainsString('#define SB_VERSION                        "9.8.7"', $inc);
         self::assertStringContainsString('#define MAJOR_REVISION                    2', $inc);
-        self::assertStringContainsString('#define MINOR_REVISION                    0', $inc);
+        self::assertStringContainsString('#define MINOR_REVISION                    1', $inc);
         self::assertSame(self::$incBackup, file_get_contents(self::incPath()));
 
         @unlink($jsonPath);