# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Linux Hello is a Windows Hello-equivalent biometric authentication system for Linux. It provides secure facial authentication using IR cameras and TPM2-backed credential storage.

**Current Status**: All phases complete (1-5). Feature complete with ONNX model support.

## Build Commands

```bash
# Development build (works on any Linux)
cargo build

# Release build
cargo build --release

# Build with ONNX ML models
# - Ubuntu 24.04+ / glibc 2.38+: works directly
# - Ubuntu 22.04 / glibc 2.35+: run installer first (see below)
cargo build --release --features onnx

# Build with TPM hardware support
cargo build --release --features tpm

# Build with all features
cargo build --release --features "onnx,tpm"

# Run all tests
cargo test

# Run tests for a specific package
cargo test -p linux-hello-daemon

# Run specific integration test suite
cargo test --test phase3_security_test

# Run benchmarks
cargo bench -p linux-hello-daemon

# Generate documentation
cargo doc --workspace --no-deps --open

# Build PAM module (C)
cd pam-module && make

# Install PAM module (requires sudo)
cd pam-module && sudo make install

# Build GNOME Settings app (requires libgtk-4-dev, libadwaita-1-dev)
cargo build -p linux-hello-settings
```

## Architecture

### Workspace Crates

| Crate | Purpose |
|-------|---------|
| `linux-hello-common` | Shared types (`Config`, `Error`, `FaceTemplate`, `TemplateStore`) |
| `linux-hello-daemon` | Core daemon with camera, auth, security, D-Bus; builds `linux-hello-daemon` binary |
| `linux-hello-cli` | CLI tool, builds `linux-hello` binary |
| `linux-hello-settings` | GNOME Settings app (GTK4/libadwaita) |
| `linux-hello-tests` | Integration test harness |
| `pam-module` | C PAM module (`pam_linux_hello.so`) |

### External Directories

| Directory | Purpose |
|-----------|---------|
| `kde-settings/` | KDE System Settings module (CMake/Qt6) |
| `debian/` | Debian packaging files |
| `rpm/` | RPM spec file |
| `aur/` | Arch Linux PKGBUILD |
| `dist/` | Config templates, systemd service, D-Bus files |
| `models/` | ONNX model files (download separately) |
| `docs/` | API documentation, benchmarks |
| `scripts/` | Installation and setup scripts |

### Key Daemon Modules (`linux-hello-daemon/src/`)

| Module | Purpose |
|--------|---------|
| `camera/` | V4L2 camera enumeration, frame capture, IR emitter control |
| `detection/` | Face detection (placeholder + ONNX) |
| `embedding.rs` | Face embedding extraction (placeholder + ONNX) |
| `matching.rs` | Template matching with cosine similarity |
| `anti_spoofing.rs` | Liveness detection (IR, depth, texture, blink, movement) |
| `secure_memory.rs` | `SecureBytes`, `SecureEmbedding` with zeroization, memory locking |
| `secure_template_store.rs` | Encrypted template storage |
| `tpm.rs` | TPM2 integration with AES-256-GCM software fallback |
| `ipc.rs` | Unix socket server/client with peer credentials, rate limiting |
| `auth.rs` | Authentication service orchestration |
| `dbus_service.rs` | D-Bus interface implementation |
| `dbus_server.rs` | D-Bus server bootstrap |
| `onnx/` | ONNX model integration (feature-gated) |

### Communication Flow

```
Desktop/PAM → pam_linux_hello.so → Unix Socket → linux-hello-daemon → Camera/TPM
Settings App → D-Bus → linux-hello-daemon → Camera/TPM
```

## Platform-Specific Code

Camera code uses conditional compilation:
- `#[cfg(target_os = "linux")]` - Real V4L2 implementation
- `#[cfg(not(target_os = "linux"))]` - Mock implementation for development

ONNX code is feature-gated:
- `#[cfg(feature = "onnx")]` - Real ONNX models
- `#[cfg(not(feature = "onnx"))]` - Placeholder algorithms

## Security Considerations

- **Encryption**: AES-256-GCM with PBKDF2-HMAC-SHA256 (600k iterations)
- **Secure memory**: `SecureEmbedding` and `SecureBytes` auto-zeroize on drop
- **Constant-time**: Template comparisons use `subtle` crate (timing attack resistant)
- **Memory locking**: Sensitive data locked in RAM (no swap)
- **IPC security**: Peer credentials (SO_PEERCRED), rate limiting, authorization
- **Software TPM fallback**: Cryptographically strong but not hardware-bound

## Key Dependencies

| Dependency | Purpose |
|------------|---------|
| `zbus` | D-Bus integration |
| `tokio` | Async runtime |
| `v4l` | V4L2 camera interface |
| `aes-gcm` | Template encryption |
| `subtle` | Constant-time operations |
| `zeroize` | Secure memory wiping |
| `ort` | ONNX Runtime (optional) |
| `tss-esapi` | TPM2 support (optional) |

## Testing

```bash
# Quick test (default packages only)
cargo test

# All packages including integration tests
cargo test --workspace

# Specific test file
cargo test --test phase3_security_test

# With output
cargo test -- --nocapture

# ONNX tests
# On Ubuntu 22.04, set ORT_DYLIB_PATH first (see ONNX section below)
cargo test --features onnx
```

## ONNX Runtime Setup

The ONNX feature requires different setup depending on your glibc version:

| System | glibc | Setup Required |
|--------|-------|----------------|
| Ubuntu 24.04+, Fedora 39+ | >= 2.38 | None - works directly |
| Ubuntu 22.04, Debian 12 | 2.35-2.37 | Run installer script |
| Ubuntu 20.04 and older | < 2.28 | Not supported |

### For Ubuntu 22.04 / glibc 2.35-2.37

Run the installer to download a compatible ONNX Runtime:

```bash
# Check compatibility
./scripts/install-onnx-runtime.sh --check

# User install (no sudo)
./scripts/install-onnx-runtime.sh --user

# System-wide install
sudo ./scripts/install-onnx-runtime.sh
```

After installation, set the environment variable:

```bash
# Source the environment file
source ~/.local/etc/linux-hello/onnx-env.sh

# Or set directly
export ORT_DYLIB_PATH=~/.local/lib/linux-hello/libonnxruntime.so

# Then run
./target/release/linux-hello detect
```

## Common Tasks

### Adding a new D-Bus method
1. Add method to `dbus_service.rs` in the `LinuxHelloManager` impl
2. Update D-Bus client in `linux-hello-settings/src/dbus_client.rs`
3. Update KDE client in `kde-settings/src/dbus_client.cpp`

### Adding a new CLI command
1. Add subcommand to `linux-hello-cli/src/main.rs`
2. Implement handler using daemon's IPC client

### Adding a new anti-spoofing check
1. Add check method to `anti_spoofing.rs`
2. Add config option to `Config` in `linux-hello-common/src/config.rs`
3. Add test in `tests/integration/phase3_security_test.rs`