% =========================================================================== %
\part{Practical part}

\n{1}{Introduction}

A part of the task of this thesis was to build an actual Password Compromise
Monitoring Tool. Therefore, the development process, the tools and practices
used generally, and with more specificity the outcome are all described in the
following sections. A whole section is dedicated to application architecture,
whereby relevant engineering choices are justified and motifs preceding the
decisions are explained. This part then flows into recommendations for more of
a production deployment and concludes by describing the validation methods
chosen and used to ensure correctness and stability of the program.


\n{2}{Kudos}

The program that has been developed as part of this thesis used and utilised a
great deal of free (as in \textit{freedom}) and open-source software in the
process, either directly or as an outstanding work tool, and the author would
like to take this opportunity to recognise that fact\footnotemark.

In particular, the author acknowledges that this work would not be the same
without:

\begin{itemize}
  \item vim (\url{https://www.vim.org/})
  \item Arch Linux (\url{https://archlinux.org/})
  \item ZSH (\url{https://www.zsh.org/})
  \item kitty (\url{https://sw.kovidgoyal.net/kitty/})
  \item Nix (\url{https://nixos.org/explore.html})
  \item pre-commit (\url{https://pre-commit.com/})
  \item Podman (\url{https://podman.io/})
  \item Go (\url{https://go.dev/})
\end{itemize}

All of the code written has been typed into VIM (\texttt{9.0}), the shell used
to run the commands was ZSH, both running in the author's terminal emulator of
choice, \texttt{kitty}. The development machines ran a recent installation of
\textit{Arch Linux (by the way)} and Fedora 38, both using a
\texttt{6.\{2,3,4\}.x} XanMod variant of the Linux kernel.

\footnotetext{\textbf{Disclaimer:} the author is not affiliated with any of the
projects mentioned on this page.}


\n{1}{Development}

The source code of the project was being versioned since the start, using the
popular and industry-standard git (\url{https://git-scm.com}) source code
management (SCM) tool. Commits were made frequently and, if at all possible,
for small and self-contained changes of code, trying to follow sane commit
message \emph{hygiene}, i.e.\ striving for meaningful and well-formatted commit
messages. The name of the default branch is \texttt{development}, since that is
what the author likes to choose for new projects that are not yet stable (it is
in fact the default in author's \texttt{.gitconfig}).


\n{2}{Commit signing}

Since git allows cryptographically \emph{singing} all commits, it would be
unwise not to take advantage of this. For the longest time, GPG was the only
method available for signing commits in git; however, that is no longer
applicable~\cite{agwagitssh}. These days, it is also possible to both sign and
verify one's git commits (and tags!) using SSH keys, namely those produced by
OpenSSH, which \emph{can} be the same ones that can be used to log in to remote
systems. The author has, of course, not reused the same key pairs that are used
to connect to machines for signing commits. A different, \texttt{Ed25519}
elliptic curve key pairs have been used specifically for signing. Public
components of these keys are enclosed in this thesis as
Appendix~\ref{appendix:signingkeys} for future reference.

The validity of a signature on a particular commit can be viewed with git using
the following commands (the \% sign denotes the shell prompt):

\vspace{\parskip}
\begin{lstlisting}[language=bash, caption={Verifying the signature of a git commit},
label=gitverif, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg}]
    % cd <cloned project dir>
    % git show --show-signature <commit>
    % # alternatively:
    % git verify-commit <commit>
\end{lstlisting}
\vspace*{-\baselineskip}

There is one caveat to this though, git first needs some additional
configuration for the code in Listing~\ref{gitverif} to work as one would
expect. Namely that the public key used to verify the signature needs to be
stored in git's ``allowed signers file'', then git needs to be told where that
file is located using the configuration value
\texttt{gpg.ssh.allowedsignersfile} and finally the configuration value of the
\texttt{gpg.format} field needs to be set to \texttt{ssh}.  Luckily, because
git also allows the configuration values to be local to each repository, both
of the mentioned issues can be solved by running the following commands from
inside the cloned repository:

\vspace{\parskip}
\begin{lstlisting}[language=bash, caption={Prepare allowed signers file and signature format for git},
label=gitsshprep, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg}]
% # set the signature format for the local repository.
% git config --local gpg.format ssh
% # save the public key.
% cat > ./.tmp-allowed_signers \
  <<<'surtur <insert literal surtur pubkey>
  leo <insert literal leo pubkey>'
% # set the allowed signers file path for the local repository.
% git config --local gpg.ssh.allowedsignersfile=./.tmp-allowed_signers
\end{lstlisting}
\vspace*{-\baselineskip}

After the code in Listing~\ref{gitsshprep} is run, everything from the
Listing~\ref{gitverif} should remain applicable for the lifetime of the
repository or until git changes implementation of signature verification. The
git \texttt{user.name} that can be seen on the commits in the \textbf{Author}
field is named after the machine that was used to develop the program, since
the author uses different signing keys on each machine. That way the committer
machine can be determined post-hoc.

For future reference, git has been used in the version \texttt{git version
2.4\{0,1,2\}.x}.


\n{2}{Continuous Integration}

To increase both the author's and public confidence in the atomic changes made
over time, it was attempted to thoroughly \emph{integrate} them using a
continuous integration (CI) service that was plugged into the main source code
repository since the early stages of development. This, of course, was again
self-hosted, including the workers. The tool of choice there was Drone
(\url{https://drone.io}) and the ``docker'' runner (in fact it runs any OCI
container) was used to run the builds.

The way this runner works is that it creates an ephemeral container for every
pipeline step and executes given \emph{commands} inside of it. At the end of
each step the container is discarded, while the repository, which is mounted
into each container's \texttt{/drone/src} is persisted between steps, allowing
it to be cloned only from \emph{origin} only at the start of the pipeline and
then shared for all the following steps, saving bandwidth, time and disk
writes.

The entire configuration used to run the pipelines can be found in a file named
\texttt{.drone.yml} at the root of the main source code repository. The
workflow consists of four pipelines, which are run in parallel. Two main
pipelines are defined to build the frontend assets, the \texttt{pcmt} binary
and run tests on \texttt{x86\_64} GNU/Linux targets, one for each of Arch and
Alpine (version 3.1\{7,8\}). These two pipelines are identical apart from
OS-specific bits such as installing a certain package, etc. For the record,
other OS-architecture combinations were not tested.

A third pipeline contains instructions to build a popular static analysis tool
called \texttt{golangci-lint}, which is sort of a meta-linter, bundling a
staggering amount of linters (linter is a tool that performs static code
analysis and can raise awareness of programming errors, flag potentially buggy
code constructs, or \emph{mere} stylistic errors) - from sources and then
perform the analysis of project's codebase using the freshly built binary. If
the result of this step is successful, a handful of code analysis services get
pinged in the next steps to take notice of the changes to project's source code
and update their metrics, details can be found in the main Drone configuration
file \texttt{.drone.yml} and the configuration for the \texttt{golangci-lint}
tool itself (such as what linters are enabled/disabled and with what settings)
can be found in the root of the repository in the file named
\texttt{.golangci.yml}.

The fourth pipeline focuses on linting the \texttt{Containerfile} and building
the container and pushing in to a public container registry, although the
latter action is only performed on feature branches, \emph{pull request} or
\emph{tag} events.

\obr{Drone CI median build
time}{fig:drone-median-build}{.84}{graphics/drone-median-build}

The median build time as of writing was 1 minute, which includes running all
four pipelines, and that is acceptable. Build times might of course vary
depending on the hardware, for reference, these builds were run on a machine
equipped with a Zen 3 Ryzen 5 5600 CPU with nominal clock times, DDR4 @ 3200
MHz RAM, a couple of PCIe Gen 4 NVMe drives in a mirrored setup (using ZFS) and
a 600 Mbps downlink, software-wise running Arch with an author-flavoured Xanmod
kernel version 6.\{2,3,4\}.x.


\n{2}{Source code repositories}\label{sec:repos}

The git repository containing source code of the \texttt{pcmt} project:\\
\url{https://git.dotya.ml/mirre-mt/pcmt.git}.
The git repository hosting the \texttt{pcmt} configuration schema:\\
\url{https://git.dotya.ml/mirre-mt/pcmt-config-schema.git}.
The repository containing the \LaTeX{} source code of this thesis:\\
\url{https://git.dotya.ml/mirre-mt/masters-thesis.git}.

All the pertaining source code was published in repositories on a publicly
available git server operated by the author, the reasoning \emph{pro}
self-hosting being that it is the preferred way of guaranteed autonomy over
one's source code, as opposed to large silos owned by big corporations having a
track record of arguably not always deciding with user's best interest in mind
(although recourse has been observed~\cite{ytdl}). When these providers act on
impulse or under public pressure they can potentially (at least temporarily)
disrupt operations of their users. Thus, they are not only beholding their
users to lengthy \emph{terms of service} that \emph{are subject to change at
any given moment}, but also outside factors beyond their control. Granted,
decentralisation can take a toll on discoverability of the project, but that is
only a concern if rapid market penetration is a goal, not when aiming for an
organically grown community.


\n{2}{Toolchain}

Throughout the creation of this work, the \emph{then-current} version of the Go
programming language was used, i.e. \texttt{go1.20}.

To read more on why Go was chosen in particular, see
Appendix~\ref{appendix:whygo}. Equally, Nix and Nix-based tools such as
\texttt{devenv}  have also aided heavily during development, more on those is
written in Appendix~\ref{appendix:whynix}.

\tab{Tool/Library-Usage Matrix}{tab:toolchain}{1.0}{ll}{
  \textbf{Tool/Library} & \textbf{Usage} \\
  Go programming language & program core \\
  Dhall configuration language & program configuration \\
  Echo & HTTP handlers, controllers \\
  ent & ORM using graph-based modelling \\
  pq & Pure-Go Postgres drivers \\
  bluemonday & sanitising HTML \\
  TailwindCSS & utility-first approach to Cascading Style Sheets \\
  PostgreSQL & persistent data storage \\
}

Table~\ref{tab:depsversionmx} contains the names and versions of the most
important libraries and supporting software that were used to build the
application.

\tab{Dependency-Version Matrix}{tab:depsversionmx}{1.0}{ll}{
  \textbf{Name} & \textbf{version} \\
  \texttt{echo} (\url{https://echo.labstack.com/}) & 4.11.1 \\
  \texttt{go-dhall} (\url{https://github.com/philandstuff/dhall-golang}) & 6.0.2\\
  \texttt{ent} (\url{https://entgo.io/}) & 0.12.3 \\
  \texttt{pq} (\url{https://github.com/lib/pq/}) & 1.10.9 \\
  \texttt{bluemonday} (\url{https://github.com/microcosm-cc/bluemonday}) & 1.0.25 \\
  \texttt{tailwindcss} (\url{https://tailwindcss.com/}) & 3.3.0 \\
  \texttt{PostgreSQL} (\url{https://www.postgresql.org/}) & 15.3 \\
}

Additionally, the dependency-version mapping for the Go program can be inferred
from looking at the \texttt{go.mod}'s first \textit{require} block at any point
in time. The same can be achieved for \emph{frontend} by glancing at the
\texttt{package-lock.json} file.


\n{1}{Application architecture}

The application is written in Go and uses \textit{gomodules}. The full name of
the module is \texttt{git.dotya.ml/mirre-mt/pcmt}.

\obr{Application class diagram}{fig:classdiagram}{.79}{graphics/pcmt-class-diagram.pdf}

\n{2}{Package structure}

The source code of the module is organised into smaller, self-contained Go
\emph{packages} appropriately along a couple of domains: logging, core
application, web routers, configuration and settings, etc. In Go, packages are
delimited by folder structure -- each folder can be a package.

Generally speaking, the program aggregates decision points into central places,
such as \texttt{run.go}, which then imports child packages that facilitate each
of the tasks of loading the configuration, connecting to the database and
running migrations, consolidating flag, environment variable and
configuration-based values into canonical \emph{settings} \texttt{struct},
setting up web routes, authenticating requests, or handling \texttt{signals}
and performing graceful shutdowns.

\n{3}{Internal package}

The \texttt{internal} package was not used as of writing, but the author plans
to eventually migrate \emph{internal} logic of the program into the internal
package to prevent accidental imports.


\n{2}{Logging}

The program uses \emph{dependency injection} to share a single logger instance
(the same technique is also used to share the database client). This logger is
then passed around as a pointer, so that the underlying data stays the same or
is modified concurrently for all consumers. As a rule of thumb throughout the
application, every larger \texttt{struct} that needs to be passed around is
passed around as a pointer.

An experimental (note: not anymore, with \texttt{go1.21} it was brought into
Go's \textit{stdlib}) library for \textit{structured} logging \texttt{slog} was
used to facilitate every logging need the program might have.  It supports both
JSON and plain-text logging, which was made configurable by the program. Either
a configuration file value or an environment variable can be used to set this.

There are four log levels available by default (\texttt{DEBUG}, \texttt{INFO},
\texttt{WARNING}, \texttt{ERROR}) and the pertinent library funtions are
parametric. The first parameter of type \texttt{string} is the main message,
that is supplied as a \emph{value} to the \emph{key} named appropriately
`\texttt{msg}', a feature of structured loggers which can later be used for
filtering. Any other parameters need to be supplied in pairs, serving as key
and value, respectively.

This main \texttt{slog} interface has been extended in package
\texttt{slogging} to also provide the formatting functionality of the
\texttt{fmt} standard library package. This was achieved by directly embedding
\texttt{slog.Logger} in a custom \texttt{struct} type named \texttt{Slogger}
and implementing the additional methods on the custom type. The new type that
embeds the original \texttt{slog.Logger} gets to keep its methods thanks to the
composition nature of Go. Thus, common formatting directives like the one seen
in Listing~\ref{goFmtExpression} are now supported with the custom logger, in
addition to anything the base \texttt{slog.Logger} offers.

\vspace{\parskip}
\begin{lstlisting}[language=Go, caption={Example formatting expression supplied
to the logger}, label=goFmtExpression, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg},
otherkeywords={\%s, \%q, \%v},
]
slogger.Debugf("operation %q for user %q completed at %s", op, usr.ID, time.Now())
\end{lstlisting}

Furthermore, functionality was added to support changing the log level at
runtime, which is a convenient feature in certain situations.


\n{2}{Authentication}

The authentication logic is relatively simple and its core has mostly been
isolated into a custom \emph{middleware}. User passwords are hashed using a
secure KDF before ever being sent to the database. The KDF of choice is
\texttt{bcrypt} (with a sane \emph{Cost} of 10), which automatically includes
\emph{salt} for the password and provides ``length-constant'' time hash
comparisons. The author plans to add support for the more modern
\texttt{scrypt} and the state-of-the-art, P-H-C (Password Hashing Competition)
winner algorithm \texttt{Argon2}
(\url{https://github.com/P-H-C/phc-winner-argon2}) for flexibility.

\n{2}{SQLi prevention}

No raw SQL queries are directly used to access the database, thus decreasing
the likelihood of SQL injection attacks. Instead, parametric queries are
constructed in code using a graph-like API of the \texttt{ent} library, which
is attended to in depth in Section~\ref{sec:dbschema}.


\n{2}{Configurability}

Virtually any important value in the program has been made into a configuration
value, so that the operator can customise the experience as needed. A choice of
sane configuration defaults was attempted, which resulted in the configuration
file essentially only needing to contain secrets, unless there is a need to
override the defaults. It is not entirely a \emph{zero-config} situation,
rather a \emph{minimal-config} one. An example can be seen in
Section~\ref{sec:configuration}.

Certain options deemed important enough (this was largely subjective) were
additionally made into command-line \emph{flags}, using the standard library
package \texttt{flags}. Users wishing to display all available options can
append the program with the \texttt{-help} flag, a courtesy of the mentioned
\texttt{flags} package.

\vspace*{-\baselineskip}

\paragraph{\texttt{-host <hostname/IP>} (string)}{Takes one argument and specifies
the hostname, or the address to listen on.}

\vspace*{-\baselineskip}

\paragraph{\texttt{-port <port number>} (int)}{This flag takes one integer
  argument and specifies the port to listen on. The argument is validated at
  program start-up and the program has a fallback built in for the case that
  the supplied value is bogus, such as a string or a number outside the allowed
TCP range $1-65535$.}

\vspace*{-\baselineskip}

\paragraph{\texttt{-printMigration}}{A boolean option that if set, makes the
  program print any \textbf{upcoming} database migrations (based on the current
  state of the database) and exit. The connection string environment variable
  still needs to be set in order to be able connect to the database and perform
the schema \emph{diff}. This option is mainly useful during debugging.}

\vspace*{-\baselineskip}

\paragraph{\texttt{-devel}}{This flag instructs the program to enter
\textit{devel mode}, in which all templates are re-parsed and re-executed upon
each request, and the default log verbosity is changed to level
\texttt{DEBUG}. Should not be used in production.}

\vspace*{-\baselineskip}

\paragraph{\texttt{-import <path/to/file>} (string)}{This option tells the program
  to perform an import of local breach data into program's main database.
  Obviously, the database connection string environment variable also needs to
  be present for this. The option takes one argument that is the path to file
formatted according to the \texttt{ImportSchema} (consult
Listing~\ref{breachImportSchema}). The program prints the result of the import
operation, indicating success or failure, and exits.}

\vspace*{-\baselineskip}

\paragraph{\texttt{-version}}{As could probably be inferred from its name, this
  flag makes the program to print its own version (that has been embedded into
  the binary at build time) and exit. A release binary would print something
  akin to a \emph{semantic versioning}-compliant git tag string, while a
development binary might simply print the truncated commit ID (consult
\texttt{Containerfile} and \texttt{justfile}) of the sources used to build it.}


\n{2}{Embedded assets}

An important thing to mention is embedded assets and templates. Go has multiple
mechanisms to natively embed arbitrary files directly into the binary during
the regular build process. \texttt{embed.FS} from the standard library'
\texttt{embed} package was used to bundle all template files and web assets,
such as images, logos and stylesheets at the module level. These are then
passed around the program as needed, such as to the \texttt{handlers} package.

There is also a toggle in the application configuration (\texttt{LiveMode}),
which instructs the program at start-up to either rely entirely on embedded
assets, or pull live template and asset files from the filesystem. The former
option makes the application more portable as it is wholy self-contained, while
the latter allows for flexibility and customisation not only during
development. Where the program looks for assets and templates in \emph{live
mode} is determined by another configuration options: \texttt{assetsPath} and
\texttt{templatePath}.


\n{2}{Composability}

The core templating functionality was provided by the \texttt{html/template} Go
standard library package. Echo's \texttt{Renderer} interface has been
implemented, so that template rendering could be performed directly using
Echo's built-in facilities in a more ergonomic manner using \texttt{return
c.Render(http.StatusOk, "home.tmpl")}.

\vspace{\parskip}
\begin{lstlisting}[
caption={Conditionaly enabling functionality inside a Go template based on user access level},
label=tmplConditionals, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg},
morekeywords={if,and,end},
]
{{ if and .User .User.IsLoggedIn .User.IsAdmin }}
...
{{ end }}
\end{lstlisting}

Templates used for rendering of the web pages were created in a composable
manner, split into smaller, reusable parts, such as \texttt{footer.tmpl} and
\texttt{head.tmpl}. Those could then be included e.g.\ using \texttt{\{\{
	template "footer.tmpl" \}\}}. Specific functionality is conditionally
executed based on the determined level of access of the user, see
Listing~\ref{tmplConditionals} for reference.

A popular HTML sanitiser \texttt{bluemonday} has been employed to aid with
battling XSS. The program first runs every template through the sanitiser
before rendering it, so that any user-controlled inputs are handled safely.

A dynamic web application should include a CSP configuration. The program
therefore has the ability to calculate the hashes (SHA256/SHA384) of its assets
(scripts, images) on the fly and it is able to use them inside the templates.
This unlocks potentially using third party assets without opening up CSP with
directives like \texttt{script-src 'unsafe-hashes'}. It also means that there
is no need to maintain a set of customised \texttt{head} templates with
pre-computed hashes next to script sources, since the application can perform
the necessary calculations in user's stead.


\n{2}{Server-side rendering}

The application constructs the web pages \emph{entirely} on the server side,
and it runs without a single line of JavaScript, of which the author is
especially proud. It improves load times, decreases the attack surface,
increases maintainability and reduces cognitive load that is required when
dealing with JavaScript. Of course, that requires extensive usage of
non-semantic \texttt{POST} requests in web forms even for data \emph{updates}
(where HTTP \texttt{PUT}s should be used) and the accompanying frequent
full-page refreshes, but that still is not enough to warrant the use of
JavaScript.


\n{2}{Frontend}

Frontend-side, the application Tailwind was used for CSS. It promotes the usage
of flexible \emph{utility-first} classes in the HTML markup instead of
separating out styles from content. Understandably, this is somewhat of a
preference issue and the author does not hold hard opinions in either
direction; however, it has to be noted that this approach empirically allows
for rather quick UI prototyping. Tailwind was chosen for having a reasonably
detailed documentation and offering built-in support for dark/light mode, and
partially also because it \emph{looks} nice.

The Go templates containing the CSS classes need to be parsed by Tailwind in
order t produce the final stylesheet that can be bundled with the application.
The upstream provides an original CLI tool (\texttt{tailwindcss}), which can be
used exactly for that action. Simple and accessible layouts were overall
preferred, a single page was rather split into multiple when becoming
convoluted. Data-backed efforts were made to create reasonably contrasting
pages.

\n{3}{Frontend experiments}

As an aside, the author has briefly experimented with WebAssembly to provide
client-side dynamic functionality for this project, but has ultimately scrapped
it in favour of the entirely server-side rendered approach. It is possible that
it would get revisited in the future if necessary, and performance mattered.
Even from the short experiments it was obvious how much faster WebAssembly was
when compared to JavaScript.


% \newpage
\n{2}{User isolation}

\obr{Application use case diagram}{fig:usecasediagram}{.9}{graphics/pcmt-use-case.pdf}

Users are only allowed into specific parts of the application based on the role
they currently possess (Role-based Access Control).

While this short list might get amended in the future, initially only two basic
roles were envisioned:

\begin{itemize}
  \item Administrator
  \item User
\end{itemize}

It is paramount that the program protects itself from the insider threats as
well and therefore each role is only able to perform actions that it is
explicitly assigned. While there definitely is certain overlap between the
capabilities of the two outlined roles, each also possesses unique features
that the other one does not.

For instance, the administrator role is not able to perform searches on the
breach data directly, for that a separate \emph{user} account has to be
devised. Similarly, a regular user is not able to manage breach lists and other
users, because that is a privileged operation.

In-application administrators are not able to view (any) sensitive user data
and should therefore only be able to perform the following actions:

\begin{itemize}
  \item Create user accounts
  \item View user listing
  \item View user details
  \item Change user details, including administrative status
  \item Delete user accounts
  \item Refresh breach data from online sources
\end{itemize}

Let us consider a case when a user performs an operation on their own account.
While demoting from administrator to a regular user should be permitted,
promoting self to be an administrator would constitute a \emph{privilege
escalation} and likely be a precursor to at least a \emph{denial of service} of
sorts, as there would be nothing preventing the newly-\emph{admined} user from
disabling the accounts of all other administrators.


\n{2}{Zero trust principle}

\textit{Confidentiality, i.e.\ not trusting the provider}

There is no way for the application (and consequently, the in-application
administrator) to read user's data (such as saved search queries). This is
possible by virtue of encrypting the pertinent data before saving them in the
database by a state-of-the-art \texttt{age} tool (backed by
X25519)~\cite{age},~\cite{x25519rfc7748}. The \texttt{age} \emph{identity}
itself is in turn encrypted by a passphrase that only the user controls. Of
course, the user-supplied password is run by a password based key derivation
function (\texttt{argon2}, version \emph{id} with the officially {recommended}
configuration parameters) before letting it encrypt the \emph{age} key.

The \texttt{age} identity is only generated once the user changes their
password for the first time, in an attempt to prevent scenarios like the
in-application administrator with access to physical database being able to
both \textbf{recover} the key from the database and \textbf{decrypt} it given
that they already know the user password (because they set it when they created
the user), which would subsequently give them unbounded access to any future
encrypted data, as long as they would be able to maintain their database
access. This is why generating the \texttt{age} identity is are bound to the
first password change.

Of course, the supposed evil administrator could simply perform the password
change themselves! However, the user would at least be able to find those
changes in the activity logs and know to \emph{not} use the application under
such circumstances. But given the scenario of a total database compromise, the
author finds that all hope is \emph{already} lost at that point. At least when
the database is dumped, it should only contain non-sensitive, functional
information in plain text, everything else should be encrypted.

Consequently, both the application operators and the in-application
administrators should ideally never be able to learn the details of what the
user is tracking/searching for, the same being by extension applicable even to
potential attackers with direct access to the database. Thus, the author
maintains that every scenario that could potentially lead to a data breach
(apart from a compromised actual user password) would have to entail some form
of operating memory acquisition on the machine hosting the application, for
instance using \texttt{LiME}~\cite{lime}, or perhaps directly the
\emph{hypervisor}, if considering a virtualised (``cloud'') environments.


\n{1}{Implementation}

\n{2}{Dhall Configuration Schema}\label{sec:configuration}

The configuration schema was at first being developed as part of the main
project's repository, before it was determined that it would benefit both the
development and overall clarity if the schema lived in its own repository (see
Section~\ref{sec:repos} for details). This enabled the schema to be
independently developed and versioned, and only be pulled into the main
application whenever it was determined to be ready.


% \vspace{\parskip}
\smallskip
% \vspace{\baselineskip}
\begin{lstlisting}[language=Haskell, caption={Dhall configuration schema version 0.0.1-rc.2},
label=dhallschema, basicstyle=\linespread{0.9}\footnotesize\ttfamily,
backgroundcolor=\color{lstbg},
morekeywords={Text, Natural, Optional, Type}
]
let Schema =
  { Type =
      { Host : Text
      , Port : Natural
      , HTTP :
          { Domain : Text
          , Secure : Bool
          , AutoTLS : Bool
          , TLSKeyPath : Text
          , TLSCertKeyPath : Text
          , HSTSMaxAge : Natural
          , ContentSecurityPolicy : Text
          , RateLimit : Natural
          , Gzip : Natural
          , Timeout : Natural
          }
      , Mailer :
          { Enabled : Bool
          , Protocol : Text
          , SMTPAddr : Text
          , SMTPPort : Natural
          , ForceTrustServerCert : Bool
          , EnableHELO : Bool
          , HELOHostname : Text
          , Auth : Text
          , From : Text
          , User : Text
          , Password : Text
          , SubjectPrefix : Text
          , SendPlainText : Bool
          }
      , LiveMode : Bool
      , DevelMode : Bool
      , AppPath : Text
      , Session :
          { CookieName : Text
          , CookieAuthSecret : Text
          , CookieEncrSecret : Text
          , MaxAge : Natural
          }
      , Logger : { JSON : Bool, Fmt : Optional Text }
      , Init : { CreateAdmin : Bool, AdminPassword : Text }
      , Registration : { Allowed : Bool }
      }
  }
\end{lstlisting}
\vspace*{-\baselineskip}

Full schema with type annotations can be seen in Listing~\ref{dhallschema}.

\newpage

The \texttt{let} statement declares a variable called \texttt{Schema} and
assigns to it the result of the expression on the right side of the equals
sign, which has for practical reasons been trimmed and is displayed without the
\emph{default} block. The default block is instead shown in its own
Listing~\ref{dhallschemadefaults}.

The main configuration comprises both raw attributes and child records, which
allow for grouping of related functionality. For instance, configuration
settings pertaining mailserver setup are grouped in a record named
\textbf{Mailer}. Its attribute \textbf{Enabled} is annotated as \textbf{Bool},
which was deemed appropriate for an on-off switch-like functionality, with the
only permissible values being either \emph{True} or \emph{False}.

Do note that in Dhall $true\ != True$, since internally \textbf{True} is a
\texttt{Bool} constant built directly into Dhall (see ``The
Prelude''~\cite{dhallprelude} for reference), while \textbf{true} is evaluated
as an \emph{unbound} variable, that is, a variable \emph{not} defined in the
current \emph{scope} and thus not \emph{present} in the current scope.

Another one of Dhall's specialties is that `$==$' and `$!=$' (in)equality
operators \textbf{only} work on values of type \texttt{Bool}, which for example
means that variables of type \texttt{Natural} (\texttt{uint}) or \texttt{Text}
(\texttt{string}) cannot be compared directly as is the case in other
languages. That either leaves the comparing work for a higher-level language
(such as Go). Alternatively, from the perspective of the Dhall authors
\emph{enums} are the promoted way to solve this when the value matters, i.e.\
derive a custom \emph{named} type from a primitive type and compare
\emph{that}.

\newpage
% \vspace{\parskip}
\begin{lstlisting}[language=Haskell, caption={Dhall configuration defaults for
schema version 0.0.1-rc.2},
label=dhallschemadefaults, basicstyle=\linespread{0.9}\footnotesize\ttfamily,
backgroundcolor=\color{lstbg},
]
  , default =
      -- | have sane defaults.
      { Host = ""
      , Port = 3000
      , HTTP =
        { Domain = ""
        , Secure = False
        , AutoTLS = False
        , TLSKeyPath = ""
        , TLSCertKeyPath = ""
        , HSTSMaxAge = 0
        , ContentSecurityPolicy = ""
        , RateLimit = 0
        , Gzip = 0
        , Timeout = 0
        }
      , Mailer =
        { Enabled = False
        , Protocol = "smtps"
        , SMTPAddr = ""
        , SMTPPort = 465
        , ForceTrustServerCert = False
        , EnableHELO = False
        , HELOHostname = ""
        , Auth = ""
        , From = ""
        , User = ""
        , Password = ""
        , SubjectPrefix = "pcmt - "
        , SendPlainText = True
        }
      , LiveMode =
          -- | LiveMode controls whether the application looks for
          -- | directories "assets" and "templates" on the filesystem or
          -- | in its bundled Embed.FS.
          False
      , DevelMode = False
      , AppPath =
          -- | AppPath specifies where the program looks for "assets" and
          -- | "templates" in case LiveMode is True.
          "."
      , Session =
        { CookieName = "pcmt_session"
        , CookieAuthSecret = ""
        , CookieEncrSecret = ""
        , MaxAge = 3600
        }
      , Logger = { JSON = True, Fmt = None Text }
      , Init =
        { CreateAdmin =
            -- | if this is True, attempt to create a user with admin
            -- | privileges with the password specified below
            False
        , AdminPassword =
            -- | used for the first admin, forced change on first login.
            "50ce50fd0e4f5894d74c4caecb450b00c594681d9397de98ffc0c76af5cff5953eb795f7"
        }
      , Registration.Allowed = True
      }
  }

in  Schema
\end{lstlisting}
\vspace*{-\baselineskip}
\vspace*{-\baselineskip}
\vspace*{-\baselineskip}
\n{2}{Data integrity and authenticity}

The user can interact with the application via a web client, such as a browser,
and is required to authenticate for all sensitive operations. To not only know
\emph{who} the user is but also make sure they are \emph{permitted} to perform
the action they are attempting, the program employs an \emph{authorisation}
mechanism in the form of sessions. These are on the client side represented by
cryptographically signed and encrypted (using 256-bit AES) HTTP cookies. That
lays foundations for a few things: the data saved into the cookies can be
regarded as private because short of future \emph{quantum computers} only the
program itself can decrypt and access the data, and the data can be trusted
since it is both signed using the key that only the program controls and
\emph{encrypted} with \emph{another} key that equally only the program holds.

The cookie data is only ever written \emph{or} read at the server side,
solidifying the authors decision to let it be encrypted, as there is no point
in not encrypting it for some perceived client-side simplification. Users
navigating the website send their session cookie (if it exists) with
\textbf{every request} to the server, which subsequently verifies the integrity
of the data and in case it is valid, determines the existence and potential
amount of user privilege that should be granted. Public endpoints do not
mandate the presence of a valid session by definition, while at protected
endpoints the user is authenticated at every request. When a session expires or
if there is no session to begin with, the user is either shown a \emph{Not
found} error message, the \emph{Unauthorised} error message or redirected to
\texttt{/signin}, depending on the endpoint or resource, as can be seen, this
behaviour is not uniform and depends on the resource and/or the endpoint.

Another aspect that contributes to data integrity from \emph{another} point of
view is utilising database \emph{transactions} for bundling together multiple
database operations that collectively change the \emph{state}. Using the
transactional jargon, the data is only \emph{committed} if each individual
change was successful. In case of any errors, the database is instructed to
perform an atomic \emph{rollback}, which brings it back to a state before the
changes were ever attempted.

The author has additionally considered the thought of utilising an embedded
immutable database like immudb (\url{https://immudb.io}) for record keeping
(verifiably storing data change history) and additional data integrity checks,
e.g.\ for tamper protection purposes and similar; however, that work remains
yet to be materialised.


\n{2}{Database schema}\label{sec:dbschema}

The database schema is not being created by manually typing out SQL statements.
Instead, an Object-relational Mapping (ORM) tool named \texttt{ent} is used,
which allows defining the table schema and relations entirely in Go. The upside
of this approach is that the \emph{entity} types are natively understood by
code editors, and they also get type-checked by the compiler for correctness,
preventing all sorts of headaches and potential bugs.

Since \texttt{ent} encourages the usage of \emph{declarative migrations} at
early stages of the project, it is not required for the database schema to
exist on application start-up in form of raw SQL (or HCL). Instead,
\texttt{ent} only requires a valid connection string providing reasonably
privileged access to the database and it handlers the database configuration by
auto-generating SQL with the help of the companion embedded library
\texttt{Atlas} (\url{https://atlasgo.io/}). The upstream project (\texttt{ent})
encourages moving to otherwise more traditional \emph{versioned migrations} for
more mature projects, so that is on the roadmap for later.

The best part about using \texttt{ent} is that there is no need to define
supplemental methods on the models, as with \texttt{ent} these are meant to be
\emph{code generated} (in the older sense of word, not with Large Language
Models) into existence. Code generation creates files with actual Go models
based on the types of the attributes in the database schema model, and the
respective relations are transformed into methods on the receiver or functions
taking object attributes as arguments.

For instance, if the model's attribute is a string value \texttt{Email}, ent
can be used to generate code that contains methods on the user object like the
following:

\begin{itemize}
\item \texttt{EmailIn(pattern string)}
\item \texttt{EmailEQ(email string)}
\item \texttt{EmailNEQ(email string)}
\item \texttt{EmailHasSuffix(suffix string)}
\end{itemize}

These methods can further be imported into other packages and this makes
working with the database a morning breeze.

All the database \empg{entity} IDs were declared as type \texttt{UUID}
(\emph{universally unique ID, theoretically across space and time}), contrary
to the more traditional \emph{integer} IDs.

Support for \texttt{UUID}s was provided natively by the supported databases and
in Go via a popular and vetted open-source library
(\url{github.com/google/uuid}). Among the upsides of using \texttt{UUID}s over
integer IDs is that there is no need to manually increment the ID. But more
importantly, there is also the fact that compared to 32-bit\footnotemark{}
signed integers the \texttt{UUID} is a somewhat randomly generated 16 byte (128
bit) array, reducing chances of collision.

Barring higher chances of preventing conflicts during imports of foreign
databases, this design decision might not provide any advantage for the current
system \emph{at the moment}. It could, however, hold importance in the future,
should the database ever be deployed in a replicated, high-availability (HA)
manner with more than one concurrent \emph{writer} (replicated application
instances).

\footnotetext{In Go, integer size is architecture dependent, see
\url{https://go.dev/ref/spec#Numeric_types}}

The relations between entities as modelled with \texttt{ent} can be imagined as
the edges connecting the nodes of a directed \emph{graph}, with the nodes
representing the entities. This conceptualisation lends itself for a more
human-friendly querying language, where the directionality can be expressed
with words describing ownership



\n{1}{Deployment}

A deployment setup as suggested in Section~\ref{sec:deploymentRecommendations}
is already \emph{partially} covered by the multi-stage \texttt{Containerfile}
that is available in the main sources. Once built, the resulting container
image only contains a handful of things it absolutely needs:

\begin{itemize}
  \item a self-contained statically linked copy of the program
  \item a default configuration file and corresponding Dhall expressions cached
    at build time
  \item a recent CA certs bundle
\end{itemize}

Since the program also needs a database for proper functioning, an example
scenario includes the application container being run in a Podman \textbf{pod}
(as in a pea pod or pod of whales) together with the database. That results in
not having to expose the database to the entire host or out of the pod at all,
it is only available over pod's \texttt{localhost}. Hopefully it goes without
saying that the default values of any configuration secrets should be
substituted by the application operator with new, securely generated ones
(read: using \texttt{openssl rand} or \texttt{pwgen}).


\n{2}{Rootless Podman}

Assuming rootless Podman set up and the \texttt{just} tool installed on the
host, the application could be deployed by following a series of relatively
simple steps:

\begin{itemize}
  \item build (or pull) the application container image
  \item create a pod with user namespacing, exposing the application port
  \item run the database container inside the pod
  \item run the application inside the pod
\end{itemize}

In concrete terms, it would resemble something along the lines of
Listing~\ref{podmanDeployment}. Do note that all the commands are executed
under the unprivileged \texttt{user@containerHost} that is running rootless
Podman, i.e.\ it has \texttt{UID}/\texttt{GID} mapping entries in
\texttt{/etc/setuid} and \texttt{\etc/setgid} files \textbf{prior} to running any
Podman commands.

% \newpage
\begin{lstlisting}[language=bash, caption={Example application deployment using
rootless Podman},
label=podmanDeployment, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg}, commentcolor=\color{Gray},
morekeywords={mkdir,podman,just},
]
# From inside the project folder, build the image locally using kaniko.
just kaniko

# Create a pod, limit the amount of memory/CPU available to its containers.
podman pod create --replace --name pcmt \
    --memory=100m --cpus=2 \
    --userns=keep-id -p3005:3000

# Create the database folder and run the database in the pod.
mkdir -pv ./tmp/db
podman run --pod pcmt --replace -d --name "pcmt-pg" --rm \
    -e POSTGRES_INITDB_ARGS="--auth-host=scram-sha-256 \
         --auth-local=scram-sha-256" \
    -e POSTGRES_PASSWORD=postgres \
    -v $PWD/tmp/db:/var/lib/postgresql/data:Z \
    --health-cmd "sh -c 'pg_isready -U postgres -d postgres'" \
    --health-on-failure kill \
    --health-retries 3 \
    --health-interval 10s \
    --health-timeout 1s \
    --health-start-period=5s \
    docker.io/library/postgres:15.2-alpine3.17

# Run the application itself in the pod.
podman run --pod pcmt --replace --name pcmt-og -d --rm \
    -e PCMT_LIVE=False \
    -e PCMT_DBTYPE="postgres" \
    -e PCMT_CONNSTRING="host=pcmt-pg port=5432 sslmode=disable \
         user=postgres dbname=postgres password=postgres"
    -v $PWD/config.dhall:/config.dhall:Z,ro \
    docker.io/immawanderer/mt-pcmt:testbuild -config /config.dhall
\end{lstlisting}
% \vspace*{-\baselineskip}

To summarise Listing~\ref{podmanDeployment}, first the application container is
built from inside the project folder using \texttt{kaniko}.  The container
image could alternatively be pulled from the container repository, but it makes
more sense showing the image being built from sources with the listing
depicting a \texttt{:testbuild} tag being used.

Next, a \emph{pod} is created and given a name, setting the port binding for
the application. Then, the database container is started inside the pod,
configured with a healthchecking mechanism.

As a final step, the application container itself is run inside the pod. The
application configuration named \texttt{config.dhall} located in \texttt{\$PWD}
is mounted as a volume into container's \texttt{/config.dhall}, providing the
application with a default configuration. The default container does contain a
default configuration for reference, however, running the container without
additionally providing the necessary secrets would fail.

\n{3}{Sanity checks}

Also do note that the application connects to the database using its
\emph{container} name, i.e.\ not the IP address. This is possible thanks to
Podman setting up DNS resolution inside pods using default networks in such a
way that all containers in the pod can reach each other using their (container)
names.

Interestingly, connecting via \texttt{localhost} from containers inside the pod
would also work. Inside the pod, any container in the pod can reach any other
container in the same pod via \emph{pod's} own \texttt{localhost}, thanks to a
shared network name space~\cite{podmanNet}.

In fact, \emph{pinging} (sending ICMP packets using the \texttt{ping} command)
the database and application containers from an ad-hoc Alpine Linux container
that just joined the pod temporarily yields:

\vspace{\parskip}
\begin{lstlisting}[language=bash, caption={Pinging pod containers using their
names}, label=podmanPing, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg},
morekeywords={podman,ping}
]
user@containerHost % podman run --rm -it \
    --user=0 \
    --pod=pcmt \
    docker.io/library/alpine:3.18
/ % ping -c2 pcmt-og
PING pcmt-og (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: seq=0 ttl=42 time=0.072 ms
64 bytes from 127.0.0.1: seq=1 ttl=42 time=0.118 ms

--- pcmt-og ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.072/0.095/0.118 ms
/ % ping -c2 pcmt-pg
PING pcmt-pg (127.0.0.1): 56 data bytes
64 bytes from 127.0.0.1: seq=0 ttl=42 time=0.045 ms
64 bytes from 127.0.0.1: seq=1 ttl=42 time=0.077 ms

--- pcmt-pg ping statistics ---
2 packets transmitted, 2 packets received, 0% packet loss
round-trip min/avg/max = 0.045/0.061/0.077 ms
/ %
\end{lstlisting}

Was the application deployed in a traditional manner instead of using Podman,
the use of FQDNs or IPs would be probably be necessary, as there would be no
magic resolution of container names happening transparently in the background.

\n{3}{Database isolation from the host}

A keen observer has undoubtedly noticed that the pod constructed in
Listing~\ref{podmanDeployment} did only create the binding for a port used by
the application (\texttt{5005/tcp}). The Postgres default port
\texttt{5432/tcp} is not among pod's port bindings, as can be seen in the pod
creation command in the said listing. This can also easily be verified using
the command in Listing~\ref{podmanPortBindings}:

\begin{lstlisting}[language=bash, caption={Podman pod port binding inspection},
label=podmanPortBindings, basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg},
morekeywords={podman},
]
user@containerHost % podman pod inspect pcmt \
    --format="Port bindings: {{.InfraConfig.PortBindings}}\n\
    Host network: {{.InfraConfig.HostNetwork}}"
Port bindings: map[3000/tcp:[{ 5005}]]
Host network: false
\end{lstlisting}
\vspace*{-\baselineskip}

To be absolutely sure that the database is available only internally in the pod
(unless, of course, there is another process listening on the subject port),
and that connecting to the database from outside the pod (i.e. from the
container host) really \emph{does} fail, the following commands can be issued:

\begin{lstlisting}[language=bash, caption={In-pod database is unreachable from
the host}, breaklines=true, label=podDbUnreachable,
basicstyle=\linespread{0.9}\small\ttfamily,
backgroundcolor=\color{lstbg},
]
user@containerHost % curl localhost:5432
--> curl: (7) Failed to connect to localhost port 5432 after 0 ms: Couldn't connect to server
\end{lstlisting}
\vspace*{-\baselineskip}

The error in Listing~\ref{podDbUnreachable} is indeed expected, as it is the
result of the database port not been exposed from the pod.

Of course, since a volume (essentially a bind mount) from the host is used, the
actual data is still accessible on the host, both to privileged users and the
user running the pod. On the host with SELinux support, the \texttt{:Z} volume
addendum at least ensures that the content of the volume is directly
inaccessible to other containers, including the application container running
inside the same pod, via SELinux labelling.

\n{3}{Health checks}

Running the containers with health checks can be counted among the few crucial
settings. That way
the container runtime can periodically \emph{check} that the application
running inside the container is behaving correctly and instructions can be
provided on what action should be taken, should the health of the application
evaluate unsatisfyingly. Furthermore, different sets of health checking
commands can be passed with Podman for start-up and runtime.


\n{2}{Reverse proxy configuration}

If the application is deployed behind a reverse proxy, such as NGINX, the
configuration snippet in Listing~\ref{nginxSnip} might apply. Do note how the
named upstream server \texttt{pcmt} references the port that was exposed from
the pod created in Listing~\ref{podmanDeployment}.

\begin{lstlisting}[caption={Example reverse proxy configuration snippet},
breaklines=true, label=nginxSnip, basicstyle=\linespread{0.9}\scriptsize\ttfamily,
backgroundcolor=\color{lstbg},
morekeywords={upstream,server,return,listen,server_name,add_header,access_log,error_log,location,proxy_pass,proxy_set_header,allow,include,more_set_headers,ssl_buffer_size,ssl_dhparam,ssl_certificate,ssl_certificate_key,http2},
]
upstream pcmt {
  server 127.0.0.1:5005;
}
server {
  return 301 https://<pcmt domain>$request_uri;
  listen 80;
  listen [::]:80;
  server_name: <pcmt domain> www.<pcmt domain>;
  return 404;
  add_header Referrer-Policy "no-referrer, origin-when-cross-origin";
}
server {
  server_name <pcmt domain>;
  access_log /var/log/nginx/<pcmt domain>.access.log;
  error_log /var/log/nginx/<pcmt domain>.error.log;
  location / {
    proxy_pass http://pcmt;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_forwarded_for;
  }
  location /robots.txt {
    allow all;
    add_header Content-Type "text/plain; charset=utf-8";
    add_header X-Robots-Tag "all, noarchive, notranslate";
    return 200 "User-agent: *\nDisallow: /";
  }
  include sec-headers.conf;

  add_header X-Real-IP $remote_addr;
  add_header X-Forwarded-For $proxy_add_x_forwarded_for;
  add_header X-Forwarded-Proto $scheme;
  more_set_headers 'Early-Data: $ssl_early_data';

  listen [::]:443 ssl http2;
  listen 443 ssl http2;
  ssl_certificate /etc/letsencrypt/live/<pcmt domain>/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/<pcmt domain>/privkey.pem;
  include /etc/letsencrypt/options-ssl-nginx.conf;
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

  # reduce TTFB
  ssl_buffer_size 4k;
}
\end{lstlisting}
\vspace*{-\baselineskip}

The snippet describes how traffic arriving at port \texttt{80/tcp} (IPv4 or
IPv6) that matches the domain name(s) \texttt{\{www.,\}<pcmt domain>}
(\texttt{<pcmt domain>} being the domain name that the program was configured
with, including appropriate DNS records) gets 301-redirected to the same
location (\texttt{\$request\_uri}), only over \texttt{HTTPS}. If the server
name does not match, a 404 is returned instead. In the main location block, all
traffic except for \texttt{/robots.txt} is forwarded to the named backend, with
headers added on top by the proxy in order to label the incoming requests as
\emph{not} originating at the proxy. The \emph{robots} route is treated
specially, immediately returning a directive that disallows crawling of any
resource on the page for all. The proxy is also instructed to log access and
error events to specific log files, finally load the domain's TLS certificates
(obtained out of band), reduce the \texttt{ssl\_buffer\_size} and listen on
port \texttt{443/tcp} (dual stack).


\n{1}{Validation}

\n{2}{Unit tests}

Unit testing is a hot topic for many people and the author does not count
himself to be a staunch supporter of neither extreme. The ``no unit tests''
opinion seems to discount any benefit there is to unit testing, while a
``TDD-only''\footnotemark{} approach can be a little too much for some people's
taste. The author tends to prefer a \emph{middle ground} approach in this
particular case, i.e. writing enough tests where meaningful but not necessarily
testing everything or writing tests prior to business logic code. Arguably,
following the practice of TDD should result in writing a \emph{better designed}
code, particularly because there needs to be a prior thought about the shape
and function of the code, as it is tested for before it is even written, but it
adds a slight inconvenience to what is otherwise a straightforward process.

Thanks to Go's built in support for testing via its \texttt{testing} package
and the tooling in the \texttt{go} tool, writing tests is relatively simple. Go
looks for files in the form \texttt{<filename>\_test.go} in the present working
directory but can be instructed to look for test files in packages recursively
found on any path using the ellipsis, like so: \texttt{go test
./path/to/package/\ldots}, which then \emph{runs} all the tests found, and
reports some statistics, such as the time it took to run the test or whether it
succeeded or failed. To be precise, the test files also need to contain test
functions, which are functions with the signature \texttt{func TestWhatever(t
*testing.T)\{\}} and where the function prefix ``Test'' is just as important as
the signature. Without it, the function is not considered to be a testing
function despite having the required signature and is therefore \emph{not}
executed during testing.

This test lookup behaviour; however, also has a neat side effect: all the test
files can be kept side-by-side their regular source counterparts, there is no
need to segregate them into a specially blessed \texttt{tests} folder or
similar, which in author's opinion improves readability. As a failsafe, in case
no actual test are found, the current behaviour of the tool is to print a note
informing the developer that no tests were found, which is handy to learn if it
was not intended/expected. When compiling regular source code, the Go files
with \texttt{\_test} in the name are simply ignored by the build tool.

\footnotetext{TDD, or Test Driven Development, is a development methodology
  whereby tests are written \emph{first}, then a complementary piece of code
  that is supposed to be tested is added, just enough to get past the compile
  errors and to see the test \emph{fail} and then is the code finally
  refactored to make the test \emph{pass}. The code can then be fearlessly
extended because the test is the safety net catching the programmer when the
mind slips and alters the originally intended behaviour of the code.}


\n{2}{Integration tests}

Integrating with external software, namely the database in case of this
program, is designed to utilise the same mechanism that was mentioned in the
previous section: Go's \texttt{testing} package. These tests verify that the
code changes can still perform the same actions with the external software that
were possible before the change and are run before every commit locally and
then after pushing to remote in the CI.

\n{3}{func TestUserExists(t *testing.T)}

In the integration test shown in Listing~\ref{integrationtest}, it is prefaced
at line 10 by declaring a helper function \texttt{getCtx() context.Context},
which takes no arguments and returns a new\\ \texttt{context.Context}
initialised with the value of the global logger. As previously mentioned, that
is how the logger gets injected into the user module functions. The actual test
function with the signature \texttt{TestUserExists(t *testing.T)} defines a
database connection string at line 21 and attempts to open a connection to the
database. The database in use here is SQLite3 running in memory mode, meaning
no file is actually written to disk during this process. Since the testing data
is not needed after the test, this is desirable. Next, a defer statement calls
the \texttt{Close()} method on the database object, which is the Go idiomatic
way of closing files and network connections (which are also an abstraction
over files on UNIX-like operating systems such as GNU/Linux). Contrary to where
it is declared, the \emph{defer} statement is only called after all the
statements in the surrounding function, which makes sure no file descriptors
(FDs) are leaked and the file is properly closed when the function returns.

In the next step at line 25 a database schema creation is attempted, handling
the potential error in a Go idiomatic way, which uses the return value from the
function in an assignment to a variable declared in the \texttt{if} statement,
and checks whether the \texttt{err} was \texttt{nil} or not. In case the
\texttt{err} was not \texttt{nil}, i.e.\ \emph{there was an error in the callee
function}, the condition evaluates to \texttt{true}, which is followed by
entering the inner block. Inside it, the error is announced to the user (likely
a developer running the test in this case) and the testing object's
\texttt{FailNow()} method is called. That marks the test function as having
failed, and thus stops its execution. In this case, that is the desired
outcome, since if the database schema creation call fails, there really is no
point in continuing the testing of user creation.
\\
Conversely, if the schema \emph{does} get created without an error, the code
continues to declare a few variables (lines 30-32): \texttt{username},
\texttt{email} and \texttt{ctx}, where the context injected with the logger is
saved. Two of them are subsequently (line 33) passed into the
\texttt{UsernameExists} function, \texttt{ctx} being the first argument and the
database pointer and \texttt{username} following, while the \texttt{email}
variable is only used at a later stage (line 46). The point of declaring them
together is to give a sense of relatedness. The error value returned from this
function is again checked (line 33) and if everything goes well, the
\texttt{usernameFound} boolean value is checked next at line 38.

\smallskip
\smallskip
\begin{lstlisting}[language=Go, caption={User existence integration test},
label=integrationtest,basicstyle=\linespread{0.9}\scriptsize\ttfamily,
backgroundcolor=\color{lstbg},
numbers=left,
numberstyle=\linespread{0.9}\scriptsize\ttfamily,
frame=l,
framesep=18.5pt,
framerule=0.1pt,
xleftmargin=18.7pt,
otherkeywords={\%s, \%q, \%v},
]
// modules/user/user_test.go
package user

import (
        "context"
        "testing"

        "git.dotya.ml/mirre-mt/pcmt/ent/enttest"
        "git.dotya.ml/mirre-mt/pcmt/slogging"
        _ "github.com/xiaoqidun/entps"
)

func getCtx() context.Context {
    l := slogging.Init(false)
    ctx := context.WithValue(context.Background(), CtxKey{}, l)
    return ctx
}

func TestUserExists(t *testing.T) {
    connstr := "file:ent_tests?mode=memory&_fk=1"
    db := enttest.Open(t, "sqlite3", connstr)
    defer db.Close()

    if err := db.Schema.Create(context.Background()); err != nil {
            t.Errorf("failed to create schema resources: %v", err)
            t.FailNow()
    }

    username := "dude"
    email := "dude@b.cc"
    ctx := getCtx()

    usernameFound, err := UsernameExists(ctx, db, username)
    if err != nil {
            t.Errorf("error checking for username {%s} existence: %q", username, err)
    }

    if usernameFound {
            t.Errorf("unexpected: user{%s} should not have been found", username)
    }

    if _, err := EmailExists(ctx, db, email); err != nil {
            t.Errorf("unexpected: user email '%s' should not have been found", email)
    }

    usr, err := CreateUser(ctx, db, email, username, "so strong")
    if err != nil {
            t.Errorf("failed to create user, error: %q", err)
            t.FailNow()
    } else if usr == nil {
            t.Error("got nil usr back")
            t.FailNow()
    }

    if usr.Username != username {
            t.Errorf("got back wrong username, want: %s, got: %s",
                       username, usr.Username,
            )
    } // ...more checks...
}
\end{lstlisting}

Since the database has just been created, there should be no users, which is
checked in the body of the \texttt{if} statement (line 35). The same check is
then performed using an email (line 42), which is also correctly expected to
fail.

The final statements of the described test attempts to create a user by calling
the function \texttt{CreateUser(...)} at line 46, whose return values are again
checked for both error and \emph{nillability}, respectively. The test continues
with more of the checks similar to what has been described so far, but the rest
was omitted for brevity.

As was just demonstrated in the test, a neat thing about error handling in Go
is that it allows for very easy checking of all code paths, not just the
\emph{happy path} where there are no issues. The recommended approach of
immediately explicitly handling (or deciding to ignore) the error is in
author's view superior to wrapping hundreds of lines in \texttt{try} blocks and
then \emph{catching} (or not) \emph{all the} exceptions, as is the practice in
some other languages.


\n{2}{Test environment}

The application has been deployed in a test environment on author's modest
Virtual Private Server (VPS) at \texttt{https://testpcmt.dotya.ml}, protected
by \emph{Let's Encrypt}\allowbreak issued, short-lived, ECDSA
\texttt{secp384r1} curve TLS certificate, and configured with strict CSP. It is
a test instance; therefore limits (and rate-limits) to prevent abuse might be
imposed.
\\
The test environment makes the program available over both modern IPv6 and
legacy IPv4 protocols, to maximise accessibility. Redirects were set up from
plain HTTP to HTTPS, as well as from \texttt{www} to non-\texttt{www} domain.
The subject domain configuration is hardened by setting the \texttt{CAA}
record, limiting certificate authorities (CAs) that are able to issue TLS
certificates for it (and let them be trusted by validating clients).
Additionally, \textit{HTTP Strict Transport Security} (HSTS) had been enabled
for the main domain (\texttt{dotya.ml}) including the subdomains quite some
time ago (consult the preload lists in Firefox/Chrome), which mandates that
clients speaking HTTP only ever connect to it (and the subdomains) using TLS.

The whole deployment has been orchestrated using an Ansible\footnotemark{}
playbook created for this occasion, focusing on idempotence with the aim of
reliably automating the deployment process. At the same time, it is now
described reasonably well in the code. Its code is available at
\url{https://git.dotya.ml/mirre-mt/ansible-pcmt.git}.

\footnotetext{A Nix-ops approach was considered, however, Ansible was deemed
more suitable since the existing host runs Arch.}


\n{3}{Deployment validation}

% TODO: show the results of testing the app in prod using:
% \url{https://testssl.sh/} and
% \url{https://gtmetrix.com/reports/testpcmt.dotya.ml/}.

The deployed application has been validated using the \textit{Security Headers}
tool (see \url{https://securityheaders.com/?q=https%3A%2F%2Ftestpcmt.dotya.ml}),
the results of which can be seen in Figure~\ref{fig:secheaders}.

It shows that the application sets the \texttt{Cross Origin Opener Policy} to
\texttt{same-origin}, which isolates the browsing context exclusively to
\textit{same-origin} documents, preventing \textit{cross-origin} documents from
loading in the same browser context.

\obr{Security Headers scan}{fig:secheaders}{.89}{graphics/screen-securityHeaders}

Furthermore, a \texttt{Content Security Policy} of
\texttt{upgrade-insecure-requests; default-src 'none'; manifest-src 'self';
font-src 'self'; img-src 'self' https://*; script-src 'self'; style-src 'self';
object-src 'self'; form-action 'self'; frame-ancestors'self'; base-uri 'self'}
is set by the program using a header.
This policy essentially pronounces the application (whatever domain it happens
to be hosted at - \texttt{'self'}) as the only \textit{permissible} source for
any scripts, styles and frames, the only destination of web forms. One
exception is the \texttt{image-src 'self' https://*} directive, which more
leniently also permits images from any \textit{secure} sources. This measure
ensures that no unvetted content is ever loaded from elsewhere.

The \texttt{Referrer-Policy} header setting of \texttt{no-referrer,
strict-origin-when-cross-origin} ensures that user tracking is reduced, since
no referrer is included (the \texttt{Referer} header is omitted) when the user
navigatse away from the site or somehow send requests outside the application
using other means. The \texttt{Permissions-Policy} set to
\texttt{geolocation=(), midi=(), sync-xhr=(), microphone=(), camera=(),
gyroscope=(), magnetometer=(), fullscreen=(self), payment=()} declares that the
application is, for instance, never going to request access to payment
information, user microphone or camera devices, or geolocation.

\texttt{gobuster} was used in fuzzing mode to aid in uncovering potential
application misconfigurations. The wordlists used include:

\begin{itemize}
  \item Anton Lopanitsyn's \texttt{fuzz.txt} (\url{https://github.com/Bo0oM/fuzz.txt/tree/master})
  \item Daniel Miessler's \texttt{SecLists} (\url{https://github.com/danielmiessler/SecLists})
  \item Sam's \texttt{samlists} (\url{https://github.com/the-xentropy/samlists})
\end{itemize}

Many requests yielded 404s for non-existent pages, or possibly pages requiring
authentication (\emph{NotFound} is used so as not to disclose page's
existence). The program initially also issued quite a few 503s as a result of
rate-limiting, until \texttt{gobuster} was tamed using the \texttt{--delay}
parameter. Anti-CSRF measures employed by the program caused most of the
requests to yield 400s (missing CSRF token), or 403s with a CSRF token.
% A Burp test would perhaps be more telling.

The deployed application was scanned with Quallys' \textit{SSL Labs} scanner
and the results can be seen in Figure~\ref{fig:ssllabs}, confirming that HSTS
(includes subdomains) is deployed, the server runs TLS 1.3, the DNS Certificate
Authority Authorisation (CAA) is configured for the domain, with the overall
grade being A+.

\obr{Quallys SSL Labs scan}{fig:ssllabs}{.75}{graphics/screen-sslLabs}



\n{1}{Application screenshots}

Figure~\ref{fig:homepage} depicts the initial page that a logged-out user is
greeted with when they load the application.

\obr{Homepage}{fig:homepage}{.84}{graphics/screen-homepage}

Figure~\ref{fig:signup} can be seen showing a registration page with input
fields turned green after basic validation. Visiting this page with
registration disabled in settings would yield a 404.

\obr{Registration page}{fig:signup}{.65}{graphics/screen-signup}

\newpage

\obr{Registration page email
error}{fig:signupEmailError}{.54}{graphics/screen-signup-emailError}

A sign-up form error telling the user to provide a valid email address is shown
in Figure~\ref{fig:signupEmailError}.


\obr{Sign-in page}{fig:signin}{.55}{graphics/screen-signin}

Figure~\ref{fig:signin} depicts a sign-in form similar to the sign-up one.

\obr{Short password error on
sign-in}{fig:signinShortPasswd}{.55}{graphics/screen-signin-shortPasswordError}

An error in Figure~\ref{fig:signinShortPasswd} prompts the user to lengthen the
content of the password field from 3 to at least 20 characters.

\newpage

\obr{Admin homepage}
{fig:adminHome}{.25}
{graphics/screen-adminHome}

Figure~\ref{fig:adminHome} displays a simple greeting and a logout button.

\obr{User management screen}
{fig:adminUserManagement}{.85}
{graphics/screen-adminUserManagement}

Figure~\ref{fig:adminUserManagement} shows the user management screen, which
provides links to view user details page, start creating a new user.

% \obr{User creation screen}
% {fig:adminUserCreate}{.35}
% {graphics/screen-adminUserCreate}

\obr{User creation: `username not unique' error}
{fig:adminUserCreateErrorUsernameNotUnique}{.65}
{graphics/screen-adminUserCreateErrorUsernameNotUnique}

User creation form can be seen in
Figure~\ref{fig:adminUserCreateErrorUsernameNotUnique}. Both regular and admin
level users can be created here. In this case, an error is shown, telling the
user there is an issue with username uniqueness. User experience of this
process could in the future be improved by using a bit of JavaScript (or
WebAssembly) to check uniqueness of the username on user's \emph{key-up}.

\newpage

\obr{Creation of user `demo'}
{fig:adminUserCreateDemo}{.75}
{graphics/screen-adminUserCreateDemo}

The user management screen is again shown in
Figure~\ref{fig:adminUserCreateDemo} after user `demo' was created. An
informative \emph{flash} message is printed near the top of the page
immediately after the action and not shown on subsequent page loads.


\obr{User details screen}
{fig:adminUserDetail}{.65}
{graphics/screen-adminUserDetail}

The user details page is depicted in Figure~\ref{fig:adminUserDetail}. The
interface presents key information about the user such as ID, username and
admin status. Additionally, it provides a link back to the previous page and
two buttons: one for editing the user and one for user deletion.

\obr{User edit screen}
{fig:adminUserEdit}{.65}
{graphics/screen-adminUserEdit}

Figure~\ref{fig:adminUserEdit} shows the form for user editing with a button
`Update' in the bottom for submitting, a couple of checkboxes for toggling
`admin' and `active' state of the user. Above those, there are input fields for
`username', `email', `password' and the confirmation of the password.

\newpage

\obr{User deletion confirmation}
{fig:adminUserDeleteConfirm}{.55}
{graphics/screen-adminUserDeleteConfirmation}

When attempting to delete a user, the administrator is presented with the
screen shown in Figure~\ref{fig:adminUserDeleteConfirm}, which asks them
whether they are absolutely sure to perform an action with permanent
consequences. The `Confirm permanent deletion' button is highlighted in intense
red colour, while the `Cancel' button is displayed in a light blue tone. There
are two additional links: the `All users' one that points to the user
management page, and the `Back to detail' one that simply brings the
administrator one step back to the user details page.

\obr{User deletion post-hoc}
{fig:adminUserDeletePostHoc}{.55}
{graphics/screen-adminUserDemoDeletion}

After successful user deletion, the administrator is redirected back to user
management page and a flash message confirming the deletion is printed near the
top of the page, as shown in Figure~\ref{fig:adminUserDeletePostHoc}.

\obr{Log-out message}
{fig:logout}{.20}
{graphics/screen-logout}

Figure~\ref{fig:logout} shows the message printed to users on logout.

\newpage

\obr{Manage API keys}
{fig:manageAPIKeys}{.65}
{graphics/screen-manageAPIKeys}

Figure~\ref{fig:manageAPIKeys} shows a page that allows administrators to
manage instance-wide API keys for external services, such as \emph{Have I Been
Pwned?} or \emph{DeHashed.com}. Do note that these keys are never distributed
to clients in any way and are only ever used by the application itself to make
the requests on \emph{behalf} of the users.

\obr{Import of locally available breach data from the CLI}
{fig:localImport}{.99}
{graphics/screen-localImport}

Figure~\ref{fig:localImport} depicts how formatted breach data can be imported
into the program's database using the CLI.




% =========================================================================== %