DEV Community: Enrique Marín

A minimalist password manager desktop app: a foray into Golang's Wails framework (Part 2)

Enrique Marín — Thu, 19 Dec 2024 12:25:47 +0000

Hi again, coders! In the first part of this short series we saw the creation and operation of a desktop application to store and encrypt our passwords made with the Wails framework. We also made a description of the Go backend and how we bind it to the frontend side.

In this part, we are going to deal with the user interface. As we stated in that post, Wails allows us to use any web framework we like, even Vanilla JS, to build our GUI. As I said, it seems that the creators of Wails have a preference for Svelte, because they always mention it as their first choice. The Wails CLI (in its current version) when we ask to create a project with Svelte+Typescript (wails init -n myproject -t svelte-ts) generates the scaffolding with Svelte3. As I already told you, if you prefer to use Svelte5 (and its new features) I have a bash script that automates its creation (in any case, you have to have the Wails CLI installed). In addition, it adds Taildwindcss+Daisyui which seems to me a perfect combination for the interface design.

The truth is that I had worked first with Vanilla Js and Vue, then with React, and even with that strange library that for many is HTMX (which I have to say that I love ❤️). But Svelte makes you fall in love from the beginning, and I have to say that it was while experimenting with Wails that I used it for the first time (and I promise to continue using it…). But as comfortable as a web framework is, we must remind backend developers that the frontend is not that easy 😀!!

But let's get to the point.

I - A look at the frontend structure

If you have used any web framework, you will quickly recognize that the Wails CLI uses ViteJs under the hood:

...
.
├── index.html
├── package.json
├── package.json.md5
├── package-lock.json
├── postcss.config.js
├── README.md
├── src
│   ├── App.svelte
│   ├── assets
│   │   ├── fonts
│   │   │   ├── nunito-v16-latin-regular.woff2
│   │   │   └── OFL.txt
│   │   └── images
│   │       └── logo-universal.png
│   ├── lib
│   │   ├── BackBtn.svelte
│   │   ├── BottomActions.svelte
│   │   ├── EditActions.svelte
│   │   ├── EntriesList.svelte
│   │   ├── Language.svelte
│   │   ├── popups
│   │   │   ├── alert-icons.ts
│   │   │   └── popups.ts
│   │   ├── ShowPasswordBtn.svelte
│   │   └── TopActions.svelte
│   ├── locales
│   │   ├── en.json
│   │   └── es.json
│   ├── main.ts
│   ├── pages
│   │   ├── About.svelte
│   │   ├── AddPassword.svelte
│   │   ├── Details.svelte
│   │   ├── EditPassword.svelte
│   │   ├── Home.svelte
│   │   ├── Login.svelte
│   │   └── Settings.svelte
│   ├── style.css
│   └── vite-env.d.ts
├── svelte.config.js
├── tailwind.config.js
├── tsconfig.json
├── tsconfig.node.json
├── vite.config.ts
└── wailsjs
    ├── go
    │   ├── main
    │   │   ├── App.d.ts
    │   │   └── App.js
    │   └── models.ts
    └── runtime
        ├── package.json
        ├── runtime.d.ts
        └── runtime.js

...

If you have used any web framework generated by Vite you will not be surprised by its configuration files. Here I use Svelte5 (plus the configuration of Taildwindcss+Daisyui) which is what generates my own bash script, as I have already told you. We also use TypeScript, which will facilitate the development of the frontend, so you can also see its configurations.

But the important thing in this explanation is the content of the wailsjs folder. This is where the compilation done by Wails has done its magic. The go subfolder is where the methods "translated" to Js/Ts of the backend part that has to interact with the frontend are stored. For example, in main/App.js (or its TypeScript version, main/App.d.ts) there are all the exported (public) methods of the App structure:

// Cynhyrchwyd y ffeil hon yn awtomatig. PEIDIWCH Â MODIWL
// This file is automatically generated. DO NOT EDIT
import {models} from '../models';

export function AddPasswordEntry(arg1:string,arg2:string,arg3:string):Promise<string>;

export function CheckMasterPassword(arg1:string):Promise<boolean>;

export function DeleteEntry(arg1:string):Promise<void>;

export function Drop():Promise<void>;

export function GetAllEntries():Promise<Array<models.PasswordEntry>>;

export function GetEntryById(arg1:string):Promise<models.PasswordEntry>;

export function GetLanguage():Promise<string>;

export function GetMasterPassword():Promise<boolean>;

export function GetPasswordCount():Promise<number>;

export function SaveLanguage(arg1:string):Promise<void>;

export function SaveMasterPassword(arg1:string):Promise<string>;

export function UpdateEntry(arg1:models.PasswordEntry):Promise<boolean>;

All of them return a promise. If the promise "wraps" some Go structure used as return type or the respective function takes an argument type, there will be a module (models.ts, typed in this case, because we use TypeScript) that contains the class corresponding to the Go structure and its constructor in a namespace.

Additionally, the runtime subfolder contains all the methods from Go's runtime package that allow us to manipulate the window and events listened to or emitted from or to the backend, respectively.

The src folder contains the files that will be compiled by Vite to save them in "frontend/dist" (and embedded in the final executable), as in any web application. Note that, since we use Tailwindcss, style.css contains the basic Tailwind configuration plus any CSS classes we need to use. Also, as an advantage of using web technology for the interface, we can easily use one or more fonts (folder assets/fonts) or exchange them.

To finish with this overview, note that when we compile in development mode (wails dev), in addition to allowing us to hot reloading, we can not only observe the changes made (both in the backend and in the frontend) in the application window itself, but also in a web browser through the address http://localhost:34115, since a webserver is started. This allows you to use your favorite browser development extensions. Although it must be said that Wails himself provides us with some very useful dev tools, when we right-click on the application window (only in development mode) and choose "Inspect Element":

II - And now… a dive into HTML, CSS and JavaScript 🤿

/* package.json */
...
},
  "dependencies": {
    "svelte-copy": "^2.0.0",
    "svelte-i18n": "^4.0.1",
    "svelte-spa-router": "^4.0.1",
    "sweetalert2": "^11.14.5"
  }
...

As you can see, there are 4 JavaScript packages I've added to Svelte (apart from the already mentioned Tailwindcss+Daisyui):

svelte-copy, to make it easier to copy username and password to clipboard.
svelte-i18n, for i18n handling, i.e. allowing the user to change the application's language.
svelte-spa-router, a small routing library for Svelte, which makes it easier to change views in the application window, since it's not worth it, in this case, to use the "official" routing provided by SvelteKit.
sweetalert2, basically use it to create modals/dialog boxes easily and quickly.

The entry point of every SPA is the main.js (or main.ts) file, so let's start with that:

/* main.ts */

import { mount } from 'svelte'
import './style.css'
import App from './App.svelte'
import { addMessages, init } from "svelte-i18n"; // ⇐ ⇐
import en from './locales/en.json'; // ⇐ ⇐
import es from './locales/es.json'; // ⇐ ⇐

addMessages('en', en); // ⇐ ⇐
addMessages('es', es); // ⇐ ⇐

init({
  fallbackLocale: 'en', // ⇐ ⇐
  initialLocale: 'en', // ⇐ ⇐
});

const app = mount(App, {
  target: document.getElementById('app')!,
})

export default app

I've highlighted the things I've added to the skeleton generated by the Wails CLI. The svelte-i18n library requires that JSON files containing translations be registered in the main.js/ts file, at the same time as setting the fallback/initial language (although as we'll see, that will be manipulated later based on what the user has selected as their preferences). The JSON files containing the translations are in the format:

/* frontend/src/locales/en.json */

{
    "language": "Language",
    "app_title": "Nu-i uita • minimalist password store",
    "select_directory": "Select the directory where to save the data export",
    "select_file": "Select the backup file to import",
    "master_password": "Master Password 👇",
    "generate": "Generate",
    "insert": "Insert",
    "login": "Login",
    ...
}


/* frontend/src/locales/es.json */

{
    "language": "Idioma",
    "app_title": "Nu-i uita • almacén de contraseñas minimalista",
    "select_directory": "Selecciona el directorio donde guardar los datos exportados",
    "select_file": "Selecciona el archivo de respaldo que deseas importar",
    "master_password": "Contraseña Maestra 👇",
    "generate": "Generar",
    "insert": "Insertar",
    "login": "Inciar sesión",
    ...
}

I find this library's system to be easy and convenient for facilitating translations of Svelte applications (you can consult its documentation for more details):


<script>
  import { _ } from "svelte-i18n";
</script>

<svelte:head>
  <title>{$_("app_title")}</title>
</svelte:head>

You can also use sites like this one, which will help you translate JSON files into different languages. However, the problem is that when you fill your .svelte files with $format you have to manually keep track of them, which is tedious and error-prone. I don't know of any way to automate this task, if anyone knows, I'd be interested if you'd let me know 🙏… Otherwise, I'd have to think of some kind of script to do that job.

The next step in building the interface, as in any Svelte application, is the App.svelte file:

/* App.svelte */

<script lang="ts">
    import Router from "svelte-spa-router";
    import Home from "./pages/Home.svelte";
    import Login from "./pages/Login.svelte";
    import About from "./pages/About.svelte";
    import AddPassword from "./pages/AddPassword.svelte";
    import Details from "./pages/Details.svelte";
    import EditPassword from "./pages/EditPassword.svelte";
    import Settings from "./pages/Settings.svelte";
    import { EventsEmit } from "../wailsjs/runtime/runtime";

    const routes = {
        "/": Login,
        "/home": Home,
        "/about": About,
        "/add": AddPassword,
        "/details/:id": Details,
        "/edit/:id": EditPassword,
        "/settings": Settings,
    };

    const onKeyDown = (e: KeyboardEvent) =>
        e.key === "Escape" ? EventsEmit("quit") : false;
</script>

<main class="overflow-hidden">
    <Router {routes} />
</main>

<svelte:window on:keydown={onKeyDown} />

3 things to comment here. The first is the use of the svelte-spa-router library (for more details see its doc here). For the simple purpose of changing views in a desktop application, this library more than fulfills its purpose. With the 7 views or pages we create a dictionary (or JavaScript object) that associates routes with views. Then this dictionary is passed as props to the Router component of svelte-spa-router. It's that simple. As we will see later, through programmatic navigation or through user action we can easily change views.

The other thing is that I added a little gadget: when the user presses the Escape key the application closes (on the Settings page a tip clarifies to the user that this key closes the application). Svelte actually makes the job a lot easier, because this simple line: <svelte:window on:keydown={onKeyDown} /> catches the Keyboard event from the DOM triggering the execution of the onKeyDown function which in turn emits a Wails event (which we call "quit") which is listened to in the backend and when received there, closes the application. Since App.svelte is the component that encompasses the entire application, this is the right place to put the code for this action.

The last thing to clarify is why the HTML main tag carries Tailwind's overflow-hidden utility class. Since we're going to use an animation where components appear to enter from the right, which momentarily "increases" the width of the window, overflow-hidden prevents an ugly horizontal scrollbar from appearing.

The first view the user sees when opening the application is the Login view/page. Its logic is similar to that of a login page in any web application. Let's first look at the logic used for the views animations, because it is the same as that followed on the rest of the pages:

/* Login.svelte */

<script lang="ts">
    import { onMount } from "svelte";
    import { fade, fly } from "svelte/transition";

...

let mounted = false;

...

onMount(() => {
        mounted = true;

...
};

...

</script>

{#if mounted}
    <div
        in:fly={{ x: 75, duration: 1200 }}
        out:fade={{ duration: 200 }}
        class="flex h-screen"
    >

...
    </div>
{/if}

The animation requires declaring a variable (state, let mount = false;) which is initially set to false. When the component is mounted, a lifecycle hook (onMount, similar to React) sets it to true and the animation can now begin. An entrance from the right of 1200 milliseconds duration is used (in:fly={{ x: 75, duration: 1200 }}) and a fade (out:fade={{ duration: 200 }}) of 200 milliseconds duration. Simple thanks to Svelte.

When setting up the Login view we also need to know if the user is already registered in the database or if it is the first time he/she enters the application:

/* Login.svelte */
...
let isLogin = false;
...

onMount(() => {
    GetMasterPassword().then((result) => {
        isLogin = result;
        // console.log("Master password exists in DB:", isLogin);
    });
...
};

Here we make use of GetMasterPassword which is a binding generated automatically when compiling the application and which was declared as a public method of the struct App (see the first part of this series). This function queries the database and, in case there is a master password registered in it, it considers the user as already registered (it returns a promise that wraps a boolean value), asking him to enter said password to allow him access to the rest of the views. If there is no master password in the database, the user is considered as "new" and what is asked is that he generates his own password to enter the application for the first time.

Finally, when mounting the Login.svelte component we do something that is important for the rest of the application. Although the svelte-i18n library forces us to declare the initial language code, as we have already seen, when mounting Login.svelte we ask the database (using the GetLanguage binding) to check if there is a language code saved. In case the database returns an empty string, that is, if there is no language configured as the user's preference, svelte-i18n will use the value configured as initialLocale. If instead there is a language configured, that language will be set (locale.set(result);) and the "change_titles" event will be emitted, to which the translated titles of the title bar and native dialogs of the app will be passed for the backend to handle:

/* Login.svelte */

<script lang="ts">
    import { onMount } from "svelte";
    ...
    import { _, locale } from "svelte-i18n";
    import {
        ...
        GetLanguage,
        ...
    } from "../../wailsjs/go/main/App";
    ...
    import { EventsEmit } from "../../wailsjs/runtime/runtime";

...

onMount(() => {
   ...
   GetLanguage().then((result) => {
      locale.set(result);
      EventsEmit(
         "change_titles",
         $_("app_title"),
         $_("select_directory"),
         $_("select_file"),
      );
   });
   ...
};
...
</script>

The following is the logic for handling the login:

/* Login.svelte */

<script lang="ts">
    ...

    import { _, locale } from "svelte-i18n";
    import {
        ...
        GetMasterPassword,
        SaveMasterPassword,
    } from "../../wailsjs/go/main/App";
    import { push } from "svelte-spa-router";

    // states and local variables
    let mounted = false,
        inputRef: HTMLInputElement | null = null,
        isLogin = false,
        show = false,
        newPassword = "",
        visible = false,
        toast = "",
        tmId1 = 0,
        tmId2 = 0;
...

    const onLogin = () => {
        if (newPassword.length < 6 || !isAscii(newPassword)) {
            toast = $_("password_too_short_or_non_ascii_chars");
            visible = true;
            tmId1 = setTimeout(() => {
                toast = "";
                visible = false;
            }, 2000);
            newPassword = "";
            inputRef?.focus();
            return;
        } else if (!isLogin) {
            SaveMasterPassword(newPassword).then((result) => {
                // console.log("PASSWORD_ID:", result);
                result ? push("/home") : false;
            });
            return;
        }

        CheckMasterPassword(newPassword).then((result) => {
            if (result) {
                push("/home");
            } else {
                toast = $_("wrong_password");
                visible = true;
                tmId2 = setTimeout(() => {
                    toast = "";
                    visible = false;
                }, 2000);
                newPassword = "";
                inputRef?.focus();
            }
        });
    };

    const isAscii = (str: string): boolean => /^[\x00-\x7F]+$/.test(str);
</script>

Simply put: newPassword, the state bound to the input that gets what the user types, is first checked by onLogin to see if it has at least 6 characters and that all of them are ASCII characters, i.e. they are only 1 byte long (see the reason for that in part I of this series) by this little function const isAscii = (str: string): boolean => /^[\x00-\x7F]+$/.test(str);. If the check fails the function returns and displays a warning toast to the user. Afterwards, if there is no master password saved in the database (isLogin = false), whatever the user types is saved by the SaveMasterPassword function (a binding generated by Wails); If the promise is resolved successfully (returns a uuid string as the Id of the record stored in the database), the user is taken to the home view by the svelte-spa-router library's push method. Conversely, if the password passes the check for length and absence of non-ASCII characters and there is a master password in the DB (isLogin = true) then the CheckMasterPassword function verifies its identity against the stored one and either takes the user to the home view (promise resolved with true) or a toast is shown indicating that the entered password was incorrect.

The central view of the application and at the same time the most complex is the home view. Its HTML is actually subdivided into 3 components: a top button bar with a search input (TopActions component), a bottom button bar (BottomActions component) and a central area where the total number of saved password entries or the list of these is displayed using a scrollable window (EntriesList component):

/* Home.svelte */

<script lang="ts">
    import { onMount } from "svelte";
    import { fade, fly } from "svelte/transition";
    import { _ } from "svelte-i18n";
    import BottomActions from "../lib/BottomActions.svelte";
    import TopActions from "../lib/TopActions.svelte";
    import { GetPasswordCount } from "../../wailsjs/go/main/App";
    import EntriesList from "../lib/EntriesList.svelte";

    let mounted: boolean = false,
        count: number = 0,
        showList: boolean = false,
        searchTerms: string = "";

    onMount(() => {
        mounted = true;
        GetPasswordCount().then((result) => (count = result));
    });
</script>

{#if mounted}
    <div
        in:fly={{ x: 75, duration: 1200 }}
        out:fade={{ duration: 200 }}
        class="flex h-screen relative"
    >
        <TopActions bind:isEntriesList={showList} bind:search={searchTerms} />

        {#if !showList}
            <h1 class="text-lg font-light m-auto">
                {count}&nbsp;{$_("home_title")}
            </h1>
        {:else}
            <EntriesList bind:listCounter={count} bind:search={searchTerms} />
        {/if}

        <BottomActions />
    </div>
{/if}

Let's take a look at the TopActions and EntriesList components since they are both very closely related. And they are, especially since their props are states of the parent component. This is where that new feature of Svelte5 comes into play: runes. Both components take props declared with the $bindable rune; this means that data can also flow up from child to parent. A diagram may make it clearer:

For example, in the TopActions component if the user clicks on the "Entries list" button, this is executed:

/* TopActions.svelte */

onclick={() => {
    search = ""; // is `searchTerms` in the parent component
    isEntriesList = !isEntriesList; // is `showList` in the parent component
}}

That is, it makes the search state (searchTerms) an empty string, so that if there are any search terms it is reset and thus the entire list is shown. And on the other hand, it toggles the showList state (props isEntriesList in TopActions) so that the parent component shows or hides the list.

As we can see in the diagram above, both child components share the same props with the parent's searchTerms state. The TopActions component captures the input from the user and passes it as state to the parent component Home, which in turn passes it as props to its child component EntriesList.

The main logic of displaying the full list or a list filtered by the search terms entered by the user is carried out, as expected, by the EntriesList component:

/* EntriesList.svelte */

<script lang="ts">
    import { models } from "../../wailsjs/go/models";
    import {
        GetAllEntries,
        GetPasswordCount,
        DeleteEntry,
    } from "../../wailsjs/go/main/App";
    import { onDestroy, onMount } from "svelte";
    import { _ } from "svelte-i18n";
    import { push } from "svelte-spa-router";
    import { showSuccess, showWarning } from "./popups/popups";

    let {
        listCounter = $bindable(),
        search = $bindable(),
    }: {
        listCounter: number;
        search: string;
    } = $props();

    let entries: models.PasswordEntry[] = $state([]);

    onMount(() => {
        GetAllEntries().then((result) => {
            // console.log("SEARCH:", search);
            if (search) {
                const find = search.toLowerCase();
                entries = result.filter(
                    (item) =>
                        item.Username.toLowerCase().includes(find) ||
                        item.Website.toLowerCase().includes(find),
                );
            } else {
                entries = result;
            }
        });
    });

    onDestroy(() => (search = ""));

    const showAlert = (website: string, id: string) => {
        const data: string[] = [
            `${$_("alert_deleting_password")} "${website}."`,
            `${$_("alert_confirm_deleting")}`,
        ];
        showWarning(data).then((result) => {
            if (result.value) {
                DeleteEntry(id).then(() => deleteItem(id));
                showSuccess($_("deletion_confirm_msg"));
            }
        });
    };

    const deleteItem = (id: string): void => {
        let itemIdx = entries.findIndex((x) => x.Id === id);
        entries.splice(itemIdx, 1);
        entries = entries;
        GetPasswordCount().then((result) => (listCounter = result));
    };
</script>

As we said, 2 props are received (listCounter and search) and a state is maintained (let entries: models.PasswordEntry[] = $state([]);). When the component is mounted at the user's request, the backend is asked for the complete list of saved password entries. If there are no search terms, they are stored in the state; if there are, a simple filtering of the obtained array is performed and it is saved in the state:

/* EntriesList.svelte */

...
    onMount(() => {
        GetAllEntries().then((result) => {
            // console.log("SEARCH:", search);
            if (search) {
                const find = search.toLowerCase();
                entries = result.filter(
                    (item) =>
                        item.Username.toLowerCase().includes(find) ||
                        item.Website.toLowerCase().includes(find),
                );
            } else {
                entries = result;
            }
        });
    });
...

In the displayed list, the user can perform 2 actions. The first is to display the details of the entry, which is carried out when he clicks on the corresponding button: onclick={() => push(`/details/${entry.Id}`)}. Basically, we call the push method of the routing library to take the user to the details view, but passing the Id parameter corresponding to the item in question.

The other action the user can perform is to delete an item from the list. If he clicks on the corresponding button, he will be shown a confirmation popup, calling the showAlert function. This function in turn calls showWarning, which is actually an abstraction layer over the sweetalert2 library (all the functions that call the sweetalert2 library are in frontend/src/lib/popups/popups.ts). If the user confirms the deletion action, the DeleteEntry binding is called (to delete it from the DB) and, in turn, if the promise it returns is resolved, deleteItem is called (to delete it from the array stored in the entries state):

/* EntriesList.svelte */

...

const showAlert = (website: string, id: string) => {
        const data: string[] = [
            `${$_("alert_deleting_password")} "${website}."`,
            `${$_("alert_confirm_deleting")}`,
        ];
        showWarning(data).then((result) => {
            if (result.value) {
                DeleteEntry(id).then(() => deleteItem(id));
                showSuccess($_("deletion_confirm_msg"));
            }
        });
    };

const deleteItem = (id: string): void => {
    let itemIdx = entries.findIndex((x) => x.Id === id);
    entries.splice(itemIdx, 1);
    entries = entries;
    GetPasswordCount().then((result) => (listCounter = result));
};

The other component of the Home view (BottomActions) is much simpler: it does not receive props and is limited to redirecting the user to various views (Settings, About or AddPassword).

The AddPassword and EditPassword views share very similar logic and are similar to the Login view as well. Both do not allow the user to enter spaces at the beginning and end of what they typed in the text input and follow the same policy as the Login view of requiring passwords to be at least 6 ASCII characters long. Basically, what sets them apart is that they call the Wails-generated links relevant to the action they need to perform:

/* AddPassword.svelte */

...

AddPasswordEntry(website, username, newPassword).then((result) => {
    result ? push("/home") : false;
});

...

/* EditPassword.svelte */

...

UpdateEntry(entry).then((result) => {
    result ? push("/home") : false;
});
...

The other view that is somewhat complex is Settings. This has a Language component that receives as props languageName from its parent component (Settings):

/* Language.svelte */

<script lang="ts">
    import { onMount } from "svelte";
    import { locale, _ } from "svelte-i18n";
    import { SaveLanguage } from "../../wailsjs/go/main/App";
    import { EventsEmit } from "../../wailsjs/runtime/runtime";

    type language = {
        code: string;
        name: string;
    };

    const languages: language[] = [
        { code: "en", name: "English" },
        { code: "es", name: "Español" },
    ];

    let { languageName }: { languageName: string } = $props();

    onMount(() => (selected.name = languageName));

    let selected = $state({ code: "", name: "" } as language);
    const handleChange = (newLocale: language) => {
        // console.log("Language selected:", newLocale);
        locale.set(newLocale["code"]);
        EventsEmit(
            "change_titles",
            $_("app_title"),
            $_("select_directory"),
            $_("select_file"),
        );
        SaveLanguage(newLocale["code"]);
    };
</script>

...

The HTML for this component is a single select that handles the user's language choice. In its onchange event it receives a function (handleChange) that does 3 things:

sets the language on the frontend using the svelte-i18n library
emits an event ("change_titles") so that the Wails runtime changes the title of the application's title bar and the titles of the Select Directory and Select File dialog boxes in relation to the previous action
saves the language selected by the user in the DB so that the next time the application is started it will open configured with that language.

Returning to the Settings view, its entire operation is governed by a series of events that are sent and received to or from the backend. The simplest of all is the Quit button: when the user clicks on it, a quit event is triggered and listened to in the backend and the application closes (onclick={() => EventsEmit("quit")}). A tip informs the user that the Escape key (shortcut) performs the same action, as we already explained.

The reset button calls a function that displays a popup window:

/* Setting.svelte */

...
    const showAlert = () => {
        let data: string[] = [
            `${$_("alert_delete_all")}`,
            `${$_("alert_confirm_deleting")}`,
        ];
        showWarning(data).then((result) => {
            if (result.value) {
                Drop().then(() => push("/"));
                showSuccess($_("alert_delete_confirm_msg"));
            }
        });
    };
...

If the user accepts the action, the Drop binding is called, which cleans all the collections in the DB, and if the promise it returns is resolved, it sends the user to the Login view, showing a modal indicating the success of the action.

The other two actions that remain are similar to each other, so let's look at Import Data.

If the user clicks on the corresponding button, an event is emitted (onclick={() => EventsEmit("import_data")}) which is listened for in the backend. When received, the native Select File dialog box is opened to allow the user to select the backup file. If the user chooses the file, the variable containing the path (fileLocation) will not contain an empty string and this will trigger an event in the backend ("enter_password") which is now listened for in the frontend to, in turn, display a new popup window asking for the master password used when the export was made. Again, the frontend will emit another event ("password") which carries the master password entered by the user. This new event, when received in the backend, executes the ImportDump method of the Db package which performs the work of reading and restoring the data in the DB from the backup file that the user has selected. As a result, a new event ("imported_data") is emitted, which carries the result (successful or unsuccessful) of its execution as attached data. The frontend, when it receives the event, only has to perform 2 tasks:

if the result was successful, set the language that was saved in the backup file and show a modal indicating the success of the action
if for whatever reason the import could not be done, show the error and its cause.

All of this is much easier to see in the code logic than to explain with words 😝:

/* Setting.svelte */

<script lang="ts">
    import { onMount } from "svelte";
    import { fade, fly } from "svelte/transition";
    import BackBtn from "../lib/BackBtn.svelte";
    import Language from "../lib/Language.svelte";
    import { EventsEmit, EventsOn } from "../../wailsjs/runtime/runtime";
    import { Drop, GetLanguage } from "../../wailsjs/go/main/App";
    import { _, locale } from "svelte-i18n";
    import { push } from "svelte-spa-router";
    import {
        showError,
        showQuestion,
        showSuccess,
        showWarning,
    } from "../lib/popups/popups";

    let mounted: boolean = false;

    onMount(() => {
        mounted = true;

        const cancelSavedAs = EventsOn("saved_as", (result: string) => {
            result.includes("error")
                ? showError(result)
                : showSuccess(`${$_("saved_as")} ${result}`);
        });

        const cancelEnterPassword = EventsOn("enter_password", async () => {
            const { value: password } = await showQuestion(
                $_("enter_password"),
            );
            if (password) {
                EventsEmit("password", password);
            }
        });

        const cancelImportedData = EventsOn("imported_data", (res: string) => {
            // console.log(res);
            if (res === "success") {
                GetLanguage().then((result) => {
                    locale.set(result);
                    EventsEmit(
                        "change_titles",
                        $_("app_title"),
                        $_("select_directory"),
                        $_("select_file"),
                    );
                    showSuccess($_("import_successful"));
                });
            } else {
                // `${res.replace(/^.{1}/g, res[0].toUpperCase())} !!`
                res = res.includes("cannot")
                    ? `${$_("backup_error")}`
                    : `${$_("invalid_password")}`;

                showError(res);
            }
        });

        // canceling listeners
        return () => {
            cancelSavedAs();
            cancelEnterPassword();
            cancelImportedData();
            // console.log("CANCELING LISTENERS");
        };
    });

    const showAlert = () => {
        let data: string[] = [
            `${$_("alert_delete_all")}`,
            `${$_("alert_confirm_deleting")}`,
        ];
        showWarning(data).then((result) => {
            if (result.value) {
                Drop().then(() => push("/"));
                showSuccess($_("alert_delete_confirm_msg"));
            }
        });
    };
</script>
...

It is worth mentioning that the Wails runtime function that registers listeners on the frontend (EventsOn) returns a function, which when called cancels said listener. It is convenient to cancel said listeners when the component is destroyed. Similarly to React the onMount hook can "clean up" said listeners by making them return a cleanup function that, in this case, will call all the functions returned by EventsOn that we have taken the precaution of saving in separate variables:

/* Setting.svelte */

...
        // canceling listeners
        return () => {
            cancelSavedAs();
            cancelEnterPassword();
            cancelImportedData();
        };
...

To finish this review of the frontend part of our application, it only remains to say something about the About component. This has little logic since it is limited to displaying information about the application as is usual in an about. It should be said, however, that, as we can see, the view shows a link to the application repository. Obviously, in a normal web page an anchor tag (<a>) would make us navigate to the corresponding link, but in a desktop application this would not happen if Wails did not have a specific function (BrowserOpenURL) for this in its runtime:

/* About.svelte */

...

<a
    onclick={() => BrowserOpenURL("https://github.com/emarifer/Nu-i-uita")}
    class="text-xs font-medium hover:text-sky-500 ease-in duration-300 -m-4"
    href="http://"
    target="_blank"
    rel="noopener noreferrer"
>
    https://github.com/emarifer/Nu-i-uita
</a>

...

III - A few words about building the Wails app

If you want to build the application executable by packaging everything, including the application icon and all assets (fonts, images, etc.) just run the command:

$ wails build

This will build the binary into the build/bin folder. However, for choosing other build options or performing cross-compiling, you may want to take a look at the Wails CLI documentation.

For this application, I think I already mentioned it in the first part of this series, I have only focused on the compilation for Windows and Linux. To perform these tasks (which, due to testing, are repetitive) in a comfortable way I have created some small scripts and a Makefile that "coordinates" them.

The make create-bundles command creates for the Linux version a .tar.xz compressed file with the application and a Makefile that acts as an 'installer' that installs the executable, a desktop entry to create an entry in the Start Menu and the corresponding application icon. For the Windows version, the binary is simply compressed as a .zip inside a folder called dist/.However, if you prefer a cross-platform automated build, Wails has a Github Actions that allows you to upload (default option) the generated artifacts to your repository.

Note that if you use the make create-bundles command when running it, it will call the Wails commands wails build -clean -upx (in the case of Linux) or wails build -skipbindings -s -platform windows/amd64 -upx (in the case of Windows). The -upx flag refers to the compression of the binary using the UPX utility that you should have installed on your computer. Part of the secret of the small size of the executable is due to the magnificent compression job that this utility does.

Finally, note that the build scripts automatically add the current repository tag to the About view and after the build restore its value to the default (DEV_VERSION).

Phew! These 2 posts ended up being longer than I thought! But I hope you liked them and, above all, that they help you think about new projects. Learning something in programming works like that…

Remember that you can find all the application code in this GitHub repository.

I'm sure I'll see you in other posts. Happy coding 😀!!

A minimalist password manager desktop app: a foray into Golang's Wails framework (Part 1)

Enrique Marín — Thu, 19 Dec 2024 12:24:33 +0000

I - Why develop desktop applications today?

This is a question that all developers have asked themselves, especially if they come from the webdev world: "If I can run almost anything that will render in the browser and serve almost any purpose I want, who would need to download our application and run it on their computer?". But aside from the obvious requirement of the work we are doing (for ourselves or for a company, e.g. being able to make use of all the OS features, better performance, offline capabilities, improved security and integration, etc.), there is the experience that we as developers gain from touching new aspects of programming that will always enrich us.

If you are passionate about Golang, like me, and you have developed backend in this language, but you have also done frontend with HTML, CSS and JavaScript (or some of its frameworks) this post is for you, because without needing to learn a new technology you are more than capable of creating desktop applications.

II - The answer is called Wails

Chances are you already know Electron or Tauri. Both use web technologies for the frontend; the first one uses JavaScript (or rather, NodeJs) in its backend, and the second one uses Rust. But both have more or less notable drawbacks. Electron apps have very large binaries (because they package an entire Chromium browser) and consume a lot of memory. Tauri apps improve these aspects (among other things, because they use WebView2 [Windows]/WebKit [macOS & Linux] instead of Chromium), but the binary is still relatively large and their compilation times are… are those of Rust 😰 (not to mention their learning curve, although I love Rust, I really mean it 😀).

By using Wails, you get the best of all these worlds of desktop application development with web technologies that I just described, plus all the advantages that come with using Go:

easy to learn and extraordinarily expressive language,
fast execution and, above all, fast compilation,
"out of the box" cross-compilation,
small binaries that run with moderate memory consumption (as an example, the application we will develop here would be ~100 Mb with Electron and with other native GUI frameworks like Fyne, ~20 Mb; with Wails it is only 4 Mb 😀!!),
and the possibility to use the web framework of your choice (even Vanilla JS) with which you get the ease of designing "modern" UIs that improve the user experience.

Yes, if I wanted to use Go to create desktop applications there are other possibilities (native or not). I would mention Fyne and go-gtk. Fyne is a GUI framework that allows the creation of native apps easily and although they may have an elegant design, the capabilities of the framework are somewhat limited or require a great effort from the developer to achieve the same thing that other tools and/or languages would allow you to do easily. I can say the same about go-gtk, which is a Go binding for GTK: yes, it is true that you will get native applications whose limits will be in your own capabilities, but getting into the GTK library is like going on an expedition through the jungle 😰…

III - An approach to Wails: Nu-i uita - Minimalist password manager

First of all, for those who are wondering what Nu-i uita means: in Romanian it roughly means "don't forget them". I thought it was an original name...

You can see the entire code of the application in this GitHub repository. If you want to try it out right away, you can download the executable from here (for Windows & Linux).

I will briefly describe how the application works: the user logs in for the first time and the login window asks him to enter a master password. This is saved encrypted using the password itself as the encryption key. This login window leads to another interface where the user can list the saved passwords for the corresponding websites and usernames used (you can also search in this list by username or website). You can click on each item in the list and see its details, copy it to the clipboard, edit it or delete it. Also, when adding new items it will encrypt your passwords using the master password as the key. In the configuration window you can choose the language of your choice (currently only English and Spanish), delete all stored data, export it or import it from a backup file. When importing data, the user will be asked for the master password that was used when the export was performed, and the imported data will now be saved and encrypted with the current master password. Subsequently, whenever the user logs back into the application, he or she will be prompted to enter the current master password.

I am not going to dwell on the requirements you need to use Wails because it is well explained in its excellent documentation. In any case, it is essential that you install its powerful CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest), which allows you to generate a scaffolding for the application, hot-reload when editing code, and build executables (including cross-compilation).

The Wails CLI allows you to generate projects with a variety of frontend frameworks, but for some reason the creators of Wails seem to prefer Svelte... because it's the first option they mention. When you use the command wails init -n myproject -t svelte-ts, you generate a project with Svelte3 and TypeScript.

If for some reason you prefer to use Svelte5 with its new runes system feature, I have created a bash script that automates the generation of projects with Svelte5. In this case, you will also need to have the Wails CLI installed.

The features of the application I mentioned above constitute the requirements of any todoapp (which is always a good way to learn something new in programming), but here we add a plus of features (e.g. both in the backend, the use of symmetric encryption, and in the frontend, use of Internationalization) that make it a little more useful and instructive than a simple todoapp.

Ok, enough of the introduction, so let's get down to business 😀.

IV - Wails project structure: an overview of how this framework works

If you choose to create a Wails project with Svelte+Typescript with the CLI by running the command wails init -n myproject -t svelte-ts (or with the bash script I created and that I already told you about before, that generates Wails projects with Svelte5) you will have a directory structure very similar to this one:

.
├── app.go
├── build
│   ├── appicon.png
│   ├── darwin
│   │   ├── Info.dev.plist
│   │   └── Info.plist
│   ├── README.md
│   └── windows
│       ├── icon.ico
│       ├── info.json
│       ├── installer
│       │   ├── project.nsi
│       │   └── wails_tools.nsh
│       └── wails.exe.manifest
├── frontend
│   ├── index.html
│   ├── package.json
│   ├── package.json.md5
│   ├── package-lock.json
│   ├── postcss.config.js
│   ├── README.md
│   ├── src
│   │   ├── App.svelte
│   │   ├── assets
│   │   │   ├── fonts
│   │   │   │   ├── nunito-v16-latin-regular.woff2
│   │   │   │   └── OFL.txt
│   │   │   └── images
│   │   │       └── logo-universal.png
│   │   ├── lib
│   │   │   ├── BackBtn.svelte
│   │   │   ├── BottomActions.svelte
│   │   │   ├── EditActions.svelte
│   │   │   ├── EntriesList.svelte
│   │   │   ├── Language.svelte
│   │   │   ├── popups
│   │   │   │   ├── alert-icons.ts
│   │   │   │   └── popups.ts
│   │   │   ├── ShowPasswordBtn.svelte
│   │   │   └── TopActions.svelte
│   │   ├── locales
│   │   │   ├── en.json
│   │   │   └── es.json
│   │   ├── main.ts
│   │   ├── pages
│   │   │   ├── About.svelte
│   │   │   ├── AddPassword.svelte
│   │   │   ├── Details.svelte
│   │   │   ├── EditPassword.svelte
│   │   │   ├── Home.svelte
│   │   │   ├── Login.svelte
│   │   │   └── Settings.svelte
│   │   ├── style.css
│   │   └── vite-env.d.ts
│   ├── svelte.config.js
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   ├── tsconfig.node.json
│   ├── vite.config.ts
│   └── wailsjs
│       ├── go
│       │   ├── main
│       │   │   ├── App.d.ts
│       │   │   └── App.js
│       │   └── models.ts
│       └── runtime
│           ├── package.json
│           ├── runtime.d.ts
│           └── runtime.js
├── go.mod
├── go.sum
├── internal
│   ├── db
│   │   └── db.go
│   └── models
│       ├── crypto.go
│       ├── master_password.go
│       └── password_entry.go
├── LICENSE
├── main.go
├── Makefile
├── README.md
├── scripts
└── wails.json

What you just saw is the finished application structure. The only difference with the one generated by the Wails CLI is that with it you will get the scaffolding of a Wails application with a Svelte3+TypeScript frontend, and with my script, in addition to having Svelte5, Tailwindcss+Daisyui is integrated.

But let's see how a Wails application works in general and at the same time particularizing the explanation for our case:

As Wails documentation says: "A Wails application is a standard Go application, with a webkit frontend. The Go part of the application consists of the application code and a runtime library that provides a number of useful operations, like controlling the application window. The frontend is a webkit window that will display the frontend assets". In short, and as we probably already know if we have created desktop applications with web technologies, very briefly explained, the application consists of a backend (in our case written in Go) and a frontend whose assets are managed by a Webkit window (in the case of Windows OS, Webview2), something like the essence of a web server/browser that serves/renders the frontend assets.

The main application in our specific case in which we want the application to be able to run on both Windows and Linux consists of the following code:

/* main.go */

package main

import (
    "embed"

    "github.com/wailsapp/wails/v2"
    "github.com/wailsapp/wails/v2/pkg/options"
    "github.com/wailsapp/wails/v2/pkg/options/assetserver"
    "github.com/wailsapp/wails/v2/pkg/options/linux"
)

//go:embed all:frontend/dist
var assets embed.FS

//go:embed build/appicon.png
var icon []byte

func main() {
    // Create an instance of the app structure
    app := NewApp()

    // Create application with options
    err := wails.Run(&options.App{
        // Title:         "Nu-i uita • minimalist password manager",
        Width:         450,
        Height:        300,
        DisableResize: true,
        AssetServer: &assetserver.Options{
            Assets: assets,
        },
        BackgroundColour: &options.RGBA{R: 27, G: 38, B: 54, A: 1},
        OnStartup:        app.startup,
        OnBeforeClose:    app.beforeClose,
        Bind: []interface{}{
            app,
        },
        // Linux platform specific options
        Linux: &linux.Options{
            Icon: icon,
            // WindowIsTranslucent: true,
            WebviewGpuPolicy: linux.WebviewGpuPolicyNever,
            // ProgramName:         "wails",
        },
    })

    if err != nil {
        println("Error:", err.Error())
    }
}

The first thing we need to do is instantiate a struct (with the NewApp function), which we agreed to call App, which must have a field with a Go Context. Then, wails' Run method is the one that starts the application. We need to pass it a series of options. One of these mandatory options is the assets. Once Wails compiles the frontend, it generates it in the "frontend/dist" folder. Using the //go:embed all:frontend/dist directive (that magical feature of Go) we can embed our entire frontend in the final executable. In the case of Linux, if we want to embed the application icon, we must also use the //go:embed directive.

I won't go into the rest of the options, which you can check in the documentation. I'll just say two things related to the options. The first is that the title that appears in the application's title bar can be set here as an option, but in our application, where the user can choose the language they want, we will set them (using the Wails runtime) when we receive the language change event that the user may make. We'll see this later.

The second important option-related issue is the Bind option. The documentation explains its meaning very well: "The Bind option is one of the most important options in a Wails application. It specifies which struct methods to expose to the frontend. Think of structs like controllers in a traditional web application." Indeed: the public methods of the App structure, which are those that expose the backend to the frontend, perform the magic of "connecting" Go with JavaScript. Those public methods of said struct are converted into JavaScript functions that return a promise by the compilation performed by Wails.

The other important form of communication between the backend and the frontend (which we use effectively in this application) is events. Wails provides an event system, where events can be emitted or received by Go or JavaScript. Optionally, data can be passed with the events. Studying the way we use events in our application will lead us to analyze the struct App:

/* app.go */

package main

import (
    "context"

    "github.com/emarifer/Nu-i-uita/internal/db"
    "github.com/emarifer/Nu-i-uita/internal/models"
    "github.com/wailsapp/wails/v2/pkg/runtime"
)

// App struct
type App struct {
    ctx               context.Context
    db                *db.Db
    selectedDirectory string
    selectedFile      string
}

// NewApp creates a new App application struct
func NewApp() *App {
    db := db.NewDb()

    return &App{db: db}
}

// startup is called when the app starts. The context is saved
// so we can call the runtime methods
func (a *App) startup(ctx context.Context) {
    var fileLocation string
    a.ctx = ctx

    runtime.EventsOn(a.ctx, "change_titles", func(optionalData ...interface{}) {
        if appTitle, ok := optionalData[0].(string); ok {
            runtime.WindowSetTitle(a.ctx, appTitle)
        }
        if selectedDirectory, ok := optionalData[1].(string); ok {
            a.selectedDirectory = selectedDirectory
        }
        if selectedFile, ok := optionalData[2].(string); ok {
            a.selectedFile = selectedFile
        }
    })

    runtime.EventsOn(a.ctx, "quit", func(optionalData ...interface{}) {
        runtime.Quit(a.ctx)
    })

    runtime.EventsOn(a.ctx, "export_data", func(optionalData ...interface{}) {
        d, _ := runtime.OpenDirectoryDialog(a.ctx, runtime.
            OpenDialogOptions{
            Title: a.selectedDirectory,
        })

        if d != "" {
            f, err := a.db.GenerateDump(d)
            if err != nil {
                runtime.EventsEmit(a.ctx, "saved_as", err.Error())
                return
            }
            runtime.EventsEmit(a.ctx, "saved_as", f)
        }
    })

    runtime.EventsOn(a.ctx, "import_data", func(optionalData ...interface{}) {
        fileLocation, _ = runtime.OpenFileDialog(a.ctx, runtime.OpenDialogOptions{
            Title: a.selectedFile,
        })

        // fmt.Println("SELECTED FILE:", fileLocation)
        if fileLocation != "" {
            runtime.EventsEmit(a.ctx, "enter_password")
        }
    })

    runtime.EventsOn(a.ctx, "password", func(optionalData ...interface{}) {
        // fmt.Printf("MY PASS: %v", optionalData...)
        if pass, ok := optionalData[0].(string); ok {
            if len(fileLocation) != 0 {
                err := a.db.ImportDump(pass, fileLocation)
                if err != nil {
                    runtime.EventsEmit(a.ctx, "imported_data", err.Error())
                    return
                }
                runtime.EventsEmit(a.ctx, "imported_data", "success")
            }
        }
    })
}

// beforeClose is called when the application is about to quit,
// either by clicking the window close button or calling runtime.Quit.
// Returning true will cause the application to continue, false will continue shutdown as normal.
func (a *App) beforeClose(ctx context.Context) (prevent bool) {
    defer a.db.Close()

    return false
}

...

The first thing we see is the struct App which has a field that stores a Go Context, needed by Wails, and a pointer to the struct Db (related to the database, as we will see). The other 2 properties are strings that we configure so that the native dialogs (managed by the backend) present titles according to the language selected by the user. The function that acts as the constructor (NewApp) for App simply creates the pointer to the database struct.

Next we see 2 methods required by the options that Wails needs: startup and beforeClose, which we will pass respectively to the OnStartup and OnBeforeClose options. By doing so they will automatically receive a Go Context. beforeClose simply closes the connection to the database when closing the application. But startup does more. First, it sets the context it receives in its corresponding field. Second, it registers a series of event listeners in the backend that we will need to trigger a series of actions.

In Wails all event listeners have this signature:

EventsOn(
    ctx context.Context,
    eventName string,
    callback func(optionalData ...interface{}),
) func()

That is, it receives the context (the one we save in the ctx field of App), the name of the event (which we will have established in the frontend) and a callback that will execute the action we need, and which in turn can receive optional parameters, of type any or empty interface (interface{}), which is the same, so we will have to make type assertions.

Some of the listeners we declare have nested event emitters declared within them that will be received on the frontend and trigger certain actions there. His signature looks like this:

EventsEmit(
    ctx context.Context,
    eventName string,
    optionalData ...interface{},
)

I'm not going to go into detail about what these listeners do, not just for brevity but also because Go is expressive enough that you can tell what they do just by reading the code. I'll just explain a few of them. The "change_titles" listener expects to receive an event with that name. This event is triggered when the user changes the interface language, changing the title of the application window's title bar to the value received by the listener itself. We use the Wails runtime package to achieve this. The event also receives the titles of the "Select Directory" and "Select File" dialogs which are stored in separate properties of the App struct to be used when needed. As you can see, we need this event because these "native" actions need to be performed from the backend.

Special mention for the listeners "import_data" and "password" which are, so to speak, chained. The first one ("import_data"), when received, triggers the opening of a dialog box with the runtime.OpenFileDialog method. As we can see, this method receives among its options the title to be displayed, which is stored in the selectedFile field of the App struct, as we already explained. If the user selects a file and, therefore, the fileLocation variable is not empty, an event is emitted (called "enter_password") that is received in the frontend to show a popup in which the user is asked to enter the master password that he used when he made the export. When the user does so, the frontend emits an event ("password"), which we receive in our backend listener. The data received (the master password) and the path to the backup file are used by a method of the Db struct, which represents the database (ImportDump). Depending on the result of the execution of said method, a new event ("imported_data") is emitted that will trigger a pop-up window in the frontend with the successful or failed result of the import.

As we can see, Wails events are a powerful and effective way of communication between the backend and the frontend.

The rest of the methods of the App struct are nothing more than the methods that the backend exposes to the frontend, as we already explained, and which are basically the CRUD operations with the database and which, therefore, we explain below.

V - Backend: the plumbing of the app

For this backend part I was inspired (making some modifications) by this post (here on DEV.to) by vikkio88 and his repo of a password manager, that he first created with C#/Avalonia and then adapted to use Go/Fyne (Muscurd-ig).

The "lowest level" part of the backend is the one related to password encryption. The most essential are these 3 functions:

/* crypto.go */

func keyfy(password string) []byte {
    // this is to pad the password to make it 32
    password = fmt.Sprintf("%032s", password)

    key := ""
    for i := 0; i < 32; i++ {
        key += string(password[i])
    }

    return []byte(key)
}

func encrypt(plaintext string, key []byte) ([]byte, error) {
    aes, err := aes.NewCipher(key)
    if err != nil {
        return nil, err
    }

    gcm, err := cipher.NewGCM(aes)
    if err != nil {
        return nil, err
    }

    // We need a 12-byte nonce for GCM (modifiable if you use cipher.NewGCMWithNonceSize())
    // A nonce should always be randomly generated for every encryption.
    nonce := make([]byte, gcm.NonceSize())
    _, err = rand.Read(nonce)
    // https://cs.opensource.google/go/go/+/refs/tags/go1.23.4:src/crypto/rand/rand.go;l=26
    if err != nil {
        return nil, err
    }

    // ciphertext here is actually nonce+ciphertext
    // So that when we decrypt, just knowing the nonce size
    // is enough to separate it from the ciphertext.
    ciphertext := gcm.Seal(nonce, nonce, []byte(plaintext), nil)

    return ciphertext, nil
}

func decrypt(ciphertext []byte, key []byte) (string, error) {
    aes, err := aes.NewCipher(key)
    if err != nil {
        return "", err
    }

    gcm, err := cipher.NewGCM(aes)
    if err != nil {
        return "", err
    }

    // Since we know the ciphertext is actually nonce+ciphertext
    // And len(nonce) == NonceSize(). We can separate the two.
    // Therefore, we are sure that len(ciphertext) < nonceSize
    // will never be true.
    nonceSize := gcm.NonceSize()
    nonce, ciphertext := ciphertext[:nonceSize], ciphertext[nonceSize:]

    plaintext, err := gcm.Open(nil, nonce, ciphertext, nil)
    if err != nil {
        return "", err
    }

    return string(plaintext), nil
}

I won't go into the details of symmetric encryption with AES in Go. Everything you need to know is well explained in this post, here on DEV.to.

AES is a block cipher algorithm that takes a fixed-size key and fixed-size plaintext, and returns fixed-size ciphertext. Because the block size of AES is set to 16 bytes, the plaintext must be at least 16 bytes long. Which causes a problem for us since we want to be able to encrypt/decrypt arbitrary sized data. To solve the problem of minimum plaintext block size the block cipher modes exist. Here I use GCM mode because it is one of the most widely adopted symmetric block cipher modes. GCM requires an IV (initialization vector [array]) which must always be randomly generated (the term used for such an array is nonce).

Basically, the encrypt function takes a plaintext to encrypt and a secret key that will always be 32 bytes long and generates an AES encryptor with that key. With that encryptor we generate a gcm object that we use to create a 12-byte initialization vector (nonce). The Seal method of the gcm object allows us to "join" and encrypt the plaintext (as a slice of bytes) with the vector nonce and finally convert its result back into a string.

The decrypt function does the opposite: the first part of it is equal to encrypt, then since we know that the ciphertext is actually nonce+ciphertext, we can split the ciphertext into its 2 components. The NonceSize method of the gcm object always results in "12" (which is the length of the nonce), and thus we split the byte slice at the same time as we decrypt it with the Open method of the gcm object. Finally, we convert the result into a string.

The keyfy function ensures that we have a 32-byte secret key (by padding it with "0" to reach that length). We will see that in the frontend we make sure that the user does not enter characters of more than one byte (non-ASCII characters), so that the result of this function is always 32 bytes long.

The rest of the code in this file is essentially responsible for encoding/decoding to base64 the input/output of the functions described above.

To store all the application data we use cloverDB. It is a lightweight and embedded document-oriented NoSQL Database, similar to MongoDB. One of the features of this database is that when records are saved, they are assigned an ID (by default, the field is designated as _id, a bit like what happens in MongoDB) which is a uuid string (v4). So if we want to sort the records by entry order, we must assign them a timestamp when they are stored.

Based on these facts, we will create our models and their associated methods (master_password.go & password_entry.go):

/* master_password.go */

type MasterPassword struct {
    id    string
    Value string `clover:"value"`
    clear string
}

/* password_entry.go */

type PasswordEntry struct {
    Id        string
    Website   string
    Username  string
    Password  string
    Timestamp int64
}

...

// PasswordEntryDTO represents the object that will be saved in the database.
// This struct is used so that the change of state that means
// the passage from an unencrypted password to an encrypted one
// is "detected" by the type system, making it impossible
// to save objects with an unencrypted password in the database.
type PasswordEntryDTO struct {
    Id        string
    Website   string `clover:"website"`
    Username  string `clover:"username"`
    Password  string `clover:"password"`
    Timestamp int64  `clover:"timestamp"`
}

MasterPassword has a private field (clear) that is not stored/retrieved (hence no clover tag) in/from the database, i.e. it only lives in memory and is not stored on disk. This property is the unencrypted master password itself and will be used as an encryption key for password entries. This value is stored by a setter on the MasterPassword object or set (by a callback) as a non-exported (private) field in the struct Db of the package of the same name (db.go). For password inputs we use 2 structs, one that does not have the encrypted password and another one in which the password is already encrypted, which is the object that will actually be stored in the database (similar to a DTO, data transfer object). The encryption/decryption methods of both structs internally use a Crypto object, which has a property with the encryption key (which is the master password converted to a 32-byte long slice):

/* crypto.go */

type Crypto struct {
    key []byte
}

func newCrypto(passkey string) Crypto {
    key := keyfy(passkey)

    return Crypto{key}
}

Master Password has 3 methods that play an important role in data saving/recovery:

/* master_password.go */

func (m *MasterPassword) GetCrypto() Crypto {

    return newCrypto(m.clear)
}

func (m *MasterPassword) SetClear(clear string) {
    m.clear = clear
}

func (m *MasterPassword) Check(value string, cb func(v string)) bool {
    c := newCrypto(value)

    v, err := c.decryptB64(m.Value)
    if err != nil {
        return false
    }

    if v == value {
        cb(value)
        return true
    }

    return false
}

GetCrypto allows you to get the current instance of the Crypto object so that the db.go package can encrypt/decrypt password entries. SetClear is the setter we mentioned earlier and Check is the function that verifies if the master password entered by the user is correct; as we can see, in addition to the password, it takes as an argument a callback, which depending on the case will be the aforementioned setter (when we import data from the backup file) or the SetMasterPassword method of the db.go package that sets the value in the private field of the Db struct when the user logs in.

I'm not going to explain in detail all the methods of the db.go package because most of its code is related to the way of working with cloverDB, which you can check in its documentation, although I have already mentioned some important things that will be used here.

/* db.go */
type Db struct {
    clover   *c.DB
    cachedMp *models.MasterPassword
}

...

func setupCollections(db *c.DB) {
    db.CreateCollection(language_collection)
    db.CreateCollection(master_password_collection)
    db.CreateCollection(password_entry_collection)
}

func NewDb() *Db {
    // It is necessary to create the folder that
    // will contain the DB storage files
    err := os.MkdirAll(db_files, os.ModePerm)
    if err != nil {
        panic(err)
    }
    db, err := c.Open(db_files)
    if err != nil {
        panic(err)
    }

    setupCollections(db)

    return &Db{clover: db}
}

func (db *Db) Close() error {
    return db.clover.Close()
}

func (db *Db) GetLanguageCode() string {
    doc, err := db.clover.FindFirst(query.NewQuery(language_collection))
    if err != nil {
        panic(err)
    }
    if doc == nil {
        return ""
    }

    if code, ok := doc.Get("code").(string); ok {
        return code
    }

    return ""
}

func (db *Db) SaveLanguageCode(code string) {
    db.clover.Delete(query.NewQuery(language_collection))
    doc := d.NewDocument()
    doc.Set("code", code)
    _, err := db.clover.InsertOne(language_collection, doc)
    if err != nil {
        panic(err)
    }
}

First we have the struct that will store a pointer to the cloverDB instance. It also stores a pointer to a "full" instance of the MasterPassword struct. "Full" here means that it stores both the encrypted master password (meaning it exists in the database and is therefore the current master password) and the unencrypted master password, which will be used for encryption of the password entries. Next we have setupCollections, NewDb, and Close, which are functions and methods to setup the database when the application is started and closed. cloverDB does not automatically create a storage file/directory when instantiated with the Open method, instead we have to create it manually. Finally, GetLanguageCode and SaveLanguageCode are methods to retrieve/save the application language selected by the user. Since the selected language code is a small string ("en" or "es"), for simplicity we don't use a struct to store it: for example, to retrieve the language code from the collection (cloverDB works with "documents" and "collections", similar to MongoDB), we simply pass the key under which it is stored ("code") and make a type assertion.

When the user logs in for the first time, the master password is saved in the database: this value (unencrypted) is set in the clear field of the MasterPassword object, which also stores the already encrypted password, and is saved in the Db struct:

/* db.go */

...

func (db *Db) InsertMasterPassword(mpStr string) string {
    mp := models.NewMasterPassword(mpStr)
    doc := d.NewDocumentOf(mp)
    id, err := db.clover.InsertOne(master_password_collection, doc)
    if err != nil {
        panic(err)
    }
    mp.SetClear(mpStr) // ⇐ ⇐
    db.cachedMp = &mp // ⇐ ⇐

    return id
}

...

The master password recovery is done twice when starting the application:

to check if there is a master password stored in the database.
to obtain a MasterPassword instance and to be able to use its Check method and verify that the password provided by the user is correct.

In both cases, the RecoverMasterPassword method is called, which only if there is a master password stored will set the instance in the cachedMp field of the Db struct:

/* db.go */

...

func (db *Db) RecoverMasterPassword() models.MasterPassword {
    doc, err := db.clover.FindFirst(query.NewQuery(master_password_collection))
    if err != nil {
        panic(err)
    }
    if doc == nil {
        return models.MasterPassword{}
    }

    var mp models.MasterPassword
    err = doc.Unmarshal(&mp)
    if err != nil {
        panic(err)
    }
    if mp.Value != "" { // ⇐ ⇐
        db.cachedMp = &mp // ⇐ ⇐
    }

    return mp
}

...

Next, there are 2 small but important pieces of code:

SetMasterPassword, which, as I mentioned, is used as a callback to the Check method of the MasterPassword object and will set the unencrypted master password in the cachedMp field of the Db struct only if that field is not nil.
getCryptoInstance, which will return an instance of the Crypto object only if cachedMp is not nil. Otherwise, it will panic the application: although in theory this situation cannot happen if the user is authenticated in the application, but for security reasons we terminate the application if it happens:

/* db.go */

...

func (db *Db) SetMasterPassword(v string) {
    if db.cachedMp != nil {
        db.cachedMp.SetClear(v) // ⇐ ⇐
    }
}

func (db *Db) getCryptoInstance() *models.Crypto {
    if db.cachedMp == nil {
        panic("crypto instance is nil") // ⇐ ⇐
    }
    instance := db.cachedMp.GetCrypto()

    return &instance
}

...

Beyond the usual CRUD operations typical of any todoapp, we have other functions or methods to comment on:

/* db.go */

...

func (db *Db) loadManyPasswordEntry(docs []*d.Document) []models.PasswordEntry {
    crypto := db.getCryptoInstance()
    result := make([]models.PasswordEntry, len(docs))
    for i, doc := range docs {
        dto := loadPasswordEntryDTO(doc)
        result[i] = dto.ToPasswordEntry(crypto)
    }

    return result
}

func loadPasswordEntryDTO(doc *d.Document) *models.PasswordEntryDTO {
    var dto models.PasswordEntryDTO
    doc.Unmarshal(&dto)
    dto.Id = doc.ObjectId()

    return &dto
}

func loadManyPasswordEntryDTO(docs []*d.Document) []models.PasswordEntryDTO {
    result := make([]models.PasswordEntryDTO, len(docs))
    for i, doc := range docs {
        result[i] = *loadPasswordEntryDTO(doc)
    }

    return result
}

...

loadPasswordEntryDTO is a helper function that creates a PasswordEntryDTO object from a single document obtained from cloverDB. loadManyPasswordEntryDTO does the same, but from a slice of cloverDB documents, generating a slice of PasswordEntryDTO. Finally, loadManyPasswordEntry does the same as loadManyPasswordEntryDTO but also decrypts documents obtained from cloverDB from an instance of the Crypto object generated by the getCryptoInstance method.

Finally, among the methods not related to CRUD, we have those used in the export/import of data:

/* db.go */

...

type DbDump struct {
    Mp           string
    Pwds         []models.PasswordEntryDTO
    LanguageCode string
}

...

func (db *Db) GenerateDump(baseFolder string) (string, error) {
    dumpDate := time.Now().Format("200601021504")
    fileName := filepath.Join(baseFolder, fmt.Sprintf("pwds_%s.%s", dumpDate, dump_file_extension))
    f, err := os.Create(fileName)
    if err != nil {
        return "", err
    }
    defer f.Close()

    mp := db.RecoverMasterPassword()
    pwDtosDocs, _ := db.clover.FindAll(
        query.NewQuery(password_entry_collection),
    )
    pwds := loadManyPasswordEntryDTO(pwDtosDocs)
    lc := db.GetLanguageCode()
    data := DbDump{
        mp.Value,
        pwds,
        lc,
    }

    encoder := gob.NewEncoder(f)
    errEncoding := encoder.Encode(data)

    return fileName, errEncoding
}

func (db *Db) ImportDump(password string, dumpFileLocation string) error {
    file, err := os.Open(dumpFileLocation)
    if err != nil {
        return err
    }
    defer file.Close()

    decoder := gob.NewDecoder(file)
    var importedDump DbDump
    err = decoder.Decode(&importedDump)
    if err != nil {
        return errors.New("cannot read data dump")
    }

    mp := models.NewMasterPasswordFromB64(importedDump.Mp)
    if !mp.Check(password, mp.SetClear) {
        return errors.New("invalid dump password")
    }
    cryptoImport := mp.GetCrypto()

    for _, dto := range importedDump.Pwds {
        pe := dto.ToPasswordEntry(&cryptoImport)
        db.InsertPasswordEntry(pe)
    }

    db.SaveLanguageCode(importedDump.LanguageCode)

    return nil
}

GenerateDump uses the DbDump struct which will be the object saved in the backup file. Generates a file handler whose name is a string formed by the path of the directory selected by the user (which we pass as a parameter), a date format and an ad hoc extension. Then we create a DbDump instance with the encrypted master password, the DTOs slice (with its corresponding passwords also encrypted) and the language code saved by the user in the database. This object is finally encoded in binary by the Golang gob package in the file we have created, returning the name of the file to the UI to inform the user of its successful creation.

On the other hand, ImportDump takes as arguments the master password that the UI asks the user for, which is the password in effect when the export was performed, and the path to the backup file. Now, it decrypts the selected file using the DbDump structure and then obtains a MasterPassword instance from the encrypted master password stored in DbDump. In the next step, we verify that the password supplied by the user is correct, while setting the clear field in the MasterPassword instance:

if !mp.Check(password, mp.SetClear /* ⇐ ⇐ */) {
        return errors.New("invalid dump password")
}

Finally, we get an instance of the Crypto object from the MasterPasword instance created in the previous step and do 2 things in the following loop:

We decrypt the DTOs and convert them into PasswordEntry with the already decrypted password and
We insert the PasswordEntry's into the database which will now be encrypted with the new master password.

The last thing we have left is to save the language code in the database.

And that's enough for today, this tutorial has already gotten long 😮‍💨.

In the second part, we will detail the frontend side which, as I said, is made with Svelte.

If you are impatient, as I already told you, you can find all the code in this repo.

See you in the second part. Happy coding 😀!!