fprint_fp3/lib.rs
1// SPDX-FileCopyrightText: 2026 fprintd (pure-Rust) contributors
2//
3// SPDX-License-Identifier: MIT OR Apache-2.0
4
5//! # fprint-fp3
6//!
7//! The FP3 fingerprint-template codec: the edge translator between libfprint/fprintd's
8//! on-disk `"FP3"` blob and the [`fprint_core::Print`] domain model.
9//!
10//! An FP3 blob is the three ASCII bytes `"FP3"` followed by a little-endian, normal-form
11//! GVariant value of type `(issbymsmsia{sv}v)` (see `docs/fp3-format.md`). Everything
12//! wire-specific — the magic, the GVariant signature, the Julian-day dates with their
13//! `G_MININT32` sentinel, the maybe-strings, the NBIS `(a(aiaiai))` payload — lives here
14//! and never leaks up into `fprint-core` (`ARCHITECTURE.md` principle 3).
15//!
16//! The public surface is `to_bytes` and `from_bytes`:
17//!
18//! ```
19//! use fprint_core::{Finger, Minutia, Print, Template};
20//!
21//! let print = Print::builder()
22//! .template(Template::Nbis(vec![vec![Minutia { x: 12, y: 34, theta: 90 }]]))
23//! .finger(Finger::RightIndex)
24//! .username("alice".to_string())
25//! .build();
26//!
27//! let bytes: Vec<u8> = fprint_fp3::to_bytes(&print)?;
28//! assert!(bytes.starts_with(fprint_fp3::MAGIC));
29//! assert_eq!(fprint_fp3::from_bytes(&bytes)?, print);
30//! # Ok::<(), fprint_fp3::Fp3Error>(())
31//! ```
32//!
33//! ## Round-trip
34//!
35//! `from_bytes(to_bytes(p))` reproduces `p` for every [`Print`](fprint_core::Print) whose
36//! `finger` is `Some` and whose `driver`/`device_id` are either `None` or non-empty. Outside
37//! that, two distinctions collapse because the wire cannot express them:
38//!
39//! * `finger: None` decodes as `Some(Finger::Unknown)` — the FP3 `y` byte has no "absent".
40//! * `driver`/`device_id` of `Some("")` decode as `None` — GVariant `s` is not nullable, so the
41//! empty string is the format's "unset".
42//!
43//! `tests/property.rs` states the exact law, collapse included, and sweeps it. `to_bytes` is
44//! partial for two further reasons of its own: [`Template::Undefined`](fprint_core::Template)
45//! has no on-disk form, and an [`EnrollDate`](fprint_core::EnrollDate) outside the Julian day's
46//! `i32` range has no encoding ([`Fp3Error::DateOutOfRange`]).
47//!
48//! The signature's reserved `a{sv}` metadata dictionary is not a data channel: libfprint always
49//! writes it empty, so `to_bytes` writes it empty and `from_bytes` ignores whatever it holds.
50//! Preserving a populated reserved dict would carry wire bytes inside the domain
51//! [`Print`](fprint_core::Print), which principle 3 forbids, so a non-conforming blob with a
52//! non-empty reserved dict decodes without it.
53
54#![forbid(unsafe_code)]
55#![deny(missing_docs)]
56
57mod codec;
58mod date;
59mod error;
60mod gvariant;
61
62pub use codec::{from_bytes, to_bytes};
63pub use error::{Fp3Error, Result};
64
65/// The FP3 container's leading magic bytes (`"FP3"`).
66pub const MAGIC: &[u8; 3] = b"FP3";
67
68/// The crate's essentials, for a single glob import.
69///
70/// Pulls in the two verbs, the error type and its [`Result`] alias:
71/// `use fprint_fp3::prelude::*;`.
72pub mod prelude {
73 pub use crate::{from_bytes, to_bytes, Fp3Error, Result};
74}