feat: SFTP server, virtual tree, SSH-key auth and listing (phase a) #5

Merged
KofTwentyTwo merged 3 commits from feature/phase-a-sftp-server into develop 2026-10-14 14:17:01 +00:00
KofTwentyTwo commented 2026-10-14 02:09:23 +00:00 (Migrated from github.com)

Phase (a) of docs/DESIGN.md §14.

Depends on QRun-IO/qqq#1170 (UiApiInProcessSessions, UiApiCredentials.ofInProcessSession). CI stays red until #1170 merges and develop publishes the 4.1.0-SNAPSHOT. Locally it is built against that branch installed as a private 4.1.0-FG-SNAPSHOT: ./mvnw -o -Dqqq.snapshot.version=4.1.0-FG-SNAPSHOT verify.

What's in it

  • Tables: all seven file_gateway_* tables, so the schema is stable. They come with entities, PVSs, joins, child lists and docs/ddl/file_gateway.sql. The nav lists the main tables only: Accounts, Endpoints, Upload jobs, Transfers, Connections.

  • Contingent possible values: on endpoints, the profile, view and report fields are filtered by tableName = ${input.tableName}. There's a test per pair, plus behavioural tests.

  • SSH keys: validated server-side. Fingerprint, type and bits are computed; DSA and RSA below 3072 are rejected.

  • Permissions: file_gateway.view, .admin and .connect. The system-written tables are read-only to people.

  • Client channel: sftp is registered. The sftp wall covers file_gateway_* and the security surfaces, and the assistant is denied file_gateway_*.

  • SFTP server (Apache MINA SSHD 2.16):

    • publickey only, with no password, keyboard-interactive, GSSAPI or host-based auth;
    • no shell, exec or forwarding;
    • restricted ciphers, MACs, KEX and signatures;
    • the host key is parsed in memory from the env var named in the config;
    • 15-minute idle timeout and 30-second auth timeout.
  • Authentication:

    • account and key status, expiry and CIDR allowlists;
    • DB-backed lockouts that raise a filegateway.lockout alert;
    • a per-IP connection rate limit and a concurrent-session cap;
    • live revocation.

    On success, the session is minted with createAutomatedSessionForUser, must carry file_gateway.connect, and is registered as an in-process session for /qqq/v1. All tree data comes from the UI API as that user.

  • Virtual NIO filesystem (nothing on disk):

    • it lists apps, tables, upload/<profile>/, views/<slug>.<fmt>, reports/, results/ and archive/, filtered by permissions;
    • hidden paths answer "no such file";
    • reads and writes are denied until phases (b) and (c).
  • Audit: connection-log and transfer-log rows (LIST and denied operations) with channel sftp/<sessionId>.

  • com.kingsrook.qbits.filegateway.api: the consumer and outbox contract agreed with qbit-edi (types only).

Tests

54 tests: embedded strict UI API server, H2, the real MINA SFTP client and per-test keys. They cover:

  • listing per permission;
  • auth failures (unknown, revoked or expired key; disabled or expired account; IP outside the allowlist; no connect permission; password and keyboard-interactive never offered);
  • lockout and the session cap;
  • audit rows;
  • key validation;
  • spec'd invoker operations;
  • the no-disk guard (nothing written outside the JVM temp area, and it's empty after each test);
  • API package isolation;
  • contingent possible values.

verify passes with checkstyle and JaCoCo at 95.2% instructions and 98.1% classes.

Spec tweak: core alert-type names use dots, so the lockout alert is filegateway.lockout.

🤖 Generated with Claude Code

Phase (a) of `docs/DESIGN.md` §14. **Depends on QRun-IO/qqq#1170** (`UiApiInProcessSessions`, `UiApiCredentials.ofInProcessSession`). CI stays red until #1170 merges and develop publishes the 4.1.0-SNAPSHOT. Locally it is built against that branch installed as a private `4.1.0-FG-SNAPSHOT`: `./mvnw -o -Dqqq.snapshot.version=4.1.0-FG-SNAPSHOT verify`. ### What's in it - **Tables:** all seven `file_gateway_*` tables, so the schema is stable. They come with entities, PVSs, joins, child lists and `docs/ddl/file_gateway.sql`. The nav lists the main tables only: Accounts, Endpoints, Upload jobs, Transfers, Connections. - **Contingent possible values:** on endpoints, the profile, view and report fields are filtered by `tableName = ${input.tableName}`. There's a test per pair, plus behavioural tests. - **SSH keys:** validated server-side. Fingerprint, type and bits are computed; DSA and RSA below 3072 are rejected. - **Permissions:** `file_gateway.view`, `.admin` and `.connect`. The system-written tables are read-only to people. - **Client channel:** `sftp` is registered. The `sftp` wall covers `file_gateway_*` and the security surfaces, and the assistant is denied `file_gateway_*`. - **SFTP server** (Apache MINA SSHD 2.16): - **publickey only**, with no password, keyboard-interactive, GSSAPI or host-based auth; - no shell, exec or forwarding; - restricted ciphers, MACs, KEX and signatures; - the host key is parsed in memory from the env var named in the config; - 15-minute idle timeout and 30-second auth timeout. - **Authentication:** - account and key status, expiry and CIDR allowlists; - DB-backed lockouts that raise a `filegateway.lockout` alert; - a per-IP connection rate limit and a concurrent-session cap; - live revocation. On success, the session is minted with `createAutomatedSessionForUser`, must carry `file_gateway.connect`, and is registered as an in-process session for `/qqq/v1`. All tree data comes from the UI API as that user. - **Virtual NIO filesystem** (nothing on disk): - it lists apps, tables, `upload/<profile>/`, `views/<slug>.<fmt>`, `reports/`, `results/` and `archive/`, filtered by permissions; - hidden paths answer "no such file"; - reads and writes are denied until phases (b) and (c). - **Audit:** connection-log and transfer-log rows (LIST and denied operations) with channel `sftp/<sessionId>`. - **`com.kingsrook.qbits.filegateway.api`:** the consumer and outbox contract agreed with qbit-edi (types only). ### Tests 54 tests: embedded strict UI API server, H2, the real MINA SFTP client and per-test keys. They cover: - listing per permission; - auth failures (unknown, revoked or expired key; disabled or expired account; IP outside the allowlist; no `connect` permission; password and keyboard-interactive never offered); - lockout and the session cap; - audit rows; - key validation; - spec'd invoker operations; - the no-disk guard (nothing written outside the JVM temp area, and it's empty after each test); - API package isolation; - contingent possible values. `verify` passes with checkstyle and JaCoCo at **95.2% instructions and 98.1% classes**. Spec tweak: core alert-type names use dots, so the lockout alert is `filegateway.lockout`. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign in to join this conversation.