4aa889f178
Introduces ReceiverAuthController with REST endpoints for envelope receiver authentication, replacing the previous web-based flow with a JSON API suitable for Blazor clients. Implements endpoints for status checking, access code validation, and TFA (SMS or authenticator) verification. Adds unified ReceiverAuthResponse and request models for consistent API responses. Includes detailed documentation and error handling, providing a modern, client-friendly authentication flow.
78 lines
2.8 KiB
C#
78 lines
2.8 KiB
C#
namespace EnvelopeGenerator.API.Models;
|
|
|
|
/// <summary>
|
|
/// Einheitliche Antwort des ReceiverAuthControllers.
|
|
///
|
|
/// WARUM ein einziges Response-Objekt für alle Endpunkte?
|
|
/// - Der Client braucht nur ein Format zu verstehen
|
|
/// - Der Status-String bestimmt, welche Felder relevant sind
|
|
/// - Entspricht dem, was der Web-Controller bisher über ViewData verteilt hat
|
|
///
|
|
/// Status-Werte und was sie bedeuten:
|
|
/// - "requires_access_code" → AccessCode-Eingabe zeigen
|
|
/// - "requires_tfa" → TFA-Code-Eingabe zeigen (nach AccessCode)
|
|
/// - "show_document" → Dokument laden und anzeigen
|
|
/// - "already_signed" → Info-Seite "Bereits unterschrieben"
|
|
/// - "rejected" → Info-Seite "Abgelehnt"
|
|
/// - "not_found" → Fehler-Seite "Nicht gefunden"
|
|
/// - "expired" → Fehler-Seite "Link abgelaufen"
|
|
/// </summary>
|
|
public class ReceiverAuthResponse
|
|
{
|
|
/// <summary>Aktueller Status des Empfänger-Flows</summary>
|
|
public required string Status { get; init; }
|
|
|
|
/// <summary>Titel des Umschlags (z.B. "Vertragsdokument")</summary>
|
|
public string? Title { get; init; }
|
|
|
|
/// <summary>Nachricht des Absenders</summary>
|
|
public string? Message { get; init; }
|
|
|
|
/// <summary>E-Mail des Absenders (für Rückfragen-Hinweis)</summary>
|
|
public string? SenderEmail { get; init; }
|
|
|
|
/// <summary>Name des Empfängers</summary>
|
|
public string? ReceiverName { get; init; }
|
|
|
|
/// <summary>Ob TFA für diesen Umschlag aktiviert ist</summary>
|
|
public bool TfaEnabled { get; init; }
|
|
|
|
/// <summary>Ob der Empfänger eine Telefonnummer hat (für SMS-TFA)</summary>
|
|
public bool HasPhoneNumber { get; init; }
|
|
|
|
/// <summary>Ob das Dokument nur gelesen werden soll (ReadAndConfirm)</summary>
|
|
public bool ReadOnly { get; init; }
|
|
|
|
/// <summary>TFA-Typ: "sms" oder "authenticator" (wenn Status = "requires_tfa")</summary>
|
|
public string? TfaType { get; init; }
|
|
|
|
/// <summary>Ablaufzeit des SMS-Codes (für Countdown-Timer)</summary>
|
|
public DateTime? TfaExpiration { get; init; }
|
|
|
|
/// <summary>Fehlermeldung (z.B. "Falscher Zugangscode")</summary>
|
|
public string? ErrorMessage { get; init; }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Request-Body für POST /api/receiverauth/{key}/access-code
|
|
/// </summary>
|
|
public class AccessCodeRequest
|
|
{
|
|
/// <summary>Der vom Empfänger eingegebene Zugangscode</summary>
|
|
public required string AccessCode { get; init; }
|
|
|
|
/// <summary>Ob SMS statt Authenticator bevorzugt wird</summary>
|
|
public bool PreferSms { get; init; }
|
|
}
|
|
|
|
/// <summary>
|
|
/// Request-Body für POST /api/receiverauth/{key}/tfa
|
|
/// </summary>
|
|
public class TfaCodeRequest
|
|
{
|
|
/// <summary>Der eingegebene TFA-Code (6-stellig)</summary>
|
|
public required string Code { get; init; }
|
|
|
|
/// <summary>"sms" oder "authenticator"</summary>
|
|
public required string Type { get; init; }
|
|
} |