@spec approve_authorization(
  auth_req_id_hash :: String.t(),
  subject_id :: String.t(),
  scopes :: [String.t()]
) ::
  {:ok, Lockspire.Domain.CibaAuthorization.t()}
  | {:error, :not_found | :invalid_state | term()}

Approves a pending CIBA authorization request.

Transitions the authorization status to :approved and records the subject_id and final scopes.

Returns {:ok, CibaAuthorization.t()} on success, or {:error, reason} if the authorization is not found or is in an invalid state (e.g., already expired or denied).

@spec deny_authorization(auth_req_id_hash :: String.t(), reason :: String.t() | nil) ::
  {:ok, Lockspire.Domain.CibaAuthorization.t()}
  | {:error, :not_found | :invalid_state | term()}

Denies a pending CIBA authorization request.

Transitions the authorization status to :denied.

Returns {:ok, CibaAuthorization.t()} on success.