Joseph Doherty
89 lines
4.6 KiB
C#
89 lines
4.6 KiB
C#
using ZB.MOM.WW.MxGateway.Server.Security.Authentication;
|
|
using ZB.MOM.WW.MxGateway.Server.Sessions;
|
|
|
|
namespace ZB.MOM.WW.MxGateway.Server.Security.Authorization;
|
|
|
|
public interface IConstraintEnforcer
|
|
{
|
|
/// <summary>
|
|
/// Gets a value indicating whether any read constraint applies to an identity at all, so a
|
|
/// bulk caller can hoist the question out of its per-item loop.
|
|
/// </summary>
|
|
/// <param name="identity">The API key identity.</param>
|
|
/// <returns><see langword="true"/> when at least one read constraint applies; otherwise <see langword="false"/>.</returns>
|
|
/// <remarks>
|
|
/// Every per-item <see cref="CheckReadTagAsync"/> / <see cref="CheckReadHandleAsync"/> call for
|
|
/// an unconstrained identity allows the item, so skipping the loop removes work without
|
|
/// changing a decision. The default implementation answers <see langword="true"/> — an
|
|
/// implementation that does not model constraints (test doubles, allow-all enforcers) keeps
|
|
/// being consulted per item rather than being silently bypassed.
|
|
/// </remarks>
|
|
bool HasReadConstraints(ApiKeyIdentity? identity) => true;
|
|
|
|
/// <summary>
|
|
/// Gets a value indicating whether any write constraint applies to an identity at all, the
|
|
/// write-side counterpart of <see cref="HasReadConstraints"/>.
|
|
/// </summary>
|
|
/// <param name="identity">The API key identity.</param>
|
|
/// <returns><see langword="true"/> when at least one write constraint applies; otherwise <see langword="false"/>.</returns>
|
|
/// <remarks>The same conservative default as <see cref="HasReadConstraints"/> applies.</remarks>
|
|
bool HasWriteConstraints(ApiKeyIdentity? identity) => true;
|
|
|
|
/// <summary>Checks whether a read constraint is satisfied for a tag address.</summary>
|
|
/// <param name="identity">The API key identity.</param>
|
|
/// <param name="tagAddress">Tag address to check.</param>
|
|
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
|
/// <returns>The constraint failure details if denied; otherwise null.</returns>
|
|
Task<ConstraintFailure?> CheckReadTagAsync(
|
|
ApiKeyIdentity? identity,
|
|
string tagAddress,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>Checks whether a read constraint is satisfied for an item handle.</summary>
|
|
/// <param name="identity">The API key identity.</param>
|
|
/// <param name="session">The gateway session.</param>
|
|
/// <param name="serverHandle">The MXAccess server handle.</param>
|
|
/// <param name="itemHandle">The MXAccess item handle.</param>
|
|
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
|
/// <returns>The constraint failure details if denied; otherwise null.</returns>
|
|
Task<ConstraintFailure?> CheckReadHandleAsync(
|
|
ApiKeyIdentity? identity,
|
|
GatewaySession session,
|
|
int serverHandle,
|
|
int itemHandle,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>Checks whether a write constraint is satisfied for an item handle.</summary>
|
|
/// <param name="identity">The API key identity.</param>
|
|
/// <param name="session">The gateway session.</param>
|
|
/// <param name="serverHandle">The MXAccess server handle.</param>
|
|
/// <param name="itemHandle">The MXAccess item handle.</param>
|
|
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
|
/// <returns>The constraint failure details if denied; otherwise null.</returns>
|
|
Task<ConstraintFailure?> CheckWriteHandleAsync(
|
|
ApiKeyIdentity? identity,
|
|
GatewaySession session,
|
|
int serverHandle,
|
|
int itemHandle,
|
|
CancellationToken cancellationToken);
|
|
|
|
/// <summary>Records a constraint denial for audit and metrics.</summary>
|
|
/// <param name="identity">The API key identity.</param>
|
|
/// <param name="commandKind">The kind of command denied.</param>
|
|
/// <param name="target">The target of the denied command.</param>
|
|
/// <param name="failure">The constraint failure details.</param>
|
|
/// <param name="correlationId">
|
|
/// The per-request client correlation id, if any. Stored on the audit record's
|
|
/// <c>CorrelationId</c> when it parses as a GUID; otherwise left null.
|
|
/// </param>
|
|
/// <param name="cancellationToken">Token to observe for cancellation.</param>
|
|
/// <returns>A task that represents the asynchronous operation.</returns>
|
|
Task RecordDenialAsync(
|
|
ApiKeyIdentity? identity,
|
|
string commandKind,
|
|
string target,
|
|
ConstraintFailure failure,
|
|
string? correlationId,
|
|
CancellationToken cancellationToken);
|
|
}
|