droboticflow/docs/drosync/audit-dictionary.md
2026-07-28 20:43:46 +08:00

27 lines
2.0 KiB
Markdown

# Audit dictionary
Each audit event contains:
| Field | Meaning |
|---|---|
| `id`, `eventKey` | Immutable identity and idempotent insertion key. |
| `organizationId` | Tenant chain boundary. |
| `actorType`, `actorId` | `user`, `device`, or system actor. |
| `credentialId`, `deviceId` | Device authorization lineage when applicable. |
| `requestId` | API request correlation identifier. |
| `sessionId`, `itemId` | Transfer lineage. |
| `action` | Stable verb such as `space.create`, `space.probe`, `session.create`, `space.reconcile`, or `lease.force_release`. |
| `target` | Non-secret identifiers for the affected resource. |
| `before`, `after` | Sanitized state deltas when supplied. |
| `result`, `reason` | Outcome and operator/system rationale. |
| `previousHash`, `eventHash` | Organization hash-chain link and SHA-256 hash of the canonical event payload. |
| `occurredAt` | UTC RFC3339 timestamp. |
An organization-scoped fencing lease serializes hash-chain append across API replicas. Events retain for one year. Export endpoints are read-only and available as CSV or NDJSON.
The coordinator verifies every event hash and intra-day chain link, then conditionally writes the previous UTC day's count, first/last event hash, aggregate digest, Ed25519 signature, and verifier key ID to `.drosync-internal/audit/{organizationId}/{YYYY-MM-DD}.json`. Mongo stores the BOS ETag/version ID and seal index for one year. `GET /api/object-sync/audit-seals/{day}` returns the index record.
`DROSYNC_AUDIT_SIGNING_PRIVATE_KEY` accepts a base64 Ed25519 32-byte seed or 64-byte private key; `DROSYNC_AUDIT_SIGNING_KEY_ID` identifies the verifier key. When object sync is enabled, the coordinator refuses to start without a valid signing key. The private key must be supplied through the `drosync-signing-secret` Kubernetes Secret and must never enter the repository.
Production readiness still requires a live seal HEAD/readback plus independent public-key verification; source code or an unsigned export is not equivalent evidence.