api-dock 0.9.1__tar.gz → 0.10.0__tar.gz

{api_dock-0.9.1 → api_dock-0.10.0}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: api_dock
-Version: 0.9.1
+Version: 0.10.0
 Summary: A flexible API gateway that allows you to proxy requests to multiple remote APIs and Databases
 Author-email: Brookie Guzder-Williams <bguzder-williams@berkeley.edu>
 License-Expression: BSD-3-Clause
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Database
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries
@@ -38,6 +37,8 @@ Requires-Dist: pytest<10,>=9.0.2; extra == "dev"
 Provides-Extra: postgres
 Requires-Dist: psycopg[binary]<4,>=3.3.6; extra == "postgres"
 Requires-Dist: psycopg_pool<4,>=3.3.2; extra == "postgres"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-secret-manager<3,>=2; extra == "gcp"
 Dynamic: license-file
 
 # API Dock
@@ -279,7 +280,7 @@ Publishing a GitHub Release is what publishes to PyPI: `.github/workflows/publis
 
 ```bash
 # 0. Start from a clean, up-to-date main
-export VERSION=0.9.1          # the NEW version, no leading "v"
+export VERSION=0.10.0         # the NEW version, no leading "v"
 git checkout main
 git pull origin main
 git status
@@ -290,7 +291,7 @@ git status
 pixi run -e dev pytest -q
 
 # 3. Commit, tag, push (the commit command adds the "v$VERSION: " prefix)
-export COMMIT_MESSAGE='PostgreSQL, lookups, remotes/config.yaml, numeric latest'
+export COMMIT_MESSAGE='code review fixes: remote cookies, safer SQL building, auth caching'
 git add -A
 git commit -m "v$VERSION: $COMMIT_MESSAGE"
 git tag "v$VERSION"
@@ -301,19 +302,32 @@ git push origin main "v$VERSION"
 gh release create "v$VERSION" \
   --title "v$VERSION" \
   --notes "$(cat <<'EOF'
+**Upgrading:** a remote now receives only the cookies its `cookies:` setting allows (none without it). A remote that relied on the browser's cookies being passed through needs `cookies: [<name>]`, or `cookies: true` for all of them. Configs that set `action`, an unknown version `schema:`, non-boolean `add_trailing_slash`/`follow_redirects`, or a bad `timeout` now stop at startup.
+
 * new features
-    - PostgreSQL tables (`pip install 'api_dock[postgres]'`): named `connections` in `databases/config.yaml` and `{connection, table}` tables. A route runs natively on PostgreSQL when all its tables are on one connection (one pool per connection, read-only transactions, statement timeout), otherwise on DuckDB with PostgreSQL attached read-only, so unions and joins can mix PostgreSQL and Parquet. Route `engine: postgres|duckdb` checks or forces the choice; 503 when a database is unavailable
-    - Lookups: named queries (SQL over any configured table, or an HTTP API) run at startup, every `refresh` and on demand. `from:` entries turn rows into database/versions (with inline schemas) or remote versions, `{{lookup.<name>.<column>}}` fills single values, and `databases: [- from: <lookup>]` serves what they generate. New rows are checked before use; values used as URIs must match `allow:` prefixes. Optional token-protected refresh endpoint (`settings.lookups`) and `api-dock lookups` CLI
-    - `remotes/config.yaml`: define remotes inline (`version`, `versions` or unversioned); mixes with remote files, files win
-    - Slugs can define their schema inline: `schema: {name, tables}`
-    - Database values convert to JSON recursively, including UUIDs, network addresses, intervals and arrays
+    - `api-dock describe` builds the API like `start` (lookups, startup checks) and prints every database/version with expanded route SQL, plus each remote's url
+    - `api-dock init --force` replaces existing files; the whole example tree is copied
+    - `gcp` extra (`pip install 'api_dock[gcp]'`) for GCP Secret Manager authentication
+    - Startup warning when an `authentication` block would be ignored by remote routes
 * bug fixes
-    - `latest` and version lists compare versions numerically (`0.10` > `0.9`, `0.10.0` > `0.9.0`) for remotes and databases; they used to compare as floats or text
+    - Remote cookies: the client's raw `Cookie` header is no longer forwarded; the upstream `Cookie` header is built from the remote's `cookies` setting, so filtering and injected cookies work even when the client sends cookies
+    - Several upstream `Set-Cookie` headers reach the client separately instead of merged into one (new `ProxyResponse.set_cookies`)
+    - Query-param filters join the base query's top-level `WHERE` (strings, comments, CTEs and subqueries ignored), parenthesized and before a trailing `GROUP BY`/`ORDER BY`/`LIMIT`: fixes `WHERE a OR b` letting rows past filters, CTE-only `WHERE`s and base queries ending in `ORDER BY`
+    - `[[table]]` is a table source only right after `FROM`/`JOIN` or a `FROM`-list comma (was any `FROM`/`JOIN` in the previous 20 characters, which broke `ON [[a]].id = [[b]].id`)
+    - `sql_append` values are limited to integers and column names (with `ASC`/`DESC`, `NULLS FIRST/LAST`); the unimplemented `action` (which echoed request values, including cookies) is refused
+    - Authentication providers are built once per config instead of on every request (no secret-store/KMS call per request); `refresh_interval` now refreshes, keeping the last values if a refresh fails; tokens compared in constant time; `aws_tokens_file` works (`aws_key_id` optional)
+    - Remote route mapping fills `{{route_name}}` and `{{cookies.x}}` in `remote_route`, and keeps a query string written there
+    - Include/exclude and listing filters compare versions part by part (`1.10` no longer matches `1.1`)
+    - Values in DuckDB secret SQL (S3 region, GCS keys, HTTP headers) are quoted; a second GCS `service_account` no longer overwrites the process-wide one
+    - A main config that is missing (explicit path), invalid YAML or not a mapping stops startup instead of serving an empty API; settings are validated at startup
+    - An explicit encryption `key_file` must exist (only the default key file falls back to `API_DOCK_ENCRYPTION_KEY`); `env_key` reads only its variable
+    - Remote error responses no longer include internal error text (it's logged); `map_route_sync` no longer leaks event loops
 * cleanup / other improvements
-    - Database queries go through a `DatabaseBackend` interface (`DuckDBBackend`, `PostgresBackend`); the SQL builder takes the backend's bound-value marker
-    - Startup checks also cover PostgreSQL connections, every route's engine, `remotes/config.yaml` and lookup-generated config
-    - Slim README; detailed docs moved to the wiki (https://github.com/SchmidtDSE/api_dock/wiki), including new Concepts, PostgreSQL, Lookups and Developer Guide pages
-    - Test suite grew from 373 to 626 tests (a throwaway PostgreSQL server runs the PostgreSQL tests when available)
+    - `map_database_route` split into named steps; one version-resolution helper for remotes and databases
+    - A remote request reads only that remote's config file (was every remote file, twice)
+    - Removed unused internal functions; shared YAML-loading and version-matching helpers; `follow_protocol_downgrades` (never implemented) removed
+    - FastAPI app reports the package version; classifiers match Python 3.11+; style fixes
+    - Tests grew from 626 to 760, including the first tests for authentication, encryption, config discovery and storage credentials
 EOF
 )"
 

{api_dock-0.9.1 → api_dock-0.10.0}/README.md

@@ -237,7 +237,7 @@ Publishing a GitHub Release is what publishes to PyPI: `.github/workflows/publis
 
 ```bash
 # 0. Start from a clean, up-to-date main
-export VERSION=0.9.1          # the NEW version, no leading "v"
+export VERSION=0.10.0         # the NEW version, no leading "v"
 git checkout main
 git pull origin main
 git status
@@ -248,7 +248,7 @@ git status
 pixi run -e dev pytest -q
 
 # 3. Commit, tag, push (the commit command adds the "v$VERSION: " prefix)
-export COMMIT_MESSAGE='PostgreSQL, lookups, remotes/config.yaml, numeric latest'
+export COMMIT_MESSAGE='code review fixes: remote cookies, safer SQL building, auth caching'
 git add -A
 git commit -m "v$VERSION: $COMMIT_MESSAGE"
 git tag "v$VERSION"
@@ -259,19 +259,32 @@ git push origin main "v$VERSION"
 gh release create "v$VERSION" \
   --title "v$VERSION" \
   --notes "$(cat <<'EOF'
+**Upgrading:** a remote now receives only the cookies its `cookies:` setting allows (none without it). A remote that relied on the browser's cookies being passed through needs `cookies: [<name>]`, or `cookies: true` for all of them. Configs that set `action`, an unknown version `schema:`, non-boolean `add_trailing_slash`/`follow_redirects`, or a bad `timeout` now stop at startup.
+
 * new features
-    - PostgreSQL tables (`pip install 'api_dock[postgres]'`): named `connections` in `databases/config.yaml` and `{connection, table}` tables. A route runs natively on PostgreSQL when all its tables are on one connection (one pool per connection, read-only transactions, statement timeout), otherwise on DuckDB with PostgreSQL attached read-only, so unions and joins can mix PostgreSQL and Parquet. Route `engine: postgres|duckdb` checks or forces the choice; 503 when a database is unavailable
-    - Lookups: named queries (SQL over any configured table, or an HTTP API) run at startup, every `refresh` and on demand. `from:` entries turn rows into database/versions (with inline schemas) or remote versions, `{{lookup.<name>.<column>}}` fills single values, and `databases: [- from: <lookup>]` serves what they generate. New rows are checked before use; values used as URIs must match `allow:` prefixes. Optional token-protected refresh endpoint (`settings.lookups`) and `api-dock lookups` CLI
-    - `remotes/config.yaml`: define remotes inline (`version`, `versions` or unversioned); mixes with remote files, files win
-    - Slugs can define their schema inline: `schema: {name, tables}`
-    - Database values convert to JSON recursively, including UUIDs, network addresses, intervals and arrays
+    - `api-dock describe` builds the API like `start` (lookups, startup checks) and prints every database/version with expanded route SQL, plus each remote's url
+    - `api-dock init --force` replaces existing files; the whole example tree is copied
+    - `gcp` extra (`pip install 'api_dock[gcp]'`) for GCP Secret Manager authentication
+    - Startup warning when an `authentication` block would be ignored by remote routes
 * bug fixes
-    - `latest` and version lists compare versions numerically (`0.10` > `0.9`, `0.10.0` > `0.9.0`) for remotes and databases; they used to compare as floats or text
+    - Remote cookies: the client's raw `Cookie` header is no longer forwarded; the upstream `Cookie` header is built from the remote's `cookies` setting, so filtering and injected cookies work even when the client sends cookies
+    - Several upstream `Set-Cookie` headers reach the client separately instead of merged into one (new `ProxyResponse.set_cookies`)
+    - Query-param filters join the base query's top-level `WHERE` (strings, comments, CTEs and subqueries ignored), parenthesized and before a trailing `GROUP BY`/`ORDER BY`/`LIMIT`: fixes `WHERE a OR b` letting rows past filters, CTE-only `WHERE`s and base queries ending in `ORDER BY`
+    - `[[table]]` is a table source only right after `FROM`/`JOIN` or a `FROM`-list comma (was any `FROM`/`JOIN` in the previous 20 characters, which broke `ON [[a]].id = [[b]].id`)
+    - `sql_append` values are limited to integers and column names (with `ASC`/`DESC`, `NULLS FIRST/LAST`); the unimplemented `action` (which echoed request values, including cookies) is refused
+    - Authentication providers are built once per config instead of on every request (no secret-store/KMS call per request); `refresh_interval` now refreshes, keeping the last values if a refresh fails; tokens compared in constant time; `aws_tokens_file` works (`aws_key_id` optional)
+    - Remote route mapping fills `{{route_name}}` and `{{cookies.x}}` in `remote_route`, and keeps a query string written there
+    - Include/exclude and listing filters compare versions part by part (`1.10` no longer matches `1.1`)
+    - Values in DuckDB secret SQL (S3 region, GCS keys, HTTP headers) are quoted; a second GCS `service_account` no longer overwrites the process-wide one
+    - A main config that is missing (explicit path), invalid YAML or not a mapping stops startup instead of serving an empty API; settings are validated at startup
+    - An explicit encryption `key_file` must exist (only the default key file falls back to `API_DOCK_ENCRYPTION_KEY`); `env_key` reads only its variable
+    - Remote error responses no longer include internal error text (it's logged); `map_route_sync` no longer leaks event loops
 * cleanup / other improvements
-    - Database queries go through a `DatabaseBackend` interface (`DuckDBBackend`, `PostgresBackend`); the SQL builder takes the backend's bound-value marker
-    - Startup checks also cover PostgreSQL connections, every route's engine, `remotes/config.yaml` and lookup-generated config
-    - Slim README; detailed docs moved to the wiki (https://github.com/SchmidtDSE/api_dock/wiki), including new Concepts, PostgreSQL, Lookups and Developer Guide pages
-    - Test suite grew from 373 to 626 tests (a throwaway PostgreSQL server runs the PostgreSQL tests when available)
+    - `map_database_route` split into named steps; one version-resolution helper for remotes and databases
+    - A remote request reads only that remote's config file (was every remote file, twice)
+    - Removed unused internal functions; shared YAML-loading and version-matching helpers; `follow_protocol_downgrades` (never implemented) removed
+    - FastAPI app reports the package version; classifiers match Python 3.11+; style fixes
+    - Tests grew from 626 to 760, including the first tests for authentication, encryption, config discovery and storage credentials
 EOF
 )"
 

{api_dock-0.9.1 → api_dock-0.10.0}/api_dock/auth.py

@@ -11,12 +11,16 @@ License: BSD 3-Clause
 #
 # IMPORTS
 #
+import hmac
 import json
+import logging
+import os
+import threading
 import time
-from abc import ABC, abstractmethod
+from abc import ABC
 from typing import Any, Dict, List, Optional, Tuple, Union
 
-from api_dock.encryption import create_encryption_provider, decrypt_value_if_needed, EncryptionError
+from api_dock.encryption import decrypt_value_if_needed, EncryptionError
 
 
 #
@@ -25,6 +29,24 @@ from api_dock.encryption import create_encryption_provider, decrypt_value_if_nee
 DEFAULT_CACHE_TTL: int = 300  # 5 minutes
 DEFAULT_STATUS_CODE: int = 401
 
+# Keys that choose the authentication method; exactly one must be present.
+# (`aws_key_id` is an optional detail of the KMS methods, not a method.)
+METHOD_KEYS: Tuple[str, ...] = (
+    "value", "values", "filepath", "aws_secret_name", "aws_tokens", "aws_tokens_file",
+    "gcp_project_id",
+)
+
+# Settings that name a file whose contents a provider reads at creation.
+FILE_KEYS: Tuple[str, ...] = ("filepath", "aws_tokens_file")
+
+# At most this many providers are cached (one per distinct auth config).
+PROVIDER_CACHE_SIZE: int = 64
+
+logger = logging.getLogger(__name__)
+
+_PROVIDERS: Dict[str, "AuthenticationProvider"] = {}
+_PROVIDERS_LOCK = threading.Lock()
+
 
 #
 # PUBLIC
@@ -40,20 +62,28 @@ class AuthenticationProvider(ABC):
         """
         self.failed_response_config = failed_response or {}
 
-
     def validate(self, token: str) -> bool:
-        """Validate token against a set of valid tokens with string normalization.
+        """Check a token against the expected values, in constant time per value.
 
         Args:
             token: Token to validate.
-            valid_tokens: Set of valid tokens.
 
         Returns:
             True if token is valid, False otherwise.
         """
-        normalized_tokens = self._normalize_token_set(self.expected_values)
-        return str(token) in normalized_tokens
+        candidate = str(token).encode()
+        matched = False
+        for expected in self._normalize_token_set(self.current_values()):
+            matched |= hmac.compare_digest(candidate, expected.encode())
+        return matched
 
+    def current_values(self) -> set:
+        """The values tokens are checked against (secret stores refresh them).
+
+        Returns:
+            The expected values.
+        """
+        return set(self.expected_values)
 
     def get_failed_response(self) -> Tuple[int, Any]:
         """Get the response to return when authentication fails.
@@ -85,7 +115,9 @@ class AuthenticationProvider(ABC):
 class FixedValueAuth(AuthenticationProvider):
     """Authentication using a single fixed value."""
 
-    def __init__(self, value: str, encrypted: bool = True, encryption_config: Optional[Dict[str, Any]] = None, failed_response: Optional[Dict[str, Any]] = None):
+    def __init__(self, value: str, encrypted: bool = True,
+                 encryption_config: Optional[Dict[str, Any]] = None,
+                 failed_response: Optional[Dict[str, Any]] = None):
         """Initialize fixed value authentication.
 
         Args:
@@ -108,7 +140,9 @@ class FixedValueAuth(AuthenticationProvider):
 class ListValueAuth(AuthenticationProvider):
     """Authentication using a list of allowed values."""
 
-    def __init__(self, values: List[Union[str, Dict[str, Any]]], encrypted: bool = True, encryption_config: Optional[Dict[str, Any]] = None, failed_response: Optional[Dict[str, Any]] = None):
+    def __init__(self, values: List[Union[str, Dict[str, Any]]], encrypted: bool = True,
+                 encryption_config: Optional[Dict[str, Any]] = None,
+                 failed_response: Optional[Dict[str, Any]] = None):
         """Initialize list value authentication.
 
         Args:
@@ -134,7 +168,9 @@ class ListValueAuth(AuthenticationProvider):
                     # Dict format with individual encryption setting
                     value_str = value_item.get("value", "")
                     value_encrypted = value_item.get("encrypted", encrypted)
-                    decrypted = decrypt_value_if_needed(value_str, value_encrypted, encryption_config)
+                    decrypted = decrypt_value_if_needed(
+                        value_str, value_encrypted, encryption_config
+                    )
                     self.expected_values.add(str(decrypted))
                 else:
                     raise AuthenticationError(f"Invalid value format: {type(value_item)}")
@@ -145,7 +181,9 @@ class ListValueAuth(AuthenticationProvider):
 class FileAuth(AuthenticationProvider):
     """Authentication using values from a text file (one value per line)."""
 
-    def __init__(self, filepath: str, encrypted: bool = True, encryption_config: Optional[Dict[str, Any]] = None, failed_response: Optional[Dict[str, Any]] = None):
+    def __init__(self, filepath: str, encrypted: bool = True,
+                 encryption_config: Optional[Dict[str, Any]] = None,
+                 failed_response: Optional[Dict[str, Any]] = None):
         """Initialize file-based authentication.
 
         Args:
@@ -171,7 +209,9 @@ class FileAuth(AuthenticationProvider):
                         decrypted = decrypt_value_if_needed(line, encrypted, encryption_config)
                         self.expected_values.add(str(decrypted))
                     except EncryptionError as e:
-                        raise AuthenticationError(f"Failed to decrypt value on line {line_num} in '{filepath}': {str(e)}")
+                        raise AuthenticationError(
+                            f"Failed to decrypt value on line {line_num} in '{filepath}': {e}"
+                        )
         except FileNotFoundError:
             raise AuthenticationError(f"Authentication file not found: {filepath}")
         except IOError as e:
@@ -181,7 +221,9 @@ class FileAuth(AuthenticationProvider):
 class AWSSecretsAuth(AuthenticationProvider):
     """Authentication using AWS Secrets Manager."""
 
-    def __init__(self, secret_name: str, region: str = "us-west-2", cache_ttl: int = DEFAULT_CACHE_TTL, failed_response: Optional[Dict[str, Any]] = None):
+    def __init__(self, secret_name: str, region: str = "us-west-2",
+                 cache_ttl: int = DEFAULT_CACHE_TTL,
+                 failed_response: Optional[Dict[str, Any]] = None):
         """Initialize AWS Secrets authentication.
 
         Args:
@@ -218,6 +260,22 @@ class AWSSecretsAuth(AuthenticationProvider):
         self._cache_time = 0
         self.expected_values = self._get_cached_tokens()
 
+    def current_values(self) -> set:
+        """The secret's values, re-read once ``refresh_interval`` has passed.
+
+        A failed refresh keeps the last values (and is logged), so a secret
+        store outage doesn't lock everyone out.
+
+        Returns:
+            The expected values.
+        """
+        try:
+            self.expected_values = self._get_cached_tokens()
+        except AuthenticationError as error:
+            logger.warning("Refreshing authentication values failed; using the last ones: %s",
+                           error)
+            self._cache_time = time.time()
+        return set(self.expected_values)
 
     def _get_cached_tokens(self) -> set:
         """Get authentication tokens from cache or refresh from AWS."""
@@ -268,13 +326,17 @@ class AWSSecretsAuth(AuthenticationProvider):
 class AWSKMSAuth(AuthenticationProvider):
     """Authentication using AWS KMS for encrypted tokens."""
 
-    def __init__(self, tokens: Optional[List[str]] = None, aws_tokens_file: Optional[str] = None, aws_key_id: str = None, aws_region: str = "us-west-2", failed_response: Optional[Dict[str, Any]] = None):
+    def __init__(self, tokens: Optional[List[str]] = None,
+                 aws_tokens_file: Optional[str] = None, aws_key_id: Optional[str] = None,
+                 aws_region: str = "us-west-2",
+                 failed_response: Optional[Dict[str, Any]] = None):
         """Initialize AWS KMS authentication.
 
         Args:
             tokens: List of encrypted tokens (for inline configuration).
             aws_tokens_file: Path to file containing encrypted tokens (one per line).
-            aws_key_id: AWS KMS key ID or ARN.
+            aws_key_id: AWS KMS key ID or ARN (optional: KMS finds the key from
+                the ciphertext; kept for reference).
             aws_region: AWS region.
             failed_response: Custom response for failed authentication.
 
@@ -342,7 +404,6 @@ class AWSKMSAuth(AuthenticationProvider):
         except IOError as e:
             raise AuthenticationError(f"Failed to read AWS KMS tokens file '{filepath}': {str(e)}")
 
-
     def _decrypt_token(self, encrypted_token: str) -> str:
         """Decrypt a single token using AWS KMS."""
         try:
@@ -363,7 +424,9 @@ class AWSKMSAuth(AuthenticationProvider):
 class GCPSecretsAuth(AuthenticationProvider):
     """Authentication using GCP Secret Manager."""
 
-    def __init__(self, project_id: str, secret_name: str, version: str = "latest", cache_ttl: int = DEFAULT_CACHE_TTL, failed_response: Optional[Dict[str, Any]] = None):
+    def __init__(self, project_id: str, secret_name: str, version: str = "latest",
+                 cache_ttl: int = DEFAULT_CACHE_TTL,
+                 failed_response: Optional[Dict[str, Any]] = None):
         """Initialize GCP Secrets authentication.
 
         Args:
@@ -380,7 +443,10 @@ class GCPSecretsAuth(AuthenticationProvider):
             from google.cloud import secretmanager
             from google.auth.exceptions import DefaultCredentialsError
         except ImportError:
-            raise AuthenticationError("google-cloud-secret-manager package is required for GCP Secrets authentication")
+            raise AuthenticationError(
+                "GCP Secrets authentication needs google-cloud-secret-manager: "
+                "pip install 'api_dock[gcp]'"
+            )
 
         super().__init__(failed_response)
 
@@ -405,6 +471,22 @@ class GCPSecretsAuth(AuthenticationProvider):
         self._cache_time = 0
         self.expected_values = self._get_cached_tokens()
 
+    def current_values(self) -> set:
+        """The secret's values, re-read once ``refresh_interval`` has passed.
+
+        A failed refresh keeps the last values (and is logged), so a secret
+        store outage doesn't lock everyone out.
+
+        Returns:
+            The expected values.
+        """
+        try:
+            self.expected_values = self._get_cached_tokens()
+        except AuthenticationError as error:
+            logger.warning("Refreshing authentication values failed; using the last ones: %s",
+                           error)
+            self._cache_time = time.time()
+        return set(self.expected_values)
 
     def _get_cached_tokens(self) -> set:
         """Get authentication tokens from cache or refresh from GCP."""
@@ -442,7 +524,9 @@ class GCPSecretsAuth(AuthenticationProvider):
             return self._cached_values
 
         except Exception as e:
-            raise AuthenticationError(f"Failed to retrieve GCP secret '{self.secret_name}': {str(e)}")
+            raise AuthenticationError(
+                f"Failed to retrieve GCP secret '{self.secret_name}': {e}"
+            )
 
 
 class AuthenticationError(Exception):
@@ -467,28 +551,21 @@ def create_authentication_provider(config: Dict[str, Any]) -> AuthenticationProv
     encryption_config = config.get("encryption")
     encrypted = config.get("encrypted", True)
 
-    # Identify authentication method keys
-    method_keys = []
-    if "value" in config:
-        method_keys.append("value")
-    if "values" in config:
-        method_keys.append("values")
-    if "filepath" in config:
-        method_keys.append("filepath")
-    if "aws_secret_name" in config:
-        method_keys.append("aws_secret_name")
-    if "aws_key_id" in config:
-        method_keys.append("aws_key_id")
-    if "aws_tokens_file" in config:
-        method_keys.append("aws_tokens_file")
-    if "gcp_project_id" in config:
-        method_keys.append("gcp_project_id")
-
-    # Validate exactly one method key is present
-    if len(method_keys) == 0:
-        raise AuthenticationError("Authentication configuration must specify exactly one of: value, values, filepath, aws_secret_name, aws_key_id, aws_tokens_file, or gcp_project_id")
-    elif len(method_keys) > 1:
-        raise AuthenticationError(f"Authentication configuration has conflicting method keys: {', '.join(method_keys)}. Only one is allowed.")
+    method_keys = [key for key in METHOD_KEYS if key in config]
+    if not method_keys:
+        if "aws_key_id" in config:
+            raise AuthenticationError(
+                "AWS KMS authentication needs 'aws_tokens' (a list) or 'aws_tokens_file' "
+                "alongside 'aws_key_id'"
+            )
+        raise AuthenticationError(
+            f"Authentication configuration must specify exactly one of: {', '.join(METHOD_KEYS)}"
+        )
+    if len(method_keys) > 1:
+        raise AuthenticationError(
+            f"Authentication configuration has conflicting method keys: "
+            f"{', '.join(method_keys)}. Only one is allowed."
+        )
 
     method_key = method_keys[0]
 
@@ -513,29 +590,28 @@ def create_authentication_provider(config: Dict[str, Any]) -> AuthenticationProv
         cache_ttl = config.get("refresh_interval", DEFAULT_CACHE_TTL)
         return AWSSecretsAuth(secret_name, region, cache_ttl, failed_response)
 
-    elif method_key == "aws_key_id":
-        aws_key_id = config.get("aws_key_id")
+    elif method_key == "aws_tokens":
         tokens = config.get("aws_tokens")
         if not tokens or not isinstance(tokens, list):
-            raise AuthenticationError("AWS KMS authentication requires both 'aws_key_id' and 'aws_tokens' list")
-
+            raise AuthenticationError("'aws_tokens' must be a non-empty list of encrypted tokens")
         region = config.get("aws_region", "us-west-2")
-        return AWSKMSAuth(tokens=tokens, aws_key_id=aws_key_id, aws_region=region, failed_response=failed_response)
+        return AWSKMSAuth(tokens=tokens, aws_key_id=config.get("aws_key_id"), aws_region=region,
+                          failed_response=failed_response)
 
     elif method_key == "aws_tokens_file":
         aws_key_id = config.get("aws_key_id")
-        if not aws_key_id:
-            raise AuthenticationError("AWS KMS file authentication requires both 'aws_tokens_file' and 'aws_key_id'")
-
         aws_tokens_file = config.get("aws_tokens_file")
         region = config.get("aws_region", "us-west-2")
-        return AWSKMSAuth(aws_tokens_file=aws_tokens_file, aws_key_id=aws_key_id, aws_region=region, failed_response=failed_response)
+        return AWSKMSAuth(aws_tokens_file=aws_tokens_file, aws_key_id=aws_key_id,
+                          aws_region=region, failed_response=failed_response)
 
     elif method_key == "gcp_project_id":
         project_id = config.get("gcp_project_id")
         secret_name = config.get("gcp_secret_name")
         if not secret_name:
-            raise AuthenticationError("GCP Secrets authentication requires both 'gcp_project_id' and 'gcp_secret_name'")
+            raise AuthenticationError(
+                "GCP Secrets authentication requires both 'gcp_project_id' and 'gcp_secret_name'"
+            )
 
         version = config.get("gcp_version", "latest")
         cache_ttl = config.get("refresh_interval", DEFAULT_CACHE_TTL)
@@ -545,7 +621,40 @@ def create_authentication_provider(config: Dict[str, Any]) -> AuthenticationProv
         raise AuthenticationError(f"Unknown authentication method key: {method_key}")
 
 
-def validate_authentication(cookies: Dict[str, str], auth_config: Dict[str, Any]) -> Tuple[bool, Optional[int], Optional[Any]]:
+def get_authentication_provider(config: Dict[str, Any]) -> AuthenticationProvider:
+    """The provider for an auth config, built once and then reused.
+
+    Providers are cached by the config's contents (and the modification time
+    of a token file it names), so secret-store and KMS lookups happen when a
+    provider is built (and on its refresh interval), not on every request. A
+    changed config or token file builds a new provider.
+
+    Args:
+        config: Authentication configuration dictionary.
+
+    Returns:
+        The provider.
+
+    Raises:
+        AuthenticationError: If the configuration is invalid or the provider
+            can't be built.
+    """
+    key = _provider_cache_key(config)
+    with _PROVIDERS_LOCK:
+        provider = _PROVIDERS.get(key)
+    if provider is not None:
+        return provider
+    provider = create_authentication_provider(config)
+    with _PROVIDERS_LOCK:
+        if len(_PROVIDERS) >= PROVIDER_CACHE_SIZE:
+            _PROVIDERS.clear()
+        _PROVIDERS[key] = provider
+    return provider
+
+
+def validate_authentication(
+        cookies: Dict[str, str],
+        auth_config: Dict[str, Any]) -> Tuple[bool, Optional[int], Optional[Any]]:
     """Validate authentication using cookies and configuration.
 
     Args:
@@ -565,16 +674,12 @@ def validate_authentication(cookies: Dict[str, str], auth_config: Dict[str, Any]
         auth_key = auth_config.get("key")
         if not auth_key:
             raise AuthenticationError("Authentication configuration missing 'key' field")
-        # Get the token from cookies
+        provider = get_authentication_provider(auth_config)
         auth_token = cookies.get(auth_key)
         if not auth_token:
-            # Token not provided - create provider to get proper error response
-            provider = create_authentication_provider(auth_config)
             status_code, response_body = provider.get_failed_response()
             return (False, status_code, response_body)
 
-        # Create authentication provider and validate
-        provider = create_authentication_provider(auth_config)
         is_valid = provider.validate(auth_token)
 
         if is_valid:
@@ -585,4 +690,27 @@ def validate_authentication(cookies: Dict[str, str], auth_config: Dict[str, Any]
     except AuthenticationError:
         raise
     except Exception as e:
-        raise AuthenticationError(f"Authentication validation failed: {str(e)}")
+        raise AuthenticationError(f"Authentication validation failed: {str(e)}")
+
+
+#
+# INTERNAL
+#
+def _provider_cache_key(config: Dict[str, Any]) -> str:
+    """A cache key for an auth config: its contents plus named files' mtimes.
+
+    Args:
+        config: Authentication configuration dictionary.
+
+    Returns:
+        The key.
+    """
+    files = {}
+    for key in FILE_KEYS:
+        path = config.get(key)
+        if isinstance(path, str):
+            try:
+                files[key] = os.stat(path).st_mtime_ns
+            except OSError:
+                files[key] = None
+    return json.dumps({"config": config, "files": files}, sort_keys=True, default=str)