System Contracts

Stable contracts. Do not change without updating this document.

Binaries

CLI Subcommands

Operating Modes

The CLI silently falls back to direct mode when the daemon is not available on D-Bus, regardless of config mode.

facelock auth Exit Codes

Filesystem Paths

All paths overridable via config. FACELOCK_CONFIG is honored for unprivileged processes, but privileged PAM/root auth flows ignore the environment and use either an explicit --config path or /etc/facelock/config.toml.

Config Schema

TOML format. All keys optional -- camera auto-detected, sensible defaults for everything. See Configuration for the full reference.

Sections

Camera Auto-Detection

When device.path is omitted:

1. Enumerate /dev/video0 through /dev/video63
2. Filter to VIDEO_CAPTURE devices
3. Prefer IR cameras (name contains "ir"/"infrared", or supports GREY/Y16 format)
4. Fall back to first available device

Database Schema

SQLite with WAL mode and foreign keys:

CREATE TABLE face_models (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user TEXT NOT NULL,
    label TEXT NOT NULL,
    created_at INTEGER NOT NULL,
    UNIQUE(user, label)
);

CREATE TABLE face_embeddings (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    model_id INTEGER NOT NULL REFERENCES face_models(id) ON DELETE CASCADE,
    embedding BLOB NOT NULL,  -- 512 x f32 = 2048 bytes (or encrypted blob)
    sealed INTEGER NOT NULL DEFAULT 0
);

CREATE TABLE rate_limit (
    user TEXT NOT NULL,
    attempt_time INTEGER NOT NULL
);

Only failed authentication attempts are recorded in rate_limit. Daemon mode and oneshot mode share the same SQLite-backed window, so daemon restarts do not clear lockout state.

IPC Protocol

D-Bus system bus (org.facelock.Daemon). Only used in daemon mode. The daemon exposes a D-Bus interface on the system bus, and both the PAM module and CLI connect as D-Bus clients. Access is controlled by D-Bus system bus policy (/etc/dbus-1/system.d/org.facelock.Daemon.conf).

Methods

Authenticate, Enroll, ListModels, RemoveModel, ClearModels, PreviewFrame, PreviewDetectFrame, ListDevices, ReleaseCamera, Ping, Shutdown

Raw camera frames require privilege. PreviewFrame remains root-only. PreviewDetectFrame returns the jpeg_data frame bytes to root unconditionally; a non-root caller receives them only after an interactive polkit authorization for the action org.facelock.preview-frames (checked via org.freedesktop.PolicyKit1.Authority.CheckAuthorization, AllowUserInteraction=true). While unauthorized — denied, prompt pending, polkit unreachable, or any D-Bus error — the daemon fails closed: jpeg_data is empty and the caller receives detection and recognition metadata only.

Capture concurrency: Authenticate, Enroll, PreviewFrame, and PreviewDetectFrame fail immediately with a daemon busy error while another capture is in flight. Clients treat this like any other daemon error and degrade to password auth.

Signals

AuthAttempted(user: s, matched: b) — emitted after each authentication attempt. Carries no similarity score. Bus policy restricts reception to root and the facelock group.

Return Types

AuthResult, Enrolled, Models, Removed, Frame, DetectFrame, Devices, Ok, Error

PAM Semantics

PAM module never blocks indefinitely. All operations have timeouts.

Syslog Format

pam_facelock(<service>): <result> for user <username>

Anti-Spoofing

These defaults must not be weakened without security review.

Models

Configurable via recognition.detector_model and recognition.embedder_model.