docs(comments): strip internal task/milestone/bundle bookkeeping from code comments
Remove project bookkeeping citations from shipped code comments across the solution: hyphenated task IDs (WP-14, StoreAndForward-025), milestone/task/ issue refs (M3, Task 4, Audit Log #23, #21), Bundle X task-bundle labels, and C/D/K/S/T phase labels. Comment text only — no code logic, string/log literals, or XML-doc structure changed. Genuine descriptions are preserved (only the citation is stripped), and technical lookalikes are retained (UTF-8, SHA-256, T00:00:00, M365, UTC-5, pre-C4/pre-C5 schema versions). Flagged by the new CommentChecker TaskReferenceInComment / TrackingReferenceInComment checks plus targeted grep passes; full solution builds clean, append-only guard tests pass.
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
|
||||
/// <summary>
|
||||
/// NS-009: Scrubs SMTP credential secrets out of free text (typically exception
|
||||
/// Scrubs SMTP credential secrets out of free text (typically exception
|
||||
/// messages echoed back by an SMTP server) before that text is written to a log.
|
||||
/// MailKit authentication exceptions can contain server responses that quote the
|
||||
/// supplied credentials; this prevents a password, client secret, or OAuth2 token
|
||||
@@ -25,7 +25,7 @@ public static class CredentialRedactor
|
||||
/// <c>tenantId:clientId:clientSecret</c>. May be null.
|
||||
/// </param>
|
||||
/// <summary>
|
||||
/// NS-025: minimum length for a colon-separated SECRET component to be
|
||||
/// Minimum length for a colon-separated SECRET component to be
|
||||
/// considered worth masking. Twelve characters is the standard heuristic
|
||||
/// for "long enough to be a password / client secret"; shorter components
|
||||
/// (e.g. a 4-char user name like <c>root</c>, or a 7-char "from" alias)
|
||||
@@ -52,7 +52,7 @@ public static class CredentialRedactor
|
||||
|
||||
var result = text;
|
||||
|
||||
// NS-025: redact only the obviously-secret slots — the LAST
|
||||
// Redact only the obviously-secret slots — the LAST
|
||||
// colon-separated component (the password in Basic, the client
|
||||
// secret in OAuth2) and the whole packed string — not the user
|
||||
// name / tenant id / client id. A short user name like "root" or
|
||||
|
||||
@@ -4,7 +4,7 @@ using ZB.MOM.WW.ScadaBridge.Commons.Entities.Notifications;
|
||||
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
|
||||
/// <summary>
|
||||
/// NS-008: Validates the sender and recipient email addresses before an SMTP
|
||||
/// Validates the sender and recipient email addresses before an SMTP
|
||||
/// delivery is attempted, so a malformed address surfaces as a clean error
|
||||
/// string rather than a <c>ParseException</c> escaping the delivery path.
|
||||
/// <para>
|
||||
|
||||
@@ -9,12 +9,12 @@ public interface ISmtpClientWrapper
|
||||
/// Connects to the SMTP server.
|
||||
/// </summary>
|
||||
/// <param name="tlsMode">
|
||||
/// NS-005: explicit three-state TLS mode (None/StartTls/Ssl) — replaces the old
|
||||
/// Explicit three-state TLS mode (None/StartTls/Ssl) — replaces the old
|
||||
/// <c>bool useTls</c> which could not represent implicit-SSL and silently fell
|
||||
/// back to opportunistic negotiation for non-StartTLS configurations.
|
||||
/// </param>
|
||||
/// <param name="connectionTimeoutSeconds">
|
||||
/// NS-007: SMTP connection/operation timeout in seconds. A non-positive value
|
||||
/// SMTP connection/operation timeout in seconds. A non-positive value
|
||||
/// leaves the client's default timeout in place.
|
||||
/// </param>
|
||||
/// <param name="host">SMTP server hostname or IP address.</param>
|
||||
@@ -31,9 +31,9 @@ public interface ISmtpClientWrapper
|
||||
/// <param name="authType">Authentication mechanism (e.g. <c>PLAIN</c>, <c>XOAUTH2</c>).</param>
|
||||
/// <param name="credentials">Credential string appropriate for the auth type, or null.</param>
|
||||
/// <param name="oauth2UserName">
|
||||
/// NS-021: mailbox identity the OAuth2 access token was issued for (typically
|
||||
/// Mailbox identity the OAuth2 access token was issued for (typically
|
||||
/// the SMTP <c>FromAddress</c>). Used as the <c>user=</c> field of the XOAUTH2
|
||||
/// SASL initial response — M365 rejects an empty/mismatched user with
|
||||
/// SASL initial response — Microsoft 365 rejects an empty/mismatched user with
|
||||
/// <c>535 5.7.3</c>. Ignored for non-OAuth2 auth types; default <c>null</c> for
|
||||
/// callers that do not authenticate with OAuth2.
|
||||
/// </param>
|
||||
|
||||
@@ -5,13 +5,13 @@ using MimeKit;
|
||||
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
|
||||
/// <summary>
|
||||
/// WP-11: MailKit-based SMTP client wrapper.
|
||||
/// MailKit-based SMTP client wrapper.
|
||||
/// Supports OAuth2 Client Credentials (M365) and Basic Auth.
|
||||
/// BCC delivery, plain text.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// <b>Lifetime — one wrapper, one delivery (NS-022).</b>
|
||||
/// <b>Lifetime — one wrapper, one delivery.</b>
|
||||
/// This wrapper owns a SINGLE underlying <see cref="MailKit.Net.Smtp.SmtpClient"/>
|
||||
/// — it is NOT a connection pool. MailKit's <c>SmtpClient</c> is a single TCP/TLS
|
||||
/// connection holder and is NOT thread-safe; reusing one across concurrent or
|
||||
@@ -31,14 +31,14 @@ namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// Do not reuse one wrapper across deliveries. <see cref="ConnectAsync"/>
|
||||
/// mutates <c>_client.Timeout</c> per call (NS-007), and the underlying
|
||||
/// mutates <c>_client.Timeout</c> per call, and the underlying
|
||||
/// <c>SmtpClient</c> rejects concurrent send calls — both are latent footguns
|
||||
/// for any caller tempted to "fix" the factory into a true singleton.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
|
||||
{
|
||||
// NS-022: ONE SmtpClient per wrapper — see class-level remarks. This is NOT a
|
||||
// ONE SmtpClient per wrapper — see class-level remarks. This is NOT a
|
||||
// connection pool. MailKit's SmtpClient holds a single TCP/TLS connection and
|
||||
// is not thread-safe; the wrapper is meant for a single connect/auth/send/
|
||||
// disconnect cycle per instance, after which it MUST be disposed.
|
||||
@@ -52,7 +52,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
|
||||
int connectionTimeoutSeconds,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
// NS-005: map the explicit three-state TLS mode onto MailKit's socket
|
||||
// Map the explicit three-state TLS mode onto MailKit's socket
|
||||
// options. The old code collapsed everything to a boolean and used
|
||||
// SecureSocketOptions.Auto for the non-StartTLS case, which let MailKit
|
||||
// opportunistically negotiate TLS even when "None" was configured and
|
||||
@@ -65,7 +65,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
|
||||
_ => throw new ArgumentOutOfRangeException(nameof(tlsMode), tlsMode, "Unknown TLS mode."),
|
||||
};
|
||||
|
||||
// NS-007: honour the configured connection timeout. SmtpClient.Timeout is
|
||||
// Honour the configured connection timeout. SmtpClient.Timeout is
|
||||
// in milliseconds and applies to connect/auth/send operations.
|
||||
if (connectionTimeoutSeconds > 0)
|
||||
{
|
||||
@@ -82,7 +82,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
|
||||
string? oauth2UserName = null,
|
||||
CancellationToken cancellationToken = default)
|
||||
{
|
||||
// NS-016: missing/unparseable credentials and an unrecognised auth type used
|
||||
// Missing/unparseable credentials and an unrecognised auth type used
|
||||
// to make this method silently return and the connection then sent mail
|
||||
// unauthenticated — masking a misconfiguration against an open relay and, at
|
||||
// worst, sending where authentication was required. Authentication being
|
||||
@@ -109,7 +109,7 @@ public class MailKitSmtpClientWrapper : ISmtpClientWrapper, IDisposable
|
||||
break;
|
||||
|
||||
case "oauth2":
|
||||
// NS-021: the XOAUTH2 SASL initial response embeds a `user=<userName>`
|
||||
// The XOAUTH2 SASL initial response embeds a `user=<userName>`
|
||||
// field that M365 (and most OAuth2-enabled SMTP relays) require to
|
||||
// match the mailbox identity the token was issued for. An empty user
|
||||
// gets rejected with `535 5.7.3`. The token (credentials) is
|
||||
|
||||
@@ -5,7 +5,7 @@ namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
/// <c>ScadaBridge:Notification</c> configuration section.
|
||||
///
|
||||
/// SMTP settings are primarily carried by the deployed <c>SmtpConfiguration</c>
|
||||
/// entity. NS-017: these values are the fallback used by the central
|
||||
/// entity. These values are the fallback used by the central
|
||||
/// Notification Outbox's <c>EmailNotificationDeliveryAdapter</c> when the
|
||||
/// corresponding <c>SmtpConfiguration</c> field is left unset (non-positive) on a
|
||||
/// partially deployed row — a value present on the row always takes precedence.
|
||||
|
||||
@@ -7,9 +7,9 @@ using Microsoft.Extensions.Logging;
|
||||
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
|
||||
/// <summary>
|
||||
/// WP-11: OAuth2 Client Credentials token lifecycle — fetch, cache, refresh on expiry.
|
||||
/// OAuth2 Client Credentials token lifecycle — fetch, cache, refresh on expiry.
|
||||
/// Used for Microsoft 365 SMTP authentication.
|
||||
/// NS-006: tokens are cached per credential identity (tenant/client/secret), so a
|
||||
/// Tokens are cached per credential identity (tenant/client/secret), so a
|
||||
/// second SMTP configuration with different credentials never receives the first
|
||||
/// configuration's token.
|
||||
/// </summary>
|
||||
@@ -18,7 +18,7 @@ public class OAuth2TokenService
|
||||
private readonly IHttpClientFactory _httpClientFactory;
|
||||
private readonly ILogger<OAuth2TokenService> _logger;
|
||||
|
||||
// NS-006: cache keyed by a hash of the credential string. Each distinct
|
||||
// Cache keyed by a hash of the credential string. Each distinct
|
||||
// tenant/client/secret triple gets its own cached token and its own lock.
|
||||
private readonly ConcurrentDictionary<string, CacheEntry> _cache = new();
|
||||
|
||||
@@ -93,7 +93,7 @@ public class OAuth2TokenService
|
||||
entry.Token = token;
|
||||
entry.Expiry = DateTimeOffset.UtcNow.AddSeconds(expiresIn - 60); // Refresh 60s before expiry
|
||||
|
||||
// NS-009: the token endpoint identity is logged by tenant only — never
|
||||
// The token endpoint identity is logged by tenant only — never
|
||||
// the client secret or the access token itself.
|
||||
_logger.LogInformation(
|
||||
"OAuth2 token refreshed for tenant {Tenant}, expires in {ExpiresIn}s", tenantId, expiresIn);
|
||||
@@ -106,7 +106,7 @@ public class OAuth2TokenService
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// NS-006: a stable, non-reversible key for the credential string so the cache
|
||||
/// A stable, non-reversible key for the credential string so the cache
|
||||
/// is partitioned by credential identity without holding the secret as a key.
|
||||
/// </summary>
|
||||
private static string CredentialKey(string credentials)
|
||||
|
||||
@@ -11,7 +11,7 @@ public static class ServiceCollectionExtensions
|
||||
/// Central-only — sites no longer deliver notifications (see
|
||||
/// <c>Component-NotificationService.md</c>), and the orphaned site-shaped
|
||||
/// <c>NotificationDeliveryService</c> + <c>INotificationDeliveryService</c> contract
|
||||
/// was removed (NS-019). Notification dispatch lives in <c>ZB.MOM.WW.ScadaBridge.NotificationOutbox</c>.
|
||||
/// was removed. Notification dispatch lives in <c>ZB.MOM.WW.ScadaBridge.NotificationOutbox</c>.
|
||||
/// </summary>
|
||||
/// <param name="services">The service collection to register into.</param>
|
||||
/// <returns>The same <paramref name="services"/> collection, for chaining.</returns>
|
||||
|
||||
@@ -5,7 +5,7 @@ using MailKit.Net.Smtp;
|
||||
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
|
||||
/// <summary>
|
||||
/// NS-002/NS-003: The classification of an SMTP delivery failure. This decides
|
||||
/// The classification of an SMTP delivery failure. This decides
|
||||
/// whether a failure is retried or surfaced to the caller, so it is part of the
|
||||
/// system's correctness-relevant behaviour.
|
||||
/// </summary>
|
||||
@@ -22,12 +22,12 @@ public enum SmtpErrorClass
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// NS-002/NS-003: Classifies an SMTP failure using MailKit's typed exceptions and
|
||||
/// Classifies an SMTP failure using MailKit's typed exceptions and
|
||||
/// the numeric <see cref="SmtpStatusCode"/> rather than locale-dependent substring
|
||||
/// matching on the exception message.
|
||||
/// <para>
|
||||
/// Public and shared: the central Notification Outbox's <c>EmailNotificationDeliveryAdapter</c>
|
||||
/// routes every SMTP failure through this single policy. (NS-019: the orphaned site-side
|
||||
/// routes every SMTP failure through this single policy. (The orphaned site-side
|
||||
/// <c>NotificationDeliveryService</c> that previously co-used this classifier was removed
|
||||
/// when sites stopped delivering notifications.)
|
||||
/// </para>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
namespace ZB.MOM.WW.ScadaBridge.NotificationService;
|
||||
|
||||
/// <summary>
|
||||
/// NS-005: The three TLS modes the design doc defines for SMTP connections.
|
||||
/// The three TLS modes the design doc defines for SMTP connections.
|
||||
/// A single boolean cannot represent the requirement, so the configured
|
||||
/// <c>SmtpConfiguration.TlsMode</c> string is parsed into this three-state enum.
|
||||
/// </summary>
|
||||
@@ -18,7 +18,7 @@ public enum SmtpTlsMode
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// NS-005: Parses the free-text <c>SmtpConfiguration.TlsMode</c> value into a
|
||||
/// Parses the free-text <c>SmtpConfiguration.TlsMode</c> value into a
|
||||
/// <see cref="SmtpTlsMode"/>, rejecting unknown values rather than silently
|
||||
/// falling back to opportunistic negotiation.
|
||||
/// </summary>
|
||||
|
||||
Reference in New Issue
Block a user