Adds WORM evidence storage for history events and snapshots

.github/workflows/common-tests.yml

@@ -41,6 +41,9 @@ jobs:
       - name: Run common root package tests
         run: go test -count=1 -v -cover ./internal/common
 
+      - name: Run common history tests
+        run: go test -count=1 -v -cover ./internal/common/history
+
       - name: Run common model grammar tests
         run: go test github.com/eclipse-basyx/basyx-go-components/internal/common/model/grammar -count=1 -v -cover
 

.github/workflows/examples-smoke.yml

@@ -72,6 +72,12 @@ jobs:
             image_builds: |
               eclipsebasyx/companylookup-go:SNAPSHOT|./cmd/companylookupservice/Dockerfile
               eclipsebasyx/basyxconfigurationservice-go:SNAPSHOT|./cmd/basyxconfigurationservice/Dockerfile
+          - target_name: History Audit Guarded Evidence Example
+            compose_files: |
+              examples/BaSyxHistoryAuditGuardedExample/docker-compose.yml
+            image_builds: |
+              eclipsebasyx/aasenvironment-go:SNAPSHOT|./cmd/aasenvironmentservice/Dockerfile
+              eclipsebasyx/basyxconfigurationservice-go:SNAPSHOT|./cmd/basyxconfigurationservice/Dockerfile
 
     steps:
       - name: Checkout code

cmd/aasenvironmentservice/main.go

@@ -88,6 +88,9 @@ func runServer(ctx context.Context, configPath string) error {
 		Immutability:         cfg.History.Immutability,
 		AuditIdentityMode:    cfg.History.AuditIdentityMode,
 	})
+	if err = history.ConfigureEvidence(ctx, cfg.History.Evidence); err != nil {
+		return err
+	}
 
 	registrySyncConfig, err := aasenvironment.NewRegistrySyncConfig(
 		cfg.General.AASRegistryIntegration,

cmd/aasregistryservice/main.go

@@ -68,6 +68,9 @@ func runServer(ctx context.Context, configPath string) error {
 		Immutability:         cfg.History.Immutability,
 		AuditIdentityMode:    cfg.History.AuditIdentityMode,
 	})
+	if err = history.ConfigureEvidence(ctx, cfg.History.Evidence); err != nil {
+		return err
+	}
 	commonmodel.SetSupportsSingularSupplementalSemanticId(cfg.General.SupportsSingularSupplementalSemanticId)
 
 	r := chi.NewRouter()

cmd/aasrepositoryservice/main.go

@@ -48,6 +48,9 @@ func runServer(ctx context.Context, configPath string) error {
 		Immutability:         cfg.History.Immutability,
 		AuditIdentityMode:    cfg.History.AuditIdentityMode,
 	})
+	if err = history.ConfigureEvidence(ctx, cfg.History.Evidence); err != nil {
+		return err
+	}
 
 	if err = aasenvironment.ValidateStandaloneAASRepositoryRegistrySyncConfig(cfg); err != nil {
 		return err

cmd/basyxconfigurationservice/main.go

@@ -60,7 +60,8 @@ func main() {
 	schemInit.Register(sequences.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "1_0_2.sql"), "v1.0.2"))
 	schemInit.Register(sequences.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "1_1_0.sql"), "v1.1.0"))
 	schemInit.Register(sequences.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "1_1_1.sql"), "v1.1.1"))
-	schemInit.Register(sequences.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "1_1_2.sql"), common.CURRENT_DATABASE_VERSION))
+	schemInit.Register(sequences.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "1_1_2.sql"), "v1.1.2"))
+	schemInit.Register(sequences.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "1_1_3.sql"), common.CURRENT_DATABASE_VERSION))
 
 	if err := schemInit.Execute(); err != nil {
 		log.Printf("BASYXCFG-MAIN-EXECUTE: %v", err)

cmd/conceptdescriptionrepositoryservice/main.go

@@ -67,6 +67,9 @@ func runServer(ctx context.Context, configPath string) error {
 		Immutability:         cfg.History.Immutability,
 		AuditIdentityMode:    cfg.History.AuditIdentityMode,
 	})
+	if err = history.ConfigureEvidence(ctx, cfg.History.Evidence); err != nil {
+		return err
+	}
 
 	// Create Chi router
 	r := chi.NewRouter()

cmd/digitaltwinregistryservice/main.go

@@ -72,6 +72,9 @@ func runServer(ctx context.Context, configPath string) error {
 		Immutability:         cfg.History.Immutability,
 		AuditIdentityMode:    cfg.History.AuditIdentityMode,
 	})
+	if err = history.ConfigureEvidence(ctx, cfg.History.Evidence); err != nil {
+		return err
+	}
 	commonmodel.SetSupportsSingularSupplementalSemanticId(cfg.General.SupportsSingularSupplementalSemanticId)
 
 	// Digital Twin Registry always enables discovery integration.

cmd/historyevidenceverifier/main.go

@@ -0,0 +1,265 @@
+/*******************************************************************************
+* Copyright (C) 2026 the Eclipse BaSyx Authors and Fraunhofer IESE
+*
+* Permission is hereby granted, free of charge, to any person obtaining
+* a copy of this software and associated documentation files (the
+* "Software"), to deal in the Software without restriction, including
+* without limitation the rights to use, copy, modify, merge, publish,
+* distribute, sublicense, and/or sell copies of the Software, and to
+* permit persons to whom the Software is furnished to do so, subject to
+* the following conditions:
+*
+* The above copyright notice and this permission notice shall be
+* included in all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*
+* SPDX-License-Identifier: MIT
+******************************************************************************/
+
+// Package main implements the history evidence verifier and publisher CLI.
+package main
+
+import (
+	"context"
+	"database/sql"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+
+	"github.com/eclipse-basyx/basyx-go-components/internal/common"
+	"github.com/eclipse-basyx/basyx-go-components/internal/common/history"
+)
+
+type cliOptions struct {
+	configPath        string
+	historyTable      string
+	identifier        string
+	firstHistoryID    int64
+	lastHistoryID     int64
+	writeEvidence     bool
+	manifestObjectKey string
+	manifestVersionID string
+	manifestSHA256    string
+	signerKeyID       string
+}
+
+func main() {
+	options := parseFlags()
+	flag.Parse()
+	ctx, stop := signal.NotifyContext(context.TODO(), os.Interrupt, syscall.SIGTERM)
+	err := run(ctx, *options)
+	stop()
+	if err != nil {
+		_, _ = fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+}
+
+func parseFlags() *cliOptions {
+	options := &cliOptions{}
+	flag.StringVar(&options.configPath, "config", "", "Path to BaSyx config YAML")
+	flag.StringVar(&options.historyTable, "table", "", "History table, for example aas_history or submodel_history")
+	flag.StringVar(&options.identifier, "identifier", "", "Optional entity identifier scope")
+	flag.Int64Var(&options.firstHistoryID, "from", 0, "First history_id in the range")
+	flag.Int64Var(&options.lastHistoryID, "to", 0, "Last history_id in the range")
+	flag.BoolVar(&options.writeEvidence, "write", false, "Write snapshot and manifest artifacts before verifying")
+	flag.StringVar(&options.manifestObjectKey, "manifest-object-key", "", "Stored manifest object key to verify")
+	flag.StringVar(&options.manifestVersionID, "manifest-version-id", "", "Stored manifest object version ID")
+	flag.StringVar(&options.manifestSHA256, "manifest-sha256", "", "Expected SHA-256 for the stored manifest object")
+	flag.StringVar(&options.signerKeyID, "signer-key-id", "", "Optional manifest signer key id")
+	return options
+}
+
+func run(ctx context.Context, options cliOptions) error {
+	if err := validateCLIOptions(options); err != nil {
+		return err
+	}
+	cfg, err := common.LoadConfig(options.configPath, common.QUIET)
+	if err != nil {
+		return err
+	}
+	db, err := openDatabase(cfg)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = db.Close()
+	}()
+	if options.writeEvidence {
+		return writeEvidence(ctx, cfg, db, options)
+	}
+	return verifyEvidence(ctx, cfg, db, options)
+}
+
+func validateCLIOptions(options cliOptions) error {
+	if strings.TrimSpace(options.historyTable) == "" {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-TABLE -table is required")
+	}
+	if options.firstHistoryID < 1 {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-FROM -from must be positive")
+	}
+	if options.lastHistoryID < options.firstHistoryID {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-TO -to must be greater than or equal to -from")
+	}
+	hasManifestObjectKey := strings.TrimSpace(options.manifestObjectKey) != ""
+	hasManifestSHA256 := strings.TrimSpace(options.manifestSHA256) != ""
+	if hasManifestObjectKey && !hasManifestSHA256 {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-MANIFESTHASH -manifest-sha256 is required when -manifest-object-key is set")
+	}
+	if hasManifestSHA256 && !hasManifestObjectKey {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-MANIFESTOBJECT -manifest-object-key is required when -manifest-sha256 is set")
+	}
+	if strings.TrimSpace(options.manifestVersionID) != "" && !hasManifestObjectKey {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-MANIFESTVERSION -manifest-object-key is required when -manifest-version-id is set")
+	}
+	return nil
+}
+
+func openDatabase(cfg *common.Config) (*sql.DB, error) {
+	dsn := common.BuildPostgresDSN(cfg.Postgres)
+	if err := common.ValidateSchemaVersionByDSN(dsn, common.CURRENT_DATABASE_VERSION); err != nil {
+		return nil, err
+	}
+	db, err := common.NewDatabaseConnection(dsn)
+	if err != nil {
+		return nil, err
+	}
+	if cfg.Postgres.MaxOpenConnections > 0 {
+		db.SetMaxOpenConns(cfg.Postgres.MaxOpenConnections)
+	}
+	if cfg.Postgres.MaxIdleConnections > 0 {
+		db.SetMaxIdleConns(cfg.Postgres.MaxIdleConnections)
+	}
+	return db, nil
+}
+
+func writeEvidence(ctx context.Context, cfg *common.Config, db *sql.DB, options cliOptions) error {
+	if !cfg.History.Evidence.Enabled {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-DISABLED history.evidence.enabled must be true for -write")
+	}
+	store, err := newS3EvidenceStore(ctx, cfg)
+	if err != nil {
+		return err
+	}
+	signer, err := newManifestSigner(cfg, options.signerKeyID)
+	if err != nil {
+		return err
+	}
+	result, err := history.WriteHistoryEvidence(ctx, history.WriteHistoryEvidenceOptions{
+		DB:             db,
+		Store:          store,
+		HistoryTable:   options.historyTable,
+		Identifier:     options.identifier,
+		FirstHistoryID: options.firstHistoryID,
+		LastHistoryID:  options.lastHistoryID,
+		Signer:         signer,
+	})
+	if err != nil {
+		return err
+	}
+	return printJSON(result)
+}
+
+func verifyEvidence(ctx context.Context, cfg *common.Config, db *sql.DB, options cliOptions) error {
+	verifyOptions := history.VerifyHistoryRangeOptions{
+		HistoryTable:   options.historyTable,
+		Identifier:     options.identifier,
+		FirstHistoryID: options.firstHistoryID,
+		LastHistoryID:  options.lastHistoryID,
+	}
+	store, err := optionalS3EvidenceStore(ctx, cfg)
+	if err != nil {
+		return err
+	}
+	verifyOptions.EvidenceStore = store
+	if strings.TrimSpace(options.manifestObjectKey) != "" {
+		if store == nil {
+			store, err = newS3EvidenceStore(ctx, cfg)
+			if err != nil {
+				return err
+			}
+			verifyOptions.EvidenceStore = store
+		}
+		ref := history.EvidenceReference{
+			Provider:  history.EvidenceProviderS3,
+			Bucket:    cfg.History.Evidence.Bucket,
+			ObjectKey: strings.TrimSpace(options.manifestObjectKey),
+			VersionID: strings.TrimSpace(options.manifestVersionID),
+		}
+		object, err := store.GetArtifact(ctx, ref)
+		if err != nil {
+			return err
+		}
+		manifest, _, err := history.DecodeManifestArtifact(object.Data, object.ContentType)
+		if err != nil {
+			return err
+		}
+		verifyOptions.Manifest = &manifest
+		verifyOptions.EvidenceStore = store
+		verifyOptions.ManifestArtifactRef = ref
+		verifyOptions.ManifestArtifactHash = strings.TrimSpace(options.manifestSHA256)
+	}
+	report, err := history.VerifyHistoryRange(ctx, db, verifyOptions)
+	if err != nil {
+		return err
+	}
+	return printJSON(report)
+}
+
+func newS3EvidenceStore(ctx context.Context, cfg *common.Config) (*history.S3EvidenceStore, error) {
+	if strings.ToLower(strings.TrimSpace(cfg.History.Evidence.Provider)) != history.EvidenceProviderS3 {
+		return nil, fmt.Errorf("HISTORY-EVIDENCE-CLI-PROVIDER history.evidence.provider must be s3")
+	}
+	return history.NewS3EvidenceStore(ctx, history.S3EvidenceStoreConfig{
+		Bucket:          cfg.History.Evidence.Bucket,
+		Prefix:          cfg.History.Evidence.Prefix,
+		Region:          cfg.History.Evidence.Region,
+		Endpoint:        cfg.History.Evidence.Endpoint,
+		AccessKeyID:     cfg.History.Evidence.AccessKeyID,
+		SecretAccessKey: cfg.History.Evidence.SecretAccessKey,
+		UsePathStyle:    cfg.History.Evidence.UsePathStyle,
+		RetentionMode:   cfg.History.Evidence.RetentionMode,
+		RetentionDays:   cfg.History.Evidence.RetentionDays,
+	})
+}
+
+func optionalS3EvidenceStore(ctx context.Context, cfg *common.Config) (*history.S3EvidenceStore, error) {
+	if strings.ToLower(strings.TrimSpace(cfg.History.Evidence.Provider)) != history.EvidenceProviderS3 {
+		return nil, nil
+	}
+	if strings.TrimSpace(cfg.History.Evidence.Bucket) == "" {
+		return nil, nil
+	}
+	return newS3EvidenceStore(ctx, cfg)
+}
+
+func newManifestSigner(cfg *common.Config, keyID string) (*history.ManifestJWSSigner, error) {
+	keyPath := strings.TrimSpace(cfg.History.Evidence.Signing.PrivateKeyPath)
+	if keyPath == "" {
+		keyPath = strings.TrimSpace(cfg.JWS.PrivateKeyPath)
+	}
+	if keyPath == "" {
+		return nil, nil
+	}
+	return history.NewManifestJWSSignerFromKeyFile(keyPath, keyID)
+}
+
+func printJSON(value any) error {
+	encoded, err := json.MarshalIndent(value, "", "  ")
+	if err != nil {
+		return fmt.Errorf("HISTORY-EVIDENCE-CLI-PRINTJSON %w", err)
+	}
+	_, err = fmt.Fprintln(os.Stdout, string(encoded))
+	return err
+}

cmd/historyevidenceverifier/main_test.go

@@ -0,0 +1,43 @@
+/*******************************************************************************
+* Copyright (C) 2026 the Eclipse BaSyx Authors and Fraunhofer IESE
+*
+* Permission is hereby granted, free of charge, to any person obtaining
+* a copy of this software and associated documentation files (the
+* "Software"), to deal in the Software without restriction, including
+* without limitation the rights to use, copy, modify, merge, publish,
+* distribute, sublicense, and/or sell copies of the Software, and to
+* permit persons to whom the Software is furnished to do so, subject to
+* the following conditions:
+*
+* The above copyright notice and this permission notice shall be
+* included in all copies or substantial portions of the Software.
+*
+* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+* LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+* WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+*
+* SPDX-License-Identifier: MIT
+******************************************************************************/
+
+package main
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestValidateCLIOptionsRejectsManifestObjectKeyWithoutHash(t *testing.T) {
+	err := validateCLIOptions(cliOptions{
+		historyTable:      "aas_history",
+		firstHistoryID:    1,
+		lastHistoryID:     10,
+		manifestObjectKey: "history-evidence/manifests/aas_history/1-10.json",
+	})
+
+	require.ErrorContains(t, err, "HISTORY-EVIDENCE-CLI-MANIFESTHASH")
+}