Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .envrc
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
use flake . --accept-flake-config
17 changes: 17 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,23 @@ env:
CARGO_INCREMENTAL: "0"

jobs:
nix:
name: nix (package + module + VM)
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- uses: cachix/install-nix-action@v31
with:
enable_kvm: true
extra_nix_config: |
system-features = nixos-test big-parallel kvm
max-jobs = 2
cores = 2
- name: Check Nix formatting
run: nix --accept-flake-config fmt -- --check flake.nix nix/*.nix nix/modules/*.nix nix/tests/*.nix
- name: Build package, evaluate module, and boot the integration VM
run: nix --accept-flake-config flake check --no-write-lock-file --print-build-logs

lint:
name: lint (clippy + fmt + deny + scope-discipline)
runs-on: ubuntu-latest
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,7 @@
.DS_Store
__pycache__/
*.pyc
.direnv/
.pre-commit-config.yaml
result
result-*
7 changes: 7 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,13 @@ make install # Install to ~/.cargo/bin
make docker-build # Build Docker image
make docker-test # Build and run tests in container

# Nix
nix develop . # Enter the pinned Rust development environment
nix build . # Build the package and run workspace tests
nix flake check . # Check package/module and boot integration VM (requires KVM)
nix develop . --command make lint
nix develop . --command make test

# Benchmarks
make bench # Run benchmarks
```
Expand Down
20 changes: 20 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ Approve Linux authentication on your Android phone with a fresh strong biometric

## Install

For Nix or NixOS, use the [Nix setup below](#nix-and-nixos).

On a supported Linux desktop:

```sh
Expand All @@ -29,6 +31,21 @@ Release downloads include DEB, RPM, Arch Linux packages, and manual Linux archiv

Use Debian 12+, Ubuntu 24.04+, a current Fedora/openSUSE/Arch installation, or a compatible derivative, with glibc 2.36+, PAM, systemd user services, BlueZ, and a BLE adapter capable of advertising. The phone needs Android 13+ with a supported Ed25519 Keystore implementation and an enrolled strong biometric. The APK can install on older Android versions, but that does not establish signing-key support.

### Nix and NixOS

The flake supports `x86_64-linux` and `aarch64-linux`. With Nix and flakes enabled, install into your user profile without cloning the repository:

```sh
nix profile install github:Mewplane/syauth
syauth --version
```

This installs the CLI, `syauth-presenced` daemon, and PAM module; storage, service activation, and PAM still need configuration. See [profile installation and setup](docs/how-to/install.md#install-with-nix) for details and update/removal commands.

For NixOS, add `github:Mewplane/syauth` as a flake input and import `syauth.nixosModules.default`. Enable `services.syauth`, set `desktopUser` to your existing desktop account, and select the PAM services through `pam.services` (empty by default). The module manages the package, private bond-store directory, and daemon in that account's systemd user session. Run pairing as that account, without `sudo`.

Follow the [installation guide](docs/how-to/install.md#configure-nixos) for the complete flake configuration and activation commands. The [NixOS module reference](docs/reference/nix-modules.md) documents all options and PAM policy.

## Use

1. Install the desktop package and signed Android companion.
Expand All @@ -48,12 +65,15 @@ Being nearby prepares the connection; each authentication still needs explicit a

- [First unlock tutorial](https://mewplane.github.io/syauth/tutorials/first-unlock/)
- [Install](https://mewplane.github.io/syauth/how-to/install/), [pair and revoke](https://mewplane.github.io/syauth/how-to/pair-and-revoke/), [troubleshoot](https://mewplane.github.io/syauth/how-to/troubleshoot/)
- [Nix and NixOS setup](docs/how-to/install.md#install-with-nix), [NixOS module options](docs/reference/nix-modules.md)
- [CLI](https://mewplane.github.io/syauth/reference/cli/), [configuration](https://mewplane.github.io/syauth/reference/configuration/), [protocol](https://mewplane.github.io/syauth/reference/protocol/)
- [Illustrated mechanics](https://mewplane.github.io/syauth/explanation/mechanics/) with animated pairing, discovery, and unlock
- [Release builds and signing](https://mewplane.github.io/syauth/contributing/releases/)

## Development and contributing

For a pinned Rust development environment, run `nix develop .`. Entering the shell also installs the repository's pre-commit hooks. Build from a checkout with `nix build .` and try the CLI with `nix run . -- --version`. Run `nix flake check .` to build the package, check the generated NixOS configuration, and boot the installed-PAM integration VM (requires writable `/dev/kvm`); see [building with Nix](docs/how-to/install.md#with-nix) for details.

The Rust workspace is under `crates/`; the Android app is under `syauth-android/`. Build from source with a toolchain compatible with the committed `Cargo.lock` and development packages for D-Bus, PAM, and Bluetooth:

```sh
Expand Down
98 changes: 98 additions & 0 deletions docs/how-to/install.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

This guide sets up the desktop daemon and Android companion, then explains how to enable one PAM service. It targets a single desktop account using the default `/var/lib/syauth` store.

Choose a desktop installation method: [release package](#install-a-release-package), [Nix profile](#install-with-nix), [NixOS module](#configure-nixos), or [source build](#build-the-desktop-from-source). Then install the Android companion and pair your phone. The NixOS module manages storage, the user service, and selected PAM rules; other installation methods need those setup steps separately.

## Prerequisites

Use Linux with glibc 2.36+, PAM, systemd user services, BlueZ, and a BLE adapter capable of advertising. Release packages target Debian 12+, Ubuntu 24.04+, and current Fedora, openSUSE, and Arch systems. Both x86_64 and ARM64 artifacts are available; the tested distribution/CPU matrix is listed in [release development](../contributing/releases.md#artifact-contract).
Expand Down Expand Up @@ -53,8 +55,104 @@ For ARM64, use the DEB ending in `_arm64.deb`, or the RPM/Arch filename with `aa

Packages install `/usr/bin/syauth`, `/usr/libexec/syauth-presenced`, the distribution's `pam_syauth.so`, and `/usr/lib/systemd/user/syauth-presenced.service`. Continue with storage preparation below.

## Install with Nix

On x86-64 or ARM64 Linux with flakes enabled:

```sh
nix profile install github:Mewplane/syauth
syauth --version
```

Includes the CLI, daemon, and PAM module. On NixOS, use the
[module below](#configure-nixos). Otherwise, follow [storage and service setup](#prepare-storage-and-the-user-service),
using the profile's `syauth-presenced` as `--from` and
`lib/security/pam_syauth.so` as the PAM module path.

Update or remove using the entry name from `nix profile list`:

```sh
nix profile list
nix profile upgrade syauth
nix profile remove syauth
```

Remove its PAM rules and disable the user service before uninstalling.

## Configure NixOS

Add the input and module to your NixOS `flake.nix`:

```nix
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
syauth = {
url = "github:Mewplane/syauth";
inputs.nixpkgs.follows = "nixpkgs";
};
};

outputs = { nixpkgs, syauth, ... }: {
nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
syauth.nixosModules.default
{
hardware.bluetooth.enable = true;
services.syauth = {
enable = true;
desktopUser = "alice";
pam.services = [ "sudo" ];
pam.moduleArgs = [ "socket=/run/user/1000/syauth/auth.sock" ];
};
}
];
};
};
}
```

Adjust `my-host`, `system`, and `alice` for your host. The account must
exist in `users.users`; use its UID (`id -u alice`) in the socket path.

PAM services: `sudo` (also `sudo-i` for [sudo-rs](https://github.com/trifectatechfoundation/sudo-rs)), `kde` (Plasma lock screen),
`plasmalogin` (Plasma Login Manager). See [module options](../reference/nix-modules.md)
for defaults and PAM policy. The daemon requires an active user session.

## Build the desktop from source

### With Nix

From a checkout, enter the development shell:

```sh
nix develop .
make build
make test
make lint
```

The shell provides pinned Rust, D-Bus test dependencies, OpenSSL, and pre-commit hooks;
[nix-direnv](https://github.com/nix-community/nix-direnv) users can run
`direnv allow` for automatic loading. The flake declares the nix-community
Cachix cache.

For the Nix package and module checks:

```sh
nix build .
nix run . -- --version
nix flake check .
```

The flake check also boots a disposable NixOS VM and exercises the installed
PAM library and daemon. Run it on Linux with writable `/dev/kvm`; it uses
synthetic signing fixtures and does not require your phone or Bluetooth adapter.

### With Cargo

Source builds additionally require a Rust toolchain compatible with `Cargo.lock`, a C toolchain, `pkg-config`, and development packages for D-Bus, PAM, and Bluetooth (`libdbus-1-dev`, `libpam0g-dev`, and `libbluetooth-dev` on Debian).

From a checkout of syauth:
Expand Down
47 changes: 47 additions & 0 deletions docs/reference/nix-modules.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# NixOS module options

Import `nixosModules.default` to configure syauth for one desktop account.
See the [NixOS setup example](../how-to/install.md#configure-nixos).

The user service restarts after transport failure without a start-rate limit,
matching the upstream service's recovery policy when a controller disappears.

| Option under `services.syauth` | Default | Purpose |
| --- | --- | --- |
| `enable` | `false` | Install syauth and declare the user service. |
| `desktopUser` | Required when enabled | Owns `/var/lib/syauth`, runs the daemon, and pairs phones. |
| `package` | Flake's syauth package | Supplies the CLI, daemon and PAM module. |
| `installCli` | `true` | Put syauth on the system PATH. |
| `pam.services` | `[ ]` | PAM services to change. |
| `pam.control` | `"sufficient"` | Control field applied to each injected PAM rule. |
| `pam.moduleArgs` | Socket for the declared desktop UID | Arguments passed to each rule; requires an absolute `socket=` path when PAM is enabled. |

When `users.users.<desktopUser>.uid` is explicitly declared, the default argument
is `socket=/run/user/<uid>/syauth/auth.sock`. This works for root-run PAM callers
without relying on their environment. If NixOS allocates the UID at activation,
set `pam.moduleArgs` explicitly using the account's actual runtime socket path.
An empty argument list with PAM enabled is rejected during configuration checks.
Explicit arguments replace the generated default, so retain `socket=` when
adding other arguments.

The module inserts its rule before the service's enabled Unix password rule.
For a stack such as `plasmalogin`, it inserts the rule before the first
enabled authentication rule. If you override a service's PAM text directly,
that text must include the syauth authentication rule.

With the default `sufficient` control, successful phone approval can end
authentication. On failure PAM continues with the service's other rules.
See [PAM policy](configuration.md#pam-policy) before changing the control.

## Automated validation

`nix flake check` builds the package, checks generated rules and invalid
configurations, and boots a NixOS integration VM. The VM exercises installed
PAM and the daemon with deterministic public signing fixtures, including
PAM-before-daemon audit ownership, valid and invalid signatures, password
fallback, two-account isolation, sudo and sudo-rs, profile removal, and
disable/rollback preserving bonds. It uses no physical Bluetooth adapter or
Android phone and does not establish radio or biometric behavior.

Run on a Linux machine with writable `/dev/kvm`. GitHub CI enables KVM through
the Nix installation action and runs the same flake checks with sandboxing.
104 changes: 104 additions & 0 deletions flake.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading