ENV-18 govern Gemini auth env

Author: nshkrdotcom

CHANGELOG.md

@@ -8,9 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Changed
+- **Governed authority mode**: HTTP and Live WebSocket calls can now use a `Gemini.GovernedAuthority` value that supplies authority-selected base URLs and materialized credential headers/query params while rejecting unmanaged request credentials in governed mode.
 - **Provider payload parsing**: service account keys, SSE fields, model list payloads, Live response modalities, and WebSocket redaction now use bounded field maps and deterministic string parsing.
 
 ### Tests
+- Added governed authority regression coverage for HTTP auth materialization, request override rejection, WebSocket query redaction, and standalone auth compatibility.
 - Added focused regression coverage for provider-authored service account keys and unknown SSE fields to ensure they are ignored instead of interned as new atoms.
 
 ## [0.13.0] - 2026-04-02

README.md

@@ -83,7 +83,7 @@ Or set the environment variable:
 export GEMINI_API_KEY="your_api_key_here"
 ```
 
-For default Gemini auth resolution, `config :gemini_ex, api_key: ...` now takes precedence over `GEMINI_API_KEY`. Narrower overrides still win: pass `api_key:` directly on a request or on `Gemini.Live.Session.start_link/1` for session-scoped credentials.
+For default Gemini auth resolution, `config :gemini_ex, api_key: ...` now takes precedence over `GEMINI_API_KEY`. Narrower overrides still win in standalone mode: pass `api_key:` directly on a request or on `Gemini.Live.Session.start_link/1` for session-scoped credentials. Governed mode does not use these standalone sources; pass `Gemini.GovernedAuthority` so credentials and targets come from the selected authority materializer.
 
 ### Simple Content Generation
 
@@ -1380,13 +1380,19 @@ The examples follow a consistent pattern:
 
 ## Authentication
 
-### Gemini API Key (Recommended for Development)
+### Gemini API Key (Standalone Compatibility)
 
 Default Gemini key precedence is:
 - Per-request or per-session `api_key:`
 - Application config: `config :gemini_ex, api_key: ...`
 - Environment variable: `GEMINI_API_KEY`
 
+These sources are the standalone SDK compatibility path. They are not governed
+authority. In governed runtime calls, pass a `Gemini.GovernedAuthority` instead;
+the HTTP and Live WebSocket clients reject unmanaged `api_key`, Vertex token,
+service account, project, location, ADC, and base URL overrides whenever a
+governed authority is present.
+
 ```bash
 export GEMINI_API_KEY="your_api_key"
 ```
@@ -1400,10 +1406,51 @@ Gemini.generate("Hello", api_key: "specific_key")
   Gemini.Live.Session.start_link(
     model: Gemini.Live.Models.resolve(:audio),
     api_key: "session_specific_key"
+)
+```
+
+### Governed Authority
+
+Governed execution uses authority-materialized values selected outside the SDK:
+
+```elixir
+authority =
+  Gemini.GovernedAuthority.new!(
+    base_url: "https://generativelanguage.googleapis.com/v1beta",
+    credential_ref: "credential-123",
+    credential_lease_ref: "lease-123",
+    target_ref: "target-123",
+    redaction_ref: "redaction-123",
+    credential_headers: %{"x-goog-api-key" => "materialized-key"}
+  )
+
+Gemini.Client.HTTP.post("models/gemini-2.5-flash:generateContent", %{contents: []},
+  governed_authority: authority
+)
+```
+
+For Live WebSocket sessions, authority can materialize a redacted query
+credential instead of a raw session `api_key:`:
+
+```elixir
+authority =
+  Gemini.GovernedAuthority.new!(
+    base_url: "wss://generativelanguage.googleapis.com",
+    websocket_path:
+      "/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent",
+    credential_ref: "credential-123",
+    credential_lease_ref: "lease-123",
+    target_ref: "target-123",
+    credential_query_params: [{"key", "materialized-key"}]
   )
+
+Gemini.Live.Session.start_link(
+  model: Gemini.Live.Models.resolve(:audio),
+  governed_authority: authority
+)
 ```
 
-### Vertex AI (Recommended for Production)
+### Vertex AI (Standalone Compatibility)
 
 ```elixir
 # Service Account JSON file
@@ -1424,6 +1471,7 @@ config :gemini_ex, :auth,
 ### Application Default Credentials (ADC)
 
 Zero-config GCP authentication with automatic credential discovery and token refresh.
+ADC remains standalone compatibility only and cannot satisfy governed authority.
 
 ```bash
 # Configure ADC explicitly (optional)

config/config.exs

@@ -3,8 +3,8 @@ import Config
 # Configure the Gemini client
 config :gemini_ex,
   # Default model is auto-detected based on authentication:
-  # - Gemini API (GEMINI_API_KEY): "gemini-flash-lite-latest"
-  # - Vertex AI (VERTEX_PROJECT_ID): "gemini-2.5-flash-lite"
+  # - Standalone Gemini API (GEMINI_API_KEY): "gemini-flash-lite-latest"
+  # - Standalone Vertex AI (VERTEX_PROJECT_ID): "gemini-2.5-flash-lite"
   # Uncomment to override: default_model: "your-model-name",
 
   # HTTP timeout in milliseconds

config/dev.exs

@@ -5,5 +5,6 @@ config :gemini_ex,
   # Enable debug logging in development
   log_level: :debug
 
-# You can set your API key here for development, or use environment variables
+# Standalone development can set an API key here or use environment variables.
+# Governed execution passes Gemini.GovernedAuthority instead.
 # config :gemini_ex, api_key: "your_development_api_key"

guides/AUTHENTICATION_SYSTEM.md

@@ -13,7 +13,13 @@ The system is built on two core principles:
 1.  **Dual-Strategy Support:** It natively supports both the simple **Gemini API Key** (`:gemini`) and the more complex **Vertex AI OAuth/JWT** (`:vertex_ai`) authentication methods.
 2.  **Hierarchical Configuration:** It provides a clear and predictable order of precedence for sourcing credentials, prioritizing per-request overrides, then environment variables, and finally Elixir application configuration.
 
-This design makes the library easy to use for simple scripts while being powerful enough for complex, multi-tenant production applications.
+This design makes the library easy to use for standalone scripts while keeping
+governed runtime effects separate. Env, app config, ADC, native Google
+credential discovery, and direct request/session overrides are standalone
+compatibility only. Governed execution passes `Gemini.GovernedAuthority`, which
+contains the authority-selected base URL, credential reference, lease reference,
+target reference, redaction reference, and materialized credential headers or
+query params for one bounded effect.
 
 ### 2. Core Concepts: Authentication Strategies
 
@@ -207,9 +213,11 @@ opts = [
 {:ok, stream_id} = Gemini.APIs.Coordinator.stream_generate_content("Hello", opts)
 ```
 
-#### Method 2: Environment Variables (Recommended for Production)
+#### Method 2: Environment Variables (Standalone Compatibility)
 
-This is the most secure and standard way to provide credentials in production, staging, and CI/CD environments.
+This is the standard standalone way to provide credentials in development,
+staging, CI, and direct SDK deployments. It is not governed authority and cannot
+satisfy governed runtime claims.
 
 *   **For Gemini API Key:**
     ```bash
@@ -231,11 +239,13 @@ This is the most secure and standard way to provide credentials in production, s
     export VERTEX_QUOTA_PROJECT_ID="your-quota-project-id"
     ```
 
-The library will automatically detect and use these variables.
+The library will automatically detect and use these variables only in
+standalone mode.
 
 #### Method 3: Application Configuration (Standard Elixir Way)
 
-Configure the library in your project's `config/runtime.exs` file. This is the canonical approach for managing secrets within an Elixir application.
+Configure the library in your project's `config/runtime.exs` file for
+standalone application defaults. This path is not governed authority.
 
 When both are present for Gemini auth, application config now takes precedence over `GEMINI_API_KEY`.
 
@@ -264,6 +274,32 @@ When both are present for Gemini auth, application config now takes precedence o
       }
     ```
 
+#### Governed Authority
+
+Governed callers do not pass `api_key:`, `access_token:`, `service_account:`,
+`project_id:`, `location:`, app env, env vars, ADC, or native credential files
+as authority. They pass a `Gemini.GovernedAuthority` value:
+
+```elixir
+authority =
+  Gemini.GovernedAuthority.new!(
+    base_url: "https://generativelanguage.googleapis.com/v1beta",
+    credential_ref: "credential-123",
+    credential_lease_ref: "lease-123",
+    target_ref: "target-123",
+    redaction_ref: "redaction-123",
+    credential_headers: %{"x-goog-api-key" => "materialized-key"}
+  )
+
+Gemini.Client.HTTP.post("models/gemini-2.5-flash:generateContent", %{contents: []},
+  governed_authority: authority
+)
+```
+
+For Live WebSocket calls, authority can materialize the query credential and
+the WebSocket path. GeminiEx redacts `key`, `access_token`, and `token` query
+params in path logs and test helpers.
+
 ### 6. Live API Authentication (New in v0.9.0)
 
 The Live API uses WebSocket connections for bidirectional streaming. Authentication works similarly to HTTP requests but with some specific considerations:

guides/live_api.md

@@ -283,7 +283,7 @@ model = Models.resolve(:audio)
 # Session is now ready for messages
 ```
 
-For Gemini sessions, you can also pass `api_key:` directly to `Session.start_link/1`. When `api_key:` is present and `auth:` is omitted, the session uses Gemini auth for that connection only.
+For standalone Gemini sessions, you can also pass `api_key:` directly to `Session.start_link/1`. When `api_key:` is present and `auth:` is omitted, the session uses Gemini auth for that connection only. Governed sessions use `Gemini.GovernedAuthority` instead and reject direct per-session credentials.
 
 ```elixir
 {:ok, session} = Gemini.Live.Session.start_link(

lib/gemini.ex

@@ -78,10 +78,10 @@ defmodule Gemini do
 
   ### 1. Gemini API Key (Simple)
 
-  Best for development and simple applications:
+  Standalone compatibility for development and simple applications:
 
   ```elixir
-  # Environment variable (recommended)
+  # Environment variable for standalone use
   export GEMINI_API_KEY="your_api_key"
 
   # Application config
@@ -91,9 +91,9 @@ defmodule Gemini do
   Gemini.generate("Hello", api_key: "specific_key")
   ```
 
-  ### 2. Vertex AI (Production)
+  ### 2. Vertex AI (Standalone)
 
-  Best for production Google Cloud applications:
+  Standalone compatibility for Google Cloud applications:
 
   ```elixir
   # Service Account JSON file
@@ -111,6 +111,13 @@ defmodule Gemini do
     }
   ```
 
+  ### Governed Authority
+
+  Governed execution does not use env, app config, ADC, native Google
+  credential files, or direct request/session credential overrides as
+  authority. Pass `Gemini.GovernedAuthority` with the authority-selected base
+  URL and materialized credential headers or query params instead.
+
   ## Error Handling
 
   The client provides detailed error information with recovery suggestions:

lib/gemini/client/http.ex

@@ -21,9 +21,24 @@ defmodule Gemini.Client.HTTP do
   alias Gemini.Auth
   alias Gemini.Config
   alias Gemini.Error
+  alias Gemini.GovernedAuthority
   alias Gemini.RateLimiter
   alias Gemini.Telemetry
 
+  @governed_forbidden_options [
+    :auth,
+    :api_key,
+    :project_id,
+    :location,
+    :access_token,
+    :service_account,
+    :service_account_key,
+    :service_account_data,
+    :quota_project_id,
+    :base_url,
+    :headers
+  ]
+
   @vertex_auth_override_keys [
     :project_id,
     :location,
@@ -84,19 +99,24 @@ defmodule Gemini.Client.HTTP do
   - `:max_concurrency_per_model` - Override concurrency limit
   """
   def request(method, path, body, auth_config, opts \\ []) do
-    Config.validate!()
-
     case auth_config do
       nil ->
         {:error, Error.config_error("No authentication configured")}
 
+      %{type: :governed_authority, credentials: %GovernedAuthority{} = authority} ->
+        execute_governed_request(method, path, body, authority, opts)
+
       %{type: auth_type, credentials: credentials} ->
         execute_authenticated_request(method, path, body, auth_type, credentials, opts)
     end
   end
 
   # Execute the actual HTTP request with telemetry
-  defp execute_request(method, url, headers, body, opts) do
+  defp execute_request(method, url, headers, body, opts, validate_config? \\ true) do
+    if validate_config? do
+      Config.validate!()
+    end
+
     start_time = System.monotonic_time()
     metadata = Telemetry.build_request_metadata(url, method, opts)
     measurements = %{system_time: System.system_time()}
@@ -152,16 +172,27 @@ defmodule Gemini.Client.HTTP do
 
   @spec resolve_auth_config(keyword()) :: Config.auth_config() | nil
   defp resolve_auth_config(opts) when is_list(opts) do
-    case normalize_auth_strategy(Keyword.get(opts, :auth)) || infer_auth_strategy(opts) do
+    case Keyword.get(opts, :governed_authority) do
       nil ->
-        Config.auth_config()
+        case normalize_auth_strategy(Keyword.get(opts, :auth)) || infer_auth_strategy(opts) do
+          nil ->
+            Config.auth_config()
 
-      strategy ->
-        credentials =
-          Config.get_auth_config(strategy)
-          |> apply_auth_overrides(strategy, opts)
+          strategy ->
+            credentials =
+              Config.get_auth_config(strategy)
+              |> apply_auth_overrides(strategy, opts)
 
-        %{type: strategy, credentials: credentials}
+            %{type: strategy, credentials: credentials}
+        end
+
+      authority ->
+        validate_governed_request_opts!(opts)
+
+        %{
+          type: :governed_authority,
+          credentials: GovernedAuthority.new!(authority)
+        }
     end
   end
 
@@ -198,6 +229,28 @@ defmodule Gemini.Client.HTTP do
   defp maybe_put_cred(credentials, _key, ""), do: credentials
   defp maybe_put_cred(credentials, key, value), do: Map.put(credentials, key, value)
 
+  defp validate_governed_request_opts!(opts) do
+    case Enum.find(@governed_forbidden_options, &Keyword.has_key?(opts, &1)) do
+      nil ->
+        :ok
+
+      key ->
+        raise ArgumentError, "governed authority forbids unmanaged #{key}"
+    end
+  end
+
+  defp execute_governed_request(method, path, body, authority, opts) do
+    url = build_governed_url(path, authority)
+    headers = GovernedAuthority.headers(authority)
+    model = extract_model_from_path(path)
+
+    request_fn = fn ->
+      execute_request(method, url, headers, body, opts, false)
+    end
+
+    maybe_rate_limited_request(request_fn, model, opts)
+  end
+
   defp execute_authenticated_request(method, path, body, auth_type, credentials, opts) do
     url = build_authenticated_url(auth_type, path, credentials)
 
@@ -250,6 +303,20 @@ defmodule Gemini.Client.HTTP do
     end
   end
 
+  defp build_governed_url(path, %GovernedAuthority{base_url: base_url}) do
+    if String.starts_with?(path, "https://") or String.starts_with?(path, "http://") do
+      raise ArgumentError, "governed authority forbids unmanaged absolute request URLs"
+    end
+
+    normalized_base = String.trim_trailing(base_url, "/")
+
+    if String.starts_with?(path, "/") do
+      normalized_base <> path
+    else
+      normalized_base <> "/" <> path
+    end
+  end
+
   defp build_absolute_url(base_url, absolute_path) do
     uri = URI.parse(base_url)