RedWizardsLab/EchoHub
1
0
Fork 0
mirror of https://github.com/RedWizardsLab/EchoHub.git synced 2026-09-04 08:36:11 +02:00
Code Issues 2 Packages Projects Releases 10 Wiki Activity

docs: Update documentation for 145 files

Browse Source 
Generated by AurionDocs
Job ID: 934f8c39-8082-4942-8d17-72ed8f5f8d50
Source commit: 40aea9a
This commit is contained in:
Hue
2026-07-23 11:44:20 +02:00
parent 40aea9a04b
commit 607217b314
144 changed files with 5098 additions and 6498 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/auriondocs/Synthesis/api-client-authentication.md
+12 -37
View File
@@ -1,54 +1,29 @@
# API client and authentication
# API client authentication
> How the EchoHub client authenticates with the server, handles tokens, and defines authentication DTOs.
> How the client authenticates with the server, including login, token refresh, and token usage across API calls.
This guide explains how the EchoHub client performs HTTP operations and manages authentication tokens, and it documents the DTOs the client uses when talking to the server. It focuses on the client-side [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md) as the central point for login/refresh/logout and common API operations, and the small set of DTOs and client callback interface the ApiClient consumes and produces. Read this when you need to understand which types carry credentials and tokens, how attachments and avatar uploads are represented, and where server-initiated events are delivered on the client.
A short, focused orientation to how the client authenticates to the server and then uses those credentials when making API calls. The three files described below show a single HTTP façade that owns token state and many API operations ([ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md)), plus the small immutable DTOs that carry credentials and message/attachment metadata between the client and server. Read these together to understand the runtime flow: sign in -> store tokens -> refresh when needed -> attach tokens to requests; and how message attachments are represented when uploaded or downloaded.
## ApiClient.cs
Implements token management and API calls to the EchoHub server.
Performs login, token refresh, and authenticated API calls.
The [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md) class is a high-level HTTP client that centralizes authentication lifecycle (LoginAsync, LoginWithRefreshTokenAsync, RefreshTokenAsync, LogoutAsync, SetTokens) and exposes token state via properties like Token, RefreshToken, and ExpiresAt. It provides helper methods for authenticated requests (AuthenticatedRequestAsync, AuthenticatedGetAsync, EnsureAuthenticated, GetValidTokenAsync) and common server operations surfaced to callers: channel and message management (CreateChannelAsync, DeleteChannelAsync, SendMessageWithAttachmentsAsync, DeleteMessageAsync, RekeyChannelAsync, NukeChannelAsync), moderation actions (AssignRoleAsync, BanUserAsync, KickUserAsync, MuteUserAsync, UnbanUserAsync, UnmuteUserAsync), profile and upload flows (UploadAvatarAsync, DownloadFileToTempAsync, UpdateProfileAsync, ExportMyDataAsync, DeleteMyAccountAsync), and utilities for handling file content types (GetContentType). The ApiClient implements IDisposable (Dispose) and contains response handling helpers (EnsureSuccessAsync) so callers get a single, managed surface for HTTP/authorization concerns. According to its relationships it depends on the DTO definitions in [AuthDtos](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md), [ChatDtos](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md), [ModerationDtos](../Code/src/EchoHub.Core/DTOs/ModerationDtos.cs.md), and [ProfileDtos](../Code/src/EchoHub.Core/DTOs/ProfileDtos.cs.md); in practice the ApiClient serializes and deserializes instances of those DTOs when calling corresponding endpoints and when returning structured results to its callers.
The [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md) is a sealed, disposable HTTP façade that centralizes authentication state (access token, refresh token, and expiration) and exposes the concrete operations the UI or other client code calls. The doc lists properties and members such as `BaseUrl`, `Token`, `RefreshToken`, `SetTokens`, and lifecycle helpers like `Dispose`, plus auth-focused methods `LoginAsync`, `LoginWithRefreshTokenAsync`, `RefreshTokenAsync`, and `GetValidTokenAsync` — these are the explicit entry points for establishing and renewing credentials. For making requests it provides `AuthenticatedRequestAsync` and `AuthenticatedGetAsync` (and `EnsureAuthenticated` / `EnsureSuccessAsync`) to attach the current token and validate responses; higher-level API operations are implemented as methods like `SendMessageWithAttachmentsAsync`, `DownloadFileToTempAsync`, `UploadAvatarAsync`, and many channel/user management calls (e.g., `CreateChannelAsync`, `BanUserAsync`, `AssignRoleAsync`). Within this topic the `ApiClient` depends on the DTO types defined in the other files to marshal request and response payloads (see relationships: depends on ChatDtos.cs, AuthDtos.cs) and therefore hands off typed payloads like `LoginRequest`/`LoginResponse` and `AttachmentDto` when calling the server.
## AuthDtos.cs
Defines login request data structure used to authenticate.
Defines the login response DTO used by the API client.
The [AuthDtos](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md) file defines the transport types used by the authentication endpoints: the immutable positional [LoginRequest](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md) record carrying Username and Password, the [LoginResponse](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md) record that bundles Token, RefreshToken, ExpiresAt and basic user identity fields, plus a [RefreshRequest](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md) and [RegisterRequest](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md). These DTOs are pure data containers (no business logic) intended to be serialized over HTTP; the documentation calls out that Password is sensitive and that LoginResponse is what clients consume to establish an authenticated session. The ApiClient uses these DTOs when performing login and token-refresh flows (see relationships: used by ApiClient.cs).
## AuthDtos.cs (LoginResponse)
Represents server response after authentication including tokens.
The [LoginResponse](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md) record is the structured server reply to a successful authentication, containing the short-lived Token, the RefreshToken, an ExpiresAt timestamp, and identifying fields like Username with optional display personalization. Clients (like the [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md)) consume LoginResponse to populate their in-memory token state and to drive expiration/refresh logic; because it contains the expiry moment, consumers can decide when to call RefreshTokenAsync or LoginWithRefreshTokenAsync instead of issuing unauthenticated requests.
## AuthDtos.cs (RefreshRequest)
Represents refresh token request for renewing authentication.
The [RefreshRequest](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md) is the DTO used to request new authentication tokens from the server using a refresh token. It is the lightweight, immutable payload the ApiClient will serialize when it invokes its refresh endpoint (RefreshTokenAsync / LoginWithRefreshTokenAsync) so the server can validate the refresh token and return a new [LoginResponse](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md).
## IEchoHubClient.cs
Interface for EchoHub client surface used by ApiClient to perform operations.
The [IEchoHubClient](../Code/src/EchoHub.Core/Contracts/IEchoHubClient.cs.md) interface defines the callback surface that a client implementing the real-time hub must provide: methods such as ReceiveMessage(MessageDto), UserJoined(channelName, username, UserPresenceDto?), UserLeft, ChannelUpdated(ChannelDto), UserStatusChanged, UserKicked, UserBanned, MessageDeleted, ChannelDeleted, ChannelNuked, ForceDisconnect, and Error. The doc shows example minimal implementations that log or handle these events quickly and non-blockingly. While the ApiClient handles HTTP and token management, this interface is the typed contract used by any hub/transport layer to deliver server-initiated events to client code; the relationship shows IEchoHubClient depends on DTO types like those in [ChatDtos](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) and [ProfileDtos](../Code/src/EchoHub.Core/DTOs/ProfileDtos.cs.md), which are delivered through these callbacks.
This file contains small immutable records that model the authentication payloads the client sends and receives. Notably, `LoginRequest(string Username, string Password)` packages credentials for `LoginAsync` calls, and `LoginResponse(string Token, string RefreshToken, DateTimeOffset ExpiresAt, string Username, string? DisplayName, string? NicknameColor)` is the typed response carrying the `Token`, `RefreshToken`, and `ExpiresAt` values that the [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md) stores and uses to authorize subsequent requests. There are also `RefreshRequest` and `RegisterRequest` records for refresh and registration flows; these DTOs are value objects (records) intended for transport only and are the direct inputs/outputs used by ApiClient methods like `LoginAsync`, `RefreshTokenAsync`, and `LoginWithRefreshTokenAsync` as the source of truth for token state.
## ChatDtos.cs
`AttachmentDto` collaborates directly with `ApiClient` and other members of this topic (10 dependency links).
`AttachmentDto` collaborates directly with `ApiClient` and other members of this topic (8 dependency links).
The [ChatDtos](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) file defines message and channel payloads used across both HTTP API and hub callbacks. In particular, the [AttachmentDto](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) record carries Kind (AttachmentKind), Url, FileName, FileSize, and an optional AsciiPreview; it represents a message attachment's metadata and is the shape ApiClient sends or receives when uploading, downloading, or rendering attachments. Other DTOs in the same file (MessageDto, ChannelDto, ChannelMetaDto, SendMessageRequest, SendUrlRequest, ReplyRefDto, etc.) are the structured inputs and outputs ApiClient uses for channel operations and that appear on the [IEchoHubClient](../Code/src/EchoHub.Core/Contracts/IEchoHubClient.cs.md) callbacks. The docs note an important detail: in end-to-end encrypted channels the content behind the Url (and previews) may be ciphertext opaque to the server, which affects how clients process the Url returned in AttachmentDto.
## ModerationDtos.cs
`AssignRoleRequest` collaborates directly with `ApiClient` and other members of this topic (4 dependency links).
The [ModerationDtos](../Code/src/EchoHub.Core/DTOs/ModerationDtos.cs.md) file provides small, immutable payloads for moderation actions; the [AssignRoleRequest](../Code/src/EchoHub.Core/DTOs/ModerationDtos.cs.md) record carries a Username and a ServerRole value and is intended to be sent to moderation endpoints to request a role change. The file also contains BanRequest, KickRequest, and MuteRequest records used for banning, kicking, and muting operations. The ApiClient serializes these DTOs when invoking its moderation methods (AssignRoleAsync, BanUserAsync, KickUserAsync, MuteUserAsync), so moderation actions are expressed as data objects across the HTTP boundary.
## ProfileDtos.cs
`AvatarUploadResponse` collaborates directly with `ApiClient` and other members of this topic (4 dependency links).
The [ProfileDtos](../Code/src/EchoHub.Core/DTOs/ProfileDtos.cs.md) file defines small user-profile payloads used by profile/update and avatar upload endpoints. The [AvatarUploadResponse](../Code/src/EchoHub.Core/DTOs/ProfileDtos.cs.md) record holds AvatarAscii, the ASCII-art representation returned after an avatar upload; ApiClient's UploadAvatarAsync returns or deserializes this DTO so callers can display or store the ASCII preview. UpdateProfileRequest and UpdateStatusRequest are optional-field records used for partial profile updates and are the payloads ApiClient will send via UpdateProfileAsync.
`ChatDtos.cs` defines the message- and channel-related transport shapes that the [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md) consumes and returns. The `AttachmentDto(AttachmentKind Kind, string Url, string FileName, long FileSize, string? AsciiPreview = null)` record encapsulates an attachment's metadata: a retrieval `Url`, `FileName`, `FileSize`, and optional `AsciiPreview`. The file also contains `SendMessageRequest`, `SendUrlRequest`, `ChannelDto`, `ChannelMetaDto`, `MessageDto`, `UserDto`, and `ChannelCryptoDto` among others; these records are the concrete payloads `ApiClient` methods accept and return for operations such as `SendMessageWithAttachmentsAsync`, `SendUrlAsync`, `GetChannelMetaAsync`, and `DownloadFileToTempAsync`. In practice the `AttachmentDto.Url` is the link the client will follow (via `DownloadFileToTempAsync`) to retrieve an attachment and the structured send requests are the bodies used by the ApiClient when posting messages or creating channels.
How the pieces fit
The ApiClient is the HTTP façade: it consumes and produces the DTOs in AuthDtos, ChatDtos, ModerationDtos, and ProfileDtos when calling server endpoints and populating client state. Authentication flows center on the LoginRequest/LoginResponse/RefreshRequest DTOs and ApiClient methods that set and refresh Token/RefreshToken and expose helpers like GetValidTokenAsync and EnsureAuthenticated. Separately, real-time server-to-client events are delivered through the [IEchoHubClient](../Code/src/EchoHub.Core/Contracts/IEchoHubClient.cs.md) callback interface using the same Chat and Profile DTOs, keeping transport and event handling decoupled while the ApiClient handles request/response semantics and token lifecycle.
The runtime collaboration is straightforward: the [ApiClient](../Code/src/EchoHub.Client/Services/ApiClient.cs.md) is the orchestrator that holds token state emitted by the auth DTOs (e.g., [LoginResponse](../Code/src/EchoHub.Core/DTOs/AuthDtos.cs.md)). Callers invoke `LoginAsync`/`LoginWithRefreshTokenAsync` to obtain or restore that state, `GetValidTokenAsync`/`RefreshTokenAsync` to keep it current, and the client then uses `AuthenticatedRequestAsync`/`AuthenticatedGetAsync` to attach the access token to calls. For message and file operations the ApiClient sends and receives the chat records from [ChatDtos.cs](../Code/src/EchoHub.Core/DTOs/ChatDtos.cs.md) — for example, `AttachmentDto` conveys the `Url` and metadata that `DownloadFileToTempAsync` and `SendMessageWithAttachmentsAsync` operate on — so DTOs remain passive carriers while ApiClient implements the network and auth behavior that uses them.
---
*Covers 8 of 8 source files identified for this topic.*
*Covers 3 of 3 source files identified for this topic.*
*Synthesised by Aurion on 2026-07-23 05:50:51 UTC*
*Synthesised by AurionDocs on 2026-07-23 09:30:19 UTC*