chronicle

Chronicle: tamper-evident audit logging for Go

Chronicle is an audit trail library for Go. Every event you record lands in a SHA-256 hash chain scoped to an app and tenant, and you can key that chain with HMAC, sign checkpoints over it, crypto-erase a data subject for GDPR, run retention policies and generate SOC 2, HIPAA and EU AI Act reports from it. It's built for multi-tenant SaaS backends, runs inside your own process against your own database, and plugs into Forge as an extension when you want config, DI and an admin API wired for you.

Documentation · Quick start · Features · Stores · Tamper evidence · GDPR erasure · Forge · FAQ

Quick start

You need Go 1.26 or later.

go get github.com/xraph/chronicle@latest

Save this as main.go. It records two events into an in-memory store and then verifies the chain:

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/xraph/chronicle"
	"github.com/xraph/chronicle/scope"
	"github.com/xraph/chronicle/store"
	"github.com/xraph/chronicle/store/memory"
	"github.com/xraph/chronicle/verify"
)

func main() {
	ctx := context.Background()
	ctx = scope.WithAppID(ctx, "billing")
	ctx = scope.WithTenantID(ctx, "acme")
	ctx = scope.WithUserID(ctx, "user-42")

	c, err := chronicle.New(chronicle.WithStore(store.NewAdapter(memory.New())))
	if err != nil {
		log.Fatal(err)
	}

	err = c.Info(ctx, "invoice.paid", "invoice", "inv-1001").
		Category("billing").
		Meta("amount_cents", 4999).
		Record()
	if err != nil {
		log.Fatal(err)
	}

	err = c.Critical(ctx, "role.granted", "role", "admin").
		Category("access").
		Reason("granted by support ticket 812").
		Record()
	if err != nil {
		log.Fatal(err)
	}

	report, err := c.VerifyChain(ctx, &verify.Input{AppID: "billing", TenantID: "acme"})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("valid=%v verified=%d tampered=%v\n", report.Valid, report.Verified, report.Tampered)
}

Run it:

go mod tidy
go run .
# valid=true verified=2 tampered=[]

You put the app, tenant and user on the context once, usually in middleware, and every event you record from that request picks them up. Info, Warning and Critical set the severity, and the builder takes Category, Reason, Outcome, SubjectID, Meta and the request fields (IP, UserAgent, RequestID, SessionID) before Record writes it. You read events back with c.Query, c.Aggregate or c.ByUser.

Swap memory.New() for a real backend from the table below and you have a persistent audit log.

Why Chronicle?

An audit log that anyone with database access can quietly edit is a log you can't show an auditor. Chronicle links each event to the one before it, so when you verify, a deleted or edited row shows up, and on top of that chain you get the pieces your compliance work keeps asking for.

Storage backends

Every backend implements the composite store.Store interface. Wrap one with store.NewAdapter to pass it to chronicle.New.

store/sealedstore wraps any of them so reads come back decrypted when crypto-erasure is on. The stores docs cover schema and migration for each one.

Tamper evidence

The default digest is plain SHA-256 (scheme chronicle/v4). It catches corruption and accidental edits. It will not stop someone who can write to your database, because the algorithm is public and recomputing every digest after a rewritten row takes a few lines of code. TestPlainChainDoesNotDetectARewrite in tamper_test.go pins that limit so you don't have to take it on trust.

If you key the chain, nobody can produce a digest from the stored row alone:

c, err := chronicle.New(
	chronicle.WithStore(adapter),
	chronicle.WithDigestScheme(hash.SchemeHMACV5),
	chronicle.WithKeyProvider(kp), // for example keys.NewFileProvider("/etc/chronicle/keys.json")
)

Ask for HMAC without a key provider and New returns ErrHMACKeyUnavailable. That refusal at startup is deliberate: writing unkeyed digests while you believe they are keyed would be the worse failure.

Each event records the scheme that wrote it, and each stream records the scheme it is pinned to and from which sequence. If you turn HMAC on for a database that already holds events, the pin moves forward from the next sequence you record, and your older events keep verifying under the scheme they were written with. A pin only moves up. Point a plain-configured process at a stream already pinned to HMAC and it refuses to record. An older Chronicle process doesn't know chronicle/v5, so when you change schemes, stop every instance and then start them. During a rolling restart the old and new processes would drag the pin back and forth.

v2 and v3 joined fields with a bare |, so content could slide across a separator without changing the hashed bytes. Chronicle will not write them any more, and TestDelimiterJoinedContentCollides in hash/ keeps the collision on record.

Keying narrows who can rewrite your log. Someone who can write both the events table and the streams table can still downgrade a whole stream and its pin together. Signed checkpoints close most of that gap. Turn them on and Chronicle periodically signs where each stream's chain stood, chains each checkpoint to the one before, and on verification compares the latest checkpoint against the head you claim, which catches a truncated tail or a wiped stream. If an attacker deletes a checkpoint together with the events it covers, verification still passes, because all of the evidence lives in the same database you are protecting. Anchoring checkpoints somewhere outside that database is not built yet.

The verification docs walk through each check and the test that pins it.

GDPR crypto-erasure

To use it, turn on crypto-erasure and give Chronicle a key store:

keyStore := crypto.NewInMemoryKeyStore() // tests only: losing the key store erases everyone

c, err := chronicle.New(
	chronicle.WithStore(adapter),
	chronicle.WithCryptoErasure(true),
	chronicle.WithSealer(crypto.NewSealer(keyStore)),
)

For every event with a SubjectID, the Metadata, Reason and IP fields are encrypted under a key that belongs to that subject in one app and tenant. The same subject in two tenants gets two keys. The digest covers the encrypted bytes, so destroying a key changes nothing the verifier reads, and the chain keeps verifying.

To erase a subject, call the erasure service with the subject and the scope:

svc := erasure.NewService(chronicleStore, keyStore)

result, err := svc.Erase(ctx, &erasure.Input{
	SubjectID:   "user-alice",
	Reason:      "GDPR Article 17 request",
	RequestedBy: "dpo@example.com",
}, "billing", "acme")
// result.KeyDestroyed, result.EventsAffected

After that, the sealed fields you read back say [ERASED], metadata is dropped and the event reports Erased: true. SubjectID, UserID, the action, resource, category, outcome, severity and timestamps stay readable on purpose: they are the operational record, and reports group on them. An erasure destroys what was recorded about a person, not the fact that something involving them happened. The GDPR erasure guide has the rest.

Compliance reports and retention

compliance.NewEngine(auditStore, verifyStore, reportStore, logger) builds reports with SOC2, HIPAA, EUAIAct and Custom, and Export writes one as compliance.FormatJSON, FormatCSV, FormatMarkdown or FormatHTML. Reports carry the chain verification result for their period.

Retention lives in retention/. A policy names a category, a duration and whether to archive. When it runs, the enforcer first writes a retention record into the chain, then archives the expired events through a sink.Sink if the policy asks for that (sink.NewFileSink, sink.NewS3Sink and sink.NewStdoutSink are built in), and then purges them. Verification reads those records, so a purged range shows up as retained and not as a gap.

Use it with Forge

The extension package turns Chronicle into a Forge extension. It reads extensions.chronicle from your config (falling back to a top-level chronicle key), builds the store, mounts the admin API under /chronicle, runs the retention and checkpoint schedulers, and registers chronicle.Emitter in the container so other extensions can record events with vessel.Inject[chronicle.Emitter].

go get github.com/xraph/chronicle@latest github.com/xraph/grove/extension@latest

import (
	chronicle "github.com/xraph/chronicle/extension"
	grove "github.com/xraph/grove/extension"
)

app := forge.NewApp(forge.AppConfig{
	Name: "billing-api",
	Extensions: []forge.Extension{
		grove.New(),     // extensions.grove: driver and dsn
		chronicle.New(), // extensions.chronicle: auth, tamper evidence, checkpoints
	},
})

List Grove first. Chronicle looks up the container's *grove.DB during Register and picks the PostgreSQL, SQLite or MongoDB store to match its driver. You can also name a database with grove_database, point at a Grove KV store with grove_kv for Redis, or skip discovery and pass chronicle.WithStore(memory.New()).

The admin API can purge history, so the extension won't start until you decide who may call it. Configure an auth provider, allow unauthenticated access explicitly, or turn the routes off. Requests also need an app scope on the context (Forge's scope, or scope.WithAppID from your own middleware), or they get a 401.

You get traces and metrics without wiring anything. Recording, verification, checkpoints, retention runs, reports and erasures each get a span on Forge's tracer provider, with the database spans from Grove nested under them, and the counters and histograms land on /_/metrics as forge_chronicle_*. No span or label carries a user, a subject or an event's payload. Outside Forge, pass chronicle.WithMetrics(m) with any go-utils metrics sink. Observability lists every span and metric.

Configuration

extensions:
  grove:
    driver: postgres
    dsn: postgres://app:secret@localhost:5432/app?sslmode=disable

  chronicle:
    base_path: /chronicle
    retention_interval: 24h        # 0 turns the retention scheduler off
    enable_crypto_erasure: false   # true also needs WithKeyStore
    auth:
      provider: jwt                # a forge auth provider; or allow_unauthenticated: true
      read_scopes: [chronicle:read]
      write_scopes: [chronicle:write]
      admin_scopes: [chronicle:admin]
    tamper_evidence:
      digest: hmac                 # plain (default) or hmac
      keys:
        provider: file
        path: /etc/chronicle/keys.json
    checkpoints:
      enabled: true
      every_events: 1000
      every_interval: 1h
      signer:
        provider: file
        path: /etc/chronicle/checkpoint-signer.json

Read scopes cover listing and verifying. Write scopes cover saving a retention policy and generating a report. Admin scopes cover the irreversible operations: enforcing retention, deleting a policy and requesting an erasure.

WithStore, WithArchiveSink, WithConfig and WithRequireConfig round out the options. batch_size and flush_interval still load, but Record writes each event synchronously, so they don't change how events are stored. The dashboard keys name the app a Forge dashboard session falls back to when its claims carry none; MIGRATION.md covers the move from the old server-rendered dashboard pages.

Documentation

The Go API is on pkg.go.dev.

Examples

Run one from the repository root with GOWORK=off go run ./_examples/basic.

FAQ

How do I make an audit log tamper-evident in Go?

Record events through Chronicle and verify with VerifyChain. For protection against someone with database write access, switch the digest to HMAC with a key the database never holds, and turn on signed checkpoints.

Does Chronicle support GDPR right to erasure?

Yes, through crypto-erasure. Each subject's personal fields are encrypted under their own key, and erasing the subject destroys the key. The hash chain still verifies afterwards because the digest covers the ciphertext.

Which databases can Chronicle store audit events in?

PostgreSQL, SQLite and MongoDB through Grove, Redis through Grove KV, and an in-memory store for tests. You can write your own by implementing store.Store.

Can I use Chronicle without Forge?

Yes. The root package, the stores and the subsystems are plain Go. The extension package is only there if you run a Forge app.

Does Chronicle write events in batches?

No. Record writes each event synchronously, because linking an event needs the previous event's hash. The batcher package exists for callers that drive batching themselves.

Contributing

Issues and focused pull requests are welcome on GitHub.

git clone https://github.com/xraph/chronicle.git
cd chronicle
GOWORK=off go test ./...
GOWORK=off go vet ./...
golangci-lint run ./...

The Postgres, MongoDB and Redis tests skip unless you set CHRONICLE_TEST_POSTGRES_DSN, CHRONICLE_TEST_MONGO_URI or CHRONICLE_TEST_REDIS_DSN, so a green run without them says nothing about those backends. Point them at throwaway containers on non-default ports. AGENTS.md has the container commands, the lint rules that bite and the release steps. Commits follow Conventional Commits.

License

MIT. See LICENSE.

Chronicle is part of the Forge forgery stack, built by Rex Raphael and contributors.