* **TPM 2.0**: Hardware TPM 2.0 device (``/dev/tpmrm0`` or ``/dev/tpm0``), or ``swtpm`` for software-emulated development.
* **Linux Kernel with /dev/uhid**: Native kernel support for user-space HID devices (enabled by default in modern distributions) to support virtual FIDO2 / CTAP2 browser passkeys.

Runtime Dependencies

* **Go 1.26** or later
* **GNU Make**
* **swtpm** (optional, required to execute the full integration test suite)

Package Manager Installation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

On Fedora / RHEL / AlmaLinux::

   sudo dnf install golang make tpm2-tools zenity pinentry wl-clipboard swtpm

On Arch Linux::

   sudo pacman -S go make tpm2-tools zenity pinentry wl-clipboard swtpm

On Debian / Ubuntu::

   sudo apt install golang-go make tpm2-tools zenity pinentry-curses wl-clipboard swtpm

Quick Start
-----------

Build and install for your user account (recommended, non-root)::

   make clean && make all
   make install-user   # Installs to ~/.local/bin, ~/.config/systemd/user, ~/.local/share/dbus-1

Or install system-wide (requires root)::

   sudo make install   # Installs to /usr/local/bin

Enable & start socket activation::

   systemctl --user enable --now gpasskey-ssh.socket gpasskey-gpg.socket

Initialize your vault and verify status::

   gpasskey-cli status
   # Identities are enrolled automatically on first use by clients 
   # (WebAuthn passkeys, SSH, age, GPG) or via the portal API.

WebAuthn Passkeys in Browser::

   # Open Firefox or Chrome, go to https://webauthn.io/
   # Click "Register" -> enter your PIN in the gpasskey prompt -> Passkey is created!
   # Click "Authenticate" -> enter your PIN -> Instant login verified!

Manage encrypted secrets in the TPM-backed config store::

   gpasskey-cli set-secret my-api-key "super-secret-value"
   gpasskey-cli get-secret my-api-key

Documentation & Specifications
------------------------------

Our comprehensive engineering documentation is organized into modular specifications, architecture records, and roadmaps:

* **Functional Specifications**: `Functional Spec Index`_ — Defines user requirements and authorization models.
* **Technical Blueprints**: `Technical Spec Index`_ — Detailed Go architecture, crypto primitives, and enclave designs.
* **Architecture Decision Records (ADRs)**: `ADR Index`_ — Immutable log of architectural, crypto, and security choices.
* **API & Wire Protocols**: `API Spec Index`_ — Management socket, D-Bus portals, and bridge wire schemas.
* **Project Execution Roadmap**: `Roadmap Index`_ — Phased engineering timelines and milestone deliverables.

User Guides
~~~~~~~~~~~

* `User Quick Start`_ - Get up and running in 5 minutes.
* `Installation Guide`_ - Detailed build, udev, and systemd setup.
* `Security Guide`_ - Hardware TPM 2.0 enclave and "Wrap and Clear" memory isolation.
* `Configuration Guide`_ - Environment variables and service options.

.. _Functional Spec Index: docs/functional/spec.rst
.. _Technical Spec Index: docs/technical/spec.rst
.. _ADR Index: docs/adrs/index.rst
.. _API Spec Index: docs/api/spec.rst
.. _Roadmap Index: docs/project/roadmap.rst
.. _User Quick Start: docs/user/quickstart.rst
.. _Installation Guide: docs/user/installation.rst
.. _Security Guide: docs/user/security.rst
.. _Configuration Guide: docs/user/configuration.rst

What We're Planning (Phase 7)
-----------------------------

We are currently specifying and architecting **Phase 7: Pluggable Multi-Factor & Multi-Party Quorum Engine**:

* **Streaming Arbitrary File Hasher**: Use any file (from a short text poem to a 100GB audio master FLAC or image) as an authorization factor with constant :math:`\mathcal{O}(1)` memory consumption (:math:`\le 64\,\text{KB}` buffer).
* **Multi-Party Quorum ("The Coca-Cola Recipe")**: **Key-Wrapped Shamir Secret Sharing** over :math:`\text{GF}(2^8)` with HMAC verification tags, enabling :math:`k`-of-:math:`n` split-key authorization.
* **Hardware & Biometrics**: Physical YubiKey (Slot 2 HMAC-SHA1), physical FIDO2 keys (``hmac-secret``), and Linux biometrics (``fprintd``).
* **Dynamic Factor Re-Keying**: Atomic in-memory re-encryption (``gpk rekey``) to switch an identity's factor policy on the fly without recreating keys.
* **CLI Modernization**: Streamlining the command-line interface into canonical ``gpk`` (``/usr/local/bin/gpk``).
* **Desktop Auto-Unlock**: Seamless integration with the Freedesktop Secret Service (``org.freedesktop.secrets``).

See `Phase 7 Roadmap`_ and `ADR-006`_ for full specifications.

.. _Phase 7 Roadmap: docs/project/roadmaps/phase-7-pluggable-factors.rst
.. _ADR-006: docs/adrs/2026-08-25-pluggable-auth-factors.rst

Components
----------

* **gpasskeyd**: The core security enclave and virtual USB CTAP2/FIDO2 security key daemon.
* **gpasskey-cli**: Administrative tool for vault management and encrypted configuration.
* **age-plugin-gpasskey**: Plugin for the ``age`` encryption tool.
* **gpasskey-gpg**: Emulation bridge for GnuPG-compatible signing and verification.
* **gpasskey-ui**: Graphical helper for PIN entry.

Development
-----------

Run the unit tests::

   make test

Run the full Go-native integration suite (requires ``swtpm``)::

   make integration-test

Support & Donations
-------------------

If you find **gpasskey** useful and would like to support its ongoing development, consider donating via Liberapay:

.. image:: https://liberapay.com/assets/widgets/donate.svg
   :target: https://liberapay.com/Renich/donate
   :alt: Donate using Liberapay

License
-------

Copyright 2026 EVALinux

This project is licensed under the GNU General Public License v3.0 or later.
See LICENSE file for details.