# Authentication

Add Ferrite-native subjects, opaque browser sessions, CSRF protection, password policy, recovery actions, and assurance checks to an app.

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

```bash
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.

```rust filename="src/auth.rs"
use crate::ferrite_auth::{
    issue_browser_session, validate_csrf, verify_browser_session, OpaqueSubject,
};

let subject = OpaqueSubject::derive(
    auth_root.as_bytes(),
    "shop",
    external_user_id,
);
let session = issue_browser_session(
    &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_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](/developers/apps/) demonstrates the embedded session and CSRF
contract. Its order ownership, admin role, Stripe validation, and inventory
rules remain app authorization, not Ferrite Auth policy.