Ir para o conteúdo

Component: Package Experiment Service

Responsibility

Stores large artifacts outside the Hyperledger Fabric ledger (off-chain). Guarantees integrity via SHA-256 hash, prevents path traversal, and applies a retention policy based on contract expiration (LGPD Art. 15/16).

Target architecture requested: the federated core must use Fabric as its only permanent store. This service may remain only as bounded temporary staging while data is being processed or committed; staged artifacts must be deleted after confirmed ledger commit. The current persistent store and retention-by-contract behavior do not yet satisfy this target and require implementation work.

Implementation

Item Value
Module modules/federated-package-experiment-service
Java package br.ufma.lsdi.artifactexperiment
Main class LocalArtifactExperimentService
LGPD class ArtifactRetentionPolicy
Default directory target/artifacts (configurable via HDT_AF_ARTIFACT_ROOT)

Classes

LocalArtifactExperimentService

Stores and reads federated artifacts with path traversal checks and SHA-256 hashing.

LocalArtifactExperimentService svc =
    new LocalArtifactExperimentService(ExperimentRuntimePaths.artifactRoot());

// Write an artifact
ArtifactReference ref = svc.store(
    "exp-har-001/client-3/round-1",   // namespace (sanitized)
    "local_update.bin",               // filename (sanitized)
    weightVectorCsvBytes              // content
);
// ref.uri()  → "file://target/artifacts/exp-har-001/client-3/round-1/local_update.bin"
// ref.hash() → "sha256:3a7bd3e2..."

// Read an artifact by ArtifactReference (never takes raw namespace/filename)
byte[] content = svc.read(ref);

// Poll an optional artifact without throwing if absent
Optional<byte[]> maybeContent = svc.readIfPresent("exp-har-001/client-3/round-1", "local_update.bin");

Operations: - store(namespace, filename, bytes) → ArtifactReference — writes bytes and computes the SHA-256 hash via Hashing.sha256(byte[]) - read(ArtifactReference) → byte[] — validates URI containment under root (with BL-117 resolveAcrossForeignRoot fallback for bind-mounted roots sharing root.getFileName()) and throws FederatedException(ErrorCode.ARTIFACT_NOT_FOUND, ...) on missing/escaping paths - readIfPresent(namespace, filename) → Optional<byte[]> — sanitized non-throwing poll helper used by ClientUpdateResolver - private resolveSecure(Path base, String segment) — internal containment helper (not part of the public API)

ArtifactReference

Record returned by store():

public record ArtifactReference(
    String uri,       // "file://target/artifacts/exp/client/round/file.bin"
    String hash,      // "sha256:<64 hex>"
    long   sizeBytes  // size in bytes
) {}

ArtifactRetentionPolicy

Enforces artifact retention based on contract expiration (LGPD Art. 15/16). Recursively deletes the target/artifacts/{experimentId}/ directory once validTo has passed.

ArtifactRetentionPolicy policy = new ArtifactRetentionPolicy(
    ExperimentRuntimePaths.artifactRoot()
);

// For a specific experiment
RetentionResult result = policy.enforceRetention(
    "exp-ecg5000-anomaly-001",
    contract.validTo(),          // Instant — expiration date
    Instant.now()                // reference date
);
if (result.wasEnforced()) {
    System.out.println("Deleted: " + result.deletedPaths().size() + " artifacts");
}

// For all experiments (called automatically at monitor bootstrap)
Map<String, Instant> expiries = Map.of(
    "exp-har-001",  Instant.parse("2026-12-31T23:59:59Z"),
    "exp-ecg-001",  Instant.parse("2026-06-30T23:59:59Z")
);
List<RetentionResult> results = policy.enforceAll(expiries, Instant.now());

RetentionResult status values:

Status Description
NOT_EXPIRED validTo is in the future — no action taken
NOT_APPLICABLE validTo is null or the directory does not exist
ENFORCED All artifacts successfully deleted
PARTIAL_ERROR Expired, but some deletions failed

Directory structure

target/artifacts/
  {experimentId}/
    {clientId}/
      round-{n}/
        local_update.bin        ← CSV vector of doubles (local model weights)
        metrics.json            ← per-epoch training metrics
        data_profile.json       ← data profile (counts, quality)
    round-{n}/
      aggregation_report.json   ← aggregation report with canonical hashes
    models/
      v{n}/
        model.bin               ← candidate global model weights (CSV)

Security — Path Traversal Prevention

Every external access is sanitized and checked before reaching disk outside root:

  1. sanitizeNamespace(namespace) — replaces any character outside [a-zA-Z0-9/_-] with _, collapses repeated /, and trims leading/trailing / (so . becomes _ and .. becomes __).
  2. sanitizeFilename(filename) — replaces any character outside [a-zA-Z0-9._-] with _ (forbidding directory separators).
  3. private resolveSecure(base, segment) — resolves with .normalize() and verifies resolved.startsWith(base) (throws IllegalArgumentException if violated).
  4. read(ArtifactReference) — checks startsWith(root) (supporting resolveAcrossForeignRoot only when the URI shares root.getFileName() across host/container mount boundaries) and throws FederatedException(ErrorCode.ARTIFACT_NOT_FOUND, ...) on escape or missing file.
// Sanitized inside root — ".." turns into "__" and "/" in filename turns into "_"
ArtifactReference safe = svc.store("../../../etc", "passwd", bytes);
// Writes safely under target/artifacts/______etc/passwd instead of escaping root

Content SHA-256 hash

LocalArtifactExperimentService.store(...) receives byte[] and delegates to Hashing.sha256(byte[]) (MessageDigest.getInstance("SHA-256") formatted as "sha256:" + 64 lowercase hex digits); large file streaming is supported separately by Hashing.sha256(Path) via DigestInputStream in federated-common.


Integration with Hyperledger Fabric

The Fabric ledger stores only the hash and URI, never the binary:

Artifact Service (off-chain)   →   Hyperledger Fabric (on-chain)
  model.bin (23 KB)            →   sha256:abc123... + file://target/artifacts/.../model.bin
  aggregation_report.json      →   sha256:def456... + file://target/artifacts/.../report.json

AggregationResultPublisher (federated-orchestrator, BL-244) writes the global model and report via store(...) and records the hashes/URIs on the chaincode:

ArtifactReference modelRef = artifactService.store(
    experimentId + "/models/v" + report.globalModelVersion(), "model.bin", weightsBytes);
ArtifactReference reportRef = artifactService.store(
    experimentId + "/round-" + report.roundId(), "aggregation_report.json", reportJsonBytes);
experimentChaincode.registerGlobalModelVersion(
    experimentId, report.globalModelVersion(),
    modelRef.hash(), modelRef.uri(), decision, reportRef.hash()
);

Environment variables

Variable Default Description
HDT_AF_ARTIFACT_ROOT target/artifacts Root of the off-chain artifacts

Mandatory rules

  • Every artifact written must have its SHA-256 hash recalculated at write time.
  • The hash of local_update.bin must be compared against the hash declared by the client (TrainingResult.updateHash()). A mismatch rejects the update with ErrorCode.UPDATE_REJECTED.
  • No raw data subject data (personally identifiable field) may be written as a federated artifact.
  • No complete model may be included in MQTT messages — only the URI and hash.
  • ArtifactRetentionPolicy must be applied automatically at monitor bootstrap.

Tests

7 test classes containing 32 @Test methods in modules/federated-package-experiment-service/src/test/java/..., covering store/read/readIfPresent, namespace/filename sanitization and URI escape blocking (ARTIFACT_NOT_FOUND), cross-mount resolveAcrossForeignRoot, ArtifactReference fields, and ArtifactRetentionPolicy (NOT_EXPIRED, NOT_APPLICABLE, ENFORCED). (PARTIAL_ERROR is handled in production code and remains uncovered by a fault-injection test.)