@majikah/majik-universal-id-client 0.0.1

package/dist/core/identity.js

@@ -0,0 +1,177 @@
+import { hash } from "@stablelib/sha256";
+import { arrayToBase64 } from "./utils/utilities";
+/**
+ * Utility assertions
+ */
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function assertString(value, field) {
+    assert(typeof value === "string" && value.trim().length > 0, `${field} must be a non-empty string`);
+}
+function assertISODate(value, field) {
+    const date = new Date(value);
+    assert(!isNaN(date.getTime()), `${field} must be a valid ISO timestamp`);
+}
+function sha256(input) {
+    const hashed = hash(new TextEncoder().encode(input));
+    return arrayToBase64(hashed);
+}
+/**
+ * MajikMessageIdentity
+ * Immutable identity container with integrity verification
+ */
+export class MajikMessageIdentity {
+    // 🔒 Private backing fields
+    _id;
+    _userId;
+    _publicKey;
+    _mlKey;
+    _phash;
+    _label;
+    _timestamp;
+    _restricted;
+    /**
+     * Constructor is private to enforce controlled creation
+     */
+    constructor(params) {
+        assertString(params.id, "id");
+        assertString(params.userId, "user_id");
+        assertString(params.publicKey, "public_key");
+        assertString(params.mlKey, "ml_key");
+        assertString(params.phash, "phash");
+        assertString(params.label, "label");
+        assertISODate(params.timestamp, "timestamp");
+        assert(typeof params.restricted === "boolean", "restricted must be boolean");
+        this._id = params.id;
+        this._userId = params.userId;
+        this._publicKey = params.publicKey;
+        this._mlKey = params.mlKey;
+        this._phash = params.phash;
+        this._label = params.label;
+        this._timestamp = params.timestamp;
+        this._restricted = params.restricted;
+        // Final integrity check at construction
+        assert(this.validateIntegrity(), "Identity integrity validation failed");
+    }
+    // ─────────────────────────────
+    // Static factory
+    // ─────────────────────────────
+    /**
+     * Create a new immutable identity from MajikUser
+     */
+    static create(user, account, options) {
+        assert(user, "MajikUser is required");
+        const userValidResult = user.validate();
+        if (!userValidResult.isValid) {
+            throw new Error(`Invalid MajikUser: ${userValidResult.errors.join(", ")}`);
+        }
+        const label = options?.label || account?.meta?.label || user.displayName;
+        assertString(label, "label");
+        const timestamp = new Date().toISOString();
+        const publicKey = account.publicKeyBase64;
+        const phash = sha256(`${user.id}:${publicKey}:${account.id}:${account.mlKey}`);
+        return new MajikMessageIdentity({
+            id: account.id,
+            userId: user.id,
+            publicKey: publicKey,
+            mlKey: account.mlKey,
+            phash,
+            label,
+            timestamp,
+            restricted: options?.restricted ?? false,
+        });
+    }
+    // ─────────────────────────────
+    // Getters (safe, read-only)
+    // ─────────────────────────────
+    get id() {
+        return this._id;
+    }
+    get userID() {
+        return this._userId;
+    }
+    get publicKey() {
+        return this._publicKey;
+    }
+    get phash() {
+        return this._phash;
+    }
+    get label() {
+        return this._label;
+    }
+    get timestamp() {
+        return this._timestamp;
+    }
+    get restricted() {
+        return this._restricted;
+    }
+    // ─────────────────────────────
+    // Mutators (restricted)
+    // ─────────────────────────────
+    /**
+     * Only mutable field
+     */
+    set label(label) {
+        assertString(label, "label");
+        this._label = label;
+    }
+    // ─────────────────────────────
+    // Identity checks
+    // ─────────────────────────────
+    /**
+     * Returns true if identity is restricted
+     */
+    isRestricted() {
+        return this._restricted === true;
+    }
+    /**
+     * Verify identity integrity
+     * Detects tampering of id/public_key
+     */
+    validateIntegrity() {
+        const expected = sha256(`${this._userId}:${this._publicKey}:${this._id}:${this._mlKey}`);
+        return expected === this._phash;
+    }
+    /**
+     * Explicit verification helper
+     */
+    matches(userId, publicKey) {
+        assertString(userId, "userId");
+        assertString(publicKey, "publicKey");
+        const hash = sha256(`${userId}:${publicKey}:${this._id}:${this._mlKey}`);
+        return hash === this._phash;
+    }
+    // ─────────────────────────────
+    // Serialization
+    // ─────────────────────────────
+    toJSON() {
+        return {
+            id: this._id,
+            user_id: this._userId,
+            public_key: this._publicKey,
+            ml_key: this._mlKey,
+            phash: this._phash,
+            label: this._label,
+            timestamp: this._timestamp,
+            restricted: this._restricted,
+        };
+    }
+    static fromJSON(json) {
+        const obj = typeof json === "string" ? JSON.parse(json) : json;
+        assert(typeof obj === "object" && obj !== null, "Invalid JSON object");
+        const identity = new MajikMessageIdentity({
+            id: obj.id,
+            userId: obj.user_id,
+            publicKey: obj.public_key,
+            mlKey: obj.ml_key,
+            phash: obj.phash,
+            label: obj.label,
+            timestamp: obj.timestamp,
+            restricted: obj.restricted,
+        });
+        assert(identity.validateIntegrity(), "Invalid phash in JSON");
+        return identity;
+    }
+}

package/dist/core/types.d.ts

@@ -0,0 +1,86 @@
+export type ISODateString = string;
+export type MajikMessageAccountID = string;
+export type MajikMessagePublicKey = string;
+export type MajikMessageChatID = string;
+export type MajikMessageThreadID = string;
+export type MajikMessageMailID = string;
+export interface MAJIK_API_RESPONSE {
+    success: boolean;
+    message: string;
+    code?: string;
+}
+/**
+ * types.ts — @majikah/majik-envelope
+ *
+ * ML-KEM-768 (v3) envelope types only.
+ * v1 (X25519 solo) and v2 (X25519 group) have been removed.
+ */
+/**
+ * Single-recipient envelope payload.
+ * The ML-KEM shared secret is used directly as the AES-256-GCM key.
+ */
+export interface SinglePayload {
+    iv: string;
+    ciphertext: string;
+    mlKemCipherText: string;
+}
+/**
+ * Per-recipient key entry in a group envelope.
+ * encryptedAesKey = groupAesKey XOR mlKemSharedSecret (32-byte XOR one-time-pad).
+ */
+export interface GroupKey {
+    fingerprint: string;
+    mlKemCipherText: string;
+    encryptedAesKey: string;
+}
+/**
+ * Multi-recipient envelope payload.
+ * Message is encrypted once with a random AES key.
+ * Each recipient gets their own ML-KEM encapsulation of that AES key.
+ */
+export interface GroupPayload {
+    iv: string;
+    ciphertext: string;
+    keys: GroupKey[];
+}
+export type EnvelopePayload = SinglePayload | GroupPayload;
+export declare function isSinglePayload(p: EnvelopePayload): p is SinglePayload;
+export declare function isGroupPayload(p: EnvelopePayload): p is GroupPayload;
+export interface MajikEnvelopeJSON {
+    version: 3;
+    fingerprint: string;
+    payload: EnvelopePayload;
+    plaintext?: string;
+}
+export interface MAJIK_API_RESPONSE {
+    success: boolean;
+    message: string;
+    data?: unknown;
+}
+export interface MnemonicJSON {
+    id: string;
+    seed: string[];
+    phrase?: string;
+}
+export interface MajikKeyJSON {
+    id: string;
+    label: string;
+    publicKey: string;
+    fingerprint: string;
+    encryptedPrivateKey: string;
+    salt: string;
+    backup: string;
+    timestamp: string;
+    kdfVersion: number;
+    mlKemPublicKey?: string;
+    encryptedMlKemSecretKey?: string;
+}
+export interface MajikKeyMetadata {
+    id: string;
+    fingerprint: string;
+    label: string;
+    timestamp: Date;
+    isLocked: boolean;
+    kdfVersion: number;
+    hasMlKem: boolean;
+}

package/dist/core/types.js

@@ -0,0 +1,7 @@
+// ─── Type Guards ──────────────────────────────────────────────────────────────
+export function isSinglePayload(p) {
+    return "mlKemCipherText" in p && !("keys" in p);
+}
+export function isGroupPayload(p) {
+    return "keys" in p && Array.isArray(p.keys);
+}

package/dist/core/utils/APITranscoder.d.ts

@@ -0,0 +1,114 @@
+export interface EncryptedData {
+    rqc: Uint8Array;
+    iv: Uint8Array;
+    cipher: Uint8Array;
+}
+export interface SerializedEncryptedData {
+    rqc: string;
+    iv: string;
+    cipher: string;
+}
+declare class APITranscoder {
+    /**
+     * Generates a 32-byte cipher key encoded as a base64 string, suitable for use with Fernet encryption.
+     * @returns {string} The generated cipher key ("rqc") in base64 format.
+     */
+    static generateRQC(): string;
+    /**
+     * Generates a transformed version of the rqc by reversing and interleaving the bytes.
+     * If rqc is not provided, a new one will be generated automatically.
+     * @param {string} [rqc] - Optional. The original 32-byte cipher key in base64 format.
+     * @returns {string} The transformed key as a base64 string.
+     */
+    static generateRQX(rqc?: string | null): string;
+    /**
+     * Decodes the transformed rqx back to the original rqc base64 string.
+     * @param {string} rqx - The transformed key in base64 format.
+     * @returns {string} The original rqc in base64 format.
+     */
+    static decodeRQX(rqx: string): string;
+    static hashData(inputJson: Record<string, unknown>): string;
+    /**
+     * Generates a SHA-256 hash for a given string.
+     * Validates that the input is a non-empty string.
+     * @param {string} string - The string to hash.
+     * @returns {string} The hash of the string in hexadecimal format.
+     * @throws {Error} If the input is not a valid non-empty string.
+     */
+    static hashString(string: string): string;
+    /**
+     * Verifies that the hash of a decoded JSON object matches a provided hash.
+     * @param {Object} decodedJson - The JSON object to verify.
+     * @param {string} providedHash - The hash to compare against.
+     * @returns {boolean} True if the hashes match, false otherwise.
+     * @throws {Error} If inputs are invalid.
+     */
+    static verifyHashJSON(decodedJson: Record<string, unknown>, providedHash: string): boolean;
+    /**
+     * Verifies that the hash of a given string matches a provided hash.
+     * @param {string} string - The string to verify.
+     * @param {string} providedHash - The hash to compare against.
+     * @returns {boolean} True if the hashes match, false otherwise.
+     * @throws {Error} If inputs are invalid.
+     */
+    static verifyHashString(string: string, providedHash: string): boolean;
+    /**
+     * Decrypts an encrypted payload using AES-GCM encryption and returns the original JSON.
+     * @param {string} encrypted - The encrypted object data.
+     * @returns {Object} The decrypted and parsed JSON object.
+     * @throws {Error} Throws an error if decryption fails.
+     */
+    static decryptPayload(encrypted: SerializedEncryptedData): Record<string, unknown>;
+    /**
+     * Encrypts a JSON object using AES-GCM encryption with the provided cipher key.
+     * @param {Object} json - The JSON object to encrypt.
+     * @param {string} rqc - The 32-byte cipher key in base64 format.
+     * @returns {Object} An object containing the encrypted payload and the transformed key, potentially URL-encoded.
+     * @throws {Error} Throws an error if encryption fails.
+     */
+    static encryptPayload(json: Record<string, unknown>, rqc: string): SerializedEncryptedData;
+}
+export default APITranscoder;
+export declare function generateRQKey(auth: string): string;
+export declare function getAuthFromRQKey(rqkey: string): string;
+export declare function validateRQKey(rqkey: string): boolean;
+export declare function getDecodedRQKey(rqkey: string): string;
+export declare function getSecureKeyFromRQKey(rqkey: string): string | number | object;
+/**
+ * Converts input to a string and reverses it.
+ * If the input is a number, it is converted to a string.
+ * If the input is an object (JSON), it is stringified.
+ * If secure is true, it returns a Base64 encoded result.
+ * @param {any} input - The input to reverse.
+ * @param {boolean} secure - Whether to Base64 encode the result.
+ * @returns {string} - The reversed string, possibly encoded.
+ */
+export declare function secureReverse(input: string | object | number, secure?: boolean): string;
+/**
+ * Decodes the reversed string based on the mode provided.
+ * If secure is true, the reversed string is decoded from Base64 first.
+ * @param {string} reversedString - The reversed string (possibly Base64 encoded).
+ * @param {string|null} mode - The mode to decode ('json', 'number', or 'string').
+ * @param {boolean} secure - Whether the input is Base64 encoded.
+ * @returns {any} - The decoded result based on the mode.
+ */
+export declare function decodeReverse(reversedString: string, mode?: string, secure?: boolean): string | object | number;
+/**
+ * Converts a stringified JSON into a Uint8Array (UTF-8 bytes)
+ */
+export declare function jsonStringToBytes(jsonString: string): Uint8Array;
+/**
+ * Converts a Uint8Array (UTF-8 bytes) back into a stringified JSON
+ */
+export declare function bytesToJsonString(bytes: Uint8Array): string;
+/**
+ * Converts EncryptedData (Uint8Array fields) into base64 strings
+ * for safe transport / storage (JSON, URLs, APIs, etc.)
+ */
+export declare function encryptedDataToBase64(data: EncryptedData): SerializedEncryptedData;
+/**
+ * Converts SerializedEncryptedData (base64 fields)
+ * back into EncryptedData (Uint8Array fields)
+ */
+export declare function encryptedDataFromBase64(data: SerializedEncryptedData): EncryptedData;
+export declare function base64ToJson<T = unknown>(base64: string): T;

package/dist/core/utils/APITranscoder.js

@@ -0,0 +1,305 @@
+import { hash } from "@stablelib/sha256";
+import { AES } from "@stablelib/aes";
+import { GCM } from "@stablelib/gcm";
+import { randomBytes } from "@stablelib/random";
+import { arrayToBase64, base64ToUint8Array } from "./utilities";
+class APITranscoder {
+    /**
+     * Generates a 32-byte cipher key encoded as a base64 string, suitable for use with Fernet encryption.
+     * @returns {string} The generated cipher key ("rqc") in base64 format.
+     */
+    static generateRQC() {
+        const bytes = randomBytes(32); // 32 bytes = 256 bits
+        const fKey = arrayToBase64(bytes);
+        return fKey; // Converts the byte array to a base64 string
+    }
+    /**
+     * Generates a transformed version of the rqc by reversing and interleaving the bytes.
+     * If rqc is not provided, a new one will be generated automatically.
+     * @param {string} [rqc] - Optional. The original 32-byte cipher key in base64 format.
+     * @returns {string} The transformed key as a base64 string.
+     */
+    static generateRQX(rqc = null) {
+        // Auto-generate rqc if it's empty or null
+        if (!rqc) {
+            rqc = this.generateRQC();
+        }
+        // Decode the input rqc to bytes
+        const rqcBytes = Uint8Array.from(atob(rqc), (c) => c.charCodeAt(0)); // Decode base64 to byte array
+        const intArray = Array.from(rqcBytes);
+        // Reverse the array
+        const reversedArray = [...intArray].reverse();
+        // Interleave original and reversed arrays
+        const interleavedArray = [];
+        for (let i = 0; i < intArray.length; i++) {
+            interleavedArray.push(intArray[i], reversedArray[i]);
+        }
+        // Convert the interleaved array to a base64 string and return
+        return btoa(String.fromCharCode(...interleavedArray)); // Convert the byte array to base64 string
+    }
+    /**
+     * Decodes the transformed rqx back to the original rqc base64 string.
+     * @param {string} rqx - The transformed key in base64 format.
+     * @returns {string} The original rqc in base64 format.
+     */
+    static decodeRQX(rqx) {
+        const interleavedArray = Uint8Array.from(atob(rqx), (c) => c.charCodeAt(0)); // Decode base64 to byte array
+        // Separate the original and reversed arrays from the interleaved array
+        const originalArray = [];
+        const reversedArray = [];
+        for (let i = 0; i < interleavedArray.length; i += 2) {
+            originalArray.push(interleavedArray[i]);
+            reversedArray.push(interleavedArray[i + 1]);
+        }
+        // Verify reversedArray matches the reverse of originalArray (optional, for validation)
+        if (reversedArray.join() !== [...originalArray].reverse().join()) {
+            throw new Error("Decoded rqx does not match original rqc format.");
+        }
+        // Convert the original array back to a base64 string representing the original rqc
+        return btoa(String.fromCharCode(...originalArray)); // Convert to base64 string
+    }
+    static hashData(inputJson) {
+        const jsonString = JSON.stringify(inputJson, Object.keys(inputJson).sort());
+        const hashString = hash(jsonStringToBytes(jsonString));
+        return hashString.toString();
+    }
+    /**
+     * Generates a SHA-256 hash for a given string.
+     * Validates that the input is a non-empty string.
+     * @param {string} string - The string to hash.
+     * @returns {string} The hash of the string in hexadecimal format.
+     * @throws {Error} If the input is not a valid non-empty string.
+     */
+    static hashString(string) {
+        const hashed = hash(new TextEncoder().encode(string));
+        return hashed.toString();
+    }
+    /**
+     * Verifies that the hash of a decoded JSON object matches a provided hash.
+     * @param {Object} decodedJson - The JSON object to verify.
+     * @param {string} providedHash - The hash to compare against.
+     * @returns {boolean} True if the hashes match, false otherwise.
+     * @throws {Error} If inputs are invalid.
+     */
+    static verifyHashJSON(decodedJson, providedHash) {
+        const generatedHash = this.hashData(decodedJson);
+        return generatedHash === providedHash;
+    }
+    /**
+     * Verifies that the hash of a given string matches a provided hash.
+     * @param {string} string - The string to verify.
+     * @param {string} providedHash - The hash to compare against.
+     * @returns {boolean} True if the hashes match, false otherwise.
+     * @throws {Error} If inputs are invalid.
+     */
+    static verifyHashString(string, providedHash) {
+        if (typeof string !== "string" || string.trim() === "") {
+            throw new Error("Invalid input: 'string' must be a non-empty string.");
+        }
+        if (typeof providedHash !== "string" || providedHash.trim() === "") {
+            throw new Error("Invalid input: 'providedHash' must be a non-empty string.");
+        }
+        const generatedHash = this.hashString(string);
+        return generatedHash === providedHash;
+    }
+    /**
+     * Decrypts an encrypted payload using AES-GCM encryption and returns the original JSON.
+     * @param {string} encrypted - The encrypted object data.
+     * @returns {Object} The decrypted and parsed JSON object.
+     * @throws {Error} Throws an error if decryption fails.
+     */
+    static decryptPayload(encrypted) {
+        try {
+            const serialized = encryptedDataFromBase64(encrypted);
+            const { rqc, iv, cipher } = serialized;
+            const aes = new AES(rqc);
+            const gcm = new GCM(aes);
+            const decrypted = gcm.open(iv, cipher);
+            if (!decrypted) {
+                throw new Error("Decryption failed or payload was tampered.");
+            }
+            const base64String = arrayToBase64(decrypted);
+            const parsedData = base64ToJson(base64String);
+            return parsedData;
+        }
+        catch (error) {
+            throw new Error(`Decryption failed: ${error}`);
+        }
+    }
+    /**
+     * Encrypts a JSON object using AES-GCM encryption with the provided cipher key.
+     * @param {Object} json - The JSON object to encrypt.
+     * @param {string} rqc - The 32-byte cipher key in base64 format.
+     * @returns {Object} An object containing the encrypted payload and the transformed key, potentially URL-encoded.
+     * @throws {Error} Throws an error if encryption fails.
+     */
+    static encryptPayload(json, rqc) {
+        try {
+            const jsonString = JSON.stringify(json);
+            const data = jsonStringToBytes(jsonString);
+            const bufferRQC = base64ToUint8Array(rqc);
+            const iv = randomBytes(12);
+            const aes = new AES(bufferRQC);
+            const gcm = new GCM(aes);
+            const cipher = gcm.seal(iv, data);
+            const encrypted = { rqc: bufferRQC, iv, cipher };
+            const serialized = encryptedDataToBase64(encrypted);
+            return serialized;
+        }
+        catch (error) {
+            throw new Error(`Encryption failed: ${error}`);
+        }
+    }
+}
+export default APITranscoder;
+export function generateRQKey(auth) {
+    const now = Math.floor(Date.now() / 1000);
+    const appendedKey = now + ":" + auth + ":" + secureReverse(auth, true);
+    return btoa(appendedKey);
+}
+export function getAuthFromRQKey(rqkey) {
+    const decodedKey = getDecodedRQKey(rqkey);
+    const auth = decodedKey.split(":")[1];
+    return auth;
+}
+export function validateRQKey(rqkey) {
+    const auth = getAuthFromRQKey(rqkey);
+    const secureKey = getSecureKeyFromRQKey(rqkey);
+    if (auth !== secureKey) {
+        console.error("Access denied. This key is not valid.");
+        return false;
+    }
+    return true;
+}
+export function getDecodedRQKey(rqkey) {
+    return atob(rqkey);
+}
+export function getSecureKeyFromRQKey(rqkey) {
+    const decodedKey = getDecodedRQKey(rqkey);
+    const secureKey = decodeReverse(decodedKey.split(":")[2], "string", true);
+    return secureKey;
+}
+/**
+ * Converts input to a string and reverses it.
+ * If the input is a number, it is converted to a string.
+ * If the input is an object (JSON), it is stringified.
+ * If secure is true, it returns a Base64 encoded result.
+ * @param {any} input - The input to reverse.
+ * @param {boolean} secure - Whether to Base64 encode the result.
+ * @returns {string} - The reversed string, possibly encoded.
+ */
+export function secureReverse(input, secure = true) {
+    let str;
+    if (typeof input === "number") {
+        str = input.toString();
+    }
+    else if (typeof input === "object") {
+        str = JSON.stringify(input);
+    }
+    else {
+        str = input;
+    }
+    let reversedString = str.split("").reverse().join("");
+    if (secure) {
+        // reversedString = btoa(reversedString);
+        reversedString = Buffer.from(reversedString).toString("base64");
+    }
+    return reversedString;
+}
+/**
+ * Decodes the reversed string based on the mode provided.
+ * If secure is true, the reversed string is decoded from Base64 first.
+ * @param {string} reversedString - The reversed string (possibly Base64 encoded).
+ * @param {string|null} mode - The mode to decode ('json', 'number', or 'string').
+ * @param {boolean} secure - Whether the input is Base64 encoded.
+ * @returns {any} - The decoded result based on the mode.
+ */
+export function decodeReverse(reversedString, mode = "string", secure = true) {
+    // If secure is true, decode the reversed string from Base64
+    if (secure) {
+        reversedString = atob(reversedString);
+    }
+    const restoredString = reversedString.split("").reverse().join("");
+    if (mode === "json") {
+        try {
+            return JSON.parse(restoredString);
+        }
+        catch (error) {
+            throw new Error(`Invalid JSON format. ${error}`);
+        }
+    }
+    else if (mode === "number") {
+        const number = parseFloat(restoredString);
+        if (!number) {
+            throw new Error("Reversed string is not a valid number");
+        }
+        return number;
+    }
+    else {
+        return restoredString; // Treat as string if mode is 'string' or null
+    }
+}
+/* ---------------------------------
+ * JSON <-> Bytes Utilities
+ * --------------------------------- */
+/**
+ * Converts a stringified JSON into a Uint8Array (UTF-8 bytes)
+ */
+export function jsonStringToBytes(jsonString) {
+    return new TextEncoder().encode(jsonString);
+}
+/**
+ * Converts a Uint8Array (UTF-8 bytes) back into a stringified JSON
+ */
+export function bytesToJsonString(bytes) {
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * Converts EncryptedData (Uint8Array fields) into base64 strings
+ * for safe transport / storage (JSON, URLs, APIs, etc.)
+ */
+export function encryptedDataToBase64(data) {
+    return {
+        rqc: arrayToBase64(data.rqc),
+        iv: arrayToBase64(data.iv),
+        cipher: arrayToBase64(data.cipher),
+    };
+}
+/**
+ * Converts SerializedEncryptedData (base64 fields)
+ * back into EncryptedData (Uint8Array fields)
+ */
+export function encryptedDataFromBase64(data) {
+    return {
+        rqc: base64ToUint8Array(data.rqc),
+        iv: base64ToUint8Array(data.iv),
+        cipher: base64ToUint8Array(data.cipher),
+    };
+}
+export function base64ToJson(base64) {
+    try {
+        // 🔹 Step 0: Clean the string (remove whitespace / newlines)
+        const cleanBase64 = base64.replace(/\s+/g, "");
+        let jsonString;
+        if (typeof atob === "function") {
+            // 🔹 Browser / Service Worker (atob is available globally)
+            jsonString = decodeURIComponent(atob(cleanBase64)
+                .split("")
+                .map((c) => `%${c.charCodeAt(0).toString(16).padStart(2, "0")}`)
+                .join(""));
+        }
+        else if (typeof Buffer !== "undefined") {
+            // 🔹 Node.js fallback (Buffer is available)
+            jsonString = Buffer.from(cleanBase64, "base64").toString("utf-8");
+        }
+        else {
+            throw new Error("No base64 decode available in this environment");
+        }
+        // 🔹 Parse JSON
+        return JSON.parse(jsonString);
+    }
+    catch (err) {
+        console.error("base64ToJson error:", err);
+        throw new Error("Failed to decode Base64 JSON");
+    }
+}