CLAUDE.md

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

Project

att_lock — an Android-style 4×4 dot-pattern screen locker for wlroots-based Wayland compositors. Single C11 binary, ~1500 LOC across four src/*.c files. No test suite exists.

Build

Nix flakes are the build system; the host is NixOS and has no system Wayland/cairo/pam/xkbcommon dev libraries outside the flake, so meson/ninja must always run inside nix develop.

nix build                                                     # -> ./result/bin/att_lock
nix develop --command bash -c 'meson setup build && ninja -C build'   # -> ./build/att_lock
nix develop --command ninja -C build                          # incremental rebuild

Add new dependencies to nativeDeps/libDeps in flake.nix and to meson.build, never to a global environment.

Gotcha: this repo is not git-tracked, so a plain src = ./. would vacuum the local build/ dir into the Nix sandbox and break nix build (meson chokes on a stale pre-configured build dir). flake.nix filters build and result* out via lib.cleanSourceWith — keep that filter (or init a git repo) whenever touching flake.nix.

Running it

att_lock takes over the screen via ext-session-lock-v1. Launching it in the compositor you are working in will lock that session — the protocol guarantees the session stays locked if the process dies. Test in a nested compositor (e.g. sway inside a window) rather than the live session. --setup re-records the pattern; delete $XDG_DATA_HOME/att_lock/pattern.hash to reset state.

Architecture

The Wayland protocol bindings are generated at build time by wayland-scanner from the vendored protocols/ext-session-lock-v1.xml into ext-session-lock-v1-client-protocol.h / -protocol.c — they live only in the build dir, so grepping the source for ext_session_lock_v1_* symbols finds call sites but not definitions.

One struct att (in src/att_lock.h) is the whole application state and is passed to essentially every listener; struct att_output and struct att_seat hang off it in wl_lists, one per compositor global.

Control flow — main() binds globals, calls ext_session_lock_manager_v1_lock(), then creates a lock surface per output. A lock surface only becomes visible once its configure handler commits a buffer, so lock_surface_configure() calls render_output() directly. Input handlers never render inline; they set a dirty flag via schedule_redraw() and the loop renders all outputs once per iteration.

The loop is the prepare_read/poll/read_events idiom rather than wl_display_dispatch(), because it needs a timeout: an active lockout has to wake the process to repaint its countdown, and wl_display_dispatch() would sleep until the next input event with the displayed seconds frozen. The timeout is computed to fire exactly when the displayed second changes, so an idle lockout costs one repaint per second and an idle unlock screen blocks indefinitely. If you touch this loop, every path must pair wl_display_prepare_read() with exactly one of wl_display_read_events() or wl_display_cancel_read() — leaking a prepared read deadlocks the locker, which means a session nobody can unlock.

Mode machine — enum att_mode drives both input handling and what prompt_text()/render_output() draw: MODE_UNLOCK ⇄ MODE_PASSWORD (any printable keypress enters password mode, Esc returns), and MODE_SETUP_FIRST → MODE_SETUP_CONFIRM on first run or --setup. Setup modes are pattern-only.

Failed-attempt throttling — note_failure() / locked_out() in main.c. Both begin_stroke() and submit_password() are gated, deliberately sharing one counter so that switching to the password field cannot sidestep an active pattern lockout; setup modes are not counted (there is no secret to guess yet), and strokes shorter than min_dots are rejected before auth_verify() and so are not failures either. Deadlines use CLOCK_MONOTONIC (att_now_ms()) precisely because it ignores wall-clock changes and does not advance across suspend — a lockout must not be sleepable-off.

Coordinates — everything in struct grid and struct att_pattern is in logical (surface-local) pixels. render_output() allocates a device-pixel buffer of width * scale and applies cairo_scale(scale) so all drawing code stays logical. The grid is a centred square at 70% of the shorter output dimension (att_grid()), which is what makes rotation and arbitrary aspect ratios work with no special cases.

Pattern model (src/pattern.c) — a sequence of dot indices (row * 4 + col). pattern_add() implements the Android rule that unvisited dots lying exactly on the straight line between the previous and new dot get captured first, using the gcd of the row/col delta. pattern_to_string() produces the canonical "0-1-2-5" form, which feeds the hash input, so any change to indexing or serialisation invalidates every stored pattern.

Auth (src/auth.c) — the pattern is verified against a salted crypt_r hash (yescrypt $y$ , falling back to sha512crypt $6$ ) at $XDG_DATA_HOME/att_lock/pattern.hash, mode 0600, dir 0700. PAM is used only for the password fallback (auth_pam(), service from --pam-service, default login). Comparison uses the constant-time ct_streq(), and secrets (password buffer, crypt_data, hash input, first setup entry) are wiped with explicit_bzero() — preserve both when editing.

Three things about the stored hash are deliberate and load-bearing:

The hash input is att_lock:v3:<user>:<pattern>, not the bare pattern (auth_input()). The pattern space is tiny — only 43,680 four-dot sequences — so binding the hash to the account stops an attacker amortising one cracking run across users or machines.
Cost is set explicitly, ATT_YESCRYPT_COST 9 / ATT_SHA512_ROUNDS 600000, not the 0 "low default". Cost 9 measures ~0.22 s and ~258 MB here; 11 would be ~0.88 s and ~1 GB, and an allocation that large in the unlock path can fail on a memory-pressured machine — a user who cannot unlock is worse than a marginally cheaper hash. Re-measure before changing it.
The file is versioned: line 1 is ATT_HASH_MAGIC, line 2 the crypt string. Any change to the hash input must bump that tag, otherwise stored patterns silently stop verifying and the user is stuck at "Wrong pattern" forever. auth_hash_state() returns AUTH_HASH_STALE for an untagged or corrupt file and main() routes that into the setup flow.

Rendering (src/render.c) — wl_shm + Cairo only, no EGL/GPU. Two buffers per output with a busy flag driven by wl_buffer.release; buffer_get() reallocates on size change. Background images are PNG-only (Cairo's built-in loader).

Conventions

Linux kernel style: tabs, snake_case, opening brace on its own line for functions.
Wayland listener structs are exhaustive — unused events get (void)-cast no-op stubs rather than NULL entries.
Failure while locked must never unlock: lock_finished() sets running = false without calling unlock_and_destroy(), and main() exits non-zero when app.lock still exists.
Built with warning_level=2 and -D_GNU_SOURCE; keep the build warning-free.

7.2 KiB Raw Permalink Blame History Unescape Escape