───────────────────────────────────────────────────────────────────────────────
                        🔐 K0 Encryption System - Developer Guide
───────────────────────────────────────────────────────────────────────────────

OVERVIEW:
This guide explains how to build a secure data decryption system similar to the K0 class.
It walks you through encoding/decoding logic using AES encryption, XOR cipher, and Base64,
along with secure key wrapping via methods instead of plain constants.

───────────────────────────────────────────────────────────────────────────────
1. WHY WRAP CONSTANTS INSIDE METHODS?
───────────────────────────────────────────────────────────────────────────────
- Avoid exposing AES key, IV, or XOR keys directly in bytecode.
- Makes static analysis and reverse engineering harder.
- Can later be moved to native code or obfuscated using tools like R8/ProGuard.

Example:

    private static String getAESKey() {
        return "your-16-byte-key"; // 16 chars only
    }

    private static String getAESIV() {
        return "your-16-byte-ivv"; // 16 chars only
    }

    private static byte[] getXORKey() {
        return new byte[] {0x1A, 0x2B, 0x3C, 0x4D};
    }


───────────────────────────────────────────────────────────────────────────────
2. HOW THE DECRYPTION WORKS
───────────────────────────────────────────────────────────────────────────────

Decryption flow (in reverse of encryption):

    Base64 -> XOR -> AES Decrypt -> UTF-8 String

Code Reference:

    private String decode(String input) {
        try {
            byte[] base64 = Base64.decode(input, Base64.NO_WRAP);
            byte[] xored = xor(base64);

            Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding");
            SecretKeySpec keySpec = new SecretKeySpec(getAESKey().getBytes(StandardCharsets.UTF_8), "AES");
            IvParameterSpec ivSpec = new IvParameterSpec(getAESIV().getBytes(StandardCharsets.UTF_8));
            cipher.init(Cipher.DECRYPT_MODE, keySpec, ivSpec);

            byte[] decrypted = cipher.doFinal(xored);
            return new String(decrypted, StandardCharsets.UTF_8);
        } catch (Exception e) {
            return "";
        }
    }

    private byte[] xor(byte[] data) {
        byte[] key = getXORKey();
        byte[] result = new byte[data.length];
        for (int i = 0; i < data.length; i++) {
            result[i] = (byte)(data[i] ^ key[i % key.length]);
        }
        return result;
    }


───────────────────────────────────────────────────────────────────────────────
3. HOW TO ENCODE STRINGS TO USE WITH K0
───────────────────────────────────────────────────────────────────────────────

Encoding flow:

    UTF-8 String -> AES Encrypt -> XOR -> Base64

Use this Python reference script:

    import base64
    from Crypto.Cipher import AES

    def xor(data, key):
        return bytes([b ^ key[i % len(key)] for i, b in enumerate(data)])

    def encode(plaintext, aes_key, aes_iv, xor_key):
        cipher = AES.new(aes_key.encode(), AES.MODE_CBC, aes_iv.encode())
        pad_len = 16 - (len(plaintext) % 16)
        padded = plaintext + chr(pad_len) * pad_len
        encrypted = cipher.encrypt(padded.encode())
        xored = xor(encrypted, xor_key)
        return base64.b64encode(xored).decode()

    # Example
    aes_key = "k9D2!7aL4#oXf2Qb"
    aes_iv = "Q8b@3nL6rV1eZ0pT"
    xor_key = bytes([0x5A, 0x2D, 0x6F, 0x1C])
    print(encode("HelloWorld", aes_key, aes_iv, xor_key))


───────────────────────────────────────────────────────────────────────────────
4. USING THE K0 CLASS
───────────────────────────────────────────────────────────────────────────────

Example usage:

    public String a = decode("Base64XorAesEncodedString1==");
    public String b = decode("Base64XorAesEncodedString2==");

    // Use them however needed in your logic

    if (a.equals("example")) { ... }


───────────────────────────────────────────────────────────────────────────────
5. SECURITY TIPS
───────────────────────────────────────────────────────────────────────────────

✅ Use ProGuard or R8 with string encryption.
✅ Move key logic to C++/JNI if higher security is needed.
✅ Never leave raw key/IV values as static final strings.
✅ Change the AES key regularly if possible.
✅ Keep XOR keys random and unique per project.

───────────────────────────────────────────────────────────────────────────────
For questions, contact your lead developer or security reviewer.
───────────────────────────────────────────────────────────────────────────────