Weave Code
Core Laravel Package
laravel-chronicle/core
Cryptographically verifiable audit ledger for Laravel. Append-only entries are hash-chained so tampering, deletion, or reordering is detectable—built for security logging, compliance, and forensic audit trails.
Tamper-evident audit ledger for Laravel applications.
Frequently asked questions about Core
- How do I install laravel-chronicle/core in a Laravel app?
- Run composer require laravel-chronicle/core, then php artisan chronicle:install to publish the config and migrations, and migrate the database. You also need PHP ^8.2, Laravel ^12.0 or ^13.0, and ext-sodium and ext-openssl available in every runtime image, CI runner, and local dev environment.
- What PHP and Laravel versions does Chronicle support?
- Chronicle requires PHP ^8.2 and supports Laravel ^12.0 or ^13.0 only. There is no Laravel 10 or 11 path, so any service still on those versions is blocked until it upgrades. The ext-sodium and ext-openssl extensions must also be present in all environments.
- How does Chronicle detect tampering in the audit ledger?
- Chronicle writes append-only, ULID-keyed entries and links each one to the previous entry with a SHA-256 hash chain, where chain_hash(n) = SHA256(chain_hash(n-1) + payload_hash(n)). Editing, deleting, or reordering a row breaks verification. Signed checkpoints over the chain head catch an attacker who recomputes the chain, and optional external anchoring catches a full rewrite plus re-sign.
- Can I audit existing Eloquent models without changing them?
- Yes. You can add the HasChronicle trait to models you control, or use Chronicle::observe() to capture Eloquent lifecycle events on models you do not own. Records can also be written explicitly with the fluent API: actor(), action(), subject(), metadata(), tags(), and commit().
- What is the write performance impact of Chronicle's hash chain?
- The hash chain is inherently serialized because every entry references the previous one, so writes contend on a single ledger head inside a transaction. That is the biggest performance unknown for high-churn models, and the package assessment recommends a load test before committing to covering them. Start with lower-volume, high-value events and measure before expanding.
- How do signed checkpoints and signing key rotation work?
- Chronicle signs checkpoints over the current chain head, so an attacker with database write access who recomputes the hash chain still cannot produce a valid checkpoint without the signing key. Signing configuration uses signing.active plus signing.keys, and key rotation is supported. An earlier flat signing config shape is handled by a back-compatibility shim.
- How do I export Chronicle logs for an auditor?
- Chronicle exports entries.ndjson, manifest.json, and signature.json, and the dataset can be verified offline with chronicle:verify-export. That means you can hand a signed dataset to an external party who verifies it without touching your infrastructure. It is a strong fit for auditor handoff and forensic review.
- Does Chronicle support AWS KMS and S3 Object Lock anchoring?
- Yes, through the companion packages laravel-chronicle/kms-aws and laravel-chronicle/anchor-s3. They let you keep the private signing key in AWS KMS and write anchors to an S3 Object Lock bucket, turning the enterprise posture into configuration plus IAM work rather than a build project. Anchoring runs after checkpoint commit, and an anchoring failure never invalidates the checkpoint.
- Is Chronicle a replacement for spatie/laravel-activitylog?
- Both occupy the audit-log slot, but Chronicle makes a different guarantee: append-only rows, SHA-256 hash chaining, ULID-keyed entries, and signed checkpoints instead of a mutable activity table. Use Chronicle when you have an evidentiary requirement such as SOX/ITGC, PCI DSS 10.x, HIPAA, financial reconciliation, or forensic investigation. If you just need operational activity history, Chronicle is over-engineering.
- What should I check before upgrading Chronicle in production?
- Treat chronicle:verify against a historical ledger as an upgrade gate in CI, because payload canonicalization and signature-envelope handling are where subtle verification bugs can appear. Also pin versions and review release notes: the package is at 1.9.x under a single-organization namespace with modest adoption, and it has already reworked its signing config once. That shows maintainer discipline but also warns of possible breaking changes in a future 2.0.
Weaver
How can I help you explore Laravel packages today?