Weave Code
Core Laravel Package
laravel-chronicle/core
Chronicle provides cryptographically verifiable audit logging for Laravel. It records events in an append-only, hash-chained ledger to make tampering detectable, with features like verifiable exports, signed checkpoints, key rotation, and external anchoring.
Chronicle - Verifiable Audit Logging and Append-Only Audit Trails for Laravel.
Frequently asked questions about Core
- How does Chronicle ensure audit logs in Laravel are tamper-proof?
- Chronicle uses cryptographic hash chaining—each log entry’s hash depends on the previous one. If any entry is altered, the chain breaks, making tampering immediately detectable. This is enforced via PHP’s ext-sodium for Ed25519 signatures and OpenSSL for hashing.
- Can I use Chronicle with Laravel 11 or older versions?
- No, Chronicle requires **Laravel 12 or 13** and **PHP 8.2+** due to dependencies on ext-sodium and ext-openssl. Older Laravel versions lack native support for these cryptographic primitives, so downgrades aren’t supported.
- What’s the performance impact of hash-chained logging in production?
- Hash chaining adds ~5–15ms per entry (varies by hardware). For high-volume systems, batch recording via queues or bulk inserts can mitigate latency. Benchmark with your expected throughput before deployment.
- How do I audit model changes automatically without manual logging?
- Use the `HasChronicle` trait on Eloquent models. Chronicle auto-records CRUD operations (create, update, delete) with actor, action, and subject metadata. Customize via `chronicle()` method overrides or observers.
- What happens if I lose the private key used to sign checkpoints?
- Losing the active private key makes new checkpoints unverifiable, but **historical entries remain tamper-proof** via the hash chain. Backup keys securely (e.g., AWS KMS or HSM) and rotate keys using `chronicle:rotate-key` before expiration.
- Does Chronicle support external anchoring (e.g., RFC 3161 timestamps or S3 Object Lock)?
- Yes, Chronicle supports optional external anchoring via providers like RFC 3161 TSAs or AWS S3 Object Lock. Configure in `.env` with `CHRONICLE_ANCHOR_PROVIDER`. Anchoring prevents database-level tampering by linking checkpoints to immutable third-party sources.
- How do I verify the integrity of a Chronicle ledger manually?
- Use the `chronicle:verify` Artisan command to check the hash chain’s integrity. For large ledgers, specify `--since-last-checkpoint` to verify only recent entries. Exports include a `verification_hash` to cross-check against checkpoints.
- Are there alternatives to Chronicle for Laravel audit logs?
- For **non-cryptographic** logs, consider `laravel-auditlog` or `spatie/laravel-activitylog`. For **immutable** but simpler solutions, `proengsoft/laravel-js-audit` offers append-only logs without cryptographic verification. Chronicle is unique for **verifiable** compliance trails.
- Can I customize the data stored in Chronicle entries beyond default fields?
- Yes, extend the `ChronicleEntry` model or use the `record()` method with a custom payload. Chronicle stores metadata (actor, action, timestamp) automatically but allows arbitrary JSON data in the `details` field for flexibility.
- How do I handle key rotation without breaking historical verifiability?
- Chronicle supports **key rotation** via `chronicle:rotate-key`. Each new key signs a checkpoint that includes the previous public key, ensuring backward compatibility. Historical entries remain verifiable using the old key until the next checkpoint.
Weaver
How can I help you explore Laravel packages today?