GBKomi v1.4.2

GBKomi is a high-security Python library for encryption, hashing, secure database storage, Telegram bot token management, and secure logging.
It is designed to provide military-grade security while remaining user-friendly for developers building bots, scripts, and applications.

This version (v1.4.2) introduces advanced multi-bot support, retry/lockout mechanisms, context-aware token and log management, and fully misuse-resistant APIs for Telegram bots.

🔹 Key Features

1️⃣ Military-Grade .gbtoken Security

• AES-256-GCM encryption with unique per-entry nonce
• Optional HMAC verification for cross-check
• KDF-based key derivation from password using PBKDF2
• Versioned .gbtoken format (GBT4|<salt>|<nonce>|<ciphertext>|<tag>) for future-proofing
• Automatic secure deletion of sensitive data from RAM
• Misuse-resistant API: users cannot provide weak keys or nonce manually
• Multi-bot support: store multiple bot tokens in one .gbtoken file
• Retry/lockout system: failed decrypt attempts tracked with persistent storage

Example:

from gbkomi import GBKomi, AESDecryptionError, HMACVerificationError

password = b"supersecurepassword"
gb = GBKomi(password)

# Encrypt token for Telegram bot
bot_tokens = {"bot1": "123456:ABC-DEF", "bot2": "654321:DEF-ABC"}
gb.save_to_file(".gbtoken", bot_tokens, associated_data=b"multi-bot")

# Decrypt with retry protection
try:
    tokens = gb.load_from_file(".gbtoken", associated_data=b"multi-bot")
    bot1_token = tokens["bot1"]
except (AESDecryptionError, HMACVerificationError) as e:
    print("Decryption failed:", e)
2️⃣ Secure Logging for Bots (.gblog)
Each log entry encrypted individually with AES-GCM + HMAC

Associated data (bot ID or context) ensures tamper detection

Optional persistent retry/block counter for failed decrypt attempts

Replay-attack prevention with UUID + timestamp per log entry

Multi-bot support: separate log files per bot (bot1.gblog, bot2.gblog)

Secure append-only logging and optional clearing

Example:

from gbkomi import GBLog

log_password = b"anothersecurepass"
log = GBLog(log_password, retry_file=".retry_store.json")

log.append_log("bot1.gblog", "Bot token loaded successfully", associated_data=b"bot1")
entries = log.read_logs("bot1.gblog", associated_data=b"bot1")
print(entries)
3️⃣ Context-Aware Message Encryption
Encrypt messages with metadata: chat_id, message_id, timestamp

Prevents replay attacks

AEAD encryption ensures integrity

from gbkomi import context_encrypt, context_decrypt, generate_secure_key

key = generate_secure_key()
message = b"Sensitive message"
context = {"chat_id": 12345, "message_id": 678, "timestamp": 1700000000}

cipher = context_encrypt(message, key, context)
plain = context_decrypt(cipher, key, context)
print(plain.decode())
4️⃣ Streaming File Encryption
Encrypt large files chunk by chunk (>100MB)

Low memory footprint

AES-GCM with unique nonce per file

from gbkomi import encrypt_file_stream, decrypt_file_stream

key = generate_secure_key()
encrypt_file_stream("video.mp4", "video.enc", key)
decrypt_file_stream("video.enc", "video_decoded.mp4", key)
5️⃣ Secure Database Storage
Store JSON-compatible data securely

AES-GCM + HMAC verification

Tamper-proof even if database is compromised

Works with SQLite, PostgreSQL, MySQL

from gbkomi import db_encrypt, db_decrypt

key = generate_secure_key()
data = {"balance": 1000, "settings": {"theme": "dark"}}

cipher = db_encrypt(data, key)
plain = db_decrypt(cipher, key)
print(plain)
6️⃣ Telegram Bot Security Features
Multi-bot support in a single .gbtoken

Context-aware: token usage bound to bot or session

Secure rotation of bot tokens without data loss

Retry/lockout system prevents brute-force attempts

Optional auto key rotation

Secure logging via .gblog tied to bot context

🔹 Installation
pip install gbkomi==1.4.2
🔹 Supported Python Versions
Python 3.8+

Tested on 3.11

🔹 Best Practices
Always provide associated_data when encrypting tokens or logs.

Store .gbtoken and .gblog securely on disk; never commit passwords or tokens to GitHub.

Use long, random passwords for key derivation.

Regularly rotate bot tokens and encryption keys.

For production bots, enable monitoring on retry/block events.

🔹 Versioning Notes
.gbtoken format: GBT4|<salt>|<nonce>|<ciphertext>|<tag>

.gblog format: GBL2|<salt>|<nonce>|<ciphertext>|<tag>

Future versions will maintain backward compatibility via version headers.

🔹 Optional Advanced Features
Hardware-backed keys (HSM, TPM, secure enclave)

Encrypted configuration files for webhooks or bot settings (.gbconfig)

Multi-threaded log reading for very large log files