Authentication

Ferrite Auth is the source package for adding UI-neutral identity policy and browser-session primitives to system and user-space apps. It separates authentication—who the subject is and how they authenticated—from application authorization such as roles, ownership, and tenant membership.

Add embedded authentication

ferrite add ferrite-auth
ferrite check
ferrite test

The package requires an APE binding for atomic identity state, a Queue binding for bounded background work, an /api/auth/ route that forwards cookie and x-csrf-token, and an auth-root secret. ferrite check refuses missing authority instead of substituting local storage or an external database.

use crate::ferrite_auth::{
    issue_browser_session, validate_csrf, verify_browser_session,
};

let session = issue_browser_session(
    &ctx.entropy(),
    &auth_root,
    &subject,
    credential_generation,
    ctx.now_ms(),
    8 * 60 * 60 * 1_000,
)?;
let [session_cookie, csrf_cookie] = session.cookie_headers(8 * 60 * 60 * 1_000)?;

Browser session contract

• The bearer exists only in a Secure, HttpOnly, host-only __Host-ferrite-auth-session cookie.
• JSON returns expiry and view state, never the bearer.
• A separate readable CSRF value is MAC-bound to the session and required on unsafe requests.
• Login, reauthentication, privilege change, and tenant change rotate the session.
• Password, factor, recovery, and directory deactivation can revoke all affected sessions through a credential generation.

Do not copy a browser bearer into localStorage, sessionStorage, URLs, logs, MCP, or an agent tool result.

Assurance policy

Ferrite Auth models method traits and recency rather than one mfa boolean. Your verifier records AssuranceEvidence; the protected action declares an AssuranceRequirement such as user verification, phishing resistance, a second factor, or a maximum authentication age.

Use AssuranceRequirement to enforce the evidence traits and recency required by each protected action. A general login does not silently satisfy a stronger action policy.

Resets and action links

Use ferrite_app::auth::ActionTokenService for password resets, email verification, invitations, and recovery. Tokens are purpose-bound, digest-stored, expiring, attempt-bounded, and single-use. Persist each versioned mutation with a guarded Ferrite state write before performing the protected action.

A GET displays confirmation but does not consume a link; a user-initiated POST performs the atomic consume. Password reset does not auto-login and can revoke all sessions.

The Shop demonstrates the embedded session and CSRF contract. Its order ownership, admin role, Stripe validation, and inventory rules remain app authorization, not Ferrite Auth policy.