feat(instance): expose safe proxy configuration and runtime status

[Talis-dev]

Problem

There is currently no reliable API endpoint to verify whether a proxy configured through POST /instance/proxy/{instanceId} is both persisted and actually enabled in the running WhatsApp client.

GET /instance/all and GET /instance/info/{instanceId} always return an empty proxy field because the response sanitizes this field. This is good for preventing credential leakage, but it makes an empty value indistinguishable from an instance that has no proxy configured.

The write endpoint acknowledges the submitted host and port, but that alone does not prove that the runtime client successfully enabled the proxy. The runtime may also fall back to a direct connection after proxy authentication errors. An external management system can therefore report a false positive if it trusts only HTTP 200 or the connected state.

Proposed solution

Please expose a safe administrative endpoint such as:

GET /instance/proxy/{instanceId}/status

Example response:

{
  "configured": true,
  "runtimeEnabled": true,
  "protocol": "http",
  "host": "proxy.example.com",
  "port": "8080",
  "hasAuth": true,
  "fallbackWithoutProxy": false,
  "lastAppliedAt": "2026-07-24T10:00:00Z",
  "lastError": ""
}

Alternatively, these safe fields could be included in GET /instance/info/{instanceId} under a dedicated proxyStatus object.

Security requirements

The response must never expose:

• proxy password;
• proxy username, if it may contain customer/session identifiers;
• a full proxy URL containing credentials;
• global or instance API keys.

Host and port could optionally be masked or represented by a deterministic fingerprint if exposing them is considered sensitive.

Runtime behavior

The runtime status should distinguish at least:

1. no proxy configured;
2. configuration persisted but not yet loaded by the client;
3. proxy loaded and active in the current client transport;
4. proxy failed and the client is disconnected;
5. proxy failed and the client fell back to a direct connection.

If possible, the fallback-to-direct behavior should also be configurable. For security-sensitive deployments, a failClosed option would prevent the instance from connecting without the configured proxy.

Acceptance criteria

• A caller can determine whether a proxy is configured without retrieving credentials.
• A caller can determine whether the running client transport is using the proxy.
• A caller can detect fallback to a direct connection.
• The status survives and reconciles correctly after instance restart and proxy rotation.
• No proxy credentials are returned by the endpoint.

This would allow control panels and automated provisioning systems to avoid reporting a proxy as active based only on a successful write response.