A stable remote snapshot completes the shared validation contract

Automatically Test SFTP Interfaces: Safely Validate Delivered Files

The broader idea is introduced in the main article on automated interface quality. Iteration 1 establishes JSON Schema as a local contract; Iteration 2 adds CSV and fixed-width files; Iteration 3 connects HTTP status, headers, and JSON responses. This iteration adds a secured file-transport boundary.

AI-generated illustration for tiny-tool.de: a central validation station checks a protected SFTP file for a stable snapshot, integrity, and content-contract compliance.

The SFTP profile as a local contract

The profile describes the endpoint and the rules for this run. It is local and selected with --schema or --profile, just like the earlier adapters. The local files for host-key verification, the private key, and the content profile must remain inside the profile directory.

{
  "format": "sftp",
  "version": 1,
  "host": "sftp.example.org",
  "port": 22,
  "username": "quality-check",
  "remotePath": "/inbox/delivery.json",
  "knownHosts": "known_hosts",
  "privateKey": "id_ed25519",
  "privateKeyPassphraseEnv": "SFTP_KEY_PASSPHRASE",
  "contentFormat": "json",
  "contentProfile": "delivery.schema.json",
  "quarantineRemoteDirectory": "/quarantine",
  "stabilityChecks": 2,
  "stabilityDelaySeconds": 1,
  "maxAttempts": 2,
  "retryDelaySeconds": 1,
  "connectTimeoutSeconds": 10
}

remotePath is an absolute POSIX path to exactly one file. Dots, traversal segments, backslashes, and trailing slashes are rejected. That does not prove the file is semantically correct, but it keeps a small profile from silently being interpreted as a different path.

Host keys and private keys, with no silent exceptions

The transport uses JSch with strict known_hosts verification. The server is not accepted through an arbitrary new host-key prompt. This first SFTP version deliberately supports private-key authentication only. A passphrase may come from an environment variable; it is never written to the report or findings.

Why size and modification time matter

Many delivery processes write directly to the final filename. A fast download can then capture a valid-looking but incomplete snapshot. ZEUS therefore reads remote metadata before downloading and compares the object type, byte size, and modification time across multiple observations.

If the file does not settle, the adapter waits only as long as the profile allows. After the bounded attempts, the result is an operational error with exit code 2: the check could not establish a trustworthy snapshot.

"stabilityChecks": 2,
"stabilityDelaySeconds": 1,
"maxAttempts": 2,
"retryDelaySeconds": 1

The limits are intentional: a validation run should not wait forever or quietly turn into a polling service. A more complex intake process deserves its own orchestrator, state model, and selection rule.

SHA-256 and quarantine

After the stable snapshot is confirmed, the adapter writes the bytes to a temporary local directory. If the profile contains sha256, the digest is calculated over that downloaded file. A mismatch is reported at /remote/hash; content validation is not presented as a meaningful substitute for a failed integrity check.

{
  "status" : "INVALID",
  "valid" : false,
  "findings" : [ {
    "instancePath" : "/remote/hash",
    "schemaPath" : "/sha256",
    "keyword" : "sha256",
    "message" : "Downloaded SFTP file does not match the expected SHA-256 hash"
  } ]
}

An invalid content or hash result can optionally move the remote file into a quarantine directory. The target receives a UTC timestamp and an .invalid suffix. Valid files are not moved, and a connection or stability failure never triggers quarantine.

Reusing JSON, CSV, and fixed-width validation

The SFTP adapter does not create a second content-validation language. contentFormat selects an existing validator and contentProfile points to its local profile. This keeps transport responsibility separate from the data contract itself.

A missing or mistyped JSON field therefore appears as, for example, /content/quantity. That makes it machine-readable and keeps it separate from a hash or transport failure.

The CI run without a local input file

For local file and HTTP checks, --input can be an important part of the invocation. SFTP is different: the profile identifies the remote file. The SFTP run therefore does not pretend that a second local input file is required.

mvnw.cmd -B -Dtest=SftpValidatorTest test

This run contacts no SFTP server and ends with six successful SFTP tests. The production run against a real endpoint remains clearly marked as environment-specific below.

mvnw.cmd -B -Dtest=SftpValidatorIntegrationTest test

This second run starts an embedded test server and exercises the production JSch transport with host-key and private-key authentication. It needs neither Docker nor an external SFTP account.

$jar = "target/zeus-interface-quality-0.1.0-SNAPSHOT.jar"
$profile = "docs/examples/sftp-profile.json"

java -jar $jar validate --input-format sftp --schema $profile --report json
$LASTEXITCODE

Important: docs/examples/sftp-profile.json is a configuration template. For a real run, the host, username, remote path, known_hosts, private key, and content profile must match your environment. sftp.example.org is intentionally a placeholder. The automated tests do not contact that example system; they replace the transport through a controlled test port.

Results and exit codes

This distinction matters in CI. A bad delivery can stop downstream processing in a controlled way and be quarantined. An unreachable server remains an operational problem; it must not be mistaken for a bad data record.

The automated evidence

The unit tests use a small transport port and a deterministic fake. In addition, the integration test starts an embedded Apache MINA SSHD SFTP server and runs the production JSch transport against it. That exercises host-key verification, private-key login, download, and quarantine without a public SFTP server or external credentials.

This is strong evidence for the profile and adapter logic, not an availability promise for a production endpoint. A live-server check belongs in a protected, environment-specific pipeline with managed credentials and host keys.

What is intentionally not included

• no password authentication, OpenSSH agent, or automatic OpenSSH configuration;
• no directory polling, globbing, or selection among multiple simultaneous deliveries;
• no automatic archive for valid deliveries and no multi-file correlation;
• no business rules spanning several files or transport runs;
• no live SFTP server in the standard test suite and no production-availability claim.

These boundaries keep the iteration manageable. The adapter first proves a clear and secure one-file flow. Directory watching, delivery windows, multi-file correlation, and operational orchestration can be added as separate contracts later.