Interface IAuditQuery
- Namespace
- Excalibur.Compliance
- Assembly
- Excalibur.Compliance.Abstractions.dll
Provides querying, retrieval, and integrity verification of stored audit events.
public interface IAuditQuery
Remarks
Supports efficient querying for compliance reports and hash chain integrity verification for long-term, tamper-evident audit trails.
A filter an implementation cannot serve MUST be refused, never answered emptily. An implementation that stores a field in a form no comparison can match -- a column encrypted at rest with a randomized cipher is the case that arises in practice -- throws NotSupportedException naming the field, and does not delegate a query it already knows will match nothing. An empty list or a zero count is indistinguishable, at the caller, from "there are no such events", so an operator asking what an actor did would be told in effect that the actor did nothing, while the records sit present and unmatchable. Silence is the one answer an audit trail must never give. Refusal is therefore part of this contract rather than a deviation from it: a caller may be told no, and may not be told a falsehood.
Methods
CountAsync(AuditQuery, CancellationToken)
Gets the count of audit events matching the query criteria.
Task<long> CountAsync(AuditQuery query, CancellationToken cancellationToken)
Parameters
queryAuditQueryThe query parameters (MaxResults and Skip are ignored).
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
Remarks
Confined the same way as QueryAsync(AuditQuery, CancellationToken): the count reflects only the caller's own tenant's matching events, so it does not disclose another tenant's audit volume.
A zero means no stored event matched, and carries the same obligation as an empty list from QueryAsync(AuditQuery, CancellationToken): an unservable filter throws rather than counting to zero.
Exceptions
- NotSupportedException
Thrown on the same terms as QueryAsync(AuditQuery, CancellationToken).
GetByIdAsync(string, CancellationToken)
Retrieves an audit event by its ID.
Task<AuditEvent?> GetByIdAsync(string eventId, CancellationToken cancellationToken)
Parameters
eventIdstringThe unique identifier of the event.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<AuditEvent>
The audit event, or null if not found.
Remarks
Confined to the ambient tenant established for this store instance when the implementing IAuditStore presents ITenantScopingCapability<TContract>: an event stored under another tenant is reported as not found, never resolved. See IAuditStore for the full confinement statement.
GetLastEventAsync(CancellationToken)
Gets the last recorded event (for chain linking).
Task<AuditEvent?> GetLastEventAsync(CancellationToken cancellationToken)
Parameters
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<AuditEvent>
The last audit event, or null if no events exist.
Remarks
Confined the same way as QueryAsync(AuditQuery, CancellationToken): the result is the last event within the ambient tenant established for this store instance (or the untenanted partition when no tenant is resolved), never another tenant's most recent event. This member previously accepted a caller- supplied tenant id; every implementation resolved confinement from ambient state regardless of what was passed, so the parameter was removed rather than left to teach a caller a scoping belief the call never honoured.
QueryAsync(AuditQuery, CancellationToken)
Queries audit events based on the specified criteria.
Task<IReadOnlyList<AuditEvent>> QueryAsync(AuditQuery query, CancellationToken cancellationToken)
Parameters
queryAuditQueryThe query parameters.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<IReadOnlyList<AuditEvent>>
A list of matching audit events.
Remarks
Confined to the ambient tenant established for this store instance when the implementing
IAuditStore presents ITenantScopingCapability<TContract>: returns none
of another tenant's audit events and every one of the caller's own that matches
query. See IAuditStore for the full confinement statement.
An empty list means no stored event matched. It never means the implementation was unable to apply a filter -- that case throws; see the remarks on IAuditQuery.
Exceptions
- NotSupportedException
Thrown when
queryfilters on a field this implementation cannot compare, naming the field.
VerifyChainIntegrityAsync(DateTimeOffset, DateTimeOffset, CancellationToken)
Verifies the hash chain integrity for events in the specified range.
Task<AuditIntegrityResult> VerifyChainIntegrityAsync(DateTimeOffset startDate, DateTimeOffset endDate, CancellationToken cancellationToken)
Parameters
startDateDateTimeOffsetThe start of the verification period.
endDateDateTimeOffsetThe end of the verification period.
cancellationTokenCancellationTokenA token to cancel the operation.
Returns
- Task<AuditIntegrityResult>
The integrity verification result.
Remarks
Verification scope is a property of the store, not of this contract. The SQL Server and PostgreSQL stores verify the chain estate-wide, enumerating each tenant-and-application partition that falls in the range. The in-memory store verifies only the ambient tenant's chain.
A result from an estate-wide store must therefore not be presented to a single tenant as evidence about that tenant's own data. A passing result states that every partition the store enumerated is intact; it does not by itself state which partitions those were.