nui-lambda-shared-utils 1.2.0__tar.gz → 1.2.2__tar.gz

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/CLAUDE.md

@@ -182,16 +182,33 @@ python -m twine upload dist/*
 
 ## Configuration Patterns
 
+### Credential Resolution
+
+Clients resolve credentials in this order (first match wins):
+
+1. **Explicit `credentials` dict** — constructor param, skips everything else
+2. **Environment variables** — per-client patterns, skips Secrets Manager
+3. **AWS Secrets Manager** — default behavior
+
 ### Environment Variables
 
-The package expects these environment variables for runtime configuration:
+Runtime configuration:
 
 - `ES_HOST` - Elasticsearch endpoint
 - `ES_CREDENTIALS_SECRET` - AWS secret name for ES credentials
-- `DB_CREDENTIALS_SECRET` - AWS secret name for database credentials  
+- `DB_CREDENTIALS_SECRET` - AWS secret name for database credentials
 - `SLACK_CREDENTIALS_SECRET` - AWS secret name for Slack token
 - `AWS_REGION` - AWS region for services
 
+Direct credential env vars (bypass Secrets Manager when set):
+
+| Client | Required | Optional |
+|--------|----------|----------|
+| Slack | `SLACK_BOT_TOKEN` | `SLACK_WEBHOOK_URL` |
+| Elasticsearch | `ES_PASSWORD` | `ES_USERNAME` (default: `elastic`) |
+| Database (MySQL) | `DB_HOST` + `DB_PASSWORD` | `DB_PORT` (3306), `DB_USERNAME` (root), `DB_DATABASE` (app) |
+| Database (PostgreSQL) | `DB_HOST` + `DB_PASSWORD` | `DB_PORT` (5432), `DB_USERNAME` (postgres), `DB_DATABASE` (postgres) |
+
 ### AWS Secrets Format
 
 Secrets should follow standardized JSON structures:
@@ -212,15 +229,16 @@ Secrets should follow standardized JSON structures:
 ```python
 import nui_lambda_shared_utils as nui
 
-# Configure specific settings
+# Pass credentials directly (no Secrets Manager needed)
+slack = nui.SlackClient(credentials={"bot_token": "xoxb-..."})
+es = nui.ElasticsearchClient(credentials={"username": "elastic", "password": "pass"})
+db = nui.DatabaseClient(credentials={"host": "localhost", "port": 3306, "username": "root", "password": "pass", "database": "app"})
+
+# Or configure globally
 nui.configure(
     es_host="localhost:9200",
     slack_credentials_secret="dev/slack-token"
 )
-
-# Or use Config object
-config = nui.Config(es_host="prod:9200")
-nui.set_config(config)
 ```
 
 ## Common Usage Patterns

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-lambda-shared-utils
-Version: 1.2.0
+Version: 1.2.2
 Summary: Enterprise-grade utilities for AWS Lambda functions with Slack, Elasticsearch, and monitoring integrations
 Home-page: https://github.com/nuimarkets/nui-lambda-shared-utils
 Author: NUI Markets

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/docs/getting-started/configuration.md

@@ -10,6 +10,14 @@ The package uses a hierarchical configuration system with the following priority
 2. **Environment Variables** - System environment variables
 3. **Configuration Defaults** - Package default values
 
+### Credential Resolution Precedence
+
+All clients (Slack, Elasticsearch, Database) resolve credentials in this order:
+
+1. **Explicit `credentials` dict** - Passed to constructor, skips everything else
+2. **Credential environment variables** - Per-client env vars, skips Secrets Manager
+3. **AWS Secrets Manager** - Default behavior (unchanged)
+
 ## Environment Variables
 
 ### Core Configuration
@@ -34,19 +42,60 @@ The package supports alternative environment variable names for compatibility:
 | `DB_CREDENTIALS_SECRET` | `DATABASE_CREDENTIALS_SECRET` |
 | `AWS_REGION` | `AWS_DEFAULT_REGION` |
 
+### Credential Environment Variables
+
+These environment variables provide credentials directly, bypassing AWS Secrets Manager:
+
+#### Slack
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SLACK_BOT_TOKEN` | Yes (triggers env var path) | - |
+| `SLACK_WEBHOOK_URL` | No | - |
+
+#### Elasticsearch
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `ES_PASSWORD` | Yes (triggers env var path) | - |
+| `ES_USERNAME` | No | `elastic` |
+
+#### Database (MySQL)
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `DB_HOST` | Yes (both required) | - |
+| `DB_PASSWORD` | Yes (both required) | - |
+| `DB_PORT` | No | `3306` |
+| `DB_USERNAME` | No | `root` |
+| `DB_DATABASE` | No | `app` |
+
+#### Database (PostgreSQL)
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `DB_HOST` | Yes (both required) | - |
+| `DB_PASSWORD` | Yes (both required) | - |
+| `DB_PORT` | No | `5432` |
+| `DB_USERNAME` | No | `postgres` |
+| `DB_DATABASE` | No | `postgres` |
+
 ### Example Environment Setup
 
 ```bash
-# Basic configuration
+# Secrets Manager configuration (default)
 export ES_HOST="prod-elasticsearch:9200"
 export ES_CREDENTIALS_SECRET="prod/elasticsearch-creds"
 export DB_CREDENTIALS_SECRET="prod/database-creds"
 export SLACK_CREDENTIALS_SECRET="prod/slack-token"
 export AWS_REGION="us-west-2"
 
-# Alternative names (equivalent)
-export ELASTICSEARCH_HOST="prod-elasticsearch:9200"
-export DATABASE_CREDENTIALS_SECRET="prod/database-creds"
+# Direct credentials (bypass Secrets Manager)
+export SLACK_BOT_TOKEN="xoxb-your-token"
+export ES_PASSWORD="your-password"
+export DB_HOST="localhost"
+export DB_PASSWORD="your-password"
+export DB_DATABASE="mydb"
 ```
 
 ## Programmatic Configuration
@@ -186,9 +235,21 @@ aws secretsmanager create-secret \
 4. Enter the JSON values as key-value pairs
 5. Name the secret according to your configuration
 
-### Secret Access Patterns
+### Credential Access Patterns
 
-#### Automatic Credential Loading
+#### Direct Credentials (No AWS Required)
+
+```python
+# Pass credentials directly — Secrets Manager is never called
+slack = nui.SlackClient(credentials={"bot_token": "xoxb-your-token"})
+es = nui.ElasticsearchClient(credentials={"username": "elastic", "password": "secret"})
+db = nui.DatabaseClient(credentials={
+    "host": "localhost", "port": 3306,
+    "username": "root", "password": "secret", "database": "mydb"
+})
+```
+
+#### Automatic Credential Loading (Secrets Manager)
 
 ```python
 # Credentials are automatically loaded based on configuration
@@ -197,7 +258,7 @@ db = nui.DatabaseClient()       # Uses DB_CREDENTIALS_SECRET
 slack = nui.SlackClient()       # Uses SLACK_CREDENTIALS_SECRET
 ```
 
-#### Override Credential Sources
+#### Override Secret Names
 
 ```python
 # Override default secret names
@@ -223,7 +284,17 @@ api_keys = nui.get_secret("my-service/api-keys")
 ### Development Environment
 
 ```python
-# Development configuration
+# Option 1: Direct credentials (no AWS needed)
+slack = nui.SlackClient(credentials={"bot_token": "xoxb-dev-token"})
+db = nui.DatabaseClient(credentials={
+    "host": "localhost", "port": 3306,
+    "username": "root", "password": "dev", "database": "app_dev"
+})
+
+# Option 2: Environment variables (set SLACK_BOT_TOKEN, DB_HOST, DB_PASSWORD, etc.)
+slack = nui.SlackClient()  # picks up SLACK_BOT_TOKEN from env
+
+# Option 3: Secrets Manager
 nui.configure(
     es_host="localhost:9200",
     es_credentials_secret="dev/elasticsearch",

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/nui_lambda_shared_utils/__init__.py

@@ -137,6 +137,7 @@ try:
     from .jwt_auth import (
         validate_jwt,
         require_auth,
+        check_auth,
         get_jwt_public_key,
         JWTValidationError,
         AuthenticationError,
@@ -144,6 +145,7 @@ try:
 except ImportError:
     validate_jwt = None  # type: ignore
     require_auth = None  # type: ignore
+    check_auth = None  # type: ignore
     get_jwt_public_key = None  # type: ignore
     JWTValidationError = None  # type: ignore
     AuthenticationError = None  # type: ignore
@@ -243,6 +245,7 @@ __all__ = [
     # JWT authentication
     "validate_jwt",
     "require_auth",
+    "check_auth",
     "get_jwt_public_key",
     "JWTValidationError",
     "AuthenticationError",

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/nui_lambda_shared_utils/base_client.py

@@ -23,25 +23,32 @@ class BaseClient(ABC):
     """
 
     def __init__(
-        self, 
+        self,
         secret_name: Optional[str] = None,
         config_key_prefix: Optional[str] = None,
+        credentials: Optional[Dict[str, Any]] = None,
         **kwargs
     ):
         """
         Initialize base client with standardized credential and config resolution.
-        
+
+        Credential resolution precedence:
+        1. Explicit ``credentials`` dict — skip everything else
+        2. Environment variables (per-client patterns) — skip Secrets Manager
+        3. Secrets Manager (existing behavior) — unchanged
+
         Args:
             secret_name: Override secret name for credentials
             config_key_prefix: Prefix for config keys (e.g., 'slack', 'es', 'db')
+            credentials: Direct credentials dict, bypasses Secrets Manager entirely
             **kwargs: Additional client-specific parameters
         """
         self.config = get_config()
         self.config_key_prefix = config_key_prefix or self._get_default_config_prefix()
-        
+
         # Resolve and store credentials
-        self.credentials = self._resolve_credentials(secret_name)
-        
+        self.credentials = self._resolve_credentials(secret_name, credentials)
+
         # Store additional configuration
         self.client_config = kwargs
         
@@ -72,18 +79,66 @@ class BaseClient(ABC):
         """Return the default secret name for this client type."""
         pass
 
-    def _resolve_credentials(self, secret_name: Optional[str]) -> Dict[str, Any]:
+    def _resolve_credentials_from_env(self) -> Optional[Dict[str, Any]]:
+        """
+        Resolve credentials from environment variables.
+
+        Subclasses override this to check client-specific env vars
+        (e.g. SLACK_BOT_TOKEN, ES_PASSWORD).  Return a credentials dict
+        if the required env vars are present, or ``None`` to fall through
+        to Secrets Manager.
+
+        Returns:
+            Credentials dict or None
+        """
+        return None
+
+    def _resolve_credentials(
+        self,
+        secret_name: Optional[str],
+        explicit_credentials: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
         """
         Resolve credentials using standardized precedence.
-        
+
+        Precedence:
+        1. Explicit credentials dict (constructor param)
+        2. Environment variables (per-client ``_resolve_credentials_from_env``)
+        3. AWS Secrets Manager (via ``_fetch_credentials_from_sm``)
+
         Args:
             secret_name: Optional override for secret name
-            
+            explicit_credentials: Direct credentials dict from constructor
+
         Returns:
             Dictionary containing resolved credentials
         """
-        # Determine secret name with precedence
-        resolved_secret_name = resolve_config_value(
+        # 1. Explicit credentials dict — skip everything
+        if explicit_credentials is not None:
+            log.debug("Using explicitly provided credentials")
+            return explicit_credentials
+
+        # 2. Environment variables — skip Secrets Manager
+        env_credentials = self._resolve_credentials_from_env()
+        if env_credentials is not None:
+            log.debug("Using credentials from environment variables")
+            return env_credentials
+
+        # 3. Secrets Manager
+        return self._fetch_credentials_from_sm(secret_name)
+
+    def _resolve_secret_name(self, secret_name: Optional[str]) -> str:
+        """
+        Resolve the Secrets Manager secret name using standard precedence:
+        explicit param > env var > config default.
+
+        Args:
+            secret_name: Optional explicit override
+
+        Returns:
+            Resolved secret name string
+        """
+        resolved = resolve_config_value(
             secret_name,
             [
                 f"{self.config_key_prefix.upper()}_CREDENTIALS_SECRET",
@@ -91,10 +146,24 @@ class BaseClient(ABC):
             ],
             getattr(self.config, f"{self.config_key_prefix}_credentials_secret", self._get_default_secret_name())
         )
-        
-        validate_required_param(resolved_secret_name, "secret_name")
-        
-        # Retrieve and return credentials
+        validate_required_param(resolved, "secret_name")
+        return resolved
+
+    def _fetch_credentials_from_sm(self, secret_name: Optional[str]) -> Dict[str, Any]:
+        """
+        Fetch credentials from AWS Secrets Manager.
+
+        Subclasses override this to customize the SM fetch (e.g. DB clients
+        use ``get_database_credentials`` for field normalization).
+
+        Args:
+            secret_name: Optional override for secret name
+
+        Returns:
+            Dictionary containing resolved credentials
+        """
+        resolved_secret_name = self._resolve_secret_name(secret_name)
+
         try:
             credentials = get_secret(resolved_secret_name)
             log.debug(f"Retrieved credentials from secret: {resolved_secret_name}")

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/nui_lambda_shared_utils/db_client.py

@@ -2,6 +2,7 @@
 Refactored Database client using BaseClient for DRY code patterns.
 """
 
+import os
 import time
 import logging
 from typing import Dict, List, Optional, Any
@@ -120,23 +121,26 @@ class DatabaseClient(BaseClient, ServiceHealthMixin):
         use_pool: bool = True,
         pool_size: int = 5,
         pool_recycle: int = 3600,
+        credentials: Optional[Dict[str, Any]] = None,
         **kwargs
     ):
         """
         Initialize database client.
-        
+
         Args:
             secret_name: Override secret name
             use_pool: Enable connection pooling
             pool_size: Maximum pooled connections
             pool_recycle: Recycle connections after seconds
+            credentials: Direct credentials dict (keys: host, port, username, password, database),
+                bypasses Secrets Manager
             **kwargs: Additional configuration
         """
         self.use_pool = use_pool
         self.pool_size = pool_size
         self.pool_recycle = pool_recycle
-        
-        super().__init__(secret_name=secret_name, **kwargs)
+
+        super().__init__(secret_name=secret_name, credentials=credentials, **kwargs)
         
         # Build pool key for connection management
         self._pool_key = f"{self.credentials['host']}:{self.credentials['port']}"
@@ -153,32 +157,31 @@ class DatabaseClient(BaseClient, ServiceHealthMixin):
         """Database client doesn't have a single service client - uses connections."""
         return None
 
-    def _resolve_credentials(self, secret_name: Optional[str]) -> Dict[str, Any]:
-        """
-        Override to use get_database_credentials for normalized field names.
-
-        Args:
-            secret_name: Optional secret name override
+    def _resolve_credentials_from_env(self) -> Optional[Dict[str, Any]]:
+        """Resolve MySQL credentials from environment variables.
 
-        Returns:
-            Normalized database credentials
+        Requires both DB_HOST and DB_PASSWORD to trigger.
         """
-        # Use BaseClient's resolution logic to determine the secret name
-        from .utils import resolve_config_value, validate_required_param
-
-        resolved_secret_name = resolve_config_value(
-            secret_name,
-            [
-                f"{self.config_key_prefix.upper()}_CREDENTIALS_SECRET",
-                f"{self.config_key_prefix.upper()}CREDENTIALS_SECRET"  # Alternative format
-            ],
-            getattr(self.config, f"{self.config_key_prefix}_credentials_secret", self._get_default_secret_name())
-        )
-
-        validate_required_param(resolved_secret_name, "secret_name")
+        host = os.environ.get("DB_HOST")
+        password = os.environ.get("DB_PASSWORD")
+        if not host or not password:
+            return None
+        port_str = os.environ.get("DB_PORT", "3306")
+        try:
+            port = int(port_str)
+        except ValueError:
+            raise ValueError(f"DB_PORT must be an integer, got: {port_str!r}")
+        return {
+            "host": host,
+            "port": port,
+            "username": os.environ.get("DB_USERNAME", "root"),
+            "password": password,
+            "database": os.environ.get("DB_DATABASE", "app"),
+        }
 
-        # Now use the resolved secret name with get_database_credentials
-        return get_database_credentials(resolved_secret_name)
+    def _fetch_credentials_from_sm(self, secret_name: Optional[str]) -> Dict[str, Any]:
+        """Override to use get_database_credentials for normalized field names."""
+        return get_database_credentials(self._resolve_secret_name(secret_name))
 
     def _clean_expired_connections(self, pool_key: str) -> None:
         """
@@ -476,21 +479,24 @@ class PostgreSQLClient(BaseClient, ServiceHealthMixin):
         self,
         secret_name: Optional[str] = None,
         use_auth_credentials: bool = True,
+        credentials: Optional[Dict[str, Any]] = None,
         **kwargs
     ):
         """
         Initialize PostgreSQL client.
-        
+
         Args:
             secret_name: Override secret name
             use_auth_credentials: Use auth-specific credentials
+            credentials: Direct credentials dict (keys: host, port, username, password, database),
+                bypasses Secrets Manager
             **kwargs: Additional configuration
         """
         if not HAS_POSTGRESQL:
             raise ImportError("psycopg2 is not installed. Install with: pip install psycopg2-binary")
 
         self.use_auth_credentials = use_auth_credentials
-        super().__init__(secret_name=secret_name, **kwargs)
+        super().__init__(secret_name=secret_name, credentials=credentials, **kwargs)
 
     def _get_default_config_prefix(self) -> str:
         """Return configuration prefix for PostgreSQL."""
@@ -504,20 +510,33 @@ class PostgreSQLClient(BaseClient, ServiceHealthMixin):
         """PostgreSQL client doesn't have a single service client - uses connections."""
         return None
 
-    def _resolve_credentials(self, secret_name: Optional[str]) -> Dict[str, Any]:
-        """
-        Resolve PostgreSQL credentials with auth-specific handling.
-        
-        Args:
-            secret_name: Optional secret name override
-            
-        Returns:
-            PostgreSQL credentials
+    def _resolve_credentials_from_env(self) -> Optional[Dict[str, Any]]:
+        """Resolve PostgreSQL credentials from environment variables.
+
+        Requires both DB_HOST and DB_PASSWORD to trigger.
         """
+        host = os.environ.get("DB_HOST")
+        password = os.environ.get("DB_PASSWORD")
+        if not host or not password:
+            return None
+        port_str = os.environ.get("DB_PORT", "5432")
+        try:
+            port = int(port_str)
+        except ValueError:
+            raise ValueError(f"DB_PORT must be an integer, got: {port_str!r}")
+        return {
+            "host": host,
+            "port": port,
+            "username": os.environ.get("DB_USERNAME", "postgres"),
+            "password": password,
+            "database": os.environ.get("DB_DATABASE", "postgres"),
+        }
+
+    def _fetch_credentials_from_sm(self, secret_name: Optional[str]) -> Dict[str, Any]:
+        """Override with auth-specific credential handling."""
         from .secrets_helper import get_secret
-        
-        # Get raw secret to access auth-specific fields
-        resolved_secret_name = secret_name or self._get_default_secret_name()
+
+        resolved_secret_name = self._resolve_secret_name(secret_name)
         raw_creds = get_secret(resolved_secret_name)
 
         # Use auth-specific credentials if available and requested
@@ -530,7 +549,6 @@ class PostgreSQLClient(BaseClient, ServiceHealthMixin):
                 "database": raw_creds.get("auth_database", "auth-service-db"),
             }
         else:
-            # Fall back to normalized credentials
             return get_database_credentials(resolved_secret_name)
 
     @contextmanager

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/nui_lambda_shared_utils/es_client.py

@@ -2,6 +2,7 @@
 Refactored Elasticsearch client using BaseClient for DRY code patterns.
 """
 
+import os
 import logging
 from datetime import datetime, timedelta
 from typing import Dict, Iterator, List, Optional, Any, Tuple
@@ -20,18 +21,25 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
     Refactored Elasticsearch client with standardized patterns.
     """
 
-    def __init__(self, host: Optional[str] = None, secret_name: Optional[str] = None, **kwargs):
+    def __init__(
+        self,
+        host: Optional[str] = None,
+        secret_name: Optional[str] = None,
+        credentials: Optional[Dict[str, Any]] = None,
+        **kwargs,
+    ):
         """
         Initialize Elasticsearch client.
-        
+
         Args:
             host: Override ES host
             secret_name: Override secret name
+            credentials: Direct credentials dict (keys: username, password), bypasses Secrets Manager
             **kwargs: Additional ES client configuration
         """
         # Store host for later use in service client creation
         self._host_override = host
-        super().__init__(secret_name=secret_name, **kwargs)
+        super().__init__(secret_name=secret_name, credentials=credentials, **kwargs)
 
     def _get_default_config_prefix(self) -> str:
         """Return configuration prefix for Elasticsearch."""
@@ -41,6 +49,20 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
         """Return default secret name for ES credentials."""
         return "elasticsearch-credentials"
 
+    def _resolve_credentials_from_env(self) -> Optional[Dict[str, Any]]:
+        """Resolve Elasticsearch credentials from environment variables.
+
+        Checks for ES_PASSWORD (required to trigger).
+        ES_USERNAME defaults to "elastic" if not set.
+        """
+        password = os.environ.get("ES_PASSWORD")
+        if not password:
+            return None
+        return {
+            "username": os.environ.get("ES_USERNAME", "elastic"),
+            "password": password,
+        }
+
     def _create_service_client(self) -> Elasticsearch:
         """Create Elasticsearch client with resolved configuration."""
         # Resolve host using utility
@@ -132,7 +154,7 @@ class ElasticsearchClient(BaseClient, ServiceHealthMixin):
         )
 
     @handle_client_errors(default_return=0)
-    def count(self, index: str, body: Optional[Dict] = None) -> int:
+    def count(self, index: str, body: Optional[Dict[str, Any]] = None) -> int:
         """
         Count documents with error handling.
         

{nui_lambda_shared_utils-1.2.0 → nui_lambda_shared_utils-1.2.2}/nui_lambda_shared_utils/jwt_auth.py

@@ -9,10 +9,12 @@ Install: pip install nui-lambda-shared-utils[jwt]
 
 import os
 import json
+import re
 import base64
 import time
 import logging
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING, AbstractSet, Any, Dict, Optional, Tuple
+from urllib.parse import unquote
 
 from .secrets_helper import get_secret
 
@@ -216,3 +218,60 @@ def require_auth(event: dict, secret_name: Optional[str] = None) -> dict:
         return validate_jwt(token, public_key)
     except JWTValidationError as e:
         raise AuthenticationError(f"Authentication failed: {e}") from e
+
+
+def _normalize_path(path: str) -> str:
+    """Normalize a URL path for safe comparison.
+
+    URL-decodes, collapses duplicate slashes, ensures a single leading slash,
+    and strips any trailing slash (except for root "/").
+    """
+    path = unquote(path)
+    path = re.sub(r"/+", "/", path)
+    return "/" + path.strip("/") if path.strip("/") else "/"
+
+
+def check_auth(
+    event: dict,
+    public_paths: AbstractSet[str] = frozenset(),
+    secret_name: Optional[str] = None,
+) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
+    """Check JWT authentication on an API Gateway event, skipping public paths.
+
+    Combines path normalization, public-path bypass, JWT validation,
+    and a standard JSON:API 401 error response in one call.
+
+    Args:
+        event: API Gateway Lambda proxy integration event.
+        public_paths: Set of normalized paths that skip auth (e.g. {"/health"}).
+        secret_name: Optional Secrets Manager secret name for the public key.
+
+    Returns:
+        (claims, None) on success — claims is the decoded JWT dict,
+            or None if the path is public.
+        (None, response) on auth failure — response is a 401 dict
+            ready to return from your Lambda handler.
+    """
+    raw_path = event.get("path") or event.get("rawPath") or ""
+    if _normalize_path(raw_path) in public_paths:
+        return None, None
+
+    try:
+        claims = require_auth(event, secret_name=secret_name)
+        return claims, None
+    except AuthenticationError as e:
+        log.warning("Authentication failed: %s", e)
+        return None, {
+            "statusCode": 401,
+            "headers": {
+                "Content-Type": "application/json",
+                "Access-Control-Allow-Origin": "*",
+            },
+            "body": json.dumps({
+                "errors": [{
+                    "status": "401",
+                    "title": "Unauthorized",
+                    "detail": "Authentication required",
+                }]
+            }),
+        }