Skip to content

Audit

Verify event store integrity with signature and tamper detection.

Overview

All Starweft protocol messages are recorded in a SQLite database using an event sourcing approach. The audit verify-log command verifies the integrity and signature validity of this event log, detecting tampering and corruption.

audit verify-log

Usage

bash
starweft audit verify-log

Inspection Items

audit verify-log inspects the following items.

Inspection ItemDescription
Raw JSON integrityVerifies that the stored raw JSON (raw_json) matches the values decomposed into database columns. This is a direct method for detecting tampering.
Ed25519 signature verificationRe-verifies the Ed25519 signature against the raw JSON using the sender's public key. Events with unknown keys are reported as unverifiable.
task_id presenceConfirms that task_id is set on TaskDelegated / TaskProgress / TaskResultSubmitted events.
ProjectCharter duplicationConfirms that multiple ProjectCharter entries do not exist for the same project_id.
Lamport timestampConfirms that Lamport timestamps are monotonically increasing within the same project. Regression indicates event ordering inconsistency.
JSON parsingConfirms that struct deserialization of the event completes successfully.

Reading the Output

Example output when healthy
plaintext
checked_events: 42
invalid_events: 0
signature_failures: 0
raw_json_mismatches: 0
unverifiable_signatures: 0
audit: ok
Example output when issues are detected
plaintext
checked_events: 42
invalid_events: 2
signature_failures: 1
raw_json_mismatches: 1
unverifiable_signatures: 3
error: msg_01ABC...: signature verification failed
error: msg_01DEF...: raw_json mismatch for field lamport_ts
[E_AUDIT_FAILED] Inconsistencies found in task_events

Output Field Definitions

FieldMeaning
checked_eventsTotal number of events inspected
invalid_eventsNumber of events with detected issues (sum of signature failures + raw JSON mismatches + structural errors + duplicates + Lamport regressions + missing task_ids)
signature_failuresNumber of events that failed Ed25519 signature verification
raw_json_mismatchesNumber of events where the raw JSON and column values do not match
unverifiable_signaturesNumber of events where signature verification was skipped because the public key is unknown or raw_json was not stored

Handling Detected Issues

When signature_failures / raw_json_mismatches Are Detected

Event data may have been tampered with.

  1. Consider restoring from a backup (see backup restore below)
  2. If only projections (aggregation tables) are corrupted, repair rebuild-projections may be able to repair them

When unverifiable_signatures Is High

The peer's public key may not be registered locally.

bash
# Register the peer's public key
starweft peer add /ip4/192.168.1.10/tcp/9000 \
  --public-key "<base64 public key>"
 
# Run the audit again
starweft audit verify-log

repair rebuild-projections

repair rebuild-projections is a command that rebuilds projection tables from the event log (task_events table).

bash
starweft repair rebuild-projections
Example output
plaintext
replayed_events: 42
rebuilt_projects: 3
rebuilt_tasks: 15
rebuilt_publish_events: 2
rebuilt_snapshots: 3

What rebuild-projections Can Repair

  • projects table (project state aggregation)
  • tasks table (task state aggregation)
  • task_results / evaluations / publish_events tables
  • snapshots table
  • stop_orders / stop_receipts tables
  • approval_state table

backup create / backup restore

Creating a Backup

bash
starweft backup create --output ~/starweft-backup

The backup copies the complete set of files to the specified directory and generates a signed manifest.json.

Files included in the backup
PathContents
config.tomlNode configuration
identity/actor_keyMain identity key
identity/stop_authority_keyStop authority key (if present)
ledger/node.dbSQLite database (clean copy via VACUUM INTO)
artifacts/Task artifacts
logs/Log files
cache/Cache

Backup Trust Anchor

The backup's manifest.json incorporates the following protection mechanisms.

1

Ed25519 Signature

2

The entire payload field of the manifest is signed with the actor_key. This detects tampering with the manifest itself.

3

File Set Integrity Verification

4

The manifest records the SHA-256 checksums and sizes of all included files. During restoration, the checksums of all files are verified.

5
json
{
  "files": [
    { "path": "config.toml", "sha256": "a1b2c3...", "size_bytes": 1024 },
    { "path": "identity/actor_key", "sha256": "d4e5f6...", "size_bytes": 256 }
  ]
}
6

Signer Trust Anchor

7

Verifies that the manifest's signer_public_key field matches the public key from the identity/actor_key file in the bundle. Even if an attacker replaces both the manifest and signer_public_key, the mismatch with the actor_key in the bundle will be detected. The checksum of actor_key itself is also included in the manifest, providing circular protection.

8

Extra File Detection

9

If files not listed in the manifest are present in the bundle, the restore is rejected. This prevents file injection by an attacker.

Restoring a Backup

bash
starweft backup restore --input ~/starweft-backup

During restoration, the following verifications are automatically performed.

  1. Confirm the existence of manifest.json and its format version (starweft-local-backup/v1)
  2. Ed25519 verification of the manifest signature
  3. Confirm that signer_public_key matches the actor_key in the bundle
  4. Verify SHA-256 checksums and sizes of all files
  5. Confirm that no files outside the manifest are present
  6. If an existing identity is present at the restore destination, confirm it matches the signer
bash
# Forcibly restore a backup from a different node
starweft backup restore --input ~/starweft-backup --force

Overwriting Existing Data

Without the --force flag, an error is raised if existing files are found at the restore destination. Specifying --force overwrites the existing data.

Recommended Workflow

Regular auditing and backups help maintain data integrity.

1

Periodic Auditing

2
bash
starweft audit verify-log
3

Confirm that no issues are found.

4

Creating a Backup

5
bash
starweft backup create --output ~/starweft-backup-$(date +%Y%m%d)
6

Repairing When Issues Occur

7

If projections are corrupted, first try rebuild-projections.

8
bash
starweft repair rebuild-projections
9

If the event log itself has issues, restore from a backup.

10
bash
starweft backup restore --input ~/starweft-backup-20260315 --force

Related Pages

Message Signing

Integrity guarantees through Ed25519 signing and Canonical JSON
Key Management

Ed25519 key generation, storage, and exchange methods