ljrojas91/adas-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(iec62304): [REL-1.0.2] apply curated XML doc review updates

Browse Source
This commit is contained in:
n8n IEC 62304 Bot
2026-07-06 17:08:55 +02:00
parent 481d768ebd
commit 3101c53252
2 changed files with 116 additions and 159 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adas-core.LdapLogin/LdapLoginService.cs
+31 -32
View File
@@ -78,15 +78,14 @@ public class LdapLoginService : ILoginService
public UserEnum.LoginMethod Method => UserEnum.LoginMethod.Ldap;
/// <summary>
/// Authenticates a user against the LDAP server using the provided username and password.
/// Authenticates a user against the configured LDAP server using <paramref name="username"/> and <paramref name="password"/>, and resolves the matching <see cref="User"/> entry. When an LDAP service account is configured it is used for the bind; otherwise the username is optionally prefixed with the configured domain and bound with the supplied password. Searches the directory for the user entry and creates or retrieves the local <see cref="User"/> record.
/// </summary>
/// <param name="username">The username of the user to authenticate.</param>
/// <param name="password">The password of the user to authenticate.</param>
/// <returns>The authenticated user.</returns>
/// <exception cref="LoginServicesException">Thrown when there is an error during the login process.</exception>
/// <exception cref="UserNotFoundException">Thrown when the user is not found in the LDAP directory.</exception>
/// <!-- aidoc-review:v1 severity=high kind=wrong_exception
/// "UserNotFoundException is documented as thrown 'when the user is not found in the LDAP directory', but the code actually throws it from the catch (LdapException) block during the bind operation. The 'user not found in directory' case (empty search result) throws LoginServicesException, not UserNotFoundException." -->
/// <param name="username">The username used to bind to LDAP and to locate the user entry in the directory.</param>
/// <param name="password">The password used for the LDAP bind when no service account is configured.</param>
/// <returns>The <see cref="User"/> resolved from the LDAP directory entry.</returns>
/// <exception cref="LoginServicesException">Thrown when the LDAP server is not configured, when the directory entry is not found, or when the resolved user is null.</exception>
/// <exception cref="UserNotFoundException">Thrown when the LDAP bind fails for the supplied credentials.</exception>
/// <!-- aidoc:v1 sig=bdfb451 body=e3fc1ac -->
public async Task<User> Login(string username, string password)
{
if (_ldapConfig.Server == null)
@@ -158,25 +157,25 @@ public class LdapLoginService : ILoginService
}
/// <summary>
/// This method is not implemented in the LdapLoginService, as the login process is handled through the Login(string username, string password) method.
/// Authenticates a user based on the current <see cref="HttpContext"/>.
/// This method is not yet implemented and always throws a <see cref="LoginServicesException"/>.
/// </summary>
/// <param name="context">The HTTP context of the request.</param>
/// <returns>A task representing the asynchronous operation.</returns>
/// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=missing_returns
/// "The <returns> description says 'A task representing the asynchronous operation' but the method returns Task<User>; the User element of the return type is not documented." -->
/// <param name="context">The <see cref="HttpContext"/> of the incoming HTTP request used to extract authentication information.</param>
/// <returns>A <see cref="Task{TResult}"/> that resolves to the authenticated user.</returns>
/// <exception cref="LoginServicesException">Always thrown because the method is not implemented.</exception>
/// <!-- aidoc:v1 sig=851dc90 -->
public Task<User> Login(HttpContext context)
=> throw new LoginServicesException("Not implemented");
/// <summary>
/// This method is not implemented in the LdapLoginService, as the authentication process is handled through the Login(string username, string password) method.
/// Authenticates a user with the provided <paramref name="username"/> and <paramref name="password"/> and returns the corresponding <see cref="User"/>.
/// This method is not implemented and always throws a <see cref="LoginServicesException"/> when invoked.
/// </summary>
/// <param name="username">The username of the user to authenticate.</param>
/// <param name="password">The password of the user to authenticate.</param>
/// <returns>A task representing the asynchronous operation.</returns>
/// <exception cref="LoginServicesException">Thrown when the method is not implemented.</exception>
/// <!-- aidoc-review:v1 severity=medium kind=wrong_returns
/// "The method returns Task<User>, but the documentation only states 'A task representing the asynchronous operation' without mentioning that the task produces a User." -->
/// <returns>A <see cref="Task{User}"/> that yields the authenticated <see cref="User"/>.</returns>
/// <exception cref="LoginServicesException">Thrown because authentication is not implemented.</exception>
/// <!-- aidoc:v1 sig=a0b1f46 -->
public Task<User> Authenticate(string username, string password)
=> throw new LoginServicesException("Not implemented");
@@ -247,13 +246,14 @@ public class LdapLoginService : ILoginService
/// <summary>
/// This method checks the authorities of a user based on the LDAP entry and the application's configuration.
/// Synchronizes the authorities of a <paramref name="user"/> with the authorities defined in the supplied <paramref name="entry"/>, updating existing records or inserting new ones as appropriate.
/// Authorities appearing in the whitelist are preserved and excluded from the LDAP map, while remaining LDAP authorities are compared against the current persisted list; entries with <see cref="Authorization.CanUpdate"/> set to <c>true</c> have their <see cref="Authorization.Rol"/> refreshed via <see cref="AuthorityService.updateOne"/>, otherwise they are inserted with <see cref="AuthorityService.InsertOne"/>.
/// On any failure, the error is logged and an empty list is returned.
/// </summary>
/// <param name="user">The user whose authorities are being checked.</param>
/// <param name="entry">The LDAP entry containing the user's information.</param>
/// <returns>A list of updated authorities for the user.</returns>
/// <!-- aidoc-review:v1 severity=medium kind=stale_summary
/// "Summary states the method 'checks' authorities, but the method actually synchronizes authorities: it updates existing entries (when CanUpdate is true) and inserts new ones via _authorityService, with side effects beyond a read-only check." -->
/// <param name="user">The user whose authorities are being reconciled.</param>
/// <param name="entry">The <see cref="LdapEntry"/> providing the source authorities map and whitelist.</param>
/// <returns>The updated <see cref="Authorization"/> list retrieved from the authority service.</returns>
/// <!-- aidoc:v1 sig=d2bafd5 body=4af15eb -->
private async Task<List<Authorization>> CheckAuthorities(User user, LdapEntry entry)
{
@@ -343,14 +343,13 @@ public class LdapLoginService : ILoginService
/// <summary>
/// This method retrieves a list of authorities for a user based on the LDAP entry and the application's configuration for mapping LDAP groups to authorities.
/// Maps the supplied <see cref="LdapEntry"/> to a <see cref="User"/> instance by reading attributes whose names are configured in the LDAP settings.
/// The <see cref="User.UserName"/> is taken from the configured user name property, falling back to an empty string when the attribute is absent.
/// When the first name and/or last name properties are configured, their attribute values are used to build the <see cref="User.Name"/>; otherwise the name is left unset, and the last name is appended to the first name when both are present.
/// </summary>
/// <param name="ldapEntry">The LDAP entry containing the user's information.</param>
/// <returns>The existing or newly created user with updated authorities.</returns>
/// <!-- aidoc-review:v1 severity=high kind=wrong_summary
/// "The summary claims the method retrieves a list of authorities and maps LDAP groups to authorities, but the method actually constructs a User object using username, first name, and last name properties from the LDAP entry." -->
/// <!-- aidoc-review:v1 severity=high kind=wrong_returns
/// "The <returns> tag claims to return an 'existing or newly created user with updated authorities', but the method always creates a new User and never touches authorities." -->
/// <param name="ldapEntry">The <see cref="LdapEntry"/> whose attributes are read to populate the resulting <see cref="User"/>.</param>
/// <returns>A <see cref="User"/> populated from the attributes exposed by <paramref name="ldapEntry"/> according to the current LDAP configuration.</returns>
/// <!-- aidoc:v1 sig=947181a body=33ffec8 -->
private User GetUser(LdapEntry ldapEntry)
{