How CLI Fingerprint Matching Works for Provider Authentication in OmniRoute

CLI fingerprint matching in OmniRoute uses deterministic browser fingerprints—comprising User-Agent, Accept-Language, and optional TLS hashes—to bind outbound CLI requests to specific provider accounts, enabling stateful session reuse and preventing replay attacks.

OmniRoute implements a sophisticated authentication system that verifies provider requests through cryptographic and environmental fingerprints rather than traditional session tokens alone. When you initiate a request from the command-line interface, the system injects pre-calculated browser fingerprints into HTTP headers, allowing the server to match your CLI invocation to a specific provider connection stored in the session pool. This three-stage pipeline ensures deterministic routing while mitigating replay attacks and proxy-based session confusion.

The Three-Stage Fingerprint Authentication Flow

The CLI fingerprint matching mechanism operates through generation, persistence, and runtime resolution stages, each handled by specific services within the OmniRoute codebase.

1. Fingerprint Generation via FingerprintRotator

When a provider connection is created, the FingerprintRotator service generates a unique fingerprint profile containing a distinct User-Agent string and Accept-Language value. Implemented in src/open-sse/services/sessionPool/fingerprintRotator.ts, this service produces profiles labeled with short IDs (e.g., fp-xxx) and rotates them round-robin across connection pools.

For TLS-enabled providers, the system optionally computes an additional TLS fingerprint—a SHA-1 hash of the provider’s TLS certificate—using getCertFingerprint(). This hash is stored alongside the browser fingerprint to support providers that pin connections to specific TLS signatures, such as Cloudflare-proxied endpoints.

2. Persisting Fingerprints to Connection Storage

Generated fingerprints are serialized into the providerSpecificData.fingerprints column of the connections table. The combo builder transforms each fingerprint into a selectable CLI option using the format <rowId>|fp|<fingerprint>, as defined in src/lib/combo/builderOptions.ts.

This persistence layer ensures that fingerprint profiles survive CLI restarts and can be referenced by their short ID (e.g., fp-1) in subsequent commands. The structured storage separates fingerprint metadata from credential secrets, maintaining a clear authorization boundary.

3. Request-Time Matching and Session Resolution

At request time, the CLI resolves the specified fingerprint ID and invokes the generic applyFingerprint() pipeline, gated by the CLI_FINGERPRINTS feature flag defined in src/shared/constants/cliCompatProviders.ts. This pipeline injects the stored User-Agent, Accept-Language, and optional TLS fingerprint into outbound HTTP headers.

When the request reaches the server, the session pool executes a deterministic lookup in src/sse/services/noAuthProxyResolution.ts. It searches for an existing session where:

• session.fingerprint.userAgent matches the incoming User-Agent header
• session.fingerprint.acceptLanguage matches the Accept-Language header
• If TLS fingerprinting is enabled, session.fingerprint.tlsFingerprint matches the x-tls-fingerprint header

If a matching session exists, the request is authenticated against that provider account; otherwise, the system creates a new session and stores its fingerprint for future reuse.

Optional TLS Fingerprint Layer

When the featureFlagEnableTlsFingerprint flag is enabled in src/sse/handlers/chatHelpers.ts, OmniRoute calculates a SHA-1 hash of the provider’s TLS certificate and appends it to request headers. The proxy logger persists these values in the proxy_log.tls_fingerprint column (see src/lib/proxyLogger.ts), creating an audit trail for certificate-pinned connections.

This layer is particularly effective for providers implementing TLS fingerprint pinning, as it prevents trivial proxy rotation attacks by binding the request to a specific cryptographic identity.

Practical CLI Usage Examples

Listing Available Fingerprints

Query stored fingerprints for a specific provider using the CLI:

omniroute providers list-fingerprints <provider-id>

Example output:

ID          User-Agent                              Accept-Language
fp-1        OmniRoute/3.8.49 (Linux; x86_64)       en-US,en;q=0.9
fp-2        OmniRoute/3.8.49 (Windows; x86_64)     en-GB,en;q=0.8

This command reads the providerSpecificData.fingerprints array from the database and renders the associated User-Agent and language pairs.

Making Authenticated Requests

Execute a chat completion using a specific fingerprint profile:

omniroute chat completions \
  --provider openai \
  --fingerprint fp-2 \
  -M gpt-4o-mini \
  -p "Explain fingerprint matching."

The CLI performs three operations:

1. Resolves fp-2 to its stored UA/Lang values (and TLS fingerprint if enabled)
2. Calls applyFingerprint() to inject headers into the outbound request
3. Transmits the request to the OpenAI executor with deterministic session binding

Server-Side Matching Logic

The session pool implements matching logic similar to this TypeScript pseudo-code from src/sse/services/noAuthProxyResolution.ts:

const session = sessions.find(s =>
  s.fingerprint.userAgent === incomingHeaders['user-agent'] &&
  s.fingerprint.acceptLanguage === incomingHeaders['accept-language'] &&
  (!tlsEnabled || s.fingerprint.tlsFingerprint === incomingHeaders['x-tls-fingerprint'])
);

If the lookup returns a match, the request inherits the provider credentials and proxy settings associated with that fingerprint; otherwise, the system initializes a new authenticated session.

Summary

• CLI fingerprint matching binds CLI requests to provider accounts using deterministic browser fingerprints rather than ephemeral session tokens.
• The FingerprintRotator generates unique User-Agent and Accept-Language combinations, optionally augmented with TLS certificate hashes.
• Fingerprints persist in providerSpecificData.fingerprints and are selectable via CLI options formatted as <rowId>|fp|<fingerprint>.
• The applyFingerprint() pipeline injects fingerprint headers at request time, gated by the CLI_FINGERPRINTS feature flag.
• Server-side matching in the session pool verifies header combinations against stored records to authenticate requests or create new sessions.

Frequently Asked Questions

What is a fingerprint in the context of OmniRoute CLI authentication?

A fingerprint is a deterministic identifier composed of browser metadata (User-Agent, Accept-Language) and optional TLS hashes that uniquely identifies a provider connection. According to the OmniRoute source code in src/open-sse/services/sessionPool/fingerprintRotator.ts, these fingerprints enable the system to recognize and reuse specific provider sessions across CLI invocations without retransmitting raw credentials.

How does the CLI apply fingerprints to outbound requests?

The CLI reads the fingerprint ID (e.g., fp-1) specified via the --fingerprint flag and retrieves the corresponding profile from providerSpecificData.fingerprints. It then invokes applyFingerprint() to inject the stored headers into the HTTP request before transmission. This process is controlled by the CLI_FINGERPRINTS feature flag defined in src/shared/constants/cliCompatProviders.ts.

When should I use the TLS fingerprint feature?

Enable the TLS fingerprint feature (featureFlagEnableTlsFingerprint) when communicating with providers that implement certificate pinning or TLS fingerprint filtering, such as Cloudflare-protected endpoints. As implemented in src/lib/proxyLogger.ts, this adds a SHA-1 hash of the TLS certificate to the request headers and logs it to the tls_fingerprint column, creating a cryptographic binding between the request and the specific TLS identity.

How are Zed OAuth credentials fingerprinted differently?

For the Zed import flow, OmniRoute generates a lightweight 16-character fingerprint derived from sha256(service|account|token) in src/lib/zed-oauth/credentialFingerprint.ts. Unlike standard browser fingerprints, this hash represents the credential itself, allowing the server to validate the CLI-sent fingerprint against stored credential data without exposing the actual token, thereby preventing replay attacks while maintaining authentication state.

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