matrix/docs/future-tasks.md

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.