@spec browser_state_valid?(binary(), binary(), binary()) :: boolean()

Whether value is an OP browser-state string this OP minted (under secret) for the current login_binding.

Returns false — so the caller mints a fresh value — when either:

• the value is malformed or its MAC does not verify: a value the OP never minted (a forged / cross-origin-injected cookie), which must not be trusted as authoritative browser state; or
• the MAC verifies but the embedded login_tag is for a different login state: the End-User re-authenticated or switched accounts, so the OP browser state MUST rotate (Session Management 1.0 §3.2) and any earlier RP session_state becomes changed.

Both comparisons go through Attesto.SecureCompare.equal?/2, so neither reveals HOW the presented value differs - wrong length, or right length and wrong bytes, take the same path. The segments come from an attacker-supplied string and are not length-validated first, so the time taken still varies with how much was submitted; see that module for the distinction.

Raises ArgumentError if secret is shorter than the 32-byte floor mint_browser_state/2 enforces (RFC 2104 §3).

@spec compute(String.t(), String.t(), String.t(), String.t()) :: String.t()

Compute the session_state for an authorization response (§3.2).

origin must be a browser-form origin (scheme://host[:port], default port omitted) — derive it from the response's redirect_uri with origin/1. salt defaults to a fresh generate_salt/0.

Raises ArgumentError if an explicit salt is empty or contains a space (§2 forbids a space in session_state) or a . (the hash "." salt delimiter). generate_salt/0 always satisfies this.

@spec generate_browser_state() :: String.t()

A fresh OP browser state value.

The host stores it in a JavaScript-readable cookie at the OP origin (§3.2 — the check_session_iframe script must read it, so HttpOnly cannot be set) and changes it when the End-User's login state changes (login/logout).

@spec generate_salt() :: String.t()

A fresh random salt for compute/4 (unpadded URL-safe Base64, no spaces or dots).

@spec mint_browser_state(binary(), binary()) :: String.t()

Mint an OP browser-state value that is OP-owned and bound to the End-User's current login state (see the module doc).

secret is an OP-only HMAC key; login_binding is a caller-chosen string that captures the current login state (e.g. subject, auth_time, and sid joined together). The returned random . login_tag . mac string contains no space or .-ambiguity in its parts (each part is base64url-no-pad), so it is a valid op_browser_state for compute/4 and splits back cleanly in browser_state_valid?/3.

Raises ArgumentError if secret is shorter than 32 bytes — an enforced key-length floor (RFC 2104 §3) for the HMAC that makes the value OP-owned. browser_state_valid?/3 enforces the same floor.

@spec origin(String.t()) :: {:ok, String.t()} | {:error, :invalid_uri}

The browser-form origin of uri (RFC 6454): scheme://host, with the port appended only when it is not the scheme's default — exactly the string the browser reports as MessageEvent.origin for a page loaded from uri.

The value must equal the browser's WHATWG MessageEvent.origin, or the iframe recomputation compares unequal and the OP answers a permanent, false changed (a fail-safe error - it over-reports change, never under-reports). URI.parse/1 (RFC 3986) diverges from the browser; this closes the two divergences a registered redirect_uri realistically hits:

• case — the browser lowercases the scheme and host; URI.parse/1 preserves them (https://RP.Example), so both are lowercased here.
• IPv6 — the browser serializes an IPv6 host in brackets (https://[::1]); URI.parse/1 strips them (host: "::1"), so a literal host (one containing :) is re-bracketed here.

This is NOT a full WHATWG serializer. The input is expected to be an already-validated, canonical HTTP(S) redirect_uri; noncanonical forms are left as-is and would still diverge (each yielding only the fail-safe false changed, never a security bypass):

• a non-canonical IPv6 spelling ([0:0:0:0:0:0:0:1] vs the browser's compressed [::1]) or a non-dotted-decimal IPv4 (0177.0.0.1);
• a raw non-ASCII host — full IDNA Unicode→punycode mapping is out of scope (a registered redirect_uri is already ASCII/punycode);
• a non-HTTP(S) scheme, whose browser origin is the opaque null.

Returns {:ok, origin} or {:error, :invalid_uri} for a URI with no scheme/host (a session_state computed over a malformed origin could never compare equal in the browser, so fail closed instead).