XSULA: Security of your data. Guarantee transfers to relatives.

For your convenience, we are publishing a module for encrypting records in a safe.

Cripto_core.js

/**
 * XSULA Crypto Core (Updated with Dynamic Pair Salt, Argon2id & HKDF)
 */
const SafeCrypto = {
    argonConfig: {
        mem: 65536, 
        time: 3,
        parallelism: 1,
        type: 2 // Argon2id
    },

    /**
     * Gets pair_salt from the server for the current user
     */
    async getPairSalt() {
        try {
            const response = await fetch('/api/get_pair_salt.php');
            const data = await response.json();
            if (!data.pair_salt) throw new Error("Salt not found");
            return data.pair_salt;
        } catch (error) {
            alert("Security error: Unable to retrieve encryption parameters. Please try again later.");
            throw error; 
        }
    },

    /**
     * HKDF Derivation (HMAC-based Key Derivation Function)
     * Adds an extra layer of security by deriving the actual encryption key 
     * from the master secret (Argon2 output) rather than using it directly.
     */
    async hkdfDerive(ikm, salt, info) {
        const keyMaterial = await window.crypto.subtle.importKey(
            "raw", ikm, "HKDF", false, ["deriveBits", "deriveKey"]
        );
        
        // Convert salt and info to Uint8Array
        const saltBuffer = (typeof salt === 'string') ? new TextEncoder().encode(salt) : salt;
        const infoBuffer = new TextEncoder().encode(info);

        const derivedKey = await window.crypto.subtle.deriveKey(
            {
                name: "HKDF",
                hash: "SHA-512",
                salt: saltBuffer,
                info: infoBuffer
            },
            keyMaterial,
            { name: "AES-GCM", length: 256 },
            true, ["encrypt", "decrypt"]
        );

        const exported = await window.crypto.subtle.exportKey("raw", derivedKey);
        return new Uint8Array(exported);
    },

    /**
    * Generates a master key from a seed phrase
    * Flow: Seed -> Argon2 -> MasterSecret -> HKDF -> AES Key
    * @param {string} seedPhrase - 12 words of the seed phrase
    * @param {string|null} customSalt - Optional salt (if not passed, retrieved from the server)
     */
    async deriveMasterKey(seedPhrase, customSalt = null) {
        const salt = customSalt || await this.getPairSalt();
        
        // 1. Argon2 Hashing (Memory-Hard) -> Master Secret
        const argonResult = await argon2.hash({
            pass: seedPhrase.trim().toLowerCase(),
            salt: salt,
            ...this.argonConfig,
            hashLen: 32
        });

        // 2. HKDF Expansion (Key Separation) -> Final AES Key
        // Using the Argon2 hash as the Input Key Material (IKM)
        const aesKey = await this.hkdfDerive(
            argonResult.hash, 
            salt, 
            "XSULA_VAULT_AES_KEY_V1"
        );
        
        return aesKey; // Uint8Array
    },

    /**
     * Generates login_hash from first 6 words (uses GLOBAL_SALT from server)
     */
    async deriveLoginHash(first6Words, serverSalt) {
        const result = await argon2.hash({
            pass: first6Words.trim().toLowerCase(),
            salt: serverSalt,
            ...this.argonConfig,
            hashLen: 64 
        });
        return result.encoded;
    },

    /**
     * Encrypts text using AES-256-GCM
     */
    async encrypt(text, keyUint8Array) {
        const iv = window.crypto.getRandomValues(new Uint8Array(12));
        const encodedText = new TextEncoder().encode(text);
        const cryptoKey = await window.crypto.subtle.importKey(
            'raw', keyUint8Array, 'AES-GCM', false, ['encrypt']
        );
        const ciphertext = await window.crypto.subtle.encrypt(
            { name: 'AES-GCM', iv: iv },
            cryptoKey,
            encodedText
        );
        return {
            iv: btoa(String.fromCharCode(...iv)),
            data: btoa(String.fromCharCode(...new Uint8Array(ciphertext)))
        };
    },

    /**
     * Decrypts AES-256-GCM data
     */
    async decrypt(encryptedData, ivBase64, keyUint8Array) {
        try {
            const iv = new Uint8Array(atob(ivBase64).split("").map(c => c.charCodeAt(0)));
            const data = new Uint8Array(atob(encryptedData).split("").map(c => c.charCodeAt(0)));
            const cryptoKey = await window.crypto.subtle.importKey(
                'raw', keyUint8Array, 'AES-GCM', false, ['decrypt']
            );
            const decrypted = await window.crypto.subtle.decrypt(
                { name: 'AES-GCM', iv: iv },
                cryptoKey,
                data
            );
            return new TextDecoder().decode(decrypted);
        } catch (e) {
            console.error('Decryption failed:', e);
            return null;
        }
    },

    /**
     * Stores the master key in sessionStorage
     */
    saveKeyToSession(keyUint8Array) {
        const base64Key = btoa(String.fromCharCode(...keyUint8Array));
        sessionStorage.setItem('master_key', base64Key);
    },

    /**
     * Gets the master key from sessionStorage
     */
    getKeyFromSession() {
        const base64Key = sessionStorage.getItem('master_key');
        if (!base64Key) return null;
        const binStr = atob(base64Key);
        const len = binStr.length;
        const bytes = new Uint8Array(len);
        for (let i = 0; i < len; i++) {
            bytes[i] = binStr.charCodeAt(i);
        }
        return bytes;
    },

    /**
     * Removes a key from memory (to exit)
     */
    clearKeyFromSession() {
        sessionStorage.removeItem('master_key');
    }
};

/** * XSULA Crypto Core (Updated with Dynamic Pair Salt, Argon2id & HKDF) */ const SafeCrypto = { argonConfig: { mem: 65536, time: 3, parallelism: 1, type: 2 // Argon2id }, /** * Gets pair_salt from the server for the current user */ async getPairSalt() { try { const response = await fetch('/api/get_pair_salt.php'); const data = await response.json(); if (!data.pair_salt) throw new Error("Salt not found"); return data.pair_salt; } catch (error) { alert("Security error: Unable to retrieve encryption parameters. Please try again later."); throw error; } }, /** * HKDF Derivation (HMAC-based Key Derivation Function) * Adds an extra layer of security by deriving the actual encryption key * from the master secret (Argon2 output) rather than using it directly. */ async hkdfDerive(ikm, salt, info) { const keyMaterial = await window.crypto.subtle.importKey( "raw", ikm, "HKDF", false, ["deriveBits", "deriveKey"] ); // Convert salt and info to Uint8Array const saltBuffer = (typeof salt === 'string') ? new TextEncoder().encode(salt) : salt; const infoBuffer = new TextEncoder().encode(info); const derivedKey = await window.crypto.subtle.deriveKey( { name: "HKDF", hash: "SHA-512", salt: saltBuffer, info: infoBuffer }, keyMaterial, { name: "AES-GCM", length: 256 }, true, ["encrypt", "decrypt"] ); const exported = await window.crypto.subtle.exportKey("raw", derivedKey); return new Uint8Array(exported); }, /** * Generates a master key from a seed phrase * Flow: Seed -> Argon2 -> MasterSecret -> HKDF -> AES Key * @param {string} seedPhrase - 12 words of the seed phrase * @param {string|null} customSalt - Optional salt (if not passed, retrieved from the server) */ async deriveMasterKey(seedPhrase, customSalt = null) { const salt = customSalt || await this.getPairSalt(); // 1. Argon2 Hashing (Memory-Hard) -> Master Secret const argonResult = await argon2.hash({ pass: seedPhrase.trim().toLowerCase(), salt: salt, ...this.argonConfig, hashLen: 32 }); // 2. HKDF Expansion (Key Separation) -> Final AES Key // Using the Argon2 hash as the Input Key Material (IKM) const aesKey = await this.hkdfDerive( argonResult.hash, salt, "XSULA_VAULT_AES_KEY_V1" ); return aesKey; // Uint8Array }, /** * Generates login_hash from first 6 words (uses GLOBAL_SALT from server) */ async deriveLoginHash(first6Words, serverSalt) { const result = await argon2.hash({ pass: first6Words.trim().toLowerCase(), salt: serverSalt, ...this.argonConfig, hashLen: 64 }); return result.encoded; }, /** * Encrypts text using AES-256-GCM */ async encrypt(text, keyUint8Array) { const iv = window.crypto.getRandomValues(new Uint8Array(12)); const encodedText = new TextEncoder().encode(text); const cryptoKey = await window.crypto.subtle.importKey( 'raw', keyUint8Array, 'AES-GCM', false, ['encrypt'] ); const ciphertext = await window.crypto.subtle.encrypt( { name: 'AES-GCM', iv: iv }, cryptoKey, encodedText ); return { iv: btoa(String.fromCharCode(...iv)), data: btoa(String.fromCharCode(...new Uint8Array(ciphertext))) }; }, /** * Decrypts AES-256-GCM data */ async decrypt(encryptedData, ivBase64, keyUint8Array) { try { const iv = new Uint8Array(atob(ivBase64).split("").map(c => c.charCodeAt(0))); const data = new Uint8Array(atob(encryptedData).split("").map(c => c.charCodeAt(0))); const cryptoKey = await window.crypto.subtle.importKey( 'raw', keyUint8Array, 'AES-GCM', false, ['decrypt'] ); const decrypted = await window.crypto.subtle.decrypt( { name: 'AES-GCM', iv: iv }, cryptoKey, data ); return new TextDecoder().decode(decrypted); } catch (e) { console.error('Decryption failed:', e); return null; } }, /** * Stores the master key in sessionStorage */ saveKeyToSession(keyUint8Array) { const base64Key = btoa(String.fromCharCode(...keyUint8Array)); sessionStorage.setItem('master_key', base64Key); }, /** * Gets the master key from sessionStorage */ getKeyFromSession() { const base64Key = sessionStorage.getItem('master_key'); if (!base64Key) return null; const binStr = atob(base64Key); const len = binStr.length; const bytes = new Uint8Array(len); for (let i = 0; i < len; i++) { bytes[i] = binStr.charCodeAt(i); } return bytes; }, /** * Removes a key from memory (to exit) */ clearKeyFromSession() { sessionStorage.removeItem('master_key'); } };