docs: pre-launch audit across docs, man pages, config, and website#27
Merged
Conversation
Sweep of documentation accuracy, post-D-Bus-migration drift, and stale content surfaced by a full review of every standard CLI flag, doc chapter, default config field, CHANGELOG entry, and the marketing website ahead of the v0.1.0 public launch. Man pages - Remove stale Unix-socket / SO_PEERCRED claims; describe D-Bus system bus and GetConnectionUnixUser UID verification - Fix wrong TPM subcommand names (seal-db -> seal-key, unseal-db -> unseal-key) - Add missing encrypt, decrypt, restart, audit, and setup --non-interactive sections CLI reference - Add missing commands and flags to docs/cli.md and book/src/cli-reference.md (encrypt, decrypt, audit, three tpm subcommands, three bench subcommands, global --config, setup --non-interactive) - Correct understated GPU support (CPU/CUDA -> CPU/CUDA/ROCm/OpenVINO) - Clarify that encrypt --generate-key only generates key material - Sync both files; eliminate drift Config and latency - Fix device.warmup_frames default in config/facelock.toml (3 -> 2 to match code) - Add previously undocumented landmark_displacement_px, landmark_min_moving, and tpm.seal_database fields - Standardize daemon latency to "~200ms warm / ~600ms cold" across CHANGELOG, config, architecture, troubleshooting - Bring book/src/configuration.md into parity with docs/configuration.md (missing [device] keys, [security.pam_policy], custom-model SHA256 prose, FACELOCK_CONFIG privilege caveat) Contracts - book/src/contracts.md: add facelock-polkit-agent binary, encrypt / decrypt / audit subcommands, missing [device] and [security] keys, rate_limit table, sealed column, FACELOCK_CONFIG caveat; correct SCRFD 10G size 16MB -> 17MB Security - Remove stale "creating socket" / "socket already bound" comments in docs/security.md capability-dropping example - Add suppress_unknown to the security config reference - book/src/security.md: fix [notification] enabled -> mode, use canonical /usr/share/dbus-1/system.d/ path, document per-method UID authorization (Authenticate / Enroll / Shutdown) CHANGELOG - Add [Unreleased] section - Split monolithic Added block into Added / Security / Fixed - Add missing entries: expanded status command, APT two-channel structure, PAM install/uninstall fixes README and CONTRIBUTING - Update version label v0.1.0-alpha -> v0.1.0 - Expand crate table to 11 (was 9: add facelock-bench, facelock-test-support) - Replace stale "IPC protocol" with "D-Bus interface" - Drop unverified 10MB IPC message size claim Website - Fix install command (cd dist && makepkg -si -> just install) - Redirect all broken website/docs/*.html links to GitHub source as a stopgap until the mdbook is published to GitHub Pages (TODO marker in HTML) - Add Open Graph meta tags, inline favicon, aria-hidden on decorative SVGs, mdash for em dashes Other - Standardize PAM backup filename to sudo.facelock-backup across book/src/testing.md, book/src/troubleshooting.md, docs/testing-safety.md (was inconsistent sudo.bak in two places) - Update docs/testing-roadmap.md to reflect v0.1.0 release and active tag-driven distribution channels - Add CI-distribution hedge in book/src/quickstart.md package install section Manual follow-ups (intentionally not in this PR): - Push v0.1.0 git tag (release-trigger event) - Replace website docs/ stopgap URLs once mdbook is hosted on GitHub Pages Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Pre-launch documentation/CLI/man/config/website sweep ahead of the v0.1.0 release. Purges stale Unix-socket/SO_PEERCRED references left over from the D-Bus migration, brings the CLI reference docs and man page into parity with the actual clap definitions (adds encrypt, decrypt, audit, restart, missing tpm/bench subcommands, global --config), corrects config defaults/fields, restructures the CHANGELOG to Keep-a-Changelog, and fixes broken docs/*.html links on the marketing site.
Changes:
- Doc/man/config drift fixes: IPC switched from Unix socket to D-Bus,
seal-db/unseal-db→seal-key/unseal-key,warmup_frames3→2, addedlandmark_displacement_px,landmark_min_moving,tpm.seal_database, unified daemon latency wording. - Book parity:
book/src/configuration.mdandbook/src/contracts.mdrestored to matchdocs/counterparts;[security.pam_policy],rate_limittable withsealedcolumn,facelock-polkit-agentrow,FACELOCK_CONFIGcaveat all added. - Website: dead
docs/*.htmllinks replaced with GitHub source URLs (with TODO),makepkg -si→just install, Open Graph tags, favicon,aria-hiddenon decorative SVGs, em-dashes; CHANGELOG restructured into Added/Security/Fixed; README crate count corrected to 11 and version label updated tov0.1.0.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| CHANGELOG.md | Adds [Unreleased] section and splits v0.1.0 entries into Added/Security/Fixed; embeds short commit hashes inline. |
| CONTRIBUTING.md | Corrects facelock-core description to "D-Bus interface" and softens 10MB IPC limit claim. |
| README.md | Drops v0.1.0-alpha pre-release banner; updates crate table to 11 crates incl. facelock-bench and facelock-test-support. |
| config/facelock.toml | Default warmup_frames 3→2; adds landmark_displacement_px, landmark_min_moving, tpm.seal_database. |
| docs/architecture.md | Unifies daemon latency phrasing to "~200ms warm / ~600ms cold". |
| docs/cli.md | Adds global --config, setup --non-interactive, JSON list shape, tpm seal-key/unseal-key/pcr-baseline, full bench subcommands, encrypt/decrypt/audit. |
| docs/configuration.md | Adds new fields and corrects defaults/latency wording. |
| docs/security.md | D-Bus terminology; documents suppress_unknown. |
| docs/testing-roadmap.md | Updates "current state" to v0.1.0 released; updates packaging status entries. |
| docs/testing-safety.md | Standardizes PAM backup filename to sudo.facelock-backup. |
| docs/troubleshooting.md | Updates first-start latency wording (~200ms warm / ~600ms cold). |
| man/facelock.1 | D-Bus IPC wording; seal-db/unseal-db → seal-key/unseal-key; adds encrypt/decrypt/restart/audit sections. |
| man/pam_facelock.8 | D-Bus IPC wording and updated file references. |
| book/src/cli-reference.md | Parity update mirroring docs/cli.md changes. |
| book/src/configuration.md | Restores parity with docs/configuration.md; adds new fields and [security.pam_policy]. |
| book/src/contracts.md | Adds facelock-polkit-agent, encrypt/decrypt/audit, rate_limit table, sealed column, FACELOCK_CONFIG caveat. |
| book/src/quickstart.md | Notes tag-driven CI for package availability. |
| book/src/security.md | Updates D-Bus policy path; documents per-method UID authorization; switches example notification field to mode. |
| book/src/testing.md | Standardizes PAM backup filename. |
| website/index.html | OG meta, favicon, aria-hidden on SVGs, em-dashes, replaces docs/*.html with GitHub URLs, fixes install command. |
| website/style.css | Adds clarifying comment on mobile nav. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| .B \-f\fR, \fB\-\-follow | ||
| Follow mode: watch for new log entries. | ||
| .TP | ||
| .B \-n\fR, \fB\-\-lines \fIcount\fR |
|
|
||
| [notification] | ||
| enabled = true # Show "Identifying face..." on login screen | ||
| mode = "terminal" # Show "Identifying face..." on login screen |
| | `facelock-cli` | bin | Unified CLI (`facelock` binary, includes `bench` subcommand) | | ||
| | `facelock-bench` | bin | Standalone benchmark and calibration utility | | ||
| | `pam-facelock` | cdylib | PAM module (libc + toml + serde, zbus only) | | ||
| | `pam-facelock` | cdylib | PAM module (libc, toml, serde, zbus only) | |
| <li><a href="docs/introduction.html">Documentation</a></li> | ||
| <li><a href="docs/security.html">Security</a></li> | ||
| <li><a href="docs/contributing.html">Contributing</a></li> | ||
| <li><a href="https://github.com/tyvsmith/facelock/blob/main/README.md">Documentation</a></li> |
Comment on lines
+32
to
+53
| - **Status command**: Reports inference provider and ORT library location, enrolled face count for the current user, security posture (IR enforcement, liveness, `min_auth_frames`), and notification state (`73a5c00`) | ||
| - **Models**: Self-hosted ONNX assets distributed via GitHub release downloads (no third-party model fetches in the auth path) | ||
| - **Packaging**: deb, rpm, PKGBUILD (`facelock` and `facelock-git`), Nix flake, signed APT repository (TPM `main` + non-TPM `legacy` channels), systemd/D-Bus activation, OpenRC/runit/s6 | ||
| - **Packaging**: deb, rpm, PKGBUILD (`facelock` and `facelock-git`), Nix flake, signed APT repository with two channels — `main` (TPM-enabled, Debian trixie+ / Ubuntu 25.04+) and `legacy` (non-TPM, Debian bookworm / Ubuntu 24.04) — systemd/D-Bus activation, OpenRC/runit/s6 (`c70999b`) | ||
| - **CI/CD**: Build/test/lint pipeline, TPM tests via swtpm, container PAM smoke tests, end-to-end `.deb` and `.rpm` package install validation | ||
| - **Documentation**: mdBook, man pages, ADRs, security posture assessment, threat model | ||
|
|
||
| ### Security | ||
|
|
||
| - **Constant-time matching**: Embedding comparison via `subtle` crate to prevent timing side-channels | ||
| - **Encryption at rest**: AES-256-GCM software encryption for stored face embeddings | ||
| - **TPM key sealing**: Optional TPM-backed key protection for the encryption key | ||
| - **Model integrity**: SHA256 verification of ONNX model files at load time | ||
| - **Rate limiting**: 5 auth attempts per user per 60 seconds (default), enforced in daemon | ||
| - **D-Bus authorization**: Daemon verifies caller UID via `GetConnectionUnixUser` before executing methods | ||
| - **Enrollment restriction**: Root-required enrollment enforced in auth paths (`c01a655`) | ||
| - **PAM env hardening**: Hardened PAM environment handling to prevent injection (`c01a655`) | ||
| - **systemd hardening**: `ProtectSystem=strict`, `NoNewPrivileges`, `InaccessiblePaths`, and related service restrictions | ||
|
|
||
| ### Fixed | ||
|
|
||
| - **PAM install output**: Conditional install messages — suppressed when PAM entry already present (`c12a970`) | ||
| - **PAM uninstall**: Uninstall now removes entries from all relevant PAM services, not just the primary one (`c12a970`) |
The previous commit replaced relative website links to docs/*.html with GitHub source-blob URLs after the audit flagged them as broken. They were not broken: .github/workflows/pages.yml builds the mdbook into book/book/ and copies it to _site/docs/ on every push to main, so the relative links resolve correctly on the deployed site at https://tysmith.me/facelock/. Revert nav Docs, hero Get Started, install-note, and the three footer links back to their original docs/*.html relative paths. Remove the stale TODO comment. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Single-commit sweep of doc/CLI/man/config/website accuracy ahead of the v0.1.0 public launch. Six parallel review agents audited every CLI flag, doc chapter, default config field, CHANGELOG entry, and the marketing site against the actual code; ten parallel fix agents then applied the findings.
SO_PEERCREDIPC.man/facelock.1TPM subcommands corrected (seal-db→seal-key,unseal-db→unseal-key). 4 missing top-level commands added to the man page (encrypt,decrypt,restart,audit).docs/cli.mdandbook/src/cli-reference.mdnow both documentencrypt,decrypt,audit, threetpmsubcommands, threebenchsubcommands, the global--configflag, andsetup --non-interactive. GPU support corrected from "CPU/CUDA" to all four providers.device.warmup_framesdefault corrected (3→2 to match code). Three undocumented fields (landmark_displacement_px,landmark_min_moving,tpm.seal_database) now in config, docs, and book. Daemon latency unified to "~200ms warm / ~600ms cold" across CHANGELOG, config, architecture, troubleshooting.book/src/configuration.mdandbook/src/contracts.mdwere severely truncated; now match theirdocs/counterparts including therate_limitSQLite table,sealedcolumn,facelock-polkit-agentbinary,[security.pam_policy]section, andFACELOCK_CONFIGprivilege caveat.[Unreleased]section added; v0.1.0 entries split intoAdded/Security/Fixedper Keep a Changelog. Missing entries added (expandedstatuscommand, APT two-channel structure, PAM install/uninstall fixes).v0.1.0-alpha→v0.1.0;facelock-coreIPC terminology corrected; unverified "10MB" IPC limit softened.docs/*.htmllink (hero CTA, "Get Started", footer Documentation/Security/Contributing) redirected to GitHub source as a stopgap with TODO marker; wrong install command (makepkg -si) replaced withjust install; Open Graph meta tags, favicon,aria-hiddenon decorative SVGs, em-dashes.sudo.facelock-backupacross testing and troubleshooting chapters (previously diverged fromsudo.bak).Test plan
cargo check --workspaceclean (no.rsfiles modified)man --warnings -l man/facelock.1andman/pam_facelock.8produce no warningsSO_PEERCRED,seal-db,unseal-db,/run/facelock/facelock.sock,v0.1.0-alphano longer match anywhere in docs/book/man/config/websitedocs/*.htmllinks insidewebsite/index.htmlmdbook build book/renders cleanly (I couldn't run locally —mdbooknot installed)website/index.htmlresolve as expectedFollow-ups (intentionally NOT in this PR)
v0.1.0git tag — this is the release-trigger event and should be the public-launch actiondocs/GitHub stopgap URLs with mdbook-hosted URLs once the book is published to GitHub Pages (TODO comment already in HTML)🤖 Generated with Claude Code