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:
sanitizeNamespace(namespace)— replaces any character outside[a-zA-Z0-9/_-]with_, collapses repeated/, and trims leading/trailing/(so.becomes_and..becomes__).sanitizeFilename(filename)— replaces any character outside[a-zA-Z0-9._-]with_(forbidding directory separators).private resolveSecure(base, segment)— resolves with.normalize()and verifiesresolved.startsWith(base)(throwsIllegalArgumentExceptionif violated).read(ArtifactReference)— checksstartsWith(root)(supportingresolveAcrossForeignRootonly when the URI sharesroot.getFileName()across host/container mount boundaries) and throwsFederatedException(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.binmust be compared against the hash declared by the client (TrainingResult.updateHash()). A mismatch rejects the update withErrorCode.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.
ArtifactRetentionPolicymust 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.)