From 0a22f012a8bb523f51761aef633f1502d39ac8ab Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nikola=20Jevti=C4=87?=
 <245982936+jevt1c@users.noreply.github.com>
Date: Tue, 3 Nov 2026 01:20:35 +0100
Subject: [PATCH 1/4] AUD-01: add draft audit writer contract (S-02)

---
 docs/components/audit/CONTRACTS.md | 275 +++++++++++++++++++++++++++++
 1 file changed, 275 insertions(+)
 create mode 100644 docs/components/audit/CONTRACTS.md

diff --git a/docs/components/audit/CONTRACTS.md b/docs/components/audit/CONTRACTS.md
new file mode 100644
index 0000000..9d1384e
--- /dev/null
+++ b/docs/components/audit/CONTRACTS.md
@@ -0,0 +1,275 @@
+# Contract: `IAuditWriter` (Audit module)
+
+| | |
+|-|-|
+| **Owner** | Team 12, Audit component (AUD-01, AUD-06) |
+| **Version** | 0.1 (draft, not yet accepted by the consumers listed below) |
+| **Spec reference** | Specification 3.1: structured security record, without personal secrets or sensitive solutions |
+| **Requirements** | AUD-01, AUD-03, AUD-04, SEC-02, OPS-05 |
+
+Until a consumer confirms it in a reviewed pull request, every name, field and limit below is a
+proposal. Nothing here is claimed as an existing or accepted API.
+
+## Purpose
+
+Any module that performs a security-relevant action (login, change of rights, denied access)
+reports it through one contract. The Audit module validates the report, adds the trusted
+context (who, when, which request) and stores it as an append-only record. AUD-06 later reads
+those records for teachers, filtered by course on the server.
+
+## What this contract is not
+
+- **Not a technical log.** `ILogger` output is for diagnostics. An audit record is a security
+  record with an owner, a schema and access control.
+- **Not the attempt action log.** `AttemptAction` (ATT-08) belongs to the Attempts module.
+- **Not laboratory data.** Scenarios 5.2 and 5.7 use synthetic events, never the platform audit.
+
+## Visibility and dependency direction
+
+- Only the types in the `Platform.Audit.Contracts` namespace and `AddAudit()` are public.
+  Domain, application and infrastructure types of the module are `internal`.
+- `Platform.Access` does **not** reference `Platform.Audit`. The host (`Platform.Api`) connects
+  them with an adapter that implements `IAccessAuditWriter` and calls this contract (story S-13).
+- Producers never read or write the audit table directly.
+
+## Members
+
+### `IAuditWriter`
+
+```csharp
+public interface IAuditWriter
+{
+    ValueTask<AuditWriteResult> WriteAsync(
+        AuditEventDraft draft,
+        CancellationToken cancellationToken = default);
+}
+```
+
+The usual entry point. The caller describes **what** happened. The writer takes the actor and
+the correlation ID from the trusted server context of the current request, and the time from
+`TimeProvider` (UTC). The caller cannot set the actor, the time or the correlation ID.
+
+### `ITrustedAuditWriter`
+
+```csharp
+public interface ITrustedAuditWriter
+{
+    ValueTask<AuditWriteResult> WriteAsync(
+        AuditEventDraft draft,
+        AuditContext context,
+        CancellationToken cancellationToken = default);
+}
+```
+
+For server-side adapters only, when the actor is already confirmed but is not yet (or no longer)
+in the request context:
+
+- successful login: credentials were verified, the session is not issued yet;
+- the Access adapter: it forwards the subject of an access decision that was already evaluated;
+- background jobs, such as expiry of a delegation: the actor is a service identity.
+
+`AuditContext` must never be built from an HTTP body, query string or arbitrary header. The
+compiler cannot enforce this; it is checked in code review (see residual risk below).
+
+### `AuditEventDraft`
+
+| Field | Type | Rule |
+|-|-|-|
+| `EventType` | `string` | Required. Must be a type from the catalog below. An unknown type is rejected. |
+| `Outcome` | `AuditOutcome` | Required. Must be allowed for that event type. |
+| `CourseId` | `Guid?` | Required, forbidden or optional depending on the event type. Comes from a trusted business context, never from client input. |
+| `Resource` | `AuditResourceRef?` | The subject of the change (for example the account whose rights changed). It is not the actor. |
+| `Details` | `IReadOnlyDictionary<string, string>?` | Only keys allowed for that event type, with string values. No nested objects. |
+| `EventId` | `Guid?` | Optional idempotency key. Required for producers that retry or use an outbox. When `null`, the writer generates one. |
+
+### `AuditOutcome`
+
+| Value | Meaning |
+|-|-|
+| `Success` | The action was carried out and persisted. |
+| `Denied` | The action was refused by an authorization or policy check. |
+| `Failure` | The action was allowed but failed (invalid input, missing target, technical error). |
+
+A technical failure is never recorded as `Success`.
+
+### `AuditResourceRef`
+
+`AuditResourceRef(string Type, string Id)`. `Type` is one of `Account`, `Course`, `Delegation`.
+`Id` has at most 64 characters: ASCII letters, digits, `-` and `_`.
+
+### `AuditContext` and `AuditActor`
+
+```csharp
+public sealed record AuditContext(AuditActor Actor, string CorrelationId);
+public sealed record AuditActor(AuditActorKind Kind, Guid? Id);
+public enum AuditActorKind { User, Service, Anonymous }
+```
+
+| Kind | `Id` | Used for |
+|-|-|-|
+| `User` | required | an authenticated person |
+| `Service` | required | a registered service identity (background job) |
+| `Anonymous` | must be `null` | a caller without a confirmed identity, for example a failed login |
+
+The email address or user name typed into a login form is **not** an actor and is never stored.
+Users sometimes type their password into that field.
+
+`CorrelationId` has 1 to 64 characters: ASCII letters, digits, `-`, `_` and `.`. One request can
+produce several events with the same correlation ID, so it is not a deduplication key.
+
+### `AuditWriteResult`
+
+```csharp
+public sealed record AuditWriteResult(
+    AuditWriteStatus Status,
+    AuditRejectionCode RejectionCode,
+    Guid? EventId);
+
+public enum AuditWriteStatus { Recorded, Rejected, Unavailable }
+```
+
+| Status | Meaning | Producer must |
+|-|-|-|
+| `Recorded` | The event is stored. `EventId` identifies it. | continue |
+| `Rejected` | The draft breaks the contract. Nothing is stored. `RejectionCode` says why. | treat it as a defect in its own code; do not confirm a privileged change |
+| `Unavailable` | Storage failed. Nothing is guaranteed to be stored. | treat it as failure (see producer obligations) |
+
+`AuditRejectionCode` values: `None`, `UnknownEventType`, `OutcomeNotAllowed`, `CourseRequired`,
+`CourseNotAllowed`, `InvalidResource`, `InvalidContext`, `UnknownDetailKey`, `ForbiddenDetailKey`,
+`InvalidDetailValue`, `DetailsTooLarge`, `EventIdConflict`.
+
+The writer does not throw for expected failures. The only exception it lets through is
+`OperationCanceledException` when the caller's token was cancelled before the event was stored.
+
+**Repeated `EventId`:** the same `EventId` with the same content returns `Recorded` with that
+`EventId` and stores nothing new. The same `EventId` with different content returns `Rejected`
+with `EventIdConflict` and never replaces the stored record.
+
+## Producer obligations
+
+1. **Privileged change that was allowed** (status change, role change, delegation): the business
+   change may be confirmed only when its audit record is guaranteed. Either both are committed in
+   one transaction, or the change and an outbox entry are committed together. Which of the two is
+   decided in D3 (stories S-12 and S-16). Returning an error after the change is already committed
+   is not fail-closed.
+2. **Denied action:** the denial stays a denial even if the audit write fails. The producer raises
+   a technical alarm without secrets. An audit failure never grants access.
+3. **Audit of an action that is already committed:** pass `CancellationToken.None` (or hand the
+   event to the outbox), so that a cancelled HTTP request does not lose the record.
+4. **Never put into a draft:** passwords (even wrong ones), tokens, cookies, session identifiers,
+   `Authorization` headers, evaluation keys, student answers, request or response bodies, typed
+   login names or any free text.
+
+## Event catalog (schema version 1)
+
+| Event type | Producer (requirement) | Outcomes | Actor | Course | Resource | Allowed details |
+|-|-|-|-|-|-|-|
+| `auth.login` | Identity (IDN-02) | Success, Failure | Success: `User`. Failure: `Anonymous`, or `User` when the credentials were valid but the account is not active | forbidden | `Account` on Success | `reasonCode` |
+| `auth.logout` | Identity (IDN-02) | Success | `User` | forbidden | none | none |
+| `auth.login.throttled` | Identity (IDN-05) | Denied | `Anonymous` | forbidden | none | none |
+| `account.status.changed` | Identity (IDN-03), Admin (ADM-01) | Success, Denied, Failure | `User` or `Anonymous` (Denied, not logged in) | forbidden | `Account` (required) | `oldStatus`, `newStatus`, `reasonCode` |
+| `course.member.role.changed` | Memberships (ACC-03) | Success, Denied, Failure | `User` or `Anonymous` (Denied) | required | `Account` (required) | `oldRole`, `newRole`, `reasonCode` |
+| `course.delegation.granted` | Memberships (ACC-07) | Success, Denied, Failure | `User` or `Anonymous` (Denied) | required | `Account` (required) | `action`, `delegationId`, `reasonCode` |
+| `course.delegation.revoked` | Memberships (ACC-07) | Success, Denied, Failure | `User` or `Anonymous` (Denied) | required | `Account` (required) | `action`, `delegationId`, `reasonCode` |
+| `course.delegation.expired` | Memberships (ACC-07), background job | Success | `Service` | required | `Account` (required) | `action`, `delegationId` |
+| `access.denied` | Access, Team 3 (ACC-05), through the host adapter | Denied | `User` or `Anonymous` | optional, only from a trusted resource resolver | optional | `action`, `denialReason`, `policyId`, `policyVersion` |
+| `audit.events.viewed` | Audit (AUD-06) | Success | `User` | required | `Course` (required) | `filterType`, `filterOutcome`, `filterFrom`, `filterTo`, `resultCount` |
+
+`reasonCode` is only allowed when the outcome is `Denied` or `Failure`.
+
+### Detail value formats
+
+| Key | Format |
+|-|-|
+| `reasonCode` | code: `^[a-z][a-z0-9_]{0,31}$`, for example `invalid_credentials`, `account_blocked`, `forbidden`, `not_found` |
+| `oldStatus`, `newStatus` | one of `active`, `blocked`, `archived` |
+| `oldRole`, `newRole` | one of `none`, `student`, `teacher`, `assistant` |
+| `action`, `filterType` | action or event type: `^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$`, at most 64 characters (same rule as `ActionId` in `Platform.Access`) |
+| `denialReason` | one of `unauthenticated`, `account_not_active`, `unknown_action`, `no_policy`, `policy_error` |
+| `policyId` | code, at most 64 characters |
+| `policyVersion` | `^v[0-9]{1,4}(\.[0-9]{1,4}){0,2}$` |
+| `delegationId` | UUID |
+| `filterOutcome` | one of `success`, `denied`, `failure` |
+| `filterFrom`, `filterTo` | UTC timestamp, ISO 8601, ending with `Z` |
+| `resultCount` | integer from 0 to 100000 |
+
+## Limits
+
+| Item | Limit |
+|-|-|
+| `EventType` | at most 64 characters, same pattern as `action` |
+| Detail keys per event | at most 20 |
+| Detail key | `^[a-z][a-zA-Z0-9]{0,31}$`, and it must be allowed for the event type |
+| Detail value | its format above; at most 64 characters; no control characters |
+| All details together | at most 2048 bytes after serialization to UTF-8 JSON |
+
+The allowlist is the primary control. As an additional check, a key whose name contains
+`password`, `passwd`, `secret`, `token`, `authorization`, `apikey`, `cookie` or `session`
+(ignoring case) is rejected with `ForbiddenDetailKey` even if someone adds it to the catalog by
+mistake. A rejected value is never copied into a log, exception message or HTTP response.
+
+## Versioning
+
+- The contract has a version (now `0.1`). Every stored event records the schema version of its
+  type (now `1`).
+- Adding a new event type needs a catalog entry, its detail schema and a test. It does not break
+  existing producers.
+- Removing or renaming a field, an enum value or an event type, or changing what an outcome
+  means, is a breaking change even if no method signature changes. It needs a migration plan
+  (OPS-05).
+
+## Consumers
+
+| Team / module | Events | Current state |
+|-|-|-|
+| Identity, Teams 1 and 2 (IDN-02, IDN-03, IDN-05) | `auth.*`, `account.status.changed` | Has its own `IAuditWriter` in `Platform.Api.Services.Identity`, which writes to `ILogger`. Needs an agreed adapter or a switch to this contract. |
+| Access, Team 3 (ACC-05, ACC-08) | `access.denied` | Calls `IAccessAuditWriter`; today `NullAccessAuditWriter`. Connected by the host adapter (S-13). |
+| Memberships and delegation (ACC-03, ACC-07) | `course.*` | Not on `main` yet. |
+| Revision publishing (AUD-02) | not in this version | Can add its event type through a catalog change. |
+| Audit query (AUD-06) | `audit.events.viewed` | Our own story S-14/S-15. |
+
+Two interfaces named `IAuditWriter` exist in different namespaces. In `Program.cs` use an alias,
+as is already done for the two `IAccessDecision` interfaces.
+
+## Test double
+
+`FakeAuditWriter` implements both writer interfaces, records every draft and returns a result
+that the test sets (`Recorded`, `Rejected` with a code, or `Unavailable`). It does not validate
+like the real writer, so a test that passes with the fake does not prove the contract rules.
+Those are proven by the Audit module's own tests.
+
+## How the contract is verified (test group T03)
+
+Planned tests in `backend/Platform.Audit.Tests`, each with its negative case:
+
+- unknown event type: `Rejected`, `UnknownEventType`, nothing stored;
+- outcome not allowed for the type: `OutcomeNotAllowed`;
+- missing or forbidden `CourseId`: `CourseRequired` / `CourseNotAllowed`;
+- unknown detail key, forbidden key name, invalid value, too many keys, more than 2048 bytes;
+- actor rules: `User` or `Service` without `Id`, `Anonymous` with `Id`: `InvalidContext`;
+- every catalog entry accepts a valid example, so the catalog and its tests stay in sync.
+
+## Residual risk
+
+- `ITrustedAuditWriter` is a public interface, so the compiler cannot stop a module from
+  passing a forged `AuditContext`. Mitigation: code review of every use, and only server
+  adapters registered in composition.
+- Append-only rules in the application do not protect against a database administrator or a
+  fully compromised server process. Storage rights are handled in S-05/S-16.
+
+## Open questions
+
+| # | Question | Owner |
+|-|-|-|
+| 1 | Does Identity switch to this contract or keep its own interface behind an adapter? `ChangeAccountStatus` currently writes a free-text administrator reason into `Detail`, which conflicts with AUD-03; the proposal is a `reasonCode` instead. | Member 9 with Teams 1 and 2 (D1) |
+| 2 | Shared transaction or transactional outbox for privileged changes. | Members 2, 3 and 9 with producers (D3) |
+| 3 | Is `auth.login` with valid credentials on a blocked account recorded with a `User` actor? (Proposed: yes; the identity is confirmed, the login is refused.) | Members 3, 8 and 9 with Team 1 |
+| 4 | Who sees events without a course (global or administrator view)? Proposed: nobody through the teacher API. | Members 5, 7 and 9 with the assistant (D4) |
+| 5 | Is an incoming `X-Correlation-Id` header accepted, and in which format? | Member 10 with the AUD-04 owner |
+| 6 | Retention, archive and anonymization rules. | Members 2, 7 and 9 with the ADM owners (D8) |
+
+## Change history
+
+| Version | Date | Change |
+|-|-|-|
+| 0.1 | 2026-11-03 | Initial draft for review (S-02) |

From 81e13fc1714c466068c8d7daf773362e1f8da682 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nikola=20Jevti=C4=87?=
 <245982936+jevt1c@users.noreply.github.com>
Date: Tue, 3 Nov 2026 01:47:20 +0100
Subject: [PATCH 2/4] AUD-01: add audit writer contract types (S-02)

---
 .../Platform.Audit/Contracts/AuditActor.cs    | 21 ++++++++
 .../Platform.Audit/Contracts/AuditContext.cs  |  5 ++
 .../Contracts/AuditEventDraft.cs              | 19 +++++++
 .../Contracts/AuditEventTypes.cs              | 21 ++++++++
 .../Platform.Audit/Contracts/AuditOutcome.cs  | 13 +++++
 .../Contracts/AuditResourceRef.cs             | 12 +++++
 .../Contracts/AuditWriteResult.cs             | 49 +++++++++++++++++++
 .../Platform.Audit/Contracts/IAuditWriter.cs  | 13 +++++
 .../Contracts/ITrustedAuditWriter.cs          | 14 ++++++
 9 files changed, 167 insertions(+)
 create mode 100644 backend/Platform.Audit/Contracts/AuditActor.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditContext.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditEventDraft.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditEventTypes.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditOutcome.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditResourceRef.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditWriteResult.cs
 create mode 100644 backend/Platform.Audit/Contracts/IAuditWriter.cs
 create mode 100644 backend/Platform.Audit/Contracts/ITrustedAuditWriter.cs

diff --git a/backend/Platform.Audit/Contracts/AuditActor.cs b/backend/Platform.Audit/Contracts/AuditActor.cs
new file mode 100644
index 0000000..60469b9
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditActor.cs
@@ -0,0 +1,21 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// <see cref="AuditActorKind.User"/> and <see cref="AuditActorKind.Service"/> require an Id;
+/// <see cref="AuditActorKind.Anonymous"/> must not have one.
+/// </summary>
+public sealed record AuditActor(AuditActorKind Kind, Guid? Id)
+{
+    public static AuditActor Anonymous { get; } = new(AuditActorKind.Anonymous, null);
+
+    public static AuditActor ForUser(Guid userId) => new(AuditActorKind.User, userId);
+
+    public static AuditActor ForService(Guid serviceId) => new(AuditActorKind.Service, serviceId);
+}
+
+public enum AuditActorKind
+{
+    User,
+    Service,
+    Anonymous
+}
diff --git a/backend/Platform.Audit/Contracts/AuditContext.cs b/backend/Platform.Audit/Contracts/AuditContext.cs
new file mode 100644
index 0000000..df6341b
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditContext.cs
@@ -0,0 +1,5 @@
+namespace Platform.Audit.Contracts;
+
+/// <param name="Actor">Who performed the action, as confirmed by the server.</param>
+/// <param name="CorrelationId">1 to 64 characters: ASCII letters, digits, '-', '_' and '.'.</param>
+public sealed record AuditContext(AuditActor Actor, string CorrelationId);
diff --git a/backend/Platform.Audit/Contracts/AuditEventDraft.cs b/backend/Platform.Audit/Contracts/AuditEventDraft.cs
new file mode 100644
index 0000000..99d25cb
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditEventDraft.cs
@@ -0,0 +1,19 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// What happened. It deliberately has no actor, time or correlation ID: the caller
+/// cannot set them.
+/// </summary>
+/// <param name="EventType">A type from <see cref="AuditEventTypes"/>.</param>
+/// <param name="Outcome">Must be allowed for the event type.</param>
+/// <param name="CourseId">Required, forbidden or optional depending on the event type.</param>
+/// <param name="Resource">The subject of the change; not the actor.</param>
+/// <param name="Details">Only keys allowed for the event type.</param>
+/// <param name="EventId">Idempotency key for producers that retry; generated when null.</param>
+public sealed record AuditEventDraft(
+    string EventType,
+    AuditOutcome Outcome,
+    Guid? CourseId = null,
+    AuditResourceRef? Resource = null,
+    IReadOnlyDictionary<string, string>? Details = null,
+    Guid? EventId = null);
diff --git a/backend/Platform.Audit/Contracts/AuditEventTypes.cs b/backend/Platform.Audit/Contracts/AuditEventTypes.cs
new file mode 100644
index 0000000..b3b133f
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditEventTypes.cs
@@ -0,0 +1,21 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// Event types of catalog schema version 1. Adding a type also needs its schema
+/// and a test; see docs/components/audit/CONTRACTS.md.
+/// </summary>
+public static class AuditEventTypes
+{
+    public const string ContractVersion = "0.1";
+
+    public const string AuthLogin = "auth.login";
+    public const string AuthLogout = "auth.logout";
+    public const string AuthLoginThrottled = "auth.login.throttled";
+    public const string AccountStatusChanged = "account.status.changed";
+    public const string CourseMemberRoleChanged = "course.member.role.changed";
+    public const string CourseDelegationGranted = "course.delegation.granted";
+    public const string CourseDelegationRevoked = "course.delegation.revoked";
+    public const string CourseDelegationExpired = "course.delegation.expired";
+    public const string AccessDenied = "access.denied";
+    public const string AuditEventsViewed = "audit.events.viewed";
+}
diff --git a/backend/Platform.Audit/Contracts/AuditOutcome.cs b/backend/Platform.Audit/Contracts/AuditOutcome.cs
new file mode 100644
index 0000000..8c90d1c
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditOutcome.cs
@@ -0,0 +1,13 @@
+namespace Platform.Audit.Contracts;
+
+public enum AuditOutcome
+{
+    /// <summary>The action was carried out and persisted.</summary>
+    Success,
+
+    /// <summary>The action was refused by an authorization or policy check.</summary>
+    Denied,
+
+    /// <summary>The action was allowed but failed.</summary>
+    Failure
+}
diff --git a/backend/Platform.Audit/Contracts/AuditResourceRef.cs b/backend/Platform.Audit/Contracts/AuditResourceRef.cs
new file mode 100644
index 0000000..24fba69
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditResourceRef.cs
@@ -0,0 +1,12 @@
+namespace Platform.Audit.Contracts;
+
+/// <param name="Type">One of <see cref="AuditResourceTypes"/>.</param>
+/// <param name="Id">At most 64 characters: ASCII letters, digits, '-' and '_'.</param>
+public sealed record AuditResourceRef(string Type, string Id);
+
+public static class AuditResourceTypes
+{
+    public const string Account = "Account";
+    public const string Course = "Course";
+    public const string Delegation = "Delegation";
+}
diff --git a/backend/Platform.Audit/Contracts/AuditWriteResult.cs b/backend/Platform.Audit/Contracts/AuditWriteResult.cs
new file mode 100644
index 0000000..70b89c6
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditWriteResult.cs
@@ -0,0 +1,49 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// Anything other than <see cref="AuditWriteStatus.Recorded"/> is a failure for the caller.
+/// </summary>
+public sealed record AuditWriteResult(
+    AuditWriteStatus Status,
+    AuditRejectionCode RejectionCode,
+    Guid? EventId)
+{
+    public bool IsRecorded => Status == AuditWriteStatus.Recorded;
+
+    public static AuditWriteResult Recorded(Guid eventId) =>
+        new(AuditWriteStatus.Recorded, AuditRejectionCode.None, eventId);
+
+    public static AuditWriteResult Rejected(AuditRejectionCode code) =>
+        new(AuditWriteStatus.Rejected, code, null);
+
+    public static AuditWriteResult Unavailable() =>
+        new(AuditWriteStatus.Unavailable, AuditRejectionCode.None, null);
+}
+
+public enum AuditWriteStatus
+{
+    /// <summary>The event is stored.</summary>
+    Recorded,
+
+    /// <summary>The draft breaks the contract; nothing is stored.</summary>
+    Rejected,
+
+    /// <summary>Storage failed; nothing is guaranteed to be stored.</summary>
+    Unavailable
+}
+
+public enum AuditRejectionCode
+{
+    None,
+    UnknownEventType,
+    OutcomeNotAllowed,
+    CourseRequired,
+    CourseNotAllowed,
+    InvalidResource,
+    InvalidContext,
+    UnknownDetailKey,
+    ForbiddenDetailKey,
+    InvalidDetailValue,
+    DetailsTooLarge,
+    EventIdConflict
+}
diff --git a/backend/Platform.Audit/Contracts/IAuditWriter.cs b/backend/Platform.Audit/Contracts/IAuditWriter.cs
new file mode 100644
index 0000000..130dc71
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/IAuditWriter.cs
@@ -0,0 +1,13 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// Records a security-relevant event (AUD-01). The caller describes what happened;
+/// the actor, the time and the correlation ID come from the trusted server context.
+/// See docs/components/audit/CONTRACTS.md.
+/// </summary>
+public interface IAuditWriter
+{
+    ValueTask<AuditWriteResult> WriteAsync(
+        AuditEventDraft draft,
+        CancellationToken cancellationToken = default);
+}
diff --git a/backend/Platform.Audit/Contracts/ITrustedAuditWriter.cs b/backend/Platform.Audit/Contracts/ITrustedAuditWriter.cs
new file mode 100644
index 0000000..5acdeca
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/ITrustedAuditWriter.cs
@@ -0,0 +1,14 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// Records an event with an already confirmed context. For server-side adapters only
+/// (successful login, the Access adapter, background jobs). The context must never be
+/// built from an HTTP body, query string or header.
+/// </summary>
+public interface ITrustedAuditWriter
+{
+    ValueTask<AuditWriteResult> WriteAsync(
+        AuditEventDraft draft,
+        AuditContext context,
+        CancellationToken cancellationToken = default);
+}

From abd1a6961c6276ae233c3e713eb0c873bb27033c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nikola=20Jevti=C4=87?=
 <245982936+jevt1c@users.noreply.github.com>
Date: Tue, 3 Nov 2026 02:00:43 +0100
Subject: [PATCH 3/4] AUD-01: add event catalog, draft validator and T03 tests
 (S-02)

---
 .../AuditDraftExamples.cs                     | 100 ++++++
 .../AuditDraftValidatorTests.cs               | 293 ++++++++++++++++++
 .../AuditEventCatalogTests.cs                 |  61 ++++
 .../Application/AuditDetailFormats.cs         |  68 ++++
 .../Application/AuditDraftValidator.cs        | 120 +++++++
 .../Contracts/AuditEventCatalog.cs            | 147 +++++++++
 .../Contracts/AuditEventSchema.cs             |  62 ++++
 backend/Platform.Audit/Platform.Audit.csproj  |   3 +
 docs/components/audit/CONTRACTS.md            |  15 +-
 9 files changed, 866 insertions(+), 3 deletions(-)
 create mode 100644 backend/Platform.Audit.Tests/AuditDraftExamples.cs
 create mode 100644 backend/Platform.Audit.Tests/AuditDraftValidatorTests.cs
 create mode 100644 backend/Platform.Audit.Tests/AuditEventCatalogTests.cs
 create mode 100644 backend/Platform.Audit/Application/AuditDetailFormats.cs
 create mode 100644 backend/Platform.Audit/Application/AuditDraftValidator.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditEventCatalog.cs
 create mode 100644 backend/Platform.Audit/Contracts/AuditEventSchema.cs

diff --git a/backend/Platform.Audit.Tests/AuditDraftExamples.cs b/backend/Platform.Audit.Tests/AuditDraftExamples.cs
new file mode 100644
index 0000000..d20d80a
--- /dev/null
+++ b/backend/Platform.Audit.Tests/AuditDraftExamples.cs
@@ -0,0 +1,100 @@
+using Platform.Audit.Contracts;
+
+namespace Platform.Audit.Tests;
+
+// One valid draft per catalog event type, with a matching trusted context.
+// Synthetic identifiers only; no real accounts or courses.
+internal static class AuditDraftExamples
+{
+    public static readonly Guid UserId = Guid.Parse("11111111-1111-1111-1111-111111111111");
+    public static readonly Guid TargetAccountId = Guid.Parse("22222222-2222-2222-2222-222222222222");
+    public static readonly Guid ServiceId = Guid.Parse("33333333-3333-3333-3333-333333333333");
+    public static readonly Guid CourseId = Guid.Parse("44444444-4444-4444-4444-444444444444");
+    public static readonly Guid DelegationId = Guid.Parse("55555555-5555-5555-5555-555555555555");
+
+    public const string CorrelationId = "corr-0001";
+
+    public static AuditContext UserContext { get; } = new(AuditActor.ForUser(UserId), CorrelationId);
+    public static AuditContext ServiceContext { get; } = new(AuditActor.ForService(ServiceId), CorrelationId);
+    public static AuditContext AnonymousContext { get; } = new(AuditActor.Anonymous, CorrelationId);
+
+    public static AuditResourceRef TargetAccount { get; } =
+        new(AuditResourceTypes.Account, TargetAccountId.ToString());
+
+    public static AuditResourceRef Course { get; } =
+        new(AuditResourceTypes.Course, CourseId.ToString());
+
+    public static IEnumerable<(AuditEventDraft Draft, AuditContext Context)> ValidPerEventType()
+    {
+        yield return (
+            new AuditEventDraft(AuditEventTypes.AuthLogin, AuditOutcome.Success, Resource: TargetAccount),
+            UserContext);
+
+        yield return (
+            new AuditEventDraft(AuditEventTypes.AuthLogout, AuditOutcome.Success),
+            UserContext);
+
+        yield return (
+            new AuditEventDraft(AuditEventTypes.AuthLoginThrottled, AuditOutcome.Denied),
+            AnonymousContext);
+
+        yield return (StatusChange(), UserContext);
+
+        yield return (
+            new AuditEventDraft(
+                AuditEventTypes.CourseMemberRoleChanged,
+                AuditOutcome.Success,
+                CourseId,
+                TargetAccount,
+                Details(("oldRole", "student"), ("newRole", "assistant"))),
+            UserContext);
+
+        yield return (Delegation(AuditEventTypes.CourseDelegationGranted), UserContext);
+        yield return (Delegation(AuditEventTypes.CourseDelegationRevoked), UserContext);
+        yield return (Delegation(AuditEventTypes.CourseDelegationExpired), ServiceContext);
+
+        yield return (
+            new AuditEventDraft(
+                AuditEventTypes.AccessDenied,
+                AuditOutcome.Denied,
+                Details: Details(
+                    ("action", "audit.events.read"),
+                    ("denialReason", "no_policy"),
+                    ("policyVersion", "v0"))),
+            UserContext);
+
+        yield return (
+            new AuditEventDraft(
+                AuditEventTypes.AuditEventsViewed,
+                AuditOutcome.Success,
+                CourseId,
+                Course,
+                Details(
+                    ("filterType", "auth.login"),
+                    ("filterOutcome", "denied"),
+                    ("filterFrom", "2026-11-01T00:00:00Z"),
+                    ("filterTo", "2026-11-08T00:00:00Z"),
+                    ("resultCount", "3"))),
+            UserContext);
+    }
+
+    public static AuditEventDraft StatusChange(
+        AuditOutcome outcome = AuditOutcome.Success,
+        IReadOnlyDictionary<string, string>? details = null) =>
+        new(
+            AuditEventTypes.AccountStatusChanged,
+            outcome,
+            Resource: TargetAccount,
+            Details: details ?? Details(("oldStatus", "active"), ("newStatus", "blocked")));
+
+    public static IReadOnlyDictionary<string, string> Details(params (string Key, string Value)[] entries) =>
+        entries.ToDictionary(entry => entry.Key, entry => entry.Value, StringComparer.Ordinal);
+
+    private static AuditEventDraft Delegation(string eventType) =>
+        new(
+            eventType,
+            AuditOutcome.Success,
+            CourseId,
+            TargetAccount,
+            Details(("action", "audit.events.read"), ("delegationId", DelegationId.ToString())));
+}
diff --git a/backend/Platform.Audit.Tests/AuditDraftValidatorTests.cs b/backend/Platform.Audit.Tests/AuditDraftValidatorTests.cs
new file mode 100644
index 0000000..7e3deaf
--- /dev/null
+++ b/backend/Platform.Audit.Tests/AuditDraftValidatorTests.cs
@@ -0,0 +1,293 @@
+using NUnit.Framework;
+using Platform.Audit.Application;
+using Platform.Audit.Contracts;
+using static Platform.Audit.Tests.AuditDraftExamples;
+
+namespace Platform.Audit.Tests;
+
+// T03 (AUD-01): a draft outside the catalog is rejected with a stable code.
+[TestFixture]
+public sealed class AuditDraftValidatorTests
+{
+    private readonly AuditDraftValidator _validator = new();
+
+    private static IEnumerable<TestCaseData> ValidExamples() =>
+        AuditDraftExamples.ValidPerEventType()
+            .Select(example => new TestCaseData(example.Draft, example.Context)
+                .SetArgDisplayNames(example.Draft.EventType));
+
+    [TestCaseSource(nameof(ValidExamples))]
+    public void Validate_WhenDraftMatchesCatalog_AcceptsIt(AuditEventDraft draft, AuditContext context)
+    {
+        Assert.That(_validator.Validate(draft, context), Is.EqualTo(AuditRejectionCode.None));
+    }
+
+    [Test]
+    public void Validate_WhenFailedLoginIsAnonymousWithReason_AcceptsIt()
+    {
+        var draft = new AuditEventDraft(
+            AuditEventTypes.AuthLogin,
+            AuditOutcome.Failure,
+            Details: Details(("reasonCode", "invalid_credentials")));
+
+        Assert.That(_validator.Validate(draft, AnonymousContext), Is.EqualTo(AuditRejectionCode.None));
+    }
+
+    // Event type
+
+    [TestCase("auth.unknown")]
+    [TestCase("AUTH.LOGIN")]
+    [TestCase("auth.login ")]
+    [TestCase("")]
+    public void Validate_WhenEventTypeIsNotInCatalog_RejectsUnknownEventType(string eventType)
+    {
+        var draft = new AuditEventDraft(eventType, AuditOutcome.Success);
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.UnknownEventType));
+    }
+
+    // Outcome
+
+    [TestCase(AuditEventTypes.AuthLogout, AuditOutcome.Failure)]
+    [TestCase(AuditEventTypes.AuthLogin, AuditOutcome.Denied)]
+    [TestCase(AuditEventTypes.AuditEventsViewed, AuditOutcome.Denied)]
+    [TestCase(AuditEventTypes.AccessDenied, AuditOutcome.Success)]
+    public void Validate_WhenOutcomeIsNotAllowedForType_RejectsOutcome(string eventType, AuditOutcome outcome)
+    {
+        var draft = new AuditEventDraft(eventType, outcome);
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.OutcomeNotAllowed));
+    }
+
+    [Test]
+    public void Validate_WhenOutcomeIsUndefinedEnumValue_RejectsOutcome()
+    {
+        var draft = StatusChange((AuditOutcome)99);
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.OutcomeNotAllowed));
+    }
+
+    // Actor and correlation
+
+    [Test]
+    public void Validate_WhenUserActorHasNoId_RejectsContext()
+    {
+        var context = new AuditContext(new AuditActor(AuditActorKind.User, null), CorrelationId);
+
+        Assert.That(_validator.Validate(StatusChange(), context), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [Test]
+    public void Validate_WhenUserActorHasEmptyId_RejectsContext()
+    {
+        var context = new AuditContext(new AuditActor(AuditActorKind.User, Guid.Empty), CorrelationId);
+
+        Assert.That(_validator.Validate(StatusChange(), context), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [Test]
+    public void Validate_WhenAnonymousActorHasId_RejectsContext()
+    {
+        var context = new AuditContext(new AuditActor(AuditActorKind.Anonymous, UserId), CorrelationId);
+        var draft = new AuditEventDraft(AuditEventTypes.AuthLoginThrottled, AuditOutcome.Denied);
+
+        Assert.That(_validator.Validate(draft, context), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [Test]
+    public void Validate_WhenActorKindIsNotAllowedForOutcome_RejectsContext()
+    {
+        // A successful status change always has an authenticated actor.
+        Assert.That(_validator.Validate(StatusChange(), AnonymousContext), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [Test]
+    public void Validate_WhenExpiryIsNotFromServiceActor_RejectsContext()
+    {
+        var draft = new AuditEventDraft(
+            AuditEventTypes.CourseDelegationExpired,
+            AuditOutcome.Success,
+            CourseId,
+            TargetAccount,
+            Details(("action", "audit.events.read"), ("delegationId", DelegationId.ToString())));
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [TestCase("")]
+    [TestCase("corr 0001")]
+    [TestCase("corr-0001\nforged line")]
+    [TestCase("<script>")]
+    public void Validate_WhenCorrelationIdIsMalformed_RejectsContext(string correlationId)
+    {
+        var context = new AuditContext(AuditActor.ForUser(UserId), correlationId);
+
+        Assert.That(_validator.Validate(StatusChange(), context), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [Test]
+    public void Validate_WhenCorrelationIdIsLongerThan64_RejectsContext()
+    {
+        var context = new AuditContext(AuditActor.ForUser(UserId), new string('a', 65));
+
+        Assert.That(_validator.Validate(StatusChange(), context), Is.EqualTo(AuditRejectionCode.InvalidContext));
+    }
+
+    [Test]
+    public void Validate_WhenCorrelationIdIsExactly64_AcceptsIt()
+    {
+        var context = new AuditContext(AuditActor.ForUser(UserId), new string('a', 64));
+
+        Assert.That(_validator.Validate(StatusChange(), context), Is.EqualTo(AuditRejectionCode.None));
+    }
+
+    // Course
+
+    [Test]
+    public void Validate_WhenCourseIsMissingForCourseEvent_RejectsCourseRequired()
+    {
+        var draft = new AuditEventDraft(
+            AuditEventTypes.CourseMemberRoleChanged,
+            AuditOutcome.Success,
+            Resource: TargetAccount);
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.CourseRequired));
+    }
+
+    [Test]
+    public void Validate_WhenCourseIsEmptyGuid_RejectsCourseRequired()
+    {
+        var draft = new AuditEventDraft(
+            AuditEventTypes.CourseMemberRoleChanged,
+            AuditOutcome.Success,
+            Guid.Empty,
+            TargetAccount);
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.CourseRequired));
+    }
+
+    [Test]
+    public void Validate_WhenCourseIsGivenForAccountEvent_RejectsCourseNotAllowed()
+    {
+        var draft = StatusChange() with { CourseId = CourseId };
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.CourseNotAllowed));
+    }
+
+    // Resource
+
+    [Test]
+    public void Validate_WhenRequiredResourceIsMissing_RejectsResource()
+    {
+        var draft = StatusChange() with { Resource = null };
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidResource));
+    }
+
+    [Test]
+    public void Validate_WhenResourceHasWrongType_RejectsResource()
+    {
+        var draft = StatusChange() with { Resource = Course };
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidResource));
+    }
+
+    [Test]
+    public void Validate_WhenResourceIsGivenForLogout_RejectsResource()
+    {
+        var draft = new AuditEventDraft(AuditEventTypes.AuthLogout, AuditOutcome.Success, Resource: TargetAccount);
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidResource));
+    }
+
+    [TestCase("")]
+    [TestCase("id with spaces")]
+    [TestCase("id/../other")]
+    public void Validate_WhenResourceIdIsMalformed_RejectsResource(string resourceId)
+    {
+        var draft = StatusChange() with { Resource = new AuditResourceRef(AuditResourceTypes.Account, resourceId) };
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidResource));
+    }
+
+    // Details
+
+    [Test]
+    public void Validate_WhenDetailKeyIsNotInSchema_RejectsUnknownKey()
+    {
+        var draft = StatusChange(details: Details(("oldStatus", "active"), ("comment", "ok")));
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.UnknownDetailKey));
+    }
+
+    [Test]
+    public void Validate_WhenReasonCodeIsGivenOnSuccess_RejectsUnknownKey()
+    {
+        var draft = StatusChange(details: Details(("reasonCode", "forbidden")));
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.UnknownDetailKey));
+    }
+
+    [TestCase("password")]
+    [TestCase("Password")]
+    [TestCase("accessToken")]
+    [TestCase("sessionId")]
+    [TestCase("apiKey")]
+    public void Validate_WhenDetailKeyLooksLikeASecret_RejectsForbiddenKey(string key)
+    {
+        var draft = StatusChange(details: Details((key, "value")));
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.ForbiddenDetailKey));
+    }
+
+    [TestCase("deleted")]
+    [TestCase("ACTIVE")]
+    [TestCase("active\n")]
+    [TestCase("")]
+    public void Validate_WhenDetailValueBreaksItsFormat_RejectsValue(string value)
+    {
+        var draft = StatusChange(details: Details(("newStatus", value)));
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidDetailValue));
+    }
+
+    [TestCase("resultCount", "-1")]
+    [TestCase("resultCount", "100001")]
+    [TestCase("resultCount", "007")]
+    [TestCase("filterFrom", "2026-11-01T00:00:00+01:00")]
+    [TestCase("filterFrom", "2026-13-01T00:00:00Z")]
+    [TestCase("filterOutcome", "unknown")]
+    public void Validate_WhenFilterSummaryValueIsInvalid_RejectsValue(string key, string value)
+    {
+        var draft = new AuditEventDraft(
+            AuditEventTypes.AuditEventsViewed,
+            AuditOutcome.Success,
+            CourseId,
+            Course,
+            Details((key, value)));
+
+        Assert.That(_validator.Validate(draft, UserContext), Is.EqualTo(AuditRejectionCode.InvalidDetailValue));
+    }
+
+    [Test]
+    public void Validate_WhenMoreThan20DetailKeys_RejectsTooLarge()
+    {
+        var details = Enumerable.Range(0, AuditEventCatalog.MaxDetailKeys + 1)
+            .ToDictionary(i => $"key{i}", _ => "v");
+
+        Assert.That(
+            _validator.Validate(StatusChange(details: details), UserContext),
+            Is.EqualTo(AuditRejectionCode.DetailsTooLarge));
+    }
+
+    [Test]
+    public void Validate_WhenDetailsExceed2048Bytes_RejectsTooLarge()
+    {
+        var details = Enumerable.Range(0, 10)
+            .ToDictionary(i => $"key{i}", _ => new string('x', 300));
+
+        Assert.That(
+            _validator.Validate(StatusChange(details: details), UserContext),
+            Is.EqualTo(AuditRejectionCode.DetailsTooLarge));
+    }
+}
diff --git a/backend/Platform.Audit.Tests/AuditEventCatalogTests.cs b/backend/Platform.Audit.Tests/AuditEventCatalogTests.cs
new file mode 100644
index 0000000..6323b4c
--- /dev/null
+++ b/backend/Platform.Audit.Tests/AuditEventCatalogTests.cs
@@ -0,0 +1,61 @@
+using System.Reflection;
+using NUnit.Framework;
+using Platform.Audit.Contracts;
+
+namespace Platform.Audit.Tests;
+
+// T03: the catalog, its constants and its examples stay in sync.
+[TestFixture]
+public sealed class AuditEventCatalogTests
+{
+    [Test]
+    public void EveryEventTypeConstant_HasExactlyOneSchema()
+    {
+        var constants = typeof(AuditEventTypes)
+            .GetFields(BindingFlags.Public | BindingFlags.Static)
+            .Where(field => field.IsLiteral && field.Name != nameof(AuditEventTypes.ContractVersion))
+            .Select(field => (string)field.GetRawConstantValue()!)
+            .ToList();
+
+        Assert.That(AuditEventCatalog.Schemas.Keys, Is.EquivalentTo(constants));
+    }
+
+    [Test]
+    public void ValidExamples_CoverEverySchema()
+    {
+        var covered = AuditDraftExamples.ValidPerEventType().Select(example => example.Draft.EventType);
+
+        Assert.That(covered, Is.EquivalentTo(AuditEventCatalog.Schemas.Keys));
+    }
+
+    [Test]
+    public void NoSchema_AllowsADetailKeyThatLooksLikeASecret()
+    {
+        var forbidden = new[] { "password", "passwd", "secret", "token", "authorization", "apikey", "cookie", "session" };
+
+        var offending = AuditEventCatalog.Schemas.Values
+            .SelectMany(schema => schema.Details.Keys)
+            .Where(key => forbidden.Any(part => key.Contains(part, StringComparison.OrdinalIgnoreCase)));
+
+        Assert.That(offending, Is.Empty);
+    }
+
+    [Test]
+    public void EverySchema_AllowsAtLeastOneOutcomeAndActor()
+    {
+        foreach (var schema in AuditEventCatalog.Schemas.Values)
+        {
+            Assert.That(schema.ActorsByOutcome, Is.Not.Empty, schema.EventType);
+            Assert.That(schema.ActorsByOutcome.Values, Has.All.Not.Empty, schema.EventType);
+        }
+    }
+
+    [TestCase("auth.unknown")]
+    [TestCase("AUTH.LOGIN")]
+    [TestCase("")]
+    [TestCase(null)]
+    public void TryGet_WhenTypeIsNotInCatalog_ReturnsFalse(string? eventType)
+    {
+        Assert.That(AuditEventCatalog.TryGet(eventType, out _), Is.False);
+    }
+}
diff --git a/backend/Platform.Audit/Application/AuditDetailFormats.cs b/backend/Platform.Audit/Application/AuditDetailFormats.cs
new file mode 100644
index 0000000..bca22f1
--- /dev/null
+++ b/backend/Platform.Audit/Application/AuditDetailFormats.cs
@@ -0,0 +1,68 @@
+using System.Globalization;
+using System.Text.RegularExpressions;
+using Platform.Audit.Contracts;
+
+namespace Platform.Audit.Application;
+
+/// <summary>Value rules for <see cref="AuditDetailFormat"/>.</summary>
+internal static partial class AuditDetailFormats
+{
+    private const int MaxCount = 100_000;
+
+    private static readonly string[] AccountStatuses = ["active", "blocked", "archived"];
+    private static readonly string[] CourseRoles = ["none", "student", "teacher", "assistant"];
+    private static readonly string[] AccessDenialReasons =
+        ["unauthenticated", "account_not_active", "unknown_action", "no_policy", "policy_error"];
+    private static readonly string[] OutcomeNames = ["success", "denied", "failure"];
+
+    [GeneratedRegex(@"^[a-z][a-z0-9_]{0,31}$", RegexOptions.CultureInvariant)]
+    private static partial Regex CodePattern();
+
+    // Same rule as ActionId in Platform.Access; Audit does not reference that module.
+    [GeneratedRegex(@"^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$", RegexOptions.CultureInvariant)]
+    private static partial Regex ActionIdPattern();
+
+    [GeneratedRegex(@"^[a-z][a-z0-9_.-]{0,63}$", RegexOptions.CultureInvariant)]
+    private static partial Regex PolicyIdPattern();
+
+    [GeneratedRegex(@"^v[0-9]{1,4}(\.[0-9]{1,4}){0,2}$", RegexOptions.CultureInvariant)]
+    private static partial Regex PolicyVersionPattern();
+
+    [GeneratedRegex(@"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]{1,7})?Z$", RegexOptions.CultureInvariant)]
+    private static partial Regex UtcTimestampPattern();
+
+    [GeneratedRegex(@"^(0|[1-9][0-9]{0,5})$", RegexOptions.CultureInvariant)]
+    private static partial Regex CountPattern();
+
+    public static bool IsValid(AuditDetailFormat format, string? value)
+    {
+        if (string.IsNullOrEmpty(value)
+            || value.Length > AuditEventCatalog.MaxDetailValueLength
+            || value.Any(char.IsControl))
+            return false;
+
+        return format switch
+        {
+            AuditDetailFormat.Code => CodePattern().IsMatch(value),
+            AuditDetailFormat.ActionId => ActionIdPattern().IsMatch(value),
+            AuditDetailFormat.AccountStatus => AccountStatuses.Contains(value, StringComparer.Ordinal),
+            AuditDetailFormat.CourseRole => CourseRoles.Contains(value, StringComparer.Ordinal),
+            AuditDetailFormat.AccessDenialReason => AccessDenialReasons.Contains(value, StringComparer.Ordinal),
+            AuditDetailFormat.PolicyId => PolicyIdPattern().IsMatch(value),
+            AuditDetailFormat.PolicyVersion => PolicyVersionPattern().IsMatch(value),
+            AuditDetailFormat.Uuid => Guid.TryParseExact(value, "D", out var id) && id != Guid.Empty,
+            AuditDetailFormat.OutcomeName => OutcomeNames.Contains(value, StringComparer.Ordinal),
+            AuditDetailFormat.UtcTimestamp => IsUtcTimestamp(value),
+            AuditDetailFormat.Count => CountPattern().IsMatch(value) && int.Parse(value, CultureInfo.InvariantCulture) <= MaxCount,
+            _ => false
+        };
+    }
+
+    private static bool IsUtcTimestamp(string value) =>
+        UtcTimestampPattern().IsMatch(value)
+        && DateTimeOffset.TryParse(
+            value,
+            CultureInfo.InvariantCulture,
+            DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal,
+            out _);
+}
diff --git a/backend/Platform.Audit/Application/AuditDraftValidator.cs b/backend/Platform.Audit/Application/AuditDraftValidator.cs
new file mode 100644
index 0000000..ac23dcd
--- /dev/null
+++ b/backend/Platform.Audit/Application/AuditDraftValidator.cs
@@ -0,0 +1,120 @@
+using System.Text.Json;
+using System.Text.RegularExpressions;
+using Platform.Audit.Contracts;
+
+namespace Platform.Audit.Application;
+
+/// <summary>
+/// Checks a draft and its trusted context against <see cref="AuditEventCatalog"/>.
+/// Stateless. Returns <see cref="AuditRejectionCode.None"/> when the event may be stored.
+/// A rejected value is never copied into the result, a log or an exception.
+/// </summary>
+internal sealed partial class AuditDraftValidator
+{
+    // Additional check only; the allowlist in the catalog is the primary control.
+    private static readonly string[] ForbiddenKeyParts =
+        ["password", "passwd", "secret", "token", "authorization", "apikey", "cookie", "session"];
+
+    [GeneratedRegex(@"^[A-Za-z0-9._-]{1,64}$", RegexOptions.CultureInvariant)]
+    private static partial Regex CorrelationIdPattern();
+
+    [GeneratedRegex(@"^[A-Za-z0-9_-]{1,64}$", RegexOptions.CultureInvariant)]
+    private static partial Regex ResourceIdPattern();
+
+    public AuditRejectionCode Validate(AuditEventDraft draft, AuditContext context)
+    {
+        ArgumentNullException.ThrowIfNull(draft);
+        ArgumentNullException.ThrowIfNull(context);
+
+        if (!AuditEventCatalog.TryGet(draft.EventType, out var schema))
+            return AuditRejectionCode.UnknownEventType;
+
+        // An undefined enum value is not a key either, so it is rejected here as well.
+        if (!schema.ActorsByOutcome.TryGetValue(draft.Outcome, out var allowedActors))
+            return AuditRejectionCode.OutcomeNotAllowed;
+
+        if (!IsValidContext(context, allowedActors))
+            return AuditRejectionCode.InvalidContext;
+
+        var courseResult = CheckCourse(schema.Course, draft.CourseId);
+        if (courseResult != AuditRejectionCode.None)
+            return courseResult;
+
+        if (!IsValidResource(schema, draft.Resource))
+            return AuditRejectionCode.InvalidResource;
+
+        return CheckDetails(schema, draft.Outcome, draft.Details);
+    }
+
+    private static bool IsValidContext(AuditContext context, IReadOnlySet<AuditActorKind> allowedActors)
+    {
+        var actor = context.Actor;
+        if (actor is null || !allowedActors.Contains(actor.Kind))
+            return false;
+
+        var hasId = actor.Id is Guid id && id != Guid.Empty;
+        var idMatchesKind = actor.Kind == AuditActorKind.Anonymous ? actor.Id is null : hasId;
+
+        return idMatchesKind
+            && context.CorrelationId is not null
+            && CorrelationIdPattern().IsMatch(context.CorrelationId);
+    }
+
+    // An empty GUID is never a valid course.
+    private static AuditRejectionCode CheckCourse(AuditPresence rule, Guid? courseId) => rule switch
+    {
+        AuditPresence.Required when courseId is null || courseId == Guid.Empty => AuditRejectionCode.CourseRequired,
+        AuditPresence.Optional when courseId == Guid.Empty => AuditRejectionCode.CourseRequired,
+        AuditPresence.Forbidden when courseId is not null => AuditRejectionCode.CourseNotAllowed,
+        _ => AuditRejectionCode.None
+    };
+
+    private static bool IsValidResource(AuditEventSchema schema, AuditResourceRef? resource)
+    {
+        if (resource is null)
+            return schema.Resource != AuditPresence.Required;
+
+        if (schema.Resource == AuditPresence.Forbidden)
+            return false;
+
+        var typeAllowed = schema.ResourceType is null
+            ? resource.Type is AuditResourceTypes.Account or AuditResourceTypes.Course or AuditResourceTypes.Delegation
+            : string.Equals(resource.Type, schema.ResourceType, StringComparison.Ordinal);
+
+        return typeAllowed
+            && resource.Id is not null
+            && ResourceIdPattern().IsMatch(resource.Id);
+    }
+
+    private static AuditRejectionCode CheckDetails(
+        AuditEventSchema schema,
+        AuditOutcome outcome,
+        IReadOnlyDictionary<string, string>? details)
+    {
+        if (details is null || details.Count == 0)
+            return AuditRejectionCode.None;
+
+        // Size limits first, so an oversized input is refused before any per-key work.
+        if (details.Count > AuditEventCatalog.MaxDetailKeys
+            || JsonSerializer.SerializeToUtf8Bytes(details).Length > AuditEventCatalog.MaxDetailsBytes)
+            return AuditRejectionCode.DetailsTooLarge;
+
+        foreach (var (key, value) in details)
+        {
+            if (IsForbiddenKeyName(key))
+                return AuditRejectionCode.ForbiddenDetailKey;
+
+            if (!schema.Details.TryGetValue(key, out var field)
+                || (field.OnlyForOutcomes is not null && !field.OnlyForOutcomes.Contains(outcome)))
+                return AuditRejectionCode.UnknownDetailKey;
+
+            if (!AuditDetailFormats.IsValid(field.Format, value))
+                return AuditRejectionCode.InvalidDetailValue;
+        }
+
+        return AuditRejectionCode.None;
+    }
+
+    private static bool IsForbiddenKeyName(string key) =>
+        ForbiddenKeyParts.Any(part => key.Contains(part, StringComparison.OrdinalIgnoreCase));
+}
diff --git a/backend/Platform.Audit/Contracts/AuditEventCatalog.cs b/backend/Platform.Audit/Contracts/AuditEventCatalog.cs
new file mode 100644
index 0000000..f33b74a
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditEventCatalog.cs
@@ -0,0 +1,147 @@
+using System.Collections.Frozen;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// Catalog schema version 1: every event type the Audit module accepts and what each one
+/// allows. Anything not listed here is rejected. See docs/components/audit/CONTRACTS.md.
+/// </summary>
+public static class AuditEventCatalog
+{
+    public const int SchemaVersion = 1;
+    public const int MaxDetailKeys = 20;
+    public const int MaxDetailsBytes = 2048;
+    public const int MaxDetailValueLength = 64;
+
+    private static readonly IReadOnlySet<AuditActorKind> User = Kinds(AuditActorKind.User);
+    private static readonly IReadOnlySet<AuditActorKind> Service = Kinds(AuditActorKind.Service);
+    private static readonly IReadOnlySet<AuditActorKind> Anonymous = Kinds(AuditActorKind.Anonymous);
+    private static readonly IReadOnlySet<AuditActorKind> UserOrAnonymous =
+        Kinds(AuditActorKind.User, AuditActorKind.Anonymous);
+
+    private static readonly AuditDetailField ReasonCode = new(
+        AuditDetailFormat.Code,
+        new[] { AuditOutcome.Denied, AuditOutcome.Failure }.ToFrozenSet());
+
+    // Privileged changes: denied for an anonymous caller too, failed only for an authenticated one.
+    private static readonly IReadOnlyDictionary<AuditOutcome, IReadOnlySet<AuditActorKind>> PrivilegedChange =
+        Outcomes(
+            (AuditOutcome.Success, User),
+            (AuditOutcome.Denied, UserOrAnonymous),
+            (AuditOutcome.Failure, User));
+
+    public static IReadOnlyDictionary<string, AuditEventSchema> Schemas { get; } = new[]
+    {
+        new AuditEventSchema(
+            AuditEventTypes.AuthLogin,
+            Outcomes((AuditOutcome.Success, User), (AuditOutcome.Failure, UserOrAnonymous)),
+            AuditPresence.Forbidden,
+            AuditPresence.Optional,
+            AuditResourceTypes.Account,
+            Fields(("reasonCode", ReasonCode))),
+
+        new AuditEventSchema(
+            AuditEventTypes.AuthLogout,
+            Outcomes((AuditOutcome.Success, User)),
+            AuditPresence.Forbidden,
+            AuditPresence.Forbidden,
+            null,
+            Fields()),
+
+        new AuditEventSchema(
+            AuditEventTypes.AuthLoginThrottled,
+            Outcomes((AuditOutcome.Denied, Anonymous)),
+            AuditPresence.Forbidden,
+            AuditPresence.Forbidden,
+            null,
+            Fields()),
+
+        new AuditEventSchema(
+            AuditEventTypes.AccountStatusChanged,
+            PrivilegedChange,
+            AuditPresence.Forbidden,
+            AuditPresence.Required,
+            AuditResourceTypes.Account,
+            Fields(
+                ("oldStatus", new AuditDetailField(AuditDetailFormat.AccountStatus)),
+                ("newStatus", new AuditDetailField(AuditDetailFormat.AccountStatus)),
+                ("reasonCode", ReasonCode))),
+
+        new AuditEventSchema(
+            AuditEventTypes.CourseMemberRoleChanged,
+            PrivilegedChange,
+            AuditPresence.Required,
+            AuditPresence.Required,
+            AuditResourceTypes.Account,
+            Fields(
+                ("oldRole", new AuditDetailField(AuditDetailFormat.CourseRole)),
+                ("newRole", new AuditDetailField(AuditDetailFormat.CourseRole)),
+                ("reasonCode", ReasonCode))),
+
+        Delegation(AuditEventTypes.CourseDelegationGranted),
+        Delegation(AuditEventTypes.CourseDelegationRevoked),
+
+        new AuditEventSchema(
+            AuditEventTypes.CourseDelegationExpired,
+            Outcomes((AuditOutcome.Success, Service)),
+            AuditPresence.Required,
+            AuditPresence.Required,
+            AuditResourceTypes.Account,
+            Fields(
+                ("action", new AuditDetailField(AuditDetailFormat.ActionId)),
+                ("delegationId", new AuditDetailField(AuditDetailFormat.Uuid)))),
+
+        new AuditEventSchema(
+            AuditEventTypes.AccessDenied,
+            Outcomes((AuditOutcome.Denied, UserOrAnonymous)),
+            AuditPresence.Optional,
+            AuditPresence.Optional,
+            null,
+            Fields(
+                ("action", new AuditDetailField(AuditDetailFormat.ActionId)),
+                ("denialReason", new AuditDetailField(AuditDetailFormat.AccessDenialReason)),
+                ("policyId", new AuditDetailField(AuditDetailFormat.PolicyId)),
+                ("policyVersion", new AuditDetailField(AuditDetailFormat.PolicyVersion)))),
+
+        new AuditEventSchema(
+            AuditEventTypes.AuditEventsViewed,
+            Outcomes((AuditOutcome.Success, User)),
+            AuditPresence.Required,
+            AuditPresence.Required,
+            AuditResourceTypes.Course,
+            Fields(
+                ("filterType", new AuditDetailField(AuditDetailFormat.ActionId)),
+                ("filterOutcome", new AuditDetailField(AuditDetailFormat.OutcomeName)),
+                ("filterFrom", new AuditDetailField(AuditDetailFormat.UtcTimestamp)),
+                ("filterTo", new AuditDetailField(AuditDetailFormat.UtcTimestamp)),
+                ("resultCount", new AuditDetailField(AuditDetailFormat.Count)))),
+    }.ToFrozenDictionary(schema => schema.EventType, StringComparer.Ordinal);
+
+    public static bool TryGet(string? eventType, [NotNullWhen(true)] out AuditEventSchema? schema)
+    {
+        schema = null;
+        return eventType is not null && Schemas.TryGetValue(eventType, out schema);
+    }
+
+    private static AuditEventSchema Delegation(string eventType) => new(
+        eventType,
+        PrivilegedChange,
+        AuditPresence.Required,
+        AuditPresence.Required,
+        AuditResourceTypes.Account,
+        Fields(
+            ("action", new AuditDetailField(AuditDetailFormat.ActionId)),
+            ("delegationId", new AuditDetailField(AuditDetailFormat.Uuid)),
+            ("reasonCode", ReasonCode)));
+
+    private static IReadOnlySet<AuditActorKind> Kinds(params AuditActorKind[] kinds) => kinds.ToFrozenSet();
+
+    private static IReadOnlyDictionary<AuditOutcome, IReadOnlySet<AuditActorKind>> Outcomes(
+        params (AuditOutcome Outcome, IReadOnlySet<AuditActorKind> Actors)[] entries) =>
+        entries.ToFrozenDictionary(entry => entry.Outcome, entry => entry.Actors);
+
+    private static IReadOnlyDictionary<string, AuditDetailField> Fields(
+        params (string Key, AuditDetailField Field)[] entries) =>
+        entries.ToFrozenDictionary(entry => entry.Key, entry => entry.Field, StringComparer.Ordinal);
+}
diff --git a/backend/Platform.Audit/Contracts/AuditEventSchema.cs b/backend/Platform.Audit/Contracts/AuditEventSchema.cs
new file mode 100644
index 0000000..ab06976
--- /dev/null
+++ b/backend/Platform.Audit/Contracts/AuditEventSchema.cs
@@ -0,0 +1,62 @@
+namespace Platform.Audit.Contracts;
+
+/// <summary>
+/// What one event type allows. The allowed outcomes are the keys of
+/// <see cref="ActorsByOutcome"/>; each outcome lists the actor kinds allowed with it.
+/// </summary>
+/// <param name="ResourceType">Required resource type, or null for any of <see cref="AuditResourceTypes"/>.</param>
+public sealed record AuditEventSchema(
+    string EventType,
+    IReadOnlyDictionary<AuditOutcome, IReadOnlySet<AuditActorKind>> ActorsByOutcome,
+    AuditPresence Course,
+    AuditPresence Resource,
+    string? ResourceType,
+    IReadOnlyDictionary<string, AuditDetailField> Details);
+
+public enum AuditPresence
+{
+    Required,
+    Optional,
+    Forbidden
+}
+
+/// <param name="OnlyForOutcomes">Outcomes with which the field may appear, or null for all.</param>
+public sealed record AuditDetailField(
+    AuditDetailFormat Format,
+    IReadOnlySet<AuditOutcome>? OnlyForOutcomes = null);
+
+public enum AuditDetailFormat
+{
+    /// <summary><c>^[a-z][a-z0-9_]{0,31}$</c></summary>
+    Code,
+
+    /// <summary>Action or event type, same rule as <c>ActionId</c> in Platform.Access.</summary>
+    ActionId,
+
+    /// <summary><c>active</c>, <c>blocked</c> or <c>archived</c>.</summary>
+    AccountStatus,
+
+    /// <summary><c>none</c>, <c>student</c>, <c>teacher</c> or <c>assistant</c>.</summary>
+    CourseRole,
+
+    /// <summary>A denial reason of Platform.Access in snake_case.</summary>
+    AccessDenialReason,
+
+    /// <summary><c>^[a-z][a-z0-9_.-]{0,63}$</c></summary>
+    PolicyId,
+
+    /// <summary><c>^v[0-9]{1,4}(\.[0-9]{1,4}){0,2}$</c></summary>
+    PolicyVersion,
+
+    /// <summary>A non-empty UUID.</summary>
+    Uuid,
+
+    /// <summary><c>success</c>, <c>denied</c> or <c>failure</c>.</summary>
+    OutcomeName,
+
+    /// <summary>ISO 8601 UTC timestamp ending with <c>Z</c>.</summary>
+    UtcTimestamp,
+
+    /// <summary>Integer from 0 to 100000.</summary>
+    Count
+}
diff --git a/backend/Platform.Audit/Platform.Audit.csproj b/backend/Platform.Audit/Platform.Audit.csproj
index fc34a2b..dd4de7c 100644
--- a/backend/Platform.Audit/Platform.Audit.csproj
+++ b/backend/Platform.Audit/Platform.Audit.csproj
@@ -7,4 +7,7 @@
   <ItemGroup>
     <FrameworkReference Include="Microsoft.AspNetCore.App" />
   </ItemGroup>
+  <ItemGroup>
+    <InternalsVisibleTo Include="Platform.Audit.Tests" />
+  </ItemGroup>
 </Project>
diff --git a/docs/components/audit/CONTRACTS.md b/docs/components/audit/CONTRACTS.md
index 9d1384e..05010a5 100644
--- a/docs/components/audit/CONTRACTS.md
+++ b/docs/components/audit/CONTRACTS.md
@@ -164,7 +164,7 @@ with `EventIdConflict` and never replaces the stored record.
 
 | Event type | Producer (requirement) | Outcomes | Actor | Course | Resource | Allowed details |
 |-|-|-|-|-|-|-|
-| `auth.login` | Identity (IDN-02) | Success, Failure | Success: `User`. Failure: `Anonymous`, or `User` when the credentials were valid but the account is not active | forbidden | `Account` on Success | `reasonCode` |
+| `auth.login` | Identity (IDN-02) | Success, Failure | Success: `User`. Failure: `Anonymous`, or `User` when the credentials were valid but the account is not active | forbidden | optional `Account` (the account that logged in) | `reasonCode` |
 | `auth.logout` | Identity (IDN-02) | Success | `User` | forbidden | none | none |
 | `auth.login.throttled` | Identity (IDN-05) | Denied | `Anonymous` | forbidden | none | none |
 | `account.status.changed` | Identity (IDN-03), Admin (ADM-01) | Success, Denied, Failure | `User` or `Anonymous` (Denied, not logged in) | forbidden | `Account` (required) | `oldStatus`, `newStatus`, `reasonCode` |
@@ -175,7 +175,12 @@ with `EventIdConflict` and never replaces the stored record.
 | `access.denied` | Access, Team 3 (ACC-05), through the host adapter | Denied | `User` or `Anonymous` | optional, only from a trusted resource resolver | optional | `action`, `denialReason`, `policyId`, `policyVersion` |
 | `audit.events.viewed` | Audit (AUD-06) | Success | `User` | required | `Course` (required) | `filterType`, `filterOutcome`, `filterFrom`, `filterTo`, `resultCount` |
 
-`reasonCode` is only allowed when the outcome is `Denied` or `Failure`.
+`reasonCode` is only allowed when the outcome is `Denied` or `Failure`. An empty GUID is never a
+valid `CourseId`.
+
+The catalog is `AuditEventCatalog` in `Platform.Audit.Contracts`, so producers can see what each
+type allows. The checks are done by the internal `AuditDraftValidator` in
+`Platform.Audit.Application`, which the writer (story S-06) calls before storing an event.
 
 ### Detail value formats
 
@@ -186,7 +191,7 @@ with `EventIdConflict` and never replaces the stored record.
 | `oldRole`, `newRole` | one of `none`, `student`, `teacher`, `assistant` |
 | `action`, `filterType` | action or event type: `^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$`, at most 64 characters (same rule as `ActionId` in `Platform.Access`) |
 | `denialReason` | one of `unauthenticated`, `account_not_active`, `unknown_action`, `no_policy`, `policy_error` |
-| `policyId` | code, at most 64 characters |
+| `policyId` | `^[a-z][a-z0-9_.-]{0,63}$` |
 | `policyVersion` | `^v[0-9]{1,4}(\.[0-9]{1,4}){0,2}$` |
 | `delegationId` | UUID |
 | `filterOutcome` | one of `success`, `denied`, `failure` |
@@ -203,6 +208,10 @@ with `EventIdConflict` and never replaces the stored record.
 | Detail value | its format above; at most 64 characters; no control characters |
 | All details together | at most 2048 bytes after serialization to UTF-8 JSON |
 
+Details are checked in this order: number of keys and total size first, so an oversized input is
+refused before any per-key work; then, for each key, the forbidden-name check, the allowlist and
+the value format.
+
 The allowlist is the primary control. As an additional check, a key whose name contains
 `password`, `passwd`, `secret`, `token`, `authorization`, `apikey`, `cookie` or `session`
 (ignoring case) is rejected with `ForbiddenDetailKey` even if someone adds it to the catalog by

From 155244ec2812a69b8e4bcd22031919905648aa75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Nikola=20Jevti=C4=87?=
 <245982936+jevt1c@users.noreply.github.com>
Date: Tue, 3 Nov 2026 02:02:33 +0100
Subject: [PATCH 4/4] AUD-01: mark audit writer test double as planned (S-02)

---
 docs/components/audit/CONTRACTS.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/components/audit/CONTRACTS.md b/docs/components/audit/CONTRACTS.md
index 05010a5..bb3131d 100644
--- a/docs/components/audit/CONTRACTS.md
+++ b/docs/components/audit/CONTRACTS.md
@@ -242,9 +242,10 @@ as is already done for the two `IAccessDecision` interfaces.
 
 ## Test double
 
-`FakeAuditWriter` implements both writer interfaces, records every draft and returns a result
-that the test sets (`Recorded`, `Rejected` with a code, or `Unavailable`). It does not validate
-like the real writer, so a test that passes with the fake does not prove the contract rules.
+Planned, not in this version: `FakeAuditWriter` will implement both writer interfaces, record
+every draft and return a result that the test sets (`Recorded`, `Rejected` with a code, or
+`Unavailable`). It will not validate like the real writer, so a test that passes with the fake
+does not prove the contract rules.
 Those are proven by the Audit module's own tests.
 
 ## How the contract is verified (test group T03)