oidcauthlib 3.0.17__tar.gz → 3.0.19__tar.gz

{oidcauthlib-3.0.17/oidcauthlib.egg-info → oidcauthlib-3.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oidcauthlib
-Version: 3.0.17
+Version: 3.0.19
 Summary: oidcauthlib
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0

oidcauthlib-3.0.19/VERSION

@@ -0,0 +1 @@
+3.0.19

{oidcauthlib-3.0.17 → oidcauthlib-3.0.19}/oidcauthlib/auth/token_reader.py

@@ -26,6 +26,9 @@ from oidcauthlib.auth.exceptions.authorization_bearer_token_missing_exception im
     AuthorizationBearerTokenMissingException,
 )
 from oidcauthlib.auth.models.token import Token
+from oidcauthlib.utilities.environment.oidc_environment_variables import (
+    OidcEnvironmentVariables,
+)
 from oidcauthlib.utilities.logger.log_levels import SRC_LOG_LEVELS
 from oidcauthlib.auth.well_known_configuration.well_known_configuration_manager import (
     WellKnownConfigurationManager,
@@ -61,12 +64,19 @@ class TokenReader:
     - Algorithms used for verification are configurable via the constructor.
     """
 
+    # Class-level default so test doubles that bypass __init__ (a pattern
+    # already used in this test suite, e.g. tests/auth/test_token_reader_audience.py's
+    # _TestTokenReader) still find a usable environment_variables via normal
+    # attribute lookup, instead of raising AttributeError on first access.
+    environment_variables: OidcEnvironmentVariables = OidcEnvironmentVariables()
+
     def __init__(
         self,
         *,
         algorithms: Optional[list[str]] = None,
         auth_config_reader: AuthConfigReader,
         well_known_config_manager: WellKnownConfigurationManager,
+        environment_variables: Optional[OidcEnvironmentVariables] = None,
     ):
         """
         Initialize TokenReader with dependencies and verification settings.
@@ -75,6 +85,8 @@ class TokenReader:
             algorithms: Allowed JWT algorithms for signature verification (e.g., ["RS256"]).
             auth_config_reader: Provider configuration reader used for issuer/audience validation.
             well_known_config_manager: Manager responsible for well-known configs and JWKS retrieval.
+            environment_variables: Source for jwt_clock_skew_leeway_seconds. Defaults to a
+                plain OidcEnvironmentVariables() (reads directly from os.environ) if not given.
         Raises:
             ValueError: If required dependencies or provider configs are missing.
             TypeError: If dependency types do not match expected classes.
@@ -99,6 +111,8 @@ class TokenReader:
         if not isinstance(self._well_known_config_manager, WellKnownConfigurationManager):
             raise TypeError("well_known_config_manager must be an instance of WellKnownConfigurationManager")
 
+        self.environment_variables: OidcEnvironmentVariables = environment_variables or OidcEnvironmentVariables()
+
     @staticmethod
     def extract_token(*, authorization_header: str | None) -> Optional[str]:
         """
@@ -192,6 +206,10 @@ class TokenReader:
         if not token:
             raise ValueError("Token must not be empty")
 
+        # Read outside the try/except below so a misconfigured env var (ValueError)
+        # surfaces as a config error, not a per-request "invalid token" failure.
+        leeway = self.environment_variables.jwt_clock_skew_leeway_seconds
+
         jwks: KeySet = await self._well_known_config_manager.get_jwks_async()
 
         # get kids from jwks for logging
@@ -294,8 +312,11 @@ class TokenReader:
 
             exp_str = to_eastern_time(exp)
             now_str = to_eastern_time(now)
-            # Create claims registry
-            claims_requests = jwt.JWTClaimsRegistry()
+            # Create claims registry. leeway tolerates clock skew between the
+            # token issuer and this process (e.g. a container/VM clock
+            # drifting from its host) -- without it, validate_iat rejects a
+            # token as "issued in the future" on any skew at all.
+            claims_requests = jwt.JWTClaimsRegistry(leeway=leeway)
             claims_requests.validate(verified.claims)
 
             logger.debug(f"Successfully verified token: {token}")
@@ -352,7 +373,8 @@ class TokenReader:
                 verified = jwt.decode(access_token, jwks, algorithms=self.algorithms)
             exp = verified.claims.get("exp")
             now = time.time()
-            if exp and exp < now:
+            leeway = self.environment_variables.jwt_clock_skew_leeway_seconds
+            if exp and exp < now - leeway:
                 logger.warning(f"Token has expired. Exp: {exp}, Now: {now}")
                 return False
             return True

oidcauthlib-3.0.19/oidcauthlib/cache_gate/__init__.py

@@ -0,0 +1,4 @@
+from oidcauthlib.cache_gate.advisory_lock import AdvisoryLock
+from oidcauthlib.cache_gate.version_gate import VersionGate
+
+__all__ = ["AdvisoryLock", "VersionGate"]

oidcauthlib-3.0.19/oidcauthlib/cache_gate/advisory_lock.py

@@ -0,0 +1,168 @@
+"""Staged here pending extraction into a standalone shared-infra package —
+this module has no OIDC-specific logic and doesn't belong in oidc-auth-lib
+long-term; it's here because this is the one package every consumer of
+VersionGate already depends on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import uuid
+from types import TracebackType
+
+from key_value.aio.protocols.key_value import AsyncKeyValueProtocol
+
+logger = logging.getLogger(__name__)
+
+LOCK_COLLECTION = "advisory_locks"
+
+
+class AdvisoryLock:
+    """Distributed advisory lock backed by any AsyncKeyValueProtocol store.
+
+    Uses put-with-TTL so that stale locks auto-expire if the holder crashes.
+    Acquire semantics rely on get-then-put — not atomic compare-and-swap —
+    so there is a small race window. For leader-election among cooperating
+    workers at startup this is acceptable; do not use for high-contention
+    critical sections.
+
+    While held, a background task refreshes the lock's TTL every
+    `heartbeat_interval_seconds` (default `ttl_seconds / 2`) — so `ttl_seconds`
+    only bounds how quickly a *crashed* holder's lock is reclaimed, not how
+    long the guarded critical section may run. Without this, a critical
+    section that legitimately outlives `ttl_seconds` would have its lock
+    entry expire while still running, letting a second holder acquire the
+    same lock and re-enter concurrently — exactly what the lock exists to
+    prevent. A single missed heartbeat is not fatal: it's logged and retried
+    on the next tick, with a full `heartbeat_interval_seconds` of margin
+    before the lock would actually expire.
+
+    Usage:
+        async with AdvisoryLock(store, "skill_sync", ttl_seconds=300) as acquired:
+            if acquired:
+                await do_sync()
+    """
+
+    def __init__(
+        self,
+        store: AsyncKeyValueProtocol,
+        lock_name: str,
+        *,
+        ttl_seconds: int = 300,
+        collection: str = LOCK_COLLECTION,
+        heartbeat_interval_seconds: float | None = None,
+    ) -> None:
+        self._store = store
+        self._lock_name = lock_name
+        self._ttl_seconds = ttl_seconds
+        self._collection = collection
+        self._heartbeat_interval_seconds = heartbeat_interval_seconds or (ttl_seconds / 2)
+        self._holder_id = f"{os.getpid()}-{uuid.uuid4().hex[:8]}"
+        self._acquired = False
+        self._heartbeat_task: asyncio.Task[None] | None = None
+
+    @property
+    def acquired(self) -> bool:
+        return self._acquired
+
+    async def __aenter__(self) -> bool:
+        existing = await self._store.get(self._lock_name, collection=self._collection)
+
+        if existing is not None:
+            logger.info(
+                "AdvisoryLock: lock '%s' held by '%s' — skipping.",
+                self._lock_name,
+                existing.get("holder", "unknown"),
+            )
+            self._acquired = False
+            return False
+
+        await self._store.put(
+            self._lock_name,
+            {"holder": self._holder_id},
+            collection=self._collection,
+            ttl=self._ttl_seconds,
+        )
+
+        # Verify we won the race (read-after-write check)
+        written = await self._store.get(self._lock_name, collection=self._collection)
+        if written is not None and written.get("holder") == self._holder_id:
+            self._acquired = True
+            logger.info(
+                "AdvisoryLock: acquired lock '%s' (holder=%s, ttl=%ds)",
+                self._lock_name,
+                self._holder_id,
+                self._ttl_seconds,
+            )
+            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+        else:
+            self._acquired = False
+            logger.info(
+                "AdvisoryLock: lost race for lock '%s' — another holder won.",
+                self._lock_name,
+            )
+
+        return self._acquired
+
+    async def _heartbeat_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._heartbeat_interval_seconds)
+            try:
+                await self._store.put(
+                    self._lock_name,
+                    {"holder": self._holder_id},
+                    collection=self._collection,
+                    ttl=self._ttl_seconds,
+                )
+                logger.debug(
+                    "AdvisoryLock: refreshed lock '%s' (holder=%s, ttl=%ds)",
+                    self._lock_name,
+                    self._holder_id,
+                    self._ttl_seconds,
+                )
+            except Exception:
+                logger.warning(
+                    "AdvisoryLock: failed to refresh lock '%s' (holder=%s) — will retry "
+                    "in %.1fs; lock still expires in up to %ds if refreshes keep failing.",
+                    self._lock_name,
+                    self._holder_id,
+                    self._heartbeat_interval_seconds,
+                    self._ttl_seconds,
+                    exc_info=True,
+                )
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._heartbeat_task
+            self._heartbeat_task = None
+
+        if self._acquired:
+            try:
+                await self._store.delete(self._lock_name, collection=self._collection)
+                logger.info(
+                    "AdvisoryLock: released lock '%s' (holder=%s)",
+                    self._lock_name,
+                    self._holder_id,
+                )
+            except Exception:
+                # Don't let a failed release mask an exception already propagating
+                # from the caller's critical section. The heartbeat has stopped, so
+                # the lock still self-clears once its TTL elapses.
+                logger.warning(
+                    "AdvisoryLock: failed to release lock '%s' (holder=%s) — it will "
+                    "still expire via TTL in up to %ds.",
+                    self._lock_name,
+                    self._holder_id,
+                    self._ttl_seconds,
+                    exc_info=True,
+                )

oidcauthlib-3.0.19/oidcauthlib/cache_gate/version_gate.py

@@ -0,0 +1,103 @@
+"""Staged here pending extraction into a standalone shared-infra package —
+this module has no OIDC-specific logic and doesn't belong in oidc-auth-lib
+long-term; it's here because this is the one package both current consumers
+(baileyai, baileyai-skills-service) already depend on.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+
+from key_value.aio.protocols.key_value import AsyncKeyValueProtocol
+
+from oidcauthlib.cache_gate.advisory_lock import AdvisoryLock
+
+logger = logging.getLogger(__name__)
+
+VERSION_GATE_COLLECTION = "version_gate"
+
+
+class VersionGate:
+    """Runs an action at most once per distinct version, across a pod fleet.
+
+    Compares `current_version` against a marker persisted in `store`. If it
+    differs, runs `action` and — only once `action` completes without raising
+    — persists the new marker. The marker is written *after* the action
+    succeeds, never before: writing it first would let a crashed/incomplete
+    action look "done" to every other pod, forever, until the version next
+    changes.
+
+    Pass `lock_name` when `action` is not safe to run concurrently from
+    multiple pods (e.g. a multi-step load with partial-write visibility).
+    Omit it when `action` is idempotent under concurrent execution (e.g. a
+    pure cache clear followed by lazy repopulation) — redundant concurrent
+    runs are then harmless and a lock only adds latency/contention.
+    """
+
+    def __init__(
+        self,
+        *,
+        store: AsyncKeyValueProtocol,
+        key: str,
+        collection: str = VERSION_GATE_COLLECTION,
+        lock_name: str | None = None,
+        lock_ttl_seconds: int = 300,
+        lock_heartbeat_interval_seconds: float | None = None,
+    ) -> None:
+        self._store = store
+        self._key = key
+        self._collection = collection
+        self._lock_name = lock_name
+        self._lock_ttl_seconds = lock_ttl_seconds
+        self._lock_heartbeat_interval_seconds = lock_heartbeat_interval_seconds
+
+    async def run_if_changed_async(
+        self,
+        *,
+        current_version: str,
+        action: Callable[[], Awaitable[None]],
+    ) -> bool:
+        """Runs `action` and records `current_version` iff it differs from the
+        stored marker. Returns True iff `action` ran.
+        """
+        if await self._is_current(current_version):
+            return False
+
+        if self._lock_name is None:
+            await action()
+            await self._mark(current_version)
+            return True
+
+        async with AdvisoryLock(
+            self._store,
+            self._lock_name,
+            ttl_seconds=self._lock_ttl_seconds,
+            heartbeat_interval_seconds=self._lock_heartbeat_interval_seconds,
+        ) as acquired:
+            if not acquired:
+                logger.info(
+                    "VersionGate: lock '%s' held by another pod — skipping.",
+                    self._lock_name,
+                )
+                return False
+
+            # Re-check: whoever held the lock before us may have already
+            # handled this version change while we were waiting to acquire.
+            if await self._is_current(current_version):
+                return False
+
+            await action()
+            await self._mark(current_version)
+            return True
+
+    async def _is_current(self, current_version: str) -> bool:
+        stored = await self._store.get(self._key, collection=self._collection)
+        return stored is not None and stored.get("version") == current_version
+
+    async def _mark(self, current_version: str) -> None:
+        await self._store.put(
+            self._key,
+            {"version": current_version},
+            collection=self._collection,
+        )

{oidcauthlib-3.0.17 → oidcauthlib-3.0.19}/oidcauthlib/utilities/environment/oidc_environment_variables.py

@@ -234,3 +234,27 @@ class OidcEnvironmentVariables(AbstractEnvironmentVariables):
             return timeout
         except ValueError:
             raise ValueError("WELL_KNOWN_CONFIG_HTTP_TIMEOUT_SECONDS must be a positive integer representing seconds")
+
+    @property
+    def jwt_clock_skew_leeway_seconds(self) -> int:
+        """Clock-skew tolerance in seconds for JWT iat/exp/nbf claim validation.
+
+        Accounts for clock drift between the token issuer and the process
+        verifying it (e.g. containers on different hosts, or a local dev VM's
+        clock drifting from its host) — applied as joserfc JWTClaimsRegistry's
+        `leeway`. Without this, any skew at all — even sub-second — makes
+        validate_iat reject a token as "issued in the future".
+
+        Set via JWT_CLOCK_SKEW_LEEWAY_SECONDS environment variable.
+        Defaults to 10 seconds.
+
+        Returns:
+            Leeway in seconds
+        """
+        try:
+            leeway = int(os.environ.get("JWT_CLOCK_SKEW_LEEWAY_SECONDS", "10"))
+        except ValueError:
+            raise ValueError("JWT_CLOCK_SKEW_LEEWAY_SECONDS must be a non-negative integer representing seconds")
+        if leeway < 0:
+            raise ValueError("JWT_CLOCK_SKEW_LEEWAY_SECONDS must be a non-negative integer representing seconds")
+        return leeway

{oidcauthlib-3.0.17 → oidcauthlib-3.0.19/oidcauthlib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oidcauthlib
-Version: 3.0.17
+Version: 3.0.19
 Summary: oidcauthlib
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0

{oidcauthlib-3.0.17 → oidcauthlib-3.0.19}/oidcauthlib.egg-info/SOURCES.txt

@@ -55,6 +55,9 @@ oidcauthlib/auth/well_known_configuration/auth_server_metadata_discovery.py
 oidcauthlib/auth/well_known_configuration/well_known_configuration_cache.py
 oidcauthlib/auth/well_known_configuration/well_known_configuration_cache_result.py
 oidcauthlib/auth/well_known_configuration/well_known_configuration_manager.py
+oidcauthlib/cache_gate/__init__.py
+oidcauthlib/cache_gate/advisory_lock.py
+oidcauthlib/cache_gate/version_gate.py
 oidcauthlib/container/__init__.py
 oidcauthlib/container/oidc_authlib_container_factory.py
 oidcauthlib/open_telemetry/__init__.py

oidcauthlib-3.0.17/VERSION

@@ -1 +0,0 @@
-3.0.17