# Future Tasks

## Communication Architecture

- [ ] Define versioned HTTPS/JSON REST contracts between the on-premises application and the cloud service (for example, `/api/v1/...`).
- [ ] Create a shared API-contract module for request/response DTOs, validation rules, error responses, and API versioning.
- [ ] Add a dedicated on-premises cloud gateway/client layer; controllers and business services must not call `WebClient` directly.
- [ ] Use Spring `WebClient` inside the gateway while retaining synchronous gateway interfaces for the current Spring MVC/JSP application. Keep Reactor types confined to the gateway until the on-premises application is intentionally made reactive.
- [ ] Implement machine-to-machine authentication using OAuth 2.0 with asymmetric, signed JWT client assertions.
- [ ] Provision a unique asymmetric key pair and installation identity for every customer installation. Keep the private key securely on-premises and register only its public key in the cloud.
- [ ] Rotate installation keys/certificates at least annually. The key may have a one-year lifecycle, but it must never be used as a one-year bearer token.
- [ ] Generate a new signed client-assertion JWT for each token request. Give it a 1–5 minute lifetime, a token-endpoint-specific `aud` value, and a unique `jti` to prevent replay.
- [ ] Exchange each client assertion at the OAuth token endpoint for an audience-restricted access token with an initial lifetime of 10–30 minutes.
- [ ] Cache access tokens securely in memory on-premises and refresh shortly before expiration; never persist or log client assertions, access tokens, private keys, user passwords, or other credentials.
- [ ] Add cloud-side installation-key revocation, disablement, rollover, and audit facilities so a compromised installation can be blocked immediately.
- [ ] Validate JWT issuer, subject, audience, signature algorithm, signature, issued-at time, expiry, and `jti`; reject algorithm substitution and replay attempts.
- [ ] Use signed JWTs for proof of installation identity and TLS for transport confidentiality. Do not place secrets, user credentials, or PII in JWT claims; JWT encryption is not required for this flow.
- [ ] Assign a tenant identifier to every customer installation, derive it from the authenticated installation identity rather than browser input, and enforce tenant isolation in the cloud service.
- [ ] Evaluate mTLS or certificate-bound access tokens as a later hardening step for sender-constrained tokens.
- [ ] Require TLS 1.2 or newer for all communication and do not expose the customer's database to the cloud or public network.
- [ ] Add tenant resolution and authentication/authorization filters to `cygnus-cloud-service`.
- [ ] Configure connection, response, and overall request timeouts. Initial targets: 3-second connection timeout and 10-second response timeout.
- [ ] Add controlled retries only for safe/idempotent operations. Limit retries to one or two attempts and use idempotency keys for retryable write requests.
- [ ] Add circuit-breaker handling so cloud outages fail quickly without exhausting on-premises request threads.
- [ ] Add bulkhead/concurrency limits to prevent cloud calls from consuming all application threads or connections.
- [ ] Add short-lived local caching for stable cloud-owned master data where stale reads are acceptable.
- [ ] Provide clear UI and API errors when cloud services or internet connectivity are unavailable.
- [ ] Generate and propagate `X-Correlation-ID` values across browser, on-premises, and cloud request flows.
- [ ] Implement security and operational audit logging without recording applicant PII, credentials, tokens, or sensitive request bodies.
- [ ] Ensure cloud requests contain only cloud-owned master data and opaque on-premises identifiers; do not transmit applicant PII.
- [ ] Implement write APIs with idempotency, validation, authorization, and auditing.
- [ ] Start migration with a low-risk read-only API such as portfolio or verifier lookup.
- [ ] Migrate cloud-owned features incrementally: users, portfolios, verifiers, colonies, belts, operator allocation, belt allocation, and related tools.
- [ ] Add contract, integration, authentication, tenant-isolation, timeout, retry, circuit-breaker, and outage-recovery tests.
- [ ] Add monitoring for cloud API latency, error rates, circuit-breaker state, authentication failures, and per-tenant usage.