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

2.0 KiB

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.