nui-lambda-shared-utils 1.1.5__tar.gz → 1.2.1__tar.gz

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/CLAUDE.md

@@ -37,6 +37,7 @@ This is `nui-lambda-shared-utils`, a Python package providing production-ready u
 - **Elasticsearch** (`es_client.py`, `es_query_builder.py`) - Query builders and health monitoring
 - **Database** (`db_client.py`) - Connection pooling with retry logic
 - **Metrics** (`cloudwatch_metrics.py`) - Batched CloudWatch publishing with decorators
+- **JWT Authentication** (`jwt_auth.py`) - RS256 token validation for API Gateway Lambdas (uses `rsa` package)
 - **Error Handling** (`error_handler.py`) - Retry patterns with exponential backoff
 - **Timezone Utils** (`timezone.py`) - Timezone conversion and formatting utilities
 
@@ -47,6 +48,7 @@ The package uses optional extras to minimize Lambda bundle size:
 - `elasticsearch` - Elasticsearch client and query builders
 - `database` - MySQL/PostgreSQL drivers
 - `slack` - Slack SDK
+- `jwt` - RS256 JWT validation (`rsa` package)
 - `all` - All integrations
 - `dev` - Development and testing tools
 

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nui-lambda-shared-utils
-Version: 1.1.5
+Version: 1.2.1
 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
@@ -41,6 +41,8 @@ Requires-Dist: slack-sdk>=3.19.0; extra == "slack"
 Provides-Extra: powertools
 Requires-Dist: aws-lambda-powertools<4.0.0,>=3.6.0; extra == "powertools"
 Requires-Dist: coloredlogs>=15.0; extra == "powertools"
+Provides-Extra: jwt
+Requires-Dist: rsa>=4.9; extra == "jwt"
 Provides-Extra: all
 Requires-Dist: elasticsearch<8.0.0,>=7.17.0; extra == "all"
 Requires-Dist: pymysql>=1.0.0; extra == "all"
@@ -48,6 +50,7 @@ Requires-Dist: psycopg2-binary>=2.9.0; extra == "all"
 Requires-Dist: slack-sdk>=3.19.0; extra == "all"
 Requires-Dist: aws-lambda-powertools<4.0.0,>=3.6.0; extra == "all"
 Requires-Dist: coloredlogs>=15.0; extra == "all"
+Requires-Dist: rsa>=4.9; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -56,8 +59,12 @@ Requires-Dist: moto>=4.0.0; extra == "dev"
 Requires-Dist: black>=22.0.0; extra == "dev"
 Requires-Dist: mypy>=0.990; extra == "dev"
 Requires-Dist: boto3-stubs[essential]>=1.20.0; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
+Requires-Dist: types-pytz>=2021.3.0; extra == "dev"
 Requires-Dist: twine>=4.0.0; extra == "dev"
 Requires-Dist: build>=0.8.0; extra == "dev"
+Requires-Dist: rsa>=4.9; extra == "dev"
+Requires-Dist: cryptography>=41.0.0; extra == "dev"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -99,6 +106,7 @@ Production-ready utilities for AWS Lambda functions with Slack, Elasticsearch, d
 - **Elasticsearch Operations** - Query builders, index management, and health monitoring
 - **Database Connections** - Connection pooling, automatic retries, and transaction management
 - **CloudWatch Metrics** - Batched publishing with custom dimensions
+- **JWT Authentication** - RS256 token validation for API Gateway Lambdas (lightweight, no PyJWT needed)
 - **Error Handling** - Intelligent retry patterns with exponential backoff
 - **Timezone Utilities** - Timezone handling and formatting
 - **Configurable Defaults** - Environment-aware configuration system
@@ -134,6 +142,7 @@ pip install nui-lambda-shared-utils[powertools]   # AWS Powertools only
 pip install nui-lambda-shared-utils[slack]        # Slack only
 pip install nui-lambda-shared-utils[elasticsearch] # Elasticsearch only
 pip install nui-lambda-shared-utils[database]     # Database only
+pip install nui-lambda-shared-utils[jwt]          # JWT authentication only
 ```
 
 ### Basic Configuration
@@ -276,6 +285,23 @@ def lambda_handler(event, context):
 
 **[→ See full metrics guide](docs/getting-started/quickstart.md#cloudwatch-metrics)**
 
+### JWT Authentication
+
+```python
+from nui_lambda_shared_utils import require_auth, AuthenticationError
+
+def lambda_handler(event, context):
+    try:
+        claims = require_auth(event)  # Validates Bearer token from Authorization header
+    except AuthenticationError as e:
+        return {"statusCode": 401, "body": "Unauthorized"}
+
+    user_id = claims["sub"]
+    return {"statusCode": 200, "body": f"Hello {user_id}"}
+```
+
+**[→ See JWT authentication guide](docs/guides/jwt-authentication.md)**
+
 ### Error Handling
 
 ```python
@@ -330,6 +356,7 @@ This package requires AWS Secrets Manager for credential storage and IAM permiss
 - Elasticsearch: `{"host": "...", "username": "...", "password": "..."}`
 - Database: `{"host": "...", "port": 3306, "username": "...", "password": "...", "database": "..."}`
 - Slack: `{"bot_token": "xoxb-...", "webhook_url": "..."}`
+- JWT Public Key: `{"TOKEN_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----\n..."}`
 
 **IAM Permissions** - Lambda execution role needs:
 

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/README.md

@@ -34,6 +34,7 @@ Production-ready utilities for AWS Lambda functions with Slack, Elasticsearch, d
 - **Elasticsearch Operations** - Query builders, index management, and health monitoring
 - **Database Connections** - Connection pooling, automatic retries, and transaction management
 - **CloudWatch Metrics** - Batched publishing with custom dimensions
+- **JWT Authentication** - RS256 token validation for API Gateway Lambdas (lightweight, no PyJWT needed)
 - **Error Handling** - Intelligent retry patterns with exponential backoff
 - **Timezone Utilities** - Timezone handling and formatting
 - **Configurable Defaults** - Environment-aware configuration system
@@ -69,6 +70,7 @@ pip install nui-lambda-shared-utils[powertools]   # AWS Powertools only
 pip install nui-lambda-shared-utils[slack]        # Slack only
 pip install nui-lambda-shared-utils[elasticsearch] # Elasticsearch only
 pip install nui-lambda-shared-utils[database]     # Database only
+pip install nui-lambda-shared-utils[jwt]          # JWT authentication only
 ```
 
 ### Basic Configuration
@@ -211,6 +213,23 @@ def lambda_handler(event, context):
 
 **[→ See full metrics guide](docs/getting-started/quickstart.md#cloudwatch-metrics)**
 
+### JWT Authentication
+
+```python
+from nui_lambda_shared_utils import require_auth, AuthenticationError
+
+def lambda_handler(event, context):
+    try:
+        claims = require_auth(event)  # Validates Bearer token from Authorization header
+    except AuthenticationError as e:
+        return {"statusCode": 401, "body": "Unauthorized"}
+
+    user_id = claims["sub"]
+    return {"statusCode": 200, "body": f"Hello {user_id}"}
+```
+
+**[→ See JWT authentication guide](docs/guides/jwt-authentication.md)**
+
 ### Error Handling
 
 ```python
@@ -265,6 +284,7 @@ This package requires AWS Secrets Manager for credential storage and IAM permiss
 - Elasticsearch: `{"host": "...", "username": "...", "password": "..."}`
 - Database: `{"host": "...", "port": 3306, "username": "...", "password": "...", "database": "..."}`
 - Slack: `{"bot_token": "xoxb-...", "webhook_url": "..."}`
+- JWT Public Key: `{"TOKEN_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----\n..."}`
 
 **IAM Permissions** - Lambda execution role needs:
 

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/docs/README.md

@@ -2,7 +2,7 @@
 
 Welcome to the comprehensive documentation for `nui-lambda-shared-utils`.
 
-**Last Updated**: 2025-01-19
+**Last Updated**: 2026-02-13
 
 ## Quick Navigation
 
@@ -20,6 +20,7 @@ Component-specific guides for major features:
 - **[Lambda Context Helpers](guides/lambda-utilities.md)** - Environment info extraction for logging and metrics
 - **[Slack Integration](guides/slack-integration.md)** - Messaging, formatting, and file uploads
 - **[Elasticsearch Integration](guides/elasticsearch-integration.md)** - Search, bulk indexing, health checks
+- **[JWT Authentication](guides/jwt-authentication.md)** - RS256 token validation for API Gateway Lambdas
 - **[Log Processing](guides/log-processing.md)** - Kinesis log extraction and ES index naming
 - Database Connections (planned)
 - Error Handling Patterns (planned)
@@ -123,6 +124,7 @@ When contributing to documentation:
 - Lambda context helpers guide (guides/lambda-utilities.md)
 - Slack integration guide (guides/slack-integration.md)
 - Elasticsearch integration guide (guides/elasticsearch-integration.md)
+- JWT authentication guide (guides/jwt-authentication.md)
 - Shared types reference (guides/shared-types.md)
 - CLI tools guide (guides/cli-tools.md)
 - Testing guide (development/testing.md)

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/docs/getting-started/configuration.md

@@ -20,6 +20,7 @@ The package uses a hierarchical configuration system with the following priority
 | `ES_CREDENTIALS_SECRET` | AWS secret name for Elasticsearch credentials | `elasticsearch-credentials` |
 | `DB_CREDENTIALS_SECRET` | AWS secret name for database credentials | `database-credentials` |
 | `SLACK_CREDENTIALS_SECRET` | AWS secret name for Slack credentials | `slack-credentials` |
+| `JWT_PUBLIC_KEY_SECRET` | AWS secret name for JWT public key | *(none)* |
 | `AWS_REGION` | AWS region for services | `us-east-1` |
 
 ### Alternative Variable Names
@@ -143,6 +144,16 @@ The package expects AWS secrets in specific JSON formats:
 
 - `webhook_url` - Alternative to bot token for simple messaging
 
+#### JWT Public Key
+
+```json
+{
+  "TOKEN_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh...\n-----END PUBLIC KEY-----"
+}
+```
+
+The key must be in PKCS#8 PEM format (`BEGIN PUBLIC KEY`). The field name is configurable via the `key_field` parameter on `get_jwt_public_key()`.
+
 ### Creating Secrets
 
 #### Using AWS CLI

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/docs/getting-started/installation.md

@@ -31,6 +31,9 @@ pip install nui-lambda-shared-utils[elasticsearch]
 # Database integration only
 pip install nui-lambda-shared-utils[database]
 
+# JWT authentication only
+pip install nui-lambda-shared-utils[jwt]
+
 # All integrations
 pip install nui-lambda-shared-utils[all]
 
@@ -75,6 +78,10 @@ pip install -e .[dev]
 
 - `slack-sdk>=3.19.0` - Official Slack SDK
 
+#### jwt
+
+- `rsa>=4.9` - Pure Python RSA implementation (~100KB, no C extensions)
+
 #### dev
 
 - `pytest>=7.0.0` - Testing framework

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/docs/getting-started/quickstart.md

@@ -223,7 +223,42 @@ def lambda_handler(event, context):
         raise
 ```
 
-### 5. AWS Powertools Integration
+### 7. JWT Authentication for API Gateway
+
+```python
+import nui_lambda_shared_utils as nui
+
+def lambda_handler(event, context):
+    """API Gateway Lambda with JWT auth."""
+    # Validate Bearer token from Authorization header
+    # Fetches public key from Secrets Manager (cached automatically)
+    try:
+        claims = nui.require_auth(event)
+    except nui.AuthenticationError:
+        return {"statusCode": 401, "body": "Unauthorized"}
+
+    # Access token claims
+    user_id = claims["sub"]
+    role = claims.get("role", "user")
+
+    return {"statusCode": 200, "body": f"Hello {user_id} ({role})"}
+```
+
+**Installation:**
+
+```bash
+pip install nui-lambda-shared-utils[jwt]
+```
+
+**Requirements:**
+
+- `JWT_PUBLIC_KEY_SECRET` env var pointing to Secrets Manager secret
+- Secret contains `{"TOKEN_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----\n..."}` (PKCS#8 PEM)
+- IAM permission: `secretsmanager:GetSecretValue`
+
+**See:** [JWT Authentication Guide](../guides/jwt-authentication.md) for key management and advanced usage.
+
+### 8. AWS Powertools Integration
 
 For production Lambda functions, use AWS Powertools for standardized logging, metrics, and error handling:
 

nui_lambda_shared_utils-1.2.1/docs/guides/jwt-authentication.md

@@ -0,0 +1,148 @@
+# JWT Authentication Guide
+
+RS256 JWT token validation for AWS Lambda functions behind API Gateway.
+
+## Overview
+
+The `jwt_auth` module validates RS256-signed JWTs using public keys stored in AWS Secrets Manager. It uses the pure-Python `rsa` package (~100KB) instead of PyJWT or `cryptography` (~35MB), keeping Lambda bundles small without needing a Lambda Layer.
+
+## Installation
+
+```bash
+pip install nui-lambda-shared-utils[jwt]
+```
+
+## Quick Start
+
+```python
+from nui_lambda_shared_utils import require_auth, AuthenticationError
+
+def lambda_handler(event, context):
+    try:
+        claims = require_auth(event)
+    except AuthenticationError:
+        return {"statusCode": 401, "body": "Unauthorized"}
+
+    return {"statusCode": 200, "body": f"Hello {claims['sub']}"}
+```
+
+## API Reference
+
+### `require_auth(event, secret_name=None) -> dict`
+
+One-call authentication for API Gateway Lambda handlers. Extracts the Bearer token from the Authorization header, fetches the public key from Secrets Manager, and validates the token.
+
+- **event** — API Gateway Lambda proxy event (v1 REST or v2 HTTP API)
+- **secret_name** — Secrets Manager secret name (falls back to `JWT_PUBLIC_KEY_SECRET` env var)
+- **Returns** — Decoded claims dict
+- **Raises** — `AuthenticationError` on any failure (missing header, bad token, expired, bad signature, missing key)
+
+### `validate_jwt(token, public_key) -> dict`
+
+Lower-level validation when you already have the public key. Verifies token structure, RS256 signature, and expiration.
+
+- **token** — Raw JWT string (no `Bearer` prefix)
+- **public_key** — `rsa.PublicKey` instance
+- **Returns** — Decoded claims dict
+- **Raises** — `JWTValidationError` on failure
+
+### `get_jwt_public_key(secret_name=None, key_field="TOKEN_PUBLIC_KEY") -> rsa.PublicKey`
+
+Fetches and parses the PEM public key from Secrets Manager. Uses `secrets_helper` cache — repeated calls don't make additional API calls.
+
+- **secret_name** — Falls back to `JWT_PUBLIC_KEY_SECRET` env var
+- **key_field** — JSON field in the secret containing the PEM string
+- **Returns** — `rsa.PublicKey`
+- **Raises** — `JWTValidationError` if secret or field is missing/invalid
+
+### Exceptions
+
+- **`JWTValidationError`** — Base exception for token validation failures
+- **`AuthenticationError(JWTValidationError)`** — Authentication-level failures (what `require_auth` raises)
+
+## AWS Setup
+
+### 1. Store the Public Key
+
+```bash
+aws secretsmanager create-secret \
+  --name "prod/jwt-public-key" \
+  --secret-string '{"TOKEN_PUBLIC_KEY": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh...\n-----END PUBLIC KEY-----"}'
+```
+
+The key must be PKCS#8 PEM format (`BEGIN PUBLIC KEY`, not `BEGIN RSA PUBLIC KEY`).
+
+### 2. Lambda Environment
+
+```yaml
+# serverless.yml
+environment:
+  JWT_PUBLIC_KEY_SECRET: prod/jwt-public-key
+```
+
+### 3. IAM Permissions
+
+```yaml
+# serverless.yml
+iamRoleStatements:
+  - Effect: Allow
+    Action: secretsmanager:GetSecretValue
+    Resource: arn:aws:secretsmanager:*:*:secret:prod/jwt-public-key-*
+```
+
+## Usage Patterns
+
+### Skip Auth for Health Endpoints
+
+```python
+def lambda_handler(event, context):
+    path = event.get("path") or event.get("rawPath", "")
+    if path == "/health":
+        return {"statusCode": 200, "body": "ok"}
+
+    try:
+        claims = require_auth(event)
+    except AuthenticationError:
+        return {"statusCode": 401, "body": "Unauthorized"}
+
+    # Authenticated route handling
+    return handle_request(event, claims)
+```
+
+### Direct Validation (Pre-fetched Key)
+
+```python
+from nui_lambda_shared_utils import get_jwt_public_key, validate_jwt, JWTValidationError
+
+# Fetch key once at module level (cached by secrets_helper)
+public_key = get_jwt_public_key(secret_name="prod/jwt-public-key")
+
+def validate_token(token: str) -> dict:
+    try:
+        return validate_jwt(token, public_key)
+    except JWTValidationError as e:
+        raise ValueError(f"Bad token: {e}")
+```
+
+### Custom Key Field Name
+
+```python
+# If your secret uses a different field name
+key = get_jwt_public_key(
+    secret_name="prod/auth-keys",
+    key_field="RSA_PUBLIC_KEY"
+)
+```
+
+## What Gets Validated
+
+| Check | Behavior |
+|-------|----------|
+| Token structure | Must be 3 dot-separated base64url segments |
+| Algorithm | Header `alg` must be `RS256` |
+| Signature | RSA PKCS#1 v1.5 with SHA-256 |
+| Expiration | `exp` claim checked against current time (optional — tokens without `exp` are accepted) |
+
+## Dependency Details
+
+The module uses `rsa` (pure Python, ~100KB) for signature verification at runtime. This avoids the ~35MB `cryptography` C extension that PyJWT requires for RS256. The `cryptography` package is only needed in dev for generating test key pairs and signing test tokens.

{nui_lambda_shared_utils-1.1.5 → nui_lambda_shared_utils-1.2.1}/nui_lambda_shared_utils/__init__.py

@@ -132,6 +132,24 @@ from .log_processors import (
 # Lambda context helpers (no external dependencies)
 from .lambda_helpers import get_lambda_environment_info
 
+# JWT authentication - optional import
+try:
+    from .jwt_auth import (
+        validate_jwt,
+        require_auth,
+        check_auth,
+        get_jwt_public_key,
+        JWTValidationError,
+        AuthenticationError,
+    )
+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
+
 # Slack setup utilities (for CLI usage) - optional import
 try:
     from . import slack_setup
@@ -224,4 +242,11 @@ __all__ = [
     "CloudWatchLogsData",
     # Lambda context helpers
     "get_lambda_environment_info",
+    # JWT authentication
+    "validate_jwt",
+    "require_auth",
+    "check_auth",
+    "get_jwt_public_key",
+    "JWTValidationError",
+    "AuthenticationError",
 ]