v2: Design auth provider API — Token, Basic, X-Chroma-Token, custom headers

[oss-amikos]

Context

The Go client supports multiple auth methods through a CredentialsProvider interface. PR #80 had the right idea with an AuthProvider interface but needs refinement. This also covers the Chroma Cloud authentication flow.

Requirements

AuthProvider Interface

public interface AuthProvider {
    /** Apply auth credentials to the given request headers. */
    void applyAuth(Map<String, String> headers);
}

Design: auth providers modify a mutable headers map. This is simpler than returning headers or wrapping requests.

Built-in Implementations

// Token-based (Authorization: Bearer <token>)
public final class TokenAuth implements AuthProvider {
    public static TokenAuth of(String token) { ... }
}

// Basic Auth (Authorization: Basic base64(user:pass))
public final class BasicAuth implements AuthProvider {
    public static BasicAuth of(String username, String password) { ... }
}

// X-Chroma-Token header
public final class ChromaTokenAuth implements AuthProvider {
    public static ChromaTokenAuth of(String token) { ... }
}

Client Builder Integration

// Explicit auth provider
ChromaClient.builder()
    .baseUrl("http://localhost:8000")
    .auth(BasicAuth.of("admin", "secret"))
    .build();

// Convenience: API key sets X-Chroma-Token (Chroma Cloud)
ChromaClient.builder()
    .baseUrl("https://api.trychroma.com")
    .apiKey("chroma-api-key")
    .tenant("my-tenant")
    .database("my-db")
    .build();

Custom Headers

For non-standard auth or additional headers:

ChromaClient.builder()
    .baseUrl("http://localhost:8000")
    .defaultHeaders(Map.of("X-Custom-Auth", "value"))
    .build();

Design Decisions

1. applyAuth(Map<String, String> headers) — provider mutates headers map, keeps the interface simple
2. Static factory methods — TokenAuth.of(token), not new TokenAuth(token)
3. apiKey() on the builder — syntactic sugar that creates a ChromaTokenAuth internally
4. No auth is the default — no NoAuthProvider sentinel object needed; just don't set auth

Acceptance Criteria

• AuthProvider interface defined
• TokenAuth, BasicAuth, ChromaTokenAuth implementations
• Client builder auth() and apiKey() methods
• defaultHeaders() support on client builder
• All implementations are final and immutable

Supersedes

• Auth support #15 (Auth support)

[oss-amikos]

Implemented in PR #95 (v2 API skeleton)