Step-by-Step Guide to building a custom secure file encryption vault block for Gutenberg using Svelte standalone templates

Project Setup: SvelteKit, WordPress Plugin Structure, and Dependencies

This guide details the construction of a secure file encryption vault Gutenberg block, leveraging SvelteKit for the frontend component and adhering to WordPress plugin development best practices. We’ll focus on a standalone Svelte template approach, minimizing external dependencies and maximizing control over the encryption process within the WordPress ecosystem. The primary goal is to provide a robust, client-side encryption solution for sensitive files uploaded via the WordPress editor.

Our development environment will be structured as follows:

• A root directory for the WordPress plugin.
• A SvelteKit project initialized within a subdirectory (e.g., assets/svelte).
• Build scripts to compile Svelte assets and enqueue them appropriately for WordPress.

First, let’s set up the SvelteKit project. Navigate to your plugin’s root directory and initialize a new SvelteKit project. We’ll opt for a minimal setup without server-side rendering (SSR) for this client-side encryption use case, as the encryption logic will execute entirely in the user’s browser.

Initializing SvelteKit

Execute the following commands in your terminal:

cd /path/to/your/wordpress/plugin/root
mkdir assets
cd assets
npm create svelte@latest svelte-file-encryptor
cd svelte-file-encryptor
npm install

During the SvelteKit initialization, select the following options:

• “SvelteKit demo app?” – No
• “Add ESLint for code linting?” – Yes
• “Add Prettier for code formatting?” – Yes
• “Add Playwright for browser testing?” – No (for this guide’s scope)
• “Add Vitest for unit testing?” – No (for this guide’s scope)

Next, configure SvelteKit for a static build, as we will be manually enqueuing the compiled assets in WordPress. Edit svelte.config.js:

/** @type {import('@sveltejs/kit').Config} */
const config = {
    kit: {
        adapter: (await import('@sveltejs/adapter-static')).default({
            // By default, files in `public` are served at the root.
            // You can specify a different base path if your app is not served at the root.
            // For example, if your app is served at /my-app, then set this to '/my-app'
            base: '/wp-content/plugins/your-plugin-slug/assets/svelte/build',
        })
    }
};

export default config;

The base path in the adapter configuration is crucial. It tells SvelteKit where the compiled assets will be served from within your WordPress installation. Replace your-plugin-slug with the actual slug of your WordPress plugin.

WordPress Plugin Boilerplate and Asset Enqueuing

Now, let’s set up the basic WordPress plugin structure and the PHP code to enqueue our Svelte application. Create the main plugin file (e.g., secure-file-encryptor.php) in the root of your plugin directory.

<?php
/**
 * Plugin Name: Secure File Encryptor
 * Description: A Gutenberg block for secure client-side file encryption.
 * Version: 1.0.0
 * Author: Your Name
 * License: GPL-2.0-or-later
 * Text Domain: secure-file-encryptor
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit; // Exit if accessed directly.
}

/**
 * Enqueue Gutenberg block assets.
 */
function sfe_enqueue_block_assets() {
    // Enqueue Svelte build assets.
    wp_enqueue_script(
        'svelte-file-encryptor-app',
        plugin_dir_url( __FILE__ ) . 'assets/svelte/build/app.js', // Path to your compiled Svelte app.js
        array(),
        filemtime( plugin_dir_path( __FILE__ ) . 'assets/svelte/build/app.js' ),
        true // Load in footer
    );

    // Enqueue Svelte styles.
    wp_enqueue_style(
        'svelte-file-encryptor-styles',
        plugin_dir_url( __FILE__ ) . 'assets/svelte/build/assets/index.css', // Path to your compiled CSS
        array(),
        filemtime( plugin_dir_path( __FILE__ ) . 'assets/svelte/build/assets/index.css' )
    );

    // Register the block type.
    register_block_type( __DIR__ . '/build' );
}
add_action( 'init', 'sfe_enqueue_block_assets' );

/**
 * Register block assets for the editor.
 */
function sfe_register_editor_assets() {
    // Enqueue editor-specific assets if needed.
    // For a standalone Svelte app, we might not need separate editor assets
    // if the app.js handles both editor and frontend rendering.
    // If you have specific editor-only logic, enqueue them here.
}
add_action( 'enqueue_block_editor_assets', 'sfe_register_editor_assets' );

In this PHP file:

• We define the plugin header.
• The sfe_enqueue_block_assets function is hooked into the init action. This function enqueues the compiled JavaScript and CSS files from our SvelteKit build. We use filemtime for cache busting.
• register_block_type( __DIR__ . '/build' ); assumes you will have a build directory at the root of your plugin containing the block.json file and the compiled JavaScript for the block editor. We will address this in the next step.
• The sfe_register_editor_assets function is a placeholder for any editor-specific scripts or styles you might need. For a fully integrated Svelte app, the main app.js might handle both.

Gutenberg Block Registration and `block.json`

Gutenberg blocks are registered using a block.json file. This file describes the block’s attributes, styles, and script dependencies. Create a build directory at the root of your plugin and place a block.json file inside it.

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "secure-file-encryptor/vault",
  "version": "1.0.0",
  "title": "Secure File Encryptor Vault",
  "category": "media",
  "icon": "lock",
  "description": "A secure vault for encrypting and decrypting files client-side.",
  "attributes": {
    "fileUrl": {
      "type": "string",
      "default": ""
    },
    "fileName": {
      "type": "string",
      "default": ""
    },
    "encryptedContent": {
      "type": "string",
      "default": ""
    }
  },
  "editorScript": "file:./index.js",
  "editorStyle": "file:./index.css",
  "style": "file:./style.css",
  "viewScript": "file:./view.js"
}

Explanation of block.json:

• name: A unique identifier for the block.
• title, category, icon, description: Standard block metadata.
• attributes: Defines the data associated with the block. Here, we have fileUrl, fileName, and encryptedContent to store information about the encrypted file.
• editorScript: Points to the JavaScript file that will be loaded in the block editor. This will be our compiled Svelte entry point.
• editorStyle: Points to the CSS file for the editor.
• style: Points to the CSS file for the frontend.
• viewScript: Points to a JavaScript file that will be loaded on the frontend when the block is rendered. This is where our Svelte app will likely be mounted.

Crucially, the paths in block.json (e.g., file:./index.js) are relative to the build directory. This means we need to configure our SvelteKit build process to output these files correctly.

SvelteKit Build Configuration for WordPress

We need to adjust the SvelteKit build output to match the expectations of block.json and our PHP enqueuing. The default SvelteKit static adapter outputs files into a build directory. We want the main application entry point (app.js) and its associated assets (like index.css) to be accessible as index.js and index.css within the plugin’s build directory, and potentially a separate view.js for frontend-only logic.

Modify your svelte.config.js to output to the plugin’s build directory:

import adapter from '@sveltejs/adapter-static';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
    // Consult https://kit.svelte.dev/docs/integrations#preprocessors
    // for more information about preprocessors
    preprocess: vitePreprocess(),

    kit: {
        adapter: adapter({
            // Output directory relative to the SvelteKit project root.
            // We'll use a build script to move these to the plugin's build directory.
            pages: 'build',
            assets: 'build',
            fallback: null,
            // The base path where the app will be served from.
            // This should match the path in your WordPress plugin.
            // Example: '/wp-content/plugins/your-plugin-slug/assets/svelte/build'
            // For block registration, we'll adjust this to be relative to the plugin root.
            // For now, let's focus on the output structure.
        }),
        paths: {
            base: '/wp-content/plugins/your-plugin-slug/assets/svelte/build', // This is for the app's internal routing if needed
        }
    }
};

export default config;

Now, we need a build script to compile the Svelte app and copy the necessary files to the plugin’s build directory. Add a script to your SvelteKit project’s package.json:

{
  "name": "svelte-file-encryptor",
  "version": "0.0.1",
  "private": true,
  "scripts": {
    "dev": "vite dev",
    "build": "vite build && npm run copy-build-files",
    "preview": "vite preview",
    "copy-build-files": "node scripts/copy-build.js"
  },
  "devDependencies": {
    "@sveltejs/adapter-static": "^2.0.0",
    "@sveltejs/kit": "^1.0.0",
    "@sveltejs/vite-plugin-svelte": "^3.0.0",
    "eslint": "^8.28.0",
    "eslint-plugin-svelte": "^2.30.0",
    "svelte": "^4.0.0",
    "vite": "^4.0.0"
  },
  "type": "module"
}

Create a scripts/copy-build.js file in your SvelteKit project:

import fs from 'fs-extra';
import path from 'path';
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

const svelteBuildDir = path.join(__dirname, 'build'); // SvelteKit's output dir
const pluginBuildDir = path.join(__dirname, '..', 'build'); // Plugin's build dir (one level up)
const svelteAssetsDir = path.join(__dirname, '..', 'assets', 'svelte', 'build'); // For the adapter's base path reference

// Ensure plugin build directory exists
fs.ensureDirSync(pluginBuildDir);

// Copy SvelteKit's output to the plugin's build directory
// This will place app.js, index.css, etc. directly into the plugin's build folder
fs.copySync(svelteBuildDir, pluginBuildDir, { overwrite: true });

// Copy SvelteKit's output to the assets/svelte/build directory for adapter reference
fs.ensureDirSync(svelteAssetsDir);
fs.copySync(svelteBuildDir, svelteAssetsDir, { overwrite: true });

console.log('Svelte build files copied to plugin build directory and assets directory.');

Now, when you run npm run build in your SvelteKit project, it will first build the Svelte app and then execute the copy-build.js script. This script copies the compiled Svelte assets (app.js, index.css, etc.) into your plugin’s build directory, making them available for WordPress to enqueue and for block.json to reference.

Svelte Component Structure for the Vault Block

Let’s define the Svelte components that will form our file encryption vault. We’ll create a main Vault.svelte component and potentially helper components for file upload, encryption/decryption forms, and display.

Create a new file src/routes/+page.svelte within your SvelteKit project. This will be the main entry point for our application when it’s loaded by WordPress.

<script>
    import { onMount } from 'svelte';
    import FileUploader from './components/FileUploader.svelte';
    import EncryptionForm from './components/EncryptionForm.svelte';
    import DecryptionForm from './components/DecryptionForm.svelte';
    import FileDisplay from './components/FileDisplay.svelte';

    let file = null;
    let password = '';
    let encryptedContent = null;
    let decryptedContent = null;
    let fileName = '';
    let errorMessage = '';

    // Function to handle file selection
    function handleFileSelect(event) {
        file = event.target.files[0];
        fileName = file ? file.name : '';
        encryptedContent = null;
        decryptedContent = null;
        errorMessage = '';
    }

    // Function to handle encryption
    async function encryptFile(event) {
        event.preventDefault();
        if (!file || !password) {
            errorMessage = 'Please select a file and enter a password.';
            return;
        }

        try {
            const fileContent = await file.arrayBuffer();
            const key = await deriveKey(password, fileContent); // Derive key from password and file content for added security
            const iv = crypto.getRandomValues(new Uint8Array(12)); // Initialization vector

            const encrypted = await crypto.subtle.encrypt(
                {
                    name: 'AES-GCM',
                    iv: iv,
                },
                key,
                fileContent
            );

            // Store IV and encrypted data. IV needs to be prepended or stored separately.
            // For simplicity here, we'll store as a base64 string with IV prepended.
            const ivBase64 = btoa(String.fromCharCode(...iv));
            const encryptedBase64 = btoa(String.fromCharCode(...new Uint8Array(encrypted)));
            encryptedContent = `${ivBase64}:${encryptedBase64}`;
            decryptedContent = null; // Clear any previous decryption
            errorMessage = '';

            // In a real WordPress block, you'd save this encryptedContent to the block's attributes.
            // For this standalone example, we're just displaying it.

        } catch (e) {
            errorMessage = 'Encryption failed: ' + e.message;
            console.error('Encryption error:', e);
        }
    }

    // Function to handle decryption
    async function decryptFile(event) {
        event.preventDefault();
        if (!encryptedContent || !password) {
            errorMessage = 'Please provide encrypted content and a password.';
            return;
        }

        try {
            const [ivBase64, encryptedBase64] = encryptedContent.split(':');
            const iv = Uint8Array.from(atob(ivBase64), c => c.charCodeAt(0));
            const encrypted = Uint8Array.from(atob(encryptedBase64), c => c.charCodeAt(0));

            // Re-derive the key using the same method as encryption
            // Note: For robust decryption, the original file content isn't needed if the key derivation is deterministic
            // and the password is the sole secret. However, using file content adds a layer of salt-like behavior.
            // For this example, we'll assume we can re-derive or have a way to get a consistent key.
            // A more practical approach might involve storing a salt or using a password-based key derivation function (PBKDF2)
            // with a stored salt. For simplicity, we'll re-derive using a placeholder.
            // In a real scenario, you'd need a consistent way to get the key.
            // Let's assume for this demo that the password alone is sufficient for key derivation if we use a standard PBKDF.
            // For this example, we'll use a simplified key derivation for demonstration.
            // A proper implementation would use PBKDF2 or Argon2.

            // Simplified key derivation for demo purposes. Replace with a secure PBKDF.
            const key = await deriveKey(password); // Assuming password is the only secret for key derivation

            const decrypted = await crypto.subtle.decrypt(
                {
                    name: 'AES-GCM',
                    iv: iv,
                },
                key,
                encrypted
            );

            const decoder = new TextDecoder();
            decryptedContent = decoder.decode(decrypted);
            errorMessage = '';

        } catch (e) {
            errorMessage = 'Decryption failed: ' + e.message;
            console.error('Decryption error:', e);
        }
    }

    // Placeholder for secure key derivation (e.g., using PBKDF2)
    async function deriveKey(password, salt = null) {
        const encoder = new TextEncoder();
        const passwordBuffer = encoder.encode(password);

        // For AES-GCM, we need a 256-bit key (32 bytes)
        // Using crypto.subtle.importKey with PBKDF2 is the standard way.
        // A salt is crucial for security. If not provided during encryption,
        // it should be generated and stored/associated with the encrypted data.
        // For this demo, we'll use a fixed salt or derive from file content if available.
        // A real implementation would store the salt alongside the encrypted data.

        const effectiveSalt = salt || encoder.encode('default-salt-for-demo'); // Use provided salt or a default

        const keyMaterial = await crypto.subtle.importKey(
            "raw",
            passwordBuffer,
            { name: "PBKDF2" },
            false,
            ["deriveKey"]
        );

        const key = await crypto.subtle.deriveKey(
            {
                name: "PBKDF2",
                salt: effectiveSalt,
                iterations: 100000, // Recommended: 100,000+ iterations
                hash: "SHA-256",
            },
            keyMaterial,
            { name: "AES-GCM", length: 256 },
            true, // Extractable
            ["encrypt", "decrypt"]
        );
        return key;
    }

    // Function to handle saving the block's data to WordPress
    // This would typically be called by the Gutenberg editor's save function.
    function saveBlockData() {
        // In a real Gutenberg block, this function would return the block's attributes
        // to be saved in the post content.
        // For example:
        // return {
        //     attributes: {
        //         fileUrl: file ? URL.createObjectURL(file) : '', // Not ideal for security
        //         fileName: fileName,
        //         encryptedContent: encryptedContent
        //     }
        // };
        console.log('Saving block data:', { fileName, encryptedContent });
        // This function is usually part of the block's edit component and returns the save data.
        // For this standalone example, we're just logging.
    }

    onMount(() => {
        // Initialize any necessary libraries or set up event listeners
        console.log('Svelte app mounted.');
    });


<main>
    <h1>Secure File Encryptor Vault</h1>

    {#if errorMessage}
        <p style="color: red;">{errorMessage}</p>
    {/if}

    {#if !encryptedContent && !decryptedContent}
        <!-- File Upload and Encryption -->
        <div>
            <h2>Encrypt File</h2>
            <label for="fileInput">Choose File:</label>
            <input type="file" id="fileInput" on:change={handleFileSelect} />
            {#if file}
                <p>Selected: {fileName}</p>
                <EncryptionForm password={password} on:passwordChange={(e) => password = e.detail.password} on:encrypt={encryptFile} />
            {/if}
        </div>
    {/if}

    {#if encryptedContent && !decryptedContent}
        <!-- Display Encrypted Content and Decryption Form -->
        <div>
            <h2>File Encrypted</h2>
            <p>File: {fileName}</p>
            <p>Encrypted Data (Base64): {encryptedContent.substring(0, 50)}...</p>
            <DecryptionForm password={password} on:passwordChange={(e) => password = e.detail.password} on:decrypt={decryptFile} />
        </div>
    {/if}

    {#if decryptedContent}
        <!-- Display Decrypted Content -->
        <div>
            <h2>File Decrypted</h2>
            <FileDisplay content={decryptedContent} fileName={fileName} />
        </div>
    {/if}

    <!-- Button to trigger save (for demonstration) -->
    <button on:click={saveBlockData}>Log Block Data for Save</button>

</main>

<style>
    main {
        font-family: sans-serif;
        padding: 20px;
        border: 1px solid #ccc;
        border-radius: 5px;
        margin-bottom: 20px;
    }
    h1, h2 {
        color: #333;
    }
    input[type="file"], input[type="password"] {
        margin-bottom: 10px;
        padding: 8px;
        border: 1px solid #ddd;
        border-radius: 3px;
    }
    button {
        padding: 10px 15px;
        background-color: #007bff;
        color: white;
        border: none;
        border-radius: 3px;
        cursor: pointer;
        margin-top: 10px;
    }
    button:hover {
        background-color: #0056b3;
    }
</style>

Create the helper components:

src/routes/components/FileUploader.svelte

<script>
    export let fileName = '';
</script>

<div>
    <label for="fileInput">Choose File:</label>
    <input type="file" id="fileInput" on:change />
    {#if fileName}
        <p>Selected: {fileName}</p>
    {/if}
</div>

<style>
    /* Add styles if needed */
</style>

src/routes/components/EncryptionForm.svelte

<script>
    import { createEventDispatcher } from 'svelte';

    const dispatch = createEventDispatcher();

    export let password = '';

    function handlePasswordInput(event) {
        password = event.target.value;
        dispatch('passwordChange', { password });
    }

    function handleSubmit(event) {
        dispatch('encrypt', event);
    }
</script>

<form on:submit|preventDefault={handleSubmit}>
    <label for="passwordInput">Password:</label>
    <input
        type="password"
        id="passwordInput"
        bind:value={password}
        on:input={handlePasswordInput}
        placeholder="Enter password for encryption"
        required
    />
    <button type="submit">Encrypt File</button>
</form>

<style>
    form {
        margin-top: 15px;
        display: flex;
        align-items: center;
        gap: 10px;
    }
    label {
        font-weight: bold;
    }
    input[type="password"] {
        padding: 8px;
        border: 1px solid #ddd;
        border-radius: 3px;
        flex-grow: 1;
    }
    button {
        padding: 10px 15px;
        background-color: #28a745;
        color: white;
        border: none;
        border-radius: 3px;
        cursor: pointer;
    }
    button:hover {
        background-color: #218838;
    }
</style>

src/routes/components/DecryptionForm.svelte

<script>
    import { createEventDispatcher } from 'svelte';

    const dispatch = createEventDispatcher();

    export let password = '';

    function handlePasswordInput(event) {
        password = event.target.value;
        dispatch('passwordChange', { password });
    }

    function handleSubmit(event) {
        dispatch('decrypt', event);
    }
</script>

<form on:submit|preventDefault={handleSubmit}>
    <label for="passwordInput">Password:</label>
    <input
        type="password"
        id="passwordInput"
        bind:value={password}
        on:input={handlePasswordInput}
        placeholder="Enter password for decryption"
        required
    />
    <button type="submit">Decrypt File</button>
</form>

<style>
    form {
        margin-top: 15px;
        display: flex;
        align-items: center;
        gap: 10px;
    }
    label {
        font-weight: bold;
    }
    input[type="password"] {
        padding: 8px;
        border: 1px solid #ddd;
        border-radius: 3px;
        flex-grow: 1;
    }
    button {
        padding: 10px 15px;
        background-color: #007bff;
        color: white;
        border: none;
        border-radius: 3px;
        cursor: pointer;
    }
    button:hover {
        background-color: #0056b3;
    }
</style>

src/routes/components/FileDisplay.svelte

<script>
    import { createEventDispatcher } from 'svelte';

    const dispatch = createEventDispatcher();

    export let content = '';
    export let fileName = '';

    // Function to download the decrypted content as a file
    function downloadFile() {
        const blob = new Blob([content], { type: 'text/plain' }); // Adjust MIME type as needed
        const url = URL.createObjectURL(blob);
        const a = document.createElement('a');
        a.href = url;
        a.download = `decrypted_${fileName || 'file'}`;
        document.body.appendChild(a);
        a.click();
        document.body.removeChild(a);
        URL.revokeObjectURL(url);
    }
</script>

<div>
    <h3>Decrypted Content for: {fileName}</h3>
    <pre style="white-space: pre-wrap; word-wrap: break-word; background-color: #f4f4f4; padding: 10px; border: 1px solid #eee; border-radius: 3px;">{content}</pre>
    <button on:click={downloadFile}>Download Decrypted File</button>
</div>

<style>
    pre {
        max-height: 300px;
        overflow-y: auto;
    }
    button {
        padding: 10px 15px;
        background-color: #17a2b8;
        color: white;
        border: none;
        border-radius: 3px;
        cursor: pointer;
        margin-top: 10px;
    }
    button:hover {
        background-color: #138496;
    }
</style>

The +page.svelte acts as the main application shell. It conditionally renders different sections based on the state (file selected, encrypted, decrypted). The deriveKey function uses the Web Crypto API for encryption/decryption. For production, ensure a robust PBKDF2 or Argon2 implementation with proper salt management is used.

Integrating Svelte with Gutenberg Block Editor

The key to integrating our