Crate watchword 

Authentication for axum servers and Yew frontends: password, Cloudflare Access and Google sign-in, sessions and user management.

The design, including the full API each layer grows into, is in docs/design.md.

Features

Each layer sits behind a cargo feature, so an app takes only what it uses. Server-only and browser-only dependencies never share a feature, so a wasm frontend can take yew023 without pulling in server code. Only std is on by default. On docs.rs, items that need a feature are marked with it.

The crate is no_std. With default-features = false and neither std nor alloc, it has only the plain types (UserId, Role, Access, Method, Conflict, AuthConfig, MIN_PASSWORD_LEN, is_same_origin_path); alloc adds the rest of types. The server layers and yew023 imply std.

A dependency that is not yet 1.0 and appears in the API is named after its version: its feature (and module, if it has one) is axum08 for axum 0.8, sqll015 for sqll 0.15, musli02 for musli 0.2, musliweb05 for musli-web 0.5, phrasebookcatalog01 for phrasebook-catalog 0.1 and yew023 for yew 0.23. A later version is added beside it, so a watchword upgrade never forces an app onto a new axum, sqll, musli, musli-web, phrasebook-catalog or yew, and an app moves when it chooses.

Feature	Module	What it provides
(none)	types	UserId, Role, Access, Method, Conflict, AuthConfig, MIN_PASSWORD_LEN and is_same_origin_path, from the watchword-core crate
alloc	types	the wire types (UserInfo, LoginRequest, CreatedUser, …), AuthError and its Invalid reasons, validate_password, normalize_email
std (default)		alloc, and the standard library for the dependencies that have it
musli02		musli 0.2 Encode/Decode on the types
musliweb05	musliweb05	for musli-web 0.5: the account, user-management and Cloudflare Access settings endpoints and the AuthBroadcast of live auth changes, as API types an app carries on its own musli-web WebSocket, with their ids pinned in 32000–32255; with axum08, Connection, which answers those endpoints on one socket and turns AuthEvents into the updates it may see; with yew023, AuthContext::set_socket, through which the components follow those broadcasts (implies alloc and musli02)
server	core, store	bcrypt password hashing with dummy_hash timing, session ids and link tokens, HMAC-signed session cookies; the Auth service (sign-in, registration links, user management, sign-in throttle, AuthEvents and actor-attributed AuditEvents, bootstrap admin) and Auth::guard for WebSocket sessions; the Store trait and MemoryStore (implies std)
cloudflare	cloudflare	Cloudflare Access JWT verification with a pluggable KeyFetcher; Auth::cloudflare and Auth::set_cloudflare, which keep the settings in the store; with axum08, admin routes for them (implies server)
google	google	Google OAuth: GoogleConfig::new for AuthBuilder::google; with axum08, routes() serves its start, registration, account-switch and callback routes (implies server)
axum08	axum08	for axum 0.8: the SignedIn, Admin, MaybeSignedIn and LiveSession extractors and routes() for the /api/auth JSON routes, plus the Cloudflare and Google routes when those features are on (implies server)
sqll015		sqll 0.15 BindValue, Bind and FromColumn on UserId (an integer with the same bits), Role, Access and Method (their names), from the watchword-core crate, for an app’s own Store over SQLite such as examples/sqll-store; no storage of its own
test-util	store_suite!, google::fake	for an app’s tests: Auth::test_user and Auth::test_session, an active user and a session without signing in; store_suite!, watchword’s store conformance suite, to run over the app’s own Store; with google, AuthBuilder::google_endpoints, and with google and axum08 also FakeGoogle, a local fake Google to sign in through offline (implies server)
phrasebookcatalog01	phrasebookcatalog01	L10N, watchword’s messages (the text of the yew023 components) as a phrasebook-catalog 0.1 catalog, which phrasebook 0.2 takes, for a native tool such as an app’s localization checker that needs them without building yew, from the watchword-core crate (needs neither std nor alloc)
yew023	yew023	for yew 0.23: AuthProvider, use_auth, SignIn, Register, AccountPanel, UserMenu, AdminUsers, AdminCloudflare, CloudflareSettings, the http client and L10N, the components’ messages as a phrasebook catalog, from the watchword-yew023 crate (implies std and phrasebookcatalog01)

The most-used names that do not depend on a versioned feature are re-exported at the crate root.

Using it

Add it from crates.io with the features each crate needs. An app whose frontend talks to its server over a musli-web 0.5 WebSocket, as the example app does, takes musliweb05 on both sides: the server answers the components’ requests and sends them live updates on that socket, and the frontend hands the socket to the components. An app that uses only HTTP leaves it out of both.

# The server crate.
[dependencies]
watchword = { version = "0.3", features = ["axum08", "cloudflare", "google", "musliweb05"] }

[dev-dependencies]
watchword = { version = "0.3", features = ["test-util"] }

# The frontend crate, built for wasm32-unknown-unknown.
[dependencies]
watchword = { version = "0.3", features = ["yew023", "musliweb05"] }

Take only the sign-in methods the app offers: cloudflare and google each add one, and password sign-in is always there. test-util, under dev-dependencies, gives the app’s tests users and sessions without going through sign-in, and the store conformance suite.

Storage

watchword keeps users, sessions, registration links and settings through the Store trait, which each app implements over its own database, with its own tables and migrations: the shape of user data differs between apps, and only the app knows how to fill its own columns. watchword ships no tables or migrations, only MemoryStore, which keeps everything in memory, for tests and trying things out.

Start from examples/sqll-store, a complete Store over SQLite with sqll 0.15 (taking the sqll015 feature), and change its tables to the app’s. The Store docs say what each method must do atomically, and the store conformance suite, store_suite! (feature test-util), checks the result from the app’s tests:

cargo test --example sqll-store --features test-util,sqll015

The examples here refer to the crate as watchword. An app may give the dependency a shorter key, such as auth = { package = "watchword", ... }, and then writes auth:: where these docs write watchword::.

Then build an Auth over a store and serve its routes, as the axum08 module shows, and wrap the frontend in AuthProvider, as the yew023 module shows.

Example app

examples/app is an axum server and a Yew frontend wired up with all three sign-in methods, MemoryStore and a musli-web WebSocket held open for the session, which carries the components’ account and admin requests and live updates beside the app’s own API (musliweb05): a reference for apps taking the library, and a way to try the components by hand. It is its own cargo workspace, so it adds nothing to the library’s builds or lockfile.

Build the frontend with trunk, then run the server, which serves it:

cd examples/app/frontend && trunk build
cd examples/app && cargo run -p watchword-example-server -- --bind 127.0.0.1:8080

The server prints a registration link for the bootstrap admin (admin by default, --bootstrap-admin NAME to change it); open it to choose a password and sign in. Everything is in memory, so a restart starts over. Google sign-in is on when GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set, with the OAuth client’s redirect URL at PUBLIC_URL/api/auth/google/redirect (--public-url, by default http:// plus the bind address). Cloudflare Access is configured on the app’s Settings page, which watchword serves, or from CLOUDFLARE_TEAM_DOMAIN and CLOUDFLARE_AUDIENCE until saved there; CLOUDFLARE_TRUST_EMAIL_HEADER=1 accepts Access’s email header alone, for local testing only. --help lists the options.

trunk builds with the wasm-bindgen CLI matching examples/app/Cargo.lock, downloading it unless it is installed or already in trunk’s cache.

Re-exports

pub use self::core::Actor;server

pub use self::core::AuditEvent;server

pub use self::core::Auth;server

pub use self::core::AuthBuilder;server

pub use self::core::AuthEvent;server

pub use self::core::Bootstrap;server

pub use self::core::BootstrapAdmin;server

pub use self::core::CookieConfig;server

pub use self::core::PasswordError;server

pub use self::core::SESSION_LIFETIME;server

pub use self::core::Secure;server

pub use self::core::SessionGuard;server

pub use self::core::TOKEN_LIFETIME;server

pub use self::core::dummy_hash;server

pub use self::core::generate_session_key;server

pub use self::core::hash_password;server

pub use self::core::is_expired;server

pub use self::core::load_or_create_key;server

pub use self::core::new_session_id;server

pub use self::core::new_token;server

pub use self::core::session_cookie;server

pub use self::core::session_expiry;server

pub use self::core::token_expiry;server

pub use self::core::verify_password;server

pub use self::core::verify_session_cookie;server

pub use self::store::MemoryStore;server

pub use self::store::Store;server

pub use self::google::GoogleConfig;google

pub use self::google::GoogleConfigError;google

Modules

axum08axum08

axum 0.8 integration (the axum08 feature): extractors and the /api/auth JSON routes. A WebSocket watches its session with Auth::guard, which needs no axum.

cloudflarecloudflare

Identifying users behind Cloudflare Access.

coreserver

The server core: password hashing, session ids and link tokens, signed session cookies, and the Auth service that enforces the sign-in and user-management rules over a Store.

googlegoogle

Signing in with Google OAuth (the google feature).

musliweb05musliweb05

watchword’s account and user-management operations, and its live updates, as musli-web 0.5 API types, so an app can carry them on the musli-web WebSocket it already has.

phrasebookcatalog01phrasebookcatalog01

watchword’s messages as a phrasebook-catalog 0.1 catalog, L10N.

storeserver

Storage of users, sessions, link tokens and settings: the Store trait, the records it stores, and MemoryStore.

types

yew023yew023

Macros

store_suitetest-util

Defines the store conformance suite over a Store: one #[test] function per test of Auth that depends on what a store keeps, each over a fresh store made by the expression given. The expression is evaluated inside the test’s async context, so it may .await, and the store must be Clone, its clones sharing their records.

Structs

AuthConfig

What the sign-in page offers, from GET /api/auth/config.

CloudflareConfigalloc

The Cloudflare Access settings an app stores and edits.

CreatedUseralloc

The answer to POST /api/auth/users: the new user and their registration link, whose token is shown only this once.

Impersonatoralloc

The admin behind an impersonated session; see UserInfo::impersonated_by.

Linkalloc

A registration or reset link’s token, shown once when issued.

LoginRequestalloc

The body of POST /api/auth/login.

NewUseralloc

A user to create. At least one of login and email is required.

PasswordChangealloc

The body of POST /api/auth/account/password.

RegisterInfoalloc

What a registration or reset link is for, from GET /api/auth/register/{token}.

RegisterRequestalloc

The body of POST /api/auth/register/{token}.

UserChangealloc

A change to a user. None leaves a field as it is; Some(None) clears an optional one.

UserEntryalloc

A user in the admin list.

UserId

A user’s id. Apps convert to and from their own u64 ids with new and get or From, and to and from signed integers with TryFrom, which fails on a value out of the other’s range. With the sqll015 feature it binds and reads as a sqll column directly.

UserInfoalloc

What the frontend and the admin pages see of a user.

Enums

Access

A user’s account state.

AuthErroralloc

The error of an /api/auth route, sent as the JSON body of its 4xx response, such as {"error":"conflict","detail":"email"} or {"error":"invalid","detail":{"reason":"password_too_short","min":8}}.

Conflict

Which unique field a change conflicts on.

Invalidalloc

Why a request is invalid, the detail of AuthError::Invalid.

Method

The credential a user has stored. A user has exactly one, and can switch between them. Cloudflare Access is not a stored credential.

Role

A user’s role.

Constants

MIN_PASSWORD_LEN

The shortest password validate_password accepts, in bytes.

Functions

is_same_origin_path

Whether path, a ?next= value once decoded, is a path on this origin, and so safe to send a browser to after signing in.

normalize_emailalloc

Trims and lowercases an email so lookups and comparisons are case-insensitive.

validate_passwordalloc

Returns why the password is not acceptable, if it is not.