Skip to main content

passkey_rp/
lib.rs

1//! A small, pure Rust Passkey and `WebAuthn` relying-party verification core.
2//!
3//! `passkey-rp` verifies decoded server-side ceremony responses without
4//! depending on OpenSSL. Its deliberately narrow profile supports ES256
5//! credentials on P-256 and registration with the `none` attestation format.
6//! Unsupported algorithms and attestation formats fail closed.
7//!
8//! The crate does not create browser options, provide HTTP handlers, store
9//! ceremony state, authorize accounts, or implement account recovery. Device
10//! provenance and attestation trust are also out of scope.
11//!
12//! # Ceremony workflow
13//!
14//! 1. Construct a [`RelyingParty`] and reuse its [`PasskeyRp`] verifier.
15//! 2. Generate a [`Challenge`] and store it with the expected ceremony type,
16//!    account, user-verification policy, and a short expiration.
17//! 3. Decode the browser response's base64url fields into bytes.
18//! 4. Build [`RegistrationVerification`] or [`AuthenticationVerification`] and
19//!    call the matching verifier method.
20//! 5. Consume the challenge exactly once. Persist the returned
21//!    [`StoredCredential`] only after successful verification.
22//!
23//! Authentication requires an explicit [`UserHandleVerification`] so the
24//! response is bound to trusted server-side account state. User verification is
25//! required by default; use [`UserVerificationPolicy::Preferred`] only when the
26//! same policy was selected when the ceremony began.
27//!
28//! # Security responsibilities
29//!
30//! The caller must authorize registration, enforce credential-ID uniqueness
31//! within the relying party, rate-limit attempts, and protect ceremony state
32//! against tampering and replay. Authentication success and the updated
33//! credential returned by [`VerifiedAuthentication::into_credential`] must be
34//! committed atomically; concurrent updates must not move the stored signature
35//! counter backwards.
36//!
37//! Client extension results are not accepted by this API. Authenticator
38//! extension CBOR is checked for structural validity but not interpreted. If an
39//! application relies on an extension, it must validate both the signed
40//! authenticator output and corresponding client output separately.
41//!
42//! # Creating a verifier
43//!
44//! ```rust
45//! use passkey_rp::{Challenge, PasskeyRp, RelyingParty};
46//!
47//! let rp = PasskeyRp::new(RelyingParty::new(
48//!     "example.com",
49//!     "https://example.com",
50//! )?);
51//! let challenge = Challenge::generate()?;
52//!
53//! assert_eq!(rp.relying_party().id(), "example.com");
54//! assert_eq!(challenge.as_bytes().len(), 32);
55//! # Ok::<(), passkey_rp::PasskeyError>(())
56//! ```
57#![forbid(unsafe_code)]
58#![deny(missing_docs, rustdoc::all)]
59#![warn(
60    clippy::doc_markdown,
61    clippy::missing_errors_doc,
62    clippy::missing_panics_doc
63)]
64#![cfg_attr(
65    not(test),
66    deny(
67        clippy::dbg_macro,
68        clippy::expect_used,
69        clippy::panic,
70        clippy::todo,
71        clippy::unimplemented,
72        clippy::unreachable,
73        clippy::unwrap_used
74    )
75)]
76mod attestation;
77mod authenticator;
78mod base64url;
79mod challenge;
80mod client_data;
81mod cose;
82mod error;
83mod rp;
84
85pub use base64url::{decode_base64url, encode_base64url};
86pub use challenge::{CHALLENGE_LENGTH, Challenge};
87pub use cose::{CoseAlgorithm, PublicKey};
88pub use error::PasskeyError;
89pub use rp::{
90    AuthenticationVerification, CredentialBackupState, PasskeyRp, RegistrationVerification,
91    RelyingParty, StoredCredential, UserHandleVerification, UserVerificationPolicy,
92    VerifiedAuthentication, VerifiedRegistration,
93};