> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# AuditChain — Dashboard API (source-reviewed)

**Base URL:** `/api/v1`. **Authentication:** `Authorization: Bearer <Sanctum token>`. **Permission:** `audit.verify` for both operations. All JSON examples are illustrative values with **source-confirmed structure**, not captured live responses. `Accept: application/json` recommended. No path/query/body parameters are read by these controllers.

Sources: [routes](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/AuditChain/Routes/api.php), [controller](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/AuditChain/Interfaces/Http/Controllers/IntegrityController.php), [store interface](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/AuditChain/Application/ChainStore.php), [auditor](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/AuditChain/Application/ChainAuditor.php), [response envelope](https://gitlab.com/alalmiyalhura/outlet/-/blob/main/modules/Core/Interfaces/Http/Responses/ApiResponse.php).

## 1. `GET /api/v1/audit/integrity`

**Purpose:** display the last saved integrity verification, current chain head, and anchor count. This is a **read-only cached report**, **not** a fresh verification.

**Request:** no query, path parameters or JSON body. Example:

```http
GET /api/v1/audit/integrity HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
```

**200 Response — example (never verified):**

```json
{
  "data": {
    "status": "never_verified",
    "last_report": null,
    "head": {"seq": 0, "hash": "<chain-head-hash>"},
    "anchors": 0
  }
}
```

| JSON path | Type | Meaning / conditions |
|---|---|---|
| `data` | object | Standard `ApiResponse::ok` wrapper |
| `data.status` | enum string | `never_verified` if no report, otherwise `intact` when last report `ok=true`, or `tampered` |
| `data.last_report` | object \| null | Most recently saved verification, null until first verification |
| `data.last_report.ok` | boolean | Integrity outcome |
| `data.last_report.checked` | integer | Number of inspected chain links |
| `data.last_report.break` | object \| null | Tampering detail; inner keys depend on `Tampering::toArray()` |
| `data.last_report.anchors_checked` | boolean | Whether saved/external anchors were compared |
| `data.last_report.at` | ISO timestamp string | Time of saved verification |
| `data.head.seq` | integer | Last sealed chain sequence |
| `data.head.hash` | string | Hash of last sealed chain link |
| `data.anchors` | integer | Number of stored anchors |

**Frontend:** show `never_verified` distinctly from `intact`; don't infer that a prior `intact` status guarantees the chain is still intact now. A verification must be triggered separately.

## 2. `POST /api/v1/audit/integrity/verify`

**Purpose:** run a full integrity check immediately and persist the result. **Throttle:** 2 requests/minute. A scheduled verification is the normal path.

**Request:** no JSON body or parameters. Example:

```http
POST /api/v1/audit/integrity/verify HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
```

**200 Response — illustrative successful run:**

```json
{
  "data": {
    "ok": true,
    "checked": 125,
    "break": null
  }
}
```

| JSON path | Type | Meaning |
|---|---|---|
| `data.ok` | boolean | Whether verification passed |
| `data.checked` | integer | Number of checked links |
| `data.break` | object \| null | Null on success; tampering detail on failure, serialized by `Tampering::toArray()` |

**Business logic:** auditor checks chain rows, old unsealed audit records, and anchors. A failed integrity check returns `ok=false` in the normal 200 response (it does **not** imply an HTTP 500); the auditor also emits an `audit.integrity_failed` webhook. The check can be costly.

**Error handling:** unauthenticated → typically HTTP 401; missing permission → typically 403; throttle exceeded → typically 429. The exact error JSON envelope depends on global exception handling and is **not verified here**. Don't assume `data` exists for errors.

**Flutter:** no dedicated Flutter endpoint; these routes require administrative permission.
