Vix.cpp v2.7.6

Vix.cpp v2.7.6 introduces a browser-based authentication flow for Softadastra Cloud.

Developers can now sign in through the Cloud website when running vix login, while the CLI receives the resulting session securely through a temporary local callback. The existing email and password flow remains available for scripts, remote environments, and cases where opening a browser is not practical.

This release also fixes the Cloud API endpoint used by the CLI and resolves an HTTPS transport lifetime problem that could cause valid Cloud requests to fail with misleading memory-allocation errors.

Release focus

The first Softadastra Cloud integration allowed the Vix CLI to authenticate using an email address and password entered directly in the terminal. That workflow was useful as an initial implementation, but it was not the right default for an interactive developer tool.

Terminal authentication requires the CLI to collect account credentials directly, offers limited room for future authentication methods, and separates the login experience from the Cloud website where account and workspace activity already takes place.

Vix.cpp v2.7.6 adds a browser flow designed around a short-lived authorization code. The user authenticates on cloud.softadastra.com, while the CLI waits on a temporary local callback server and exchanges the returned code with the Cloud API.

The final session continues to use the same local configuration format as the previous login implementation. The change is therefore focused on how a session is obtained rather than how authenticated commands store or consume it.

Starting a Cloud session

Running:

vix login

now presents two authentication methods:

1. Open browser
2. Enter email and password

The browser option is intended for normal interactive use. The manual option preserves the existing terminal workflow and remains useful on headless machines, through SSH sessions, and in environments where opening a local browser is unavailable.

Explicit credentials can still be supplied with:

vix login --email user@example.com --password '...'

This keeps existing scripts and automation compatible while allowing the interactive command to use the safer browser experience by default.

Browser authentication flow

When browser login is selected, the CLI starts a temporary HTTP server on an available 127.0.0.1 port.

It then generates a cryptographically secure state value and opens the Softadastra Cloud login page with the callback address and state attached to the authorization request.

The browser handles the account authentication on the Cloud domain. After the user signs in, the Cloud backend creates a short-lived authorization code and sends it to the local callback address together with the original state value.

The CLI verifies that the returned state matches the value generated at the beginning of the flow. It then sends the authorization code to the Cloud API, which exchanges it for the final authenticated session.

The resulting session is stored in:

~/.vix/cloud/config.json

This is the same configuration location and session format used by manual login, so commands such as vix cloud status, package publication, lockfile upload, and build reporting do not need a separate authentication path.

Authorization code security

The browser never receives the final CLI session token in a redirect URL.

Instead, Softadastra Cloud creates a temporary authorization code that is bound to the current authentication flow. The code is associated with:

  • the generated state value;
  • the local redirect URI;
  • the authenticated Cloud user session;
  • a short expiration period.

Authorization codes are stored in hashed form, expire quickly, and can be exchanged only once.

This prevents a code copied from browser history or intercepted after a successful exchange from being reused to create another CLI session. Binding the code to the redirect URI and state also prevents it from being moved into an unrelated authentication attempt.

The final session token is returned directly to the CLI during the code exchange. It is not exposed in the browser address bar or passed through the local callback URL.

Cloud login page

Softadastra Cloud now provides a dedicated frontend route for CLI authentication:

/cli/login

The page receives the callback information generated by vix login, authenticates the user through the normal Cloud session, and requests a temporary CLI authorization code from the backend.

The callback is sent to the local CLI server in the background. The main browser tab remains on cloud.softadastra.com and transitions to a success state instead of navigating visibly to a temporary 127.0.0.1 page.

This avoids leaving the user on a local address that becomes unavailable as soon as the CLI closes its callback server.

The local callback response also uses a Softadastra Cloud confirmation page with animated status feedback. It clearly reports whether the callback was received, rejected, or could not be completed, while the primary browser tab remains on the Cloud site.

State validation

The state value connects the browser response to the CLI process that initiated the login.

A newly generated state is included when the CLI opens the Cloud login page. The same value must return through the local callback and must also match the authorization code record stored by the backend.

The CLI rejects the callback when the state is missing or does not match.

This validation protects the local callback server from accepting an unrelated browser request and prevents one login attempt from completing another process's authentication flow.

The callback server listens only on 127.0.0.1, so it is not exposed as a network service to other machines.

Manual login compatibility

Browser authentication does not remove terminal login.

The existing email and password request remains available through the interactive menu and through explicit command-line options. This provides a fallback when browser opening fails or when the developer is using an environment without a graphical session.

Manual login continues to return the same Cloud session structure and writes it to the same configuration file as browser login.

Machine-readable behavior is also preserved. When --json is used with the manual or scripted flow, the CLI does not mix interactive prompts, browser status messages, or decorative output into the JSON response.

This is important for tools that parse authentication failures or call vix login as part of a controlled setup process.

Cloud API endpoint

The Vix CLI now sends Cloud API requests to:

https://api.softadastra.com

Earlier builds could target the public frontend domain rather than the backend API domain. That made authentication and Cloud commands dependent on frontend routing behavior and could cause requests to reach the wrong service.

The frontend and API now have clear roles:

cloud.softadastra.com      browser interface
api.softadastra.com        CLI and backend API

The browser login page remains on the frontend domain, while authorization code creation, exchange, session validation, workspace queries, and other Cloud operations use the API domain.

HTTPS transport fix

This release fixes an HTTPS transport lifetime problem that could appear during Cloud requests as:

network_error: std::bad_alloc

The error suggested that the application had exhausted memory, but the underlying problem was related to the lifetime of state used by the asynchronous HTTPS operation.

Transport objects and response buffers now remain valid until their associated callbacks and request operations have completed. Cloud requests therefore no longer access state that has already been destroyed or moved out of scope.

This correction applies to the shared HTTPS transport used by the CLI, not only to the browser login exchange.

Response-size limit

HTTPS transport now enforces a response-size guard.

Without an explicit limit, a malformed server, unexpected endpoint, or unbounded response could cause the client to continue growing its response buffer. The new guard stops buffering when the configured maximum is exceeded and returns a controlled transport error.

Cloud API responses are expected to remain small and structured, so an unusually large response is more likely to indicate an incorrect endpoint or server-side problem than a valid CLI result.

The guard makes this failure mode explicit rather than allowing response memory usage to grow without a boundary.

Login result

After a successful browser or manual login, the CLI reports the authenticated account and Cloud API address:

✓ Login successful.
Account   user@example.com
Cloud URL https://api.softadastra.com

The stored session can be verified with:

vix cloud status

Cloud commands use the saved session automatically until it expires, becomes invalid, or is replaced by another login.

Error handling

The authentication flow distinguishes between browser, local callback, API, and session failures.

A rejected or expired authorization code produces an authentication error rather than a generic network failure. A state mismatch is rejected before the code exchange is attempted. When the backend is unavailable, the CLI reports that the Cloud service could not be reached instead of treating the request as invalid credentials.

Manual login errors remain compatible with JSON output:

vix login \
  --email user@example.com \
  --password incorrect \
  --json

This allows scripts to inspect the structured error without removing the browser-oriented experience from normal interactive use.

Cloud backend support

Softadastra Cloud now includes the backend endpoints and persistence needed for CLI authorization codes.

The backend creates a temporary code only after confirming that the browser has an authenticated Cloud session. It records the code hash, user identity, state, redirect URI, and expiration time.

During exchange, the backend verifies each of those properties before creating the final CLI session. A successful exchange consumes the code immediately.

The authorization code is not a second long-lived session. It exists only to transfer authenticated browser intent back to the CLI without exposing the final token through browser navigation.

Validation

The Vix umbrella project was built with the database configurations used by the Cloud integration:

vix build --build-target all -v -- \
  -DVIX_ENABLE_DB=ON \
  -DVIX_DB_USE_MYSQL=ON \
  -DVIX_DB_USE_SQLITE=ON

The Softadastra Cloud backend and frontend were built with the new authorization code support and /cli/login route.

The final CLI was installed with:

sudo cmake --install build-ninja --prefix /usr/local

Browser login was verified through the complete flow: local callback startup, browser authentication, state validation, authorization code creation, one-time exchange, session storage, and authenticated Cloud status.

The manual email and password fallback was also tested to confirm that the previous terminal workflow remains functional.

Validation additionally covered:

  • clean JSON errors from manual login;
  • vix cloud status after browser authentication;
  • Cloud API requests through api.softadastra.com;
  • backend-unavailable diagnostics;
  • expired or invalid authorization codes;
  • state mismatch rejection;
  • single-use authorization code behavior;
  • session persistence in ~/.vix/cloud/config.json.

Compatibility

Existing authenticated Cloud sessions remain compatible because v2.7.6 does not change the local session configuration format.

Scripts using vix login --email and --password can continue to use the terminal flow. Commands using --json retain machine-readable output without browser-oriented formatting.

The main behavior change affects interactive vix login, which now offers browser authentication before manual credential entry.

Cloud commands now use the API domain rather than the public frontend domain. Custom development environments that override the Cloud address should ensure that their configured URL points to an API-compatible backend.

Known limitations

Browser authentication requires the CLI to open or provide a URL that can be accessed in a browser on the same machine.

The callback uses a temporary 127.0.0.1 HTTP server rather than a registered operating-system URL scheme. This keeps the first implementation portable and independent of desktop registration, but it requires the browser to be able to reach the local machine where vix login is running.

Remote SSH environments may not be able to use the callback directly when the browser runs on another computer. Manual email and password login remains available for those cases.

The authentication system currently supports the existing Softadastra Cloud account session. Additional identity providers, device authorization, organization-enforced authentication policies, and passkey-specific CLI flows are not part of this release.

Release summary

Vix.cpp v2.7.6 makes Cloud authentication fit more naturally into the developer workflow.

Interactive users can authenticate through the Softadastra Cloud website without placing their password directly into a CLI prompt. The browser receives only a temporary authorization code, the CLI validates the login state, and the final session is exchanged directly with the API.

Manual authentication remains available where it is needed, and both methods produce the same local session used by existing Cloud commands.

The release also corrects the API endpoint used by the CLI and strengthens the shared HTTPS transport so Cloud requests have predictable object lifetimes and bounded response buffering.