Katta Client Library

Katta: transform your S3 storage into a secure, team-friendly workspace with client-side encryption.

This library implements the Katta Server API as Cyberduck protocol features for Katta Desktop.

Features:

• Client code is generated for Katta Server API from the OpenAPI specification.
• Implementations for device setup, retrieval of available storage profiles and creation of vaults in UVF format.
• Extensions for the OIDC authentication flow using token exchange and AWS role chaining for Katta S3 Storage Access).

This is a Maven multi-module project:

Module	Artifact	Description
hub	katta-clientlib-hub	Core client library. Contains the OpenAPI-generated Katta Server API client, the Cyberduck hub protocol, the workflow services (device and user key management, vault creation, access grants, Web of Trust) and the S3/STS storage-access extensions.
osx	katta-clientlib-osx	macOS integration. Cocoa binding controllers (ch.cyberduck:binding) that wire the workflows into the Cyberduck desktop UI, e.g. first-login and device-setup prompts.

Development Setup

Unit tests

Run unit tests only:

mvn clean verify -DskipITs

Debug logging

To run a single integration test with debug logging, use

mvn clean verify -Dit.test=cloud.katta.workflows.HubWorkflowGroupTest \\
 -Dfailsafe.failIfNoSpecifiedTests=false -Dlog4j.configurationFile=./hub/src/test/resources/log4j-test.xml

Docker Compose environment

Integration tests start the Docker Compose environment of katta-compose included with its Git URL in compose.yaml. Docker Compose fetches the referenced commit on first use. To run integration tests with a local checkout of katta-compose instead, replace the Git URL with the absolute path to compose.yaml in the checkout.

Integration Test Environment

Integration tests run Katta Server, Keycloak, PostgreSQL and MinIO with katta-compose, using the storage profiles and env files of this project in hub/src/test/resources; the MinIO policies are the ones of katta-compose. katta-compose renders the Keycloak realm from the Helm chart of Katta Server. Refer to katta-compose for the One-Stop Shop Demo, its profiles and endpoints.

To start the environment of the integration tests yourself, use

docker compose -f hub/src/test/resources/compose.yaml --env-file hub/src/test/resources/.local.env --profile local up --wait
docker compose -f hub/src/test/resources/compose.yaml --env-file hub/src/test/resources/.local.env --profile local down

The endpoints are the subdomains hub.localhost, keycloak.localhost and minio.localhost of katta-compose, which resolve to the loopback address on the host and to the containers inside the Docker network. The JVM running the tests uses the system resolver, which on macOS does not resolve subdomains of localhost. Add them to /etc/hosts:

127.0.0.1 hub.localhost keycloak.localhost minio.localhost

For the hybrid profile with Keycloak and MinIO on testing.katta.cloud and AWS S3, use .chipotle.env instead. CI writes its values from a repository secret.

Provisioned Users

Keycloak

The realm of katta-compose provisions the administrator admin with password admin. Before the tests of the local profile, KattaTestRealm adds the test configuration:

• It enables direct access grants in client cryptomator for the password grant of the integration tests.
• It creates the user HUB_USER with password HUB_PASSWORD of the env file (alice with password asd) and the roles user and create-vaults using the API of Katta Server.

The setup is idempotent. When you start the environment yourself with the commands above, run the integration tests with HubTestSetupDockerExtension.LocalAlreadyRunning, which adds the test configuration to the running environment.

MinIO

MinIO provisions the root user minioadmin with password minioadmin, and the user testuser with password top-secret for static storage access.