# Cygnus cloud client

This module is the reusable on-premises gateway client for Cygnus cloud APIs.
It obtains a short-lived machine access token, encrypts login credentials with
the cloud login public key, and calls the cloud identity API over WebFlux.

## On-premises identity configuration

Cloud login is required by the on-premises application. Configure these as
environment variables or JVM system properties:

| Setting | Purpose |
| --- | --- |
| `CYGNUS_CLOUD_BASE_URL` | Cloud gateway/API base URL |
| `CYGNUS_TOKEN_URL` | OAuth 2.0 machine-token endpoint |
| `CYGNUS_CLIENT_ID` | Provisioned customer/client identifier |
| `CYGNUS_INSTALLATION_ID` | Unique on-premises installation identifier |
| `CYGNUS_CLIENT_ASSERTION` | Provisioned encrypted assertion or `file:/secure/path/assertion.jwt` |
| `CYGNUS_LOGIN_KEY_ID` | Cloud login encryption-key identifier |
| `CYGNUS_LOGIN_PUBLIC_KEY` | X.509 RSA public key location |
| `CYGNUS_CLOUD_REQUEST_TIMEOUT` | Request timeout, for example `PT10S` |
Do not store private keys, client assertions, passwords, or production URLs in
source control.

## Provision a machine assertion

The assertion is a signed JWT nested inside an RSA-OAEP-256/AES-256-GCM JWE.
It is valid for one year; the access token obtained with it is short-lived.

For local development, the repository setup script automates prerequisite
checks, the full Maven verification, directory creation, all three cloud key
pairs, the installation key pair, database-backed tenant/install registration,
an initial license, and the encrypted machine assertion:

```bash
./scripts/setup-local-communication.sh
```

The script interactively asks for the customer name and slug, installation
identifier, cloud URL, database connection, license package/type/duration, and
whether to run the full verification. Customer and installation identifiers
cannot contain spaces. The slug is the stable tenant key and is used for its
directory and signing-key filenames.

The client account, installation public key, allowed scopes, and license are
upserted into PostgreSQL (`identity.client_account`,
`identity.client_installation`, and `identity.client_license`). The cloud
service resolves this registration dynamically through Redis with PostgreSQL
fallback, so adding another customer does not require a cloud restart.

It preserves existing private keys and assertions. Set
`CYGNUS_SETUP_FORCE_ASSERTION=true` only when the assertion needs to be
regenerated. The manual provisioning commands follow.

Generate the installation signing key:

```bash
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  -out client-signing-private.pem
openssl pkey -in client-signing-private.pem -pubout \
  -out client-signing-public.pem
```

Generate the assertion after the cloud assertion-encryption public key has
been securely delivered:

```bash
mvn -pl cygnus-cloud-client exec:java \
  -Dexec.mainClass=com.cygnus.client.provisioning.MachineAssertionGenerator \
  -Dexec.args="customer-a site-01 https://cloud.example.com/oauth2/token \
client-signing-private.pem cloud-assertion-public.pem machine-assertion.jwt"
```

The setup script stores `client-signing-public.pem` in the installation record
used by the cloud. Keep the private key and generated assertion only on the
on-premises server with owner-only filesystem permissions.