🐛 Fix / IdP-initiated flow never completes — validate_authresp returns bare :ok

[docJerem]

Closes #24.

Context

ExSaml.SPHandler.consume_signin_response/2 calls validate_authresp/4 in a with clause that pattern-matches {:ok, nonce}. The SP-initiated clause complied ({:ok, nonce}), but the IdP-initiated clause returned the bare atom :ok. The mismatch fell through to the _ -> {:error, :access_denied} catch-all, so any IdP posting a Response with an empty InResponseTo was rejected with access_denied — even when allow_idp_initiated_flow: true.

In other words: the IdP-initiated success path was effectively dead code. The guard rails (:idp_first_flow_not_allowed, :invalid_target_url) worked correctly, but the happy path never returned a usable result.

This was not strictly a regression — the feature allow_idp_initiated_flow had simply never been wired through to the end. The absence of a test on this clause let it slip.

Changes

1. Fix — validate_authresp/4 now returns {:ok, flow, nonce} on success, where:

   • flow is :idp_initiated or :sp_initiated
   • nonce is nil for IdP-initiated (no AuthnRequest exists to bind a nonce to), the SAML nonce for SP-initiated.

2. Add flow: to the success map — consume_signin_response/2 now returns %{flow: flow, assertion: …, nonce: …, user_token: …, redirect_uri: …}. Consumers no longer have to deduce the flow type from nonce == nil or assertion.subject.in_response_to == "". Adding a map field is non-breaking for consumers that only pattern-match the fields they use.

3. Rename :idp_first_flow_not_allowed → :idp_initiated_not_allowed — aligns the atom with standard SAML terminology used everywhere else in the module. A grep across the Cryptr consumer projects (cryptr_platform_beta, cryptr_api, cryptr_gateway) confirmed none of them pattern-match the old atom in application code, so the rename has no internal blast radius.

4. Tests — added test/ex_saml/sp_handler_test.exs covering the four validate_authresp/4 paths (previously uncovered): IdP-initiated success / :idp_initiated_not_allowed / :invalid_target_url, SP-initiated success + :invalid_relay_state / :invalid_idp_id.

5. Doc — consume_signin_response/2's @doc updated to reflect the new success shape and to enumerate the possible error reasons.

⚠️ Breaking changes (for release notes)

This PR does not touch the CHANGELOG — that will be done on the release branch. To capture for release notes:

• Public return shape change: consume_signin_response/2 success map now includes flow: :idp_initiated | :sp_initiated. Consumers that match %{assertion: a, nonce: n} = result keep working; consumers that pattern-match a strict map (%{assertion: a, nonce: n} with = rather than <- in with body) are unaffected too. Only consumers explicitly enumerating map keys would notice.
• Public nonce semantics change: nonce is now nil for IdP-initiated flows. Downstream code consuming nonce (e.g. SAML nonce validators) must accept nil iff allow_idp_initiated_flow: true. Follow-up issues will track this in Cryptr consumers.
• Error atom rename: :idp_first_flow_not_allowed → :idp_initiated_not_allowed. Verified non-breaking for Cryptr consumers.

Test plan

• mix test — 206 tests, 0 failures
• mix compile --warnings-as-errors — clean
• Manual smoke: post an IdP-initiated SAMLResponse with empty InResponseTo against an SP configured with allow_idp_initiated_flow: true and verify the consumer receives {:ok, %{flow: :idp_initiated, nonce: nil, ...}} instead of {:error, :access_denied}.