github/OpenArchiver
1
1
Fork 0
mirror of https://github.com/LogicLabs-OU/OpenArchiver.git synced 2026-04-06 00:31:57 +02:00
Code Issues 161 Packages Projects Releases Wiki Activity

Audit-log docs

Browse Source
This commit is contained in:
Wayne
2025-10-03 10:58:22 +02:00
parent d99fcfcc27
commit 2030264838
5 changed files with 176 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/enterprise/audit-log/api.md Normal file
View File

@@ -0,0 +1,78 @@
# Audit Log: API Endpoints
The audit log feature exposes two API endpoints for retrieving and verifying audit log data. Both endpoints require authentication and are only accessible to users with the appropriate permissions.
## Get Audit Logs
Retrieves a paginated list of audit log entries, with support for filtering and sorting.
- **Endpoint:** `GET /api/v1/enterprise/audit-logs`
- **Method:** `GET`
- **Authentication:** Required
### Query Parameters
| Parameter | Type | Description |
| ------------ | -------- | --------------------------------------------------------------------------- |
| `page` | `number` | The page number to retrieve. Defaults to `1`. |
| `limit` | `number` | The number of entries to retrieve per page. Defaults to `20`. |
| `startDate` | `date` | The start date for the date range filter. |
| `endDate` | `date` | The end date for the date range filter. |
| `actor` | `string` | The actor identifier to filter by. |
| `actionType` | `string` | The action type to filter by (e.g., `LOGIN`, `CREATE`). |
| `sort` | `string` | The sort order for the results. Can be `asc` or `desc`. Defaults to `desc`. |
### Response Body
```json
{
"data": [
{
"id": 1,
"previousHash": null,
"timestamp": "2025-10-03T00:00:00.000Z",
"actorIdentifier": "e8026a75-b58a-4902-8858-eb8780215f82",
"actorIp": "::1",
"actionType": "LOGIN",
"targetType": "User",
"targetId": "e8026a75-b58a-4902-8858-eb8780215f82",
"details": {},
"currentHash": "..."
}
],
"meta": {
"total": 100,
"page": 1,
"limit": 20
}
}
```
## Verify Audit Log Integrity
Initiates a verification process to check the integrity of the entire audit log chain.
- **Endpoint:** `POST /api/v1/enterprise/audit-logs/verify`
- **Method:** `POST`
- **Authentication:** Required
### Response Body
**Success**
```json
{
"ok": true,
"message": "Audit log integrity verified successfully."
}
```
**Failure**
```json
{
"ok": false,
"message": "Audit log chain is broken!",
"logId": 123
}
```

31
docs/enterprise/audit-log/audit-service.md Normal file
View File

@@ -0,0 +1,31 @@
# Audit Log: Backend Implementation
The backend implementation of the audit log is handled by the `AuditService`, located in `packages/backend/src/services/AuditService.ts`. This service encapsulates all the logic for creating, retrieving, and verifying audit log entries.
## Hashing and Verification Logic
The core of the audit log's immutability lies in its hashing and verification logic.
### Hash Calculation
The `calculateHash` method is responsible for generating a SHA-256 hash of a log entry. To ensure consistency, it performs the following steps:
1. **Canonical Object Creation:** It constructs a new object with a fixed property order, ensuring that the object's structure is always the same.
2. **Timestamp Normalization:** It converts the `timestamp` to milliseconds since the epoch (`getTime()`) to avoid any precision-related discrepancies between the application and the database.
3. **Canonical Stringification:** It uses a custom `canonicalStringify` function to create a JSON string representation of the object. This function sorts the object keys, ensuring that the output is always the same, regardless of the in-memory property order.
4. **Hash Generation:** It computes a SHA-256 hash of the canonical string.
### Verification Process
The `verifyAuditLog` method is designed to be highly scalable and efficient, even with millions of log entries. It processes the logs in manageable chunks (e.g., 1000 at a time) to avoid loading the entire table into memory.
The verification process involves the following steps:
1. **Iterative Processing:** It fetches the logs in batches within a `while` loop.
2. **Chain Verification:** For each log entry, it compares the `previousHash` with the `currentHash` of the preceding log. If they do not match, the chain is broken, and the verification fails.
3. **Hash Recalculation:** It recalculates the hash of the current log entry using the same `calculateHash` method used during creation.
4. **Integrity Check:** It compares the recalculated hash with the `currentHash` stored in the database. If they do not match, the log entry has been tampered with, and the verification fails.
## Service Integration
The `AuditService` is integrated into the application through the `AuditLogModule` (`packages/enterprise/src/modules/audit-log/audit-log.module.ts`), which registers the API routes for the audit log feature. The service's `createAuditLog` method is called from various other services throughout the application to record significant events.

39
docs/enterprise/audit-log/guide.md Normal file
View File

@@ -0,0 +1,39 @@
# Audit Log: User Interface
The audit log user interface provides a comprehensive view of all significant events that have occurred within the Open Archiver system. It is designed to be intuitive and user-friendly, allowing administrators to easily monitor and review system activity.
## Viewing Audit Logs
The main audit log page displays a table of log entries, with the following columns:
- **Timestamp:** The date and time of the event.
- **Actor:** The identifier of the user or system process that performed the action.
- **IP Address:** The IP address from which the action was initiated.
- **Action:** The type of action performed, displayed as a color-coded badge for easy identification.
- **Target Type:** The type of resource that was affected.
- **Target ID:** The unique identifier of the affected resource.
- **Details:** A truncated preview of the event's details. The full JSON object is displayed in a pop-up card on hover.
## Filtering and Sorting
The table can be sorted by timestamp by clicking the "Timestamp" header. This allows you to view the logs in either chronological or reverse chronological order.
## Pagination
Pagination controls are available below the table, allowing you to navigate through the entire history of audit log entries.
## Verifying Log Integrity
The "Verify Log Integrity" button allows you to initiate a verification process to check the integrity of the entire audit log chain. This process recalculates the hash of each log entry and compares it to the stored hash, ensuring that the cryptographic chain is unbroken and no entries have been tampered with.
### Verification Responses
- **Success:** A success notification is displayed, confirming that the audit log integrity has been verified successfully. This means that the log chain is complete and no entries have been tampered with.
- **Failure:** An error notification is displayed, indicating that the audit log chain is broken or an entry has been tampered with. The notification will include the ID of the log entry where the issue was detected. There are two types of failures:
- **Audit log chain is broken:** This means that the `previousHash` of a log entry does not match the `currentHash` of the preceding entry. This indicates that one or more log entries may have been deleted or inserted into the chain.
- **Audit log entry is tampered!:** This means that the recalculated hash of a log entry does not match its stored `currentHash`. This indicates that the data within the log entry has been altered.
## Viewing Log Details
You can view the full details of any log entry by clicking on its row in the table. This will open a dialog containing all the information associated with the log entry, including the previous and current hashes.

27
docs/enterprise/audit-log/index.md Normal file
View File

@@ -0,0 +1,27 @@
# Audit Log
The Audit Log is an enterprise-grade feature designed to provide a complete, immutable, and verifiable record of every significant action that occurs within the Open Archiver system. Its primary purpose is to ensure compliance with strict regulatory standards, such as the German GoBD, by establishing a tamper-proof chain of evidence for all activities.
## Core Principles
To fulfill its compliance and security functions, the audit log adheres to the following core principles:
### 1. Immutability
Every log entry is cryptographically chained to the previous one. Each new entry contains a SHA-256 hash of the preceding entry's hash, creating a verifiable chain. Any attempt to alter or delete a past entry would break this chain and be immediately detectable through the verification process.
### 2. Completeness
The system is designed to log every significant event without exception. This includes not only user-initiated actions (like logins, searches, and downloads) but also automated system processes, such as data ingestion and policy-based deletions.
### 3. Attribution
Each log entry is unambiguously linked to the actor that initiated the event. This could be a specific authenticated user, an external auditor, or an automated system process. The actor's identifier and source IP address are recorded to ensure full traceability.
### 4. Clarity and Detail
Log entries are structured to be detailed and human-readable, providing sufficient context for an auditor to understand the event without needing specialized system knowledge. This includes the action performed, the target resource affected, and a JSON object with specific, contextual details of the event.
### 5. Verifiability
The integrity of the entire audit log can be verified at any time. A dedicated process iterates through the logs from the beginning, recalculating the hash of each entry and comparing it to the stored hash, ensuring the cryptographic chain is unbroken and no entries have been tampered with.

6
packages/frontend/src/routes/dashboard/+layout.svelte
View File

@@ -6,7 +6,6 @@
import { page } from '$app/state';
import ThemeSwitcher from '$lib/components/custom/ThemeSwitcher.svelte';
import { t } from '$lib/translations';
import type { LayoutData } from '../$types';
let { data, children } = $props();
interface NavItem {
@@ -49,10 +48,7 @@
const enterpriseNavItems: NavItem[] = [
{
label: 'Compliance',
subMenu: [
{ href: '/dashboard/compliance-center', label: 'Compliance Center' },
{ href: '/dashboard/compliance/audit-log', label: 'Audit Log' },
],
subMenu: [{ href: '/dashboard/compliance/audit-log', label: 'Audit Log' }],
},
];