Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00%
1 / 1
n/a
0 / 0
 CRAP
n/a
0 / 0
1<?php
2
3declare(strict_types=1);
4
5/** @license For full copyright and license information, please see the LICENSE.md file. */
6
7namespace App\Core\Audit\Application\Service;
8
9defined('AMMONLY_APP') || exit('Direct script access is forbidden.');
10
11use App\Core\Audit\Domain\Model\SecurityEventSeverity;
12use App\Core\Audit\Domain\Model\SecurityEventType;
13use Psr\Http\Message\ServerRequestInterface;
14
15/**
16 * Contract for logging security audit events.
17 *
18 * @package App\Core\Audit\Application\Service
19 */
20interface SecurityAuditLoggerInterface
21{
22    /**
23     * Records a security event with full metadata extraction.
24     *
25     * @param SecurityEventType            $type      Classified event type.
26     * @param SecurityEventSeverity        $severity  Severity level.
27     * @param string                       $message   Incident description.
28     * @param array<string, mixed>         $context   Additional metadata context.
29     * @param ServerRequestInterface|null  $request   Optional PSR-7 server request.
30     * @param int|null                     $actorId   Optional actor user ID.
31     * @return int Persisted record ID.
32     */
33    public function log(
34        SecurityEventType $type,
35        SecurityEventSeverity $severity,
36        string $message,
37        array $context = [],
38        ?ServerRequestInterface $request = null,
39        ?int $actorId = null
40    ): int;
41
42    /**
43     * Logs rate-limit violation event.
44     *
45     * @param string $ip Remote IP address.
46     * @param string $uri Request URI.
47     * @param string|null $requestId Correlated request identifier.
48     * @return int Persisted record ID.
49     */
50    public function logRateLimitExceeded(
51        string $ip,
52        string $uri,
53        ?string $requestId = null
54    ): int;
55
56    /**
57     * Logs CSRF validation violation event (403 Forbidden).
58     *
59     * @param string $ip Remote IP address.
60     * @param string $uri Request URI.
61     * @param string|null $requestId Correlated request identifier.
62     * @param int|null $actorId Active user identifier.
63     * @return int Persisted record ID.
64     */
65    public function logCsrfViolation(
66        string $ip,
67        string $uri,
68        ?string $requestId = null,
69        ?int $actorId = null
70    ): int;
71
72    /**
73     * Logs unauthorized access attempt (401 / invalid API token).
74     *
75     * @param string $message Failure message.
76     * @param ServerRequestInterface|null $request Optional server request.
77     * @return int Persisted record ID.
78     */
79    public function logUnauthorizedAccess(
80        string $message,
81        ?ServerRequestInterface $request = null
82    ): int;
83}