GeoLibre mTLS and Certificate Handling: Environment Variables for Native HTTP Client Configuration

GeoLibre uses five environment variables—REQWEST_TLS_CA_CERT, REQWEST_TLS_CLIENT_CERT, REQWEST_TLS_CLIENT_KEY, REQWEST_TLS_REJECT_UNAUTHORIZED, and REQWEST_TLS_SERVER_NAME—to control mutual TLS (mTLS) and certificate validation in its Tauri-based native HTTP client.

GeoLibre's native HTTP client runs inside the Tauri desktop runtime and relies on the Rust reqwest library for secure network communication. While the application behaves like a standard browser by default, developers can override TLS behavior using environment variables read from process.env before any request is dispatched. This article explains each variable's purpose, default behavior, and practical implementation based on the actual source code in opengeos/GeoLibre.

REQWEST_TLS_CA_CERT: Custom Root Certificate Authority

The REQWEST_TLS_CA_CERT environment variable specifies the path to a CA bundle in PEM format that the client should trust during server certificate validation.

When this variable is omitted, reqwest falls back to the system's native root-CA store. This variable becomes essential when connecting to private services secured by an internal certificate authority that is not distributed through the operating system's trust store.

// Trust a private CA for internal API calls
process.env.REQWEST_TLS_CA_CERT = "/etc/ssl/certs/my-org-ca.pem";

await fetch("https://internal.geolibre.example.com/secure-data");

The CA bundle validation logic is referenced indirectly in src/lib/fetch-error.ts, where TLS-related failures are classified and surfaced to users.

REQWEST_TLS_CLIENT_CERT and REQWEST_TLS_CLIENT_KEY: Mutual TLS Authentication

Mutual TLS (mTLS) requires the client to present a certificate that the server can validate. GeoLibre supports mTLS through two coordinated environment variables:

Variable	Required	Description
REQWEST_TLS_CLIENT_CERT	Yes	Path to the client certificate (PEM format)
REQWEST_TLS_CLIENT_KEY	Only if cert is set	Path to the private key (PEM format) matching the certificate

The private key variable is ignored unless REQWEST_TLS_CLIENT_CERT is also defined. Neither variable has a default—no client certificate is transmitted unless explicitly configured.

// Complete mTLS configuration for a protected API
process.env.REQWEST_TLS_CA_CERT = "/path/to/ca-bundle.pem";
process.env.REQWEST_TLS_CLIENT_CERT = "/path/to/client.crt";
process.env.REQWEST_TLS_CLIENT_KEY = "/path/to/client.key";

await fetch("https://mtls.api.example.com/protected-resource");

REQWEST_TLS_REJECT_UNAUTHORIZED: Bypass Certificate Verification

Set REQWEST_TLS_REJECT_UNAUTHORIZED to "0" to disable server certificate verification entirely. This is useful for development environments using self-signed certificates but should never be enabled in production.

Default behavior rejects unauthorized certificates (equivalent to "1").

// Development-only: accept self-signed certificates
process.env.REQWEST_TLS_REJECT_UNAUTHORIZED = "0";

await fetch("https://localhost:8443/api"); // No certificate validation error

Warning: Disabling verification exposes the connection to man-in-the-middle attacks. The src/lib/diagnostics.ts module generates user-facing warnings when this configuration is detected.

REQWEST_TLS_SERVER_NAME: Override TLS SNI/Hostname

The REQWEST_TLS_SERVER_NAME variable overrides the Server Name Indication (SNI) hostname sent during the TLS handshake. This is valuable when connecting via IP address to a server that expects a specific hostname for certificate matching.

Default behavior uses the hostname extracted from the request URL.

// Connect by IP but present correct SNI for certificate validation
process.env.REQWEST_TLS_SERVER_NAME = "api.internal.geolibre.io";

await fetch("https://10.0.0.5/metrics"); // TLS handshake advertises "api.internal.geolibre.io"

Where These Variables Are Processed

The environment variables flow through several key files in the GeoLibre codebase:

• apps/geolibre-desktop/src/lib/fetch-error.ts — Classifies native HTTP (reqwest) failures and reads TLS-related environment variables to determine error context
• apps/geolibre-desktop/src/lib/diagnostics.ts — Generates user-facing diagnostic messages based on classified TLS errors
• apps/geolibre-desktop/vite.config.ts — Propagates Tauri-specific environment variables into the bundled frontend code
• backend/geolibre_server/pyproject.toml — Declares the reqwest dependency on the Rust side; the compiled binary respects TLS env vars at runtime

Complete Configuration Example

This example combines multiple variables for a complex enterprise scenario: connecting to a private API with custom CA, mTLS, and IP-based routing with SNI override.

// Enterprise mTLS configuration
process.env.REQWEST_TLS_CA_CERT = "/certs/enterprise-ca.pem";
process.env.REQWEST_TLS_CLIENT_CERT = "/certs/service-account.crt";
process.env.REQWEST_TLS_CLIENT_KEY = "/certs/service-account.key";
process.env.REQWEST_TLS_SERVER_NAME = "api.geolibre.enterprise";

// Request routes through internal network to load balancer IP
const response = await fetch("https://192.168.100.10/v1/data");

Summary

• Five environment variables control GeoLibre's native HTTP client TLS behavior: REQWEST_TLS_CA_CERT, REQWEST_TLS_CLIENT_CERT, REQWEST_TLS_CLIENT_KEY, REQWEST_TLS_REJECT_UNAUTHORIZED, and REQWEST_TLS_SERVER_NAME
• mTLS authentication requires both certificate and key paths; the CA certificate enables trust of private certificate authorities
• Development shortcuts like disabling verification are available but carry security risks
• SNI override solves hostname/certificate mismatches when connecting by IP address
• Variables are processed in fetch-error.ts and passed to the underlying reqwest instance before request execution

Frequently Asked Questions

How do I enable mTLS in GeoLibre's native HTTP client?

Set REQWEST_TLS_CLIENT_CERT and REQWEST_TLS_CLIENT_KEY to the paths of your PEM-formatted certificate and private key. Optionally set REQWEST_TLS_CA_CERT if your server uses a private certificate authority. These variables are read by the Tauri runtime before each request.

Can I use self-signed certificates during development?

Yes. Set REQWEST_TLS_REJECT_UNAUTHORIZED="0" to disable certificate validation. This is implemented in the reqwest-backed native client and surfaced through error classification in fetch-error.ts. Remove this setting before deploying to production.

Where does GeoLibre read these TLS environment variables?

The variables are read from process.env early in the native request pipeline. The apps/geolibre-desktop/src/lib/fetch-error.ts module inspects TLS-related failures, while vite.config.ts propagates these variables into the bundled application. The actual TLS configuration is applied by the reqwest library in the Rust backend.

What happens if no TLS environment variables are set?

The client behaves like a standard browser request: it validates server certificates against the system root-CA store and does not send a client certificate. No mutual TLS is performed, and SNI uses the hostname from the request URL.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}