% !TeX document-id = {28b19d8e-66e4-448e-87bf-2175f6830aca}
% !TeX encoding = UTF-8
% !TeX spellcheck = en_US
% !TeX root = stash.tex
% !TeX tex-script:compile = txs:///pdflatex/[--shell-escape]
% https://orcid.org/0000-0003-4586-8500
% DOI: 10.5281/zenodo.19122412

\documentclass[11pt]{report}


\usepackage{amsmath}
\usepackage{amsfonts}
\usepackage{amssymb}

\usepackage{graphicx}
\usepackage[margin=1in, includefoot, includehead]{geometry} %Package to setup page layout

% Sepackage{minted} % code blocks
% \usepackage[hidelinks]{hyperref} %Uses hyperlinks in PDF (optional)
\usepackage{hyperref}

\usepackage{tikz}
\usetikzlibrary{shapes.geometric, arrows.meta, positioning, calc, backgrounds, fit}
\setlength{\headheight}{14pt} % Fix the "Overfull \hbox" and Layout Warnings\textbf{}
\setlength{\footskip}{55pt} % Fix the "Overfull \hbox" and Layout Warnings\textbf{}
% Define colors for the architecture tiers
\definecolor{foundation}{RGB}{240, 244, 250}
\definecolor{boundary}{RGB}{255, 235, 235}
\definecolor{extension}{RGB}{235, 245, 235}
\definecolor{accent}{RGB}{42, 87, 154}

%%%%% ----- Header and Footer Stuff ----- %%%%%
\usepackage{fancyhdr}
\usepackage{vhistory} % Ensure this is loaded to use \vhCurrentVersion

\pagestyle{fancy}
\fancyhf{} % Clears all header and footer fields

% --- Header Configuration ---
\fancyhead[L]{Project Stash House}
\fancyhead[R]{\myTitle}

% --- Footer Configuration ---
% Left: Current version from the version history table
\fancyfoot[L]{Version \vhCurrentVersion} 

% Center: Page number
\fancyfoot[C]{\thepage}

% Right: Your University logo (scaled to fit footer height
%\fancyfoot[R]{\raisebox{-0.5\height}{\includegraphics[scale=0.30]{../../static/images/ucd-wide.jpg}}}

% --- Rules ---
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{1pt}

% title page vars ----- %%%%%
\newcommand{\myTitle}{Stash House}
\newcommand{\myName}{Franklin Diaz}
\newcommand{\myOrg}{University of Colorado}
\newcommand{\myDate}{March 19, 2026}
\newcommand{\myORCID}{0000-0003-4586-8500}
\newcommand{\myDOI}{10.5281/zenodo.19122412}

\usepackage{vhistory}

 % BIBLIOGRAPHY ----- %%%%%
% \usepackage[backend=biber,style=alphabetic,sorting=none]{biblatex}
\bibliographystyle{plain}

\begin{document}

% frontmatter: half title, title page, colophon (copyright page), epigraph, toc, preface, acknowledgements
\include{frontmatter/title2}

\pagenumbering{roman} % Ensure your front matter (abstract, TOC) uses roman numerals and the main body uses arabic
\cleardoublepage

% uncomment next lines to generate table of contents
\tableofcontents
\thispagestyle{empty}
\cleardoublepage
\setcounter{page}{1}

\pagenumbering{arabic} % Ensure your front matter (abstract, TOC) uses roman numerals and the main body uses arabic

\section{Introduction}
Developer workstations routinely accumulate sensitive credentials across shell history files, unencrypted configuration stubs, and source trees. While current tooling emphasizes pre-commit prevention (e.g., secret linting in CI/CD), practical engineering lacks standard patterns for reclaiming authority once a workstation is already disordered.

Project \texttt{stash-house} provides a reproducible framework for local secret hygiene, encrypted stewardship, and controlled runtime execution. Rather than acting as a replacement for enterprise vault services, it establishes a discipline for discovering workstation sprawl, migrating credentials into local encrypted storage, and materializing secrets strictly on demand.

\section{System Architecture}

The system defines two functional tiers separated by a critical execution boundary:

\begin{figure}[htbp]
    \centering
    \resizebox{0.9\textwidth}{!}{
        \begin{tikzpicture}[
            node distance=1.5cm and 1.8cm,
            font=\sffamily\small,
            box/.style={rectangle, draw, thick, fill=white, minimum width=2.6cm, minimum height=1cm, align=center, rounded corners=2pt},
            cloud/.style={ellipse, draw, thick, fill=white, minimum width=2.4cm, minimum height=1cm, align=center},
            boundary_line/.style={dashed, thick, red!70!black},
            arrow/.style={-{Stealth[scale=1.1]}, thick}
        ]
            % Foundation
            \node[box] (chaos) {Workstation Sprawl\\(Plaintext / Leaked)};
            \node[box, right=of chaos, fill=blue!10] (operator) {\textbf{Stash Core}\\(\texttt{scan\_local.sh})};
            \node[box, right=of operator] (stewardship) {Encrypted Store\\(GPG / \texttt{pass})};

            \begin{scope}[on background layer]
                \node[fill=gray!10, fit=(chaos) (stewardship), inner sep=12pt, label={[anchor=north west]north west:\textbf{Tier 1: Local Stewardship}}] (found_bg) {};
            \end{scope}

            % Runtime Materialization Boundary
            \node[box, above=2cm of stewardship, fill=red!10] (runtime) {Runtime Process\\(Terraform / Shell Env)};
            \draw[boundary_line] ($(stewardship.north) + (-1.8, 0.6)$) -- ($(stewardship.north) + (1.8, 0.6)$)
                node[midway, above, text=red!70!black] {\textbf{Materialization Boundary}};

            % Flows
            \draw[arrow] (chaos) -- (operator);
            \draw[arrow] (operator) -- (stewardship);
            \draw[arrow, red!70!black] (stewardship) -- (runtime) node[midway, right] {Inject JIT};
        \end{tikzpicture}
    }
    \caption{Stash House Core Architecture: Local Stewardship and Materialization Boundary. Federated transports are documented separately in Section~\ref{sec:experimental}.}
\end{figure}

\subsection{Local Stewardship (Tier 1)}
The local tier discovers exposed credentials and relocates them into standard encrypted stores managed via GPG and the UNIX \texttt{pass} utility. Secrets are tracked within a version-controlled repository utilizing \texttt{.gitattributes} filters to ensure ciphertext remains encrypted at rest.

\subsection{The Materialization Boundary}
The materialization boundary marks the exact interface where encrypted credentials become live runtime state (e.g., shell environment variables for Terraform execution). \texttt{stash-house} uses Just-In-Time (JIT) subshell injection so that secrets remain in process memory only for the duration of command execution, leaving zero plaintext residue in local disk artifacts or interactive shell history.

\section{Implementation Mechanics}

The workflow operates across three discrete phases:

\begin{enumerate}
    \item \textbf{Discovery (\texttt{scan\_local.sh}):} Scans standard developer paths (\texttt{\textasciitilde/.aws}, \texttt{\textasciitilde/.config/gcloud}, shell history) for unencrypted credentials, API keys, and service account tokens.
    \item \textbf{Encapsulation:} Automatically ingests detected tokens into the GPG-backed \texttt{pass} hierarchy and purges the plaintext source files.
    \item \textbf{Execution Wrappers:} Replaces static credentials with ephemeral evaluation wrappers (e.g., \texttt{pass show terraform/aws | eval}), ensuring secrets only exist in ephemeral child process environments.
\end{enumerate}

\section{Related Work}

\paragraph{Secret Detection vs. Recovery.} Static tools such as Gitleaks and GitGuardian inspect repositories during pre-commit or CI/CD stages. \texttt{stash-house} addresses post-sprawl workstation remediation, transitioning unencrypted secrets into active management \cite{stashhouse}.

\paragraph{Centralized Vaults vs. Local Stewardship.} HashiCorp Vault and enterprise secret managers impose central server requirements and heavy coordination overhead. \texttt{stash-house} operates local-first, treating decentralized transports as opt-in synchronization channels rather than operational dependencies.

\paragraph{Materialization Control.} Existing CLI tooling (e.g., 1Password CLI, \texttt{direnv}) injects environment variables but lacks integrated workstation remediation. Our model pairs automated scanning with scoped, ephemeral process execution to limit live-memory exposure windows.

\section{Experimental Extensions: Distributed Transport and Federated Quorum}\label{sec:experimental}
The following mechanisms extend the stable local hygiene toolchain beyond a single workstation. These are research prototypes and are not required for core \texttt{stash-house} operation.

\begin{quote}
\noindent\textbf{Boundary:} The Tier 1 stewardship pipeline (Discovery $\rightarrow$ Encapsulation $\rightarrow$ Execution Wrappers) functions independently of any federated transport. The mechanisms below operate as optional synchronization and identity-brokerage channels for multi-environment mobility.
\end{quote}

\subsection{Nostr-NIP-78 Transport}
Ciphertext can be synchronized across decentralized relays by encoding encrypted blobs as replaceable application events (\texttt{kind:30078}). NIP-78 storage decouples persistence from vendor-locked storage backends, enabling resilient replication without introducing a central coordinator \cite{nip78}. NIP-44 encryption \cite{nip44} provides the transport-level confidentiality layer for direct-message channels.

\subsection{FOKS Key Brokerage}
The Federated Open Key Service \cite{foks} can be integrated to govern decryption via hardware security keys, enabling multi-site quorum requirements for credential access.

\subsection{Enterprise Identity Bridge}
Site-to-site federation with existing directory services (LDAP/Kerberos) allows the local repository to act as a trusted source of truth that interoperates with organizational identity infrastructure \cite{kerberos}, \cite{openldap}. These bridges are opt-in and do not modify the core encryption or stewardship mechanics.

\section{Conclusion}
Project \texttt{stash-house} formalizes workstation credential hygiene by pairing automated local exposure scanning with GPG-backed secret stewardship. By isolating the runtime materialization boundary and treating distributed identity mechanisms as modular extensions, the framework restores security discipline to developer workstations without requiring disruptive changes to engineering workflows.

\begin{versionhistory}
  \vhEntry{0.1.0}{2025-11-15}{FD}{Initial draft}
  \vhEntry{0.3.6}{\myDate}{FD}{Simplified architecture: removed speculative LLM node, stripped external component diagram, merged NIP-78 into federated extensions, added implementation mechanics section, compressed related work.}
  \vhEntry{0.3.7}{March 19, 2026}{FD}{Drew explicit core vs. experimental boundary; carved Section~\ref{sec:experimental} for distributed transports and federated quorum prototypes; removed federated infrastructure references from System Architecture section.}
\end{versionhistory}

\cleardoublepage

\bibliography{bib}
\end{document}