auc

auc is a machine-local Linux software passkey authenticator. A persistent auc-agent system service exposes one external FIDO2 authenticator through Linux UHID; the ordinary auc touch command supplies one explicit user-presence gesture to one pending browser operation.

auc is software, not a hardware security boundary. It does not provide a secure element, physical tamper resistance, an independent display, FIDO certification, or protection from a compromised root account. It is useful when a stable roaming-authenticator interface and deliberate local presence are more important than hardware isolation.

This release is deliberately local to one machine. It has no pair or sync command, network replication, import/export path, background synchronization, or synchronization timer.

Requirements

• Linux with systemd, logind, the UHID kernel driver, and /dev/uhid;
• a browser or client that supports external FIDO2/CTAP2 authenticators;
• Rust/Cargo for the initial user installation and registry/toolchain network access for redeploys;
• sudo authorization for the initial system installation and explicit uninstall only.

Root never owns a Rustup installation. Capulus performs later exact-version builds as the shared capulus-build system account and installs the resulting root-owned binaries through a journaled system transaction.

Install

Install both same-version executables into the invoking user's Cargo bin directory, then bootstrap the system service as that user:

cargo install --locked auc-tool
auc system install

The installer validates that auc-agent is a same-version, executable regular file beside auc, checks the kernel audit login UID, creates the dedicated auc access group, installs /usr/local/bin/auc and /usr/local/bin/auc-agent, and starts the service. Start a new login session afterward so the new group membership is active.

The installed topology is:

/run/auc/agent.sock   (application) -----\
                                            +--> auc-agent.service
/run/auc/capulus.sock (management) ------/

systemd owns both sockets and passes the named descriptors to the single long-lived agent. The agent owns /dev/uhid and the root-only encrypted vault at /var/lib/auc.

Use

Check that the virtual authenticator is present:

auc status

When a browser is waiting for a security-key touch, run:

auc touch

The gesture is accepted only from an active, local, non-remote logind session and only while one matching CTAP operation is pending. A touch is consumed once, expires after 30 seconds, and is never cached for a later request.

Inspect or permanently tombstone local resident credentials with:

auc credentials list
auc credentials delete CREDENTIAL_ID

Deletion cannot be undone by replaying an older local event.

Repair and redeploy

Repair the installed files and units from the current managed installation:

auc system repair

Redeploy the latest published release, or require an exact version:

auc system redeploy
auc system redeploy --version 0.1.0

Redeploy returns a durable job ID and waits by default. Use --no-wait and inspect that exact job later when desired:

auc system redeploy --version 0.1.0 --no-wait
auc system job JOB_ID

The system binary is authoritative after installation. A redeploy also replaces the requesting user's existing Cargo-installed auc at the same exact version, using that user's own validated Cargo/Rustup environment and UID.

Uninstall and recovery

The normal uninstall removes the managed service, sockets, and system binaries but preserves the encrypted vault and access policy:

auc system uninstall

Permanent vault destruction is a separate explicit choice:

auc system uninstall --purge-vault

--purge-vault destroys every credential, tombstone, PIN state, signing key, and encryption key, then removes the dedicated access group. It is irreversible. --yes suppresses both confirmation prompts and should be used only by unattended workflows that already provide an equivalent safety gate.

Unknown vault schemas, malformed ownership or modes, symlinks, broken event chains, invalid signatures, AEAD failures, and live PIN-state version regression all fail closed. See DESIGN.md for the protocol, storage, cancellation, and threat-model details.