tlacacoca 0.1.3__tar.gz

tlacacoca-0.1.3/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.3
+Name: tlacacoca
+Version: 0.1.3
+Summary: Shared foundation library for TLS-based protocol implementations
+Author: Alan Velasco
+Author-email: Alan Velasco <alanvelasco.a@gmail.com>
+Requires-Dist: cryptography>=46.0.3
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
+Requires-Dist: tomli-w>=1.2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Tlacacoca - Shared Foundation Library for TLS-Based Protocols
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+A protocol-agnostic foundation library providing shared components for building secure TLS-based network protocol implementations in Python. Tlacacoca (pronounced "tla-ka-KO-ka", from Nahuatl meaning "secure/safe") provides security, middleware, and logging utilities that can be shared across multiple protocol implementations.
+
+## Key Features
+
+- **Security First** - TLS context creation, TOFU certificate validation, certificate utilities
+- **Middleware System** - Rate limiting, IP access control, certificate authentication
+- **Structured Logging** - Privacy-preserving logging with IP hashing
+- **Protocol Agnostic** - Abstract interfaces that any TLS-based protocol can build upon
+- **Modern Python** - Full type hints, async/await support, and modern tooling with `uv`
+
+## Quick Start
+
+### Installation
+
+```bash
+# As a library
+uv add tlacacoca
+
+# From source (for development)
+git clone https://github.com/alanbato/tlacacoca.git
+cd tlacacoca && uv sync
+```
+
+### Basic Usage
+
+```python
+import ssl
+from tlacacoca import (
+    create_client_context,
+    create_server_context,
+    TOFUDatabase,
+    RateLimiter,
+    RateLimitConfig,
+    AccessControl,
+    AccessControlConfig,
+    MiddlewareChain,
+)
+
+# Create TLS contexts
+client_ctx = create_client_context(verify_mode=ssl.CERT_REQUIRED)
+server_ctx = create_server_context("cert.pem", "key.pem")
+
+# Set up TOFU certificate validation
+async with TOFUDatabase(app_name="myapp") as tofu:
+    # First connection - certificate is stored
+    await tofu.verify_or_trust("example.com", 1965, cert_fingerprint)
+
+    # Subsequent connections - certificate is verified
+    await tofu.verify_or_trust("example.com", 1965, cert_fingerprint)
+
+# Configure middleware chain
+rate_config = RateLimitConfig(capacity=10, refill_rate=1.0)
+access_config = AccessControlConfig(
+    allow_list=["192.168.1.0/24"],
+    default_allow=False
+)
+
+chain = MiddlewareChain([
+    AccessControl(access_config),
+    RateLimiter(rate_config),
+])
+
+# Process requests through middleware
+result = await chain.process_request(
+    request_url="protocol://example.com/path",
+    client_ip="192.168.1.100"
+)
+
+if result.allowed:
+    # Handle request
+    pass
+else:
+    # Map denial_reason to protocol-specific response
+    if result.denial_reason == "rate_limit":
+        # e.g., Gemini: "44 SLOW DOWN\r\n"
+        pass
+```
+
+## Components
+
+### Security
+
+| Component | Description |
+|-----------|-------------|
+| `create_client_context()` | Create TLS context for client connections |
+| `create_server_context()` | Create TLS context for server connections |
+| `TOFUDatabase` | Trust-On-First-Use certificate validation |
+| `generate_self_signed_cert()` | Generate self-signed certificates |
+| `get_certificate_fingerprint()` | Get SHA-256 fingerprint of certificate |
+| `load_certificate()` | Load certificate from PEM file |
+
+### Middleware
+
+| Component | Description |
+|-----------|-------------|
+| `MiddlewareChain` | Chain multiple middleware components |
+| `RateLimiter` | Token bucket rate limiting per IP |
+| `AccessControl` | IP-based allow/deny lists with CIDR support |
+| `CertificateAuth` | Client certificate authentication |
+
+### Logging
+
+| Component | Description |
+|-----------|-------------|
+| `configure_logging()` | Configure structured logging |
+| `get_logger()` | Get a logger instance |
+| `hash_ip_processor()` | Privacy-preserving IP hashing |
+
+## Protocol Implementations Using Tlacacoca
+
+Tlacacoca is designed to be used by protocol-specific implementations:
+
+- **nauyaca** - Gemini protocol server & client
+- **amatl** - Scroll protocol implementation (planned)
+
+## Documentation
+
+### Middleware Return Types
+
+Middleware components return `MiddlewareResult` with protocol-agnostic denial reasons:
+
+```python
+from tlacacoca import MiddlewareResult, DenialReason
+
+# Allowed request
+result = MiddlewareResult(allowed=True)
+
+# Denied request
+result = MiddlewareResult(
+    allowed=False,
+    denial_reason=DenialReason.RATE_LIMIT,
+    retry_after=30
+)
+```
+
+Protocol implementations map these to their specific status codes:
+
+| Denial Reason | Gemini Status | Description |
+|--------------|---------------|-------------|
+| `RATE_LIMIT` | 44 SLOW DOWN | Rate limit exceeded |
+| `ACCESS_DENIED` | 53 PROXY REFUSED | IP not allowed |
+| `CERT_REQUIRED` | 60 CLIENT CERT REQUIRED | Need client certificate |
+| `CERT_NOT_AUTHORIZED` | 61 CERT NOT AUTHORIZED | Certificate not in allowed list |
+
+## Contributing
+
+```bash
+# Setup
+git clone https://github.com/alanbato/tlacacoca.git
+cd tlacacoca && uv sync
+
+# Test
+uv run pytest
+
+# Lint & Type Check
+uv run ruff check src/ tests/
+uv run ty check src/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Resources
+
+- [SECURITY.md](SECURITY.md) - Security documentation
+- [GitHub Issues](https://github.com/alanbato/tlacacoca/issues) - Bug reports
+- [GitHub Discussions](https://github.com/alanbato/tlacacoca/discussions) - Questions and ideas
+
+---
+
+**Status**: Active development (pre-1.0). Core security and middleware features are stable.

tlacacoca-0.1.3/README.md

@@ -0,0 +1,180 @@
+# Tlacacoca - Shared Foundation Library for TLS-Based Protocols
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+
+A protocol-agnostic foundation library providing shared components for building secure TLS-based network protocol implementations in Python. Tlacacoca (pronounced "tla-ka-KO-ka", from Nahuatl meaning "secure/safe") provides security, middleware, and logging utilities that can be shared across multiple protocol implementations.
+
+## Key Features
+
+- **Security First** - TLS context creation, TOFU certificate validation, certificate utilities
+- **Middleware System** - Rate limiting, IP access control, certificate authentication
+- **Structured Logging** - Privacy-preserving logging with IP hashing
+- **Protocol Agnostic** - Abstract interfaces that any TLS-based protocol can build upon
+- **Modern Python** - Full type hints, async/await support, and modern tooling with `uv`
+
+## Quick Start
+
+### Installation
+
+```bash
+# As a library
+uv add tlacacoca
+
+# From source (for development)
+git clone https://github.com/alanbato/tlacacoca.git
+cd tlacacoca && uv sync
+```
+
+### Basic Usage
+
+```python
+import ssl
+from tlacacoca import (
+    create_client_context,
+    create_server_context,
+    TOFUDatabase,
+    RateLimiter,
+    RateLimitConfig,
+    AccessControl,
+    AccessControlConfig,
+    MiddlewareChain,
+)
+
+# Create TLS contexts
+client_ctx = create_client_context(verify_mode=ssl.CERT_REQUIRED)
+server_ctx = create_server_context("cert.pem", "key.pem")
+
+# Set up TOFU certificate validation
+async with TOFUDatabase(app_name="myapp") as tofu:
+    # First connection - certificate is stored
+    await tofu.verify_or_trust("example.com", 1965, cert_fingerprint)
+
+    # Subsequent connections - certificate is verified
+    await tofu.verify_or_trust("example.com", 1965, cert_fingerprint)
+
+# Configure middleware chain
+rate_config = RateLimitConfig(capacity=10, refill_rate=1.0)
+access_config = AccessControlConfig(
+    allow_list=["192.168.1.0/24"],
+    default_allow=False
+)
+
+chain = MiddlewareChain([
+    AccessControl(access_config),
+    RateLimiter(rate_config),
+])
+
+# Process requests through middleware
+result = await chain.process_request(
+    request_url="protocol://example.com/path",
+    client_ip="192.168.1.100"
+)
+
+if result.allowed:
+    # Handle request
+    pass
+else:
+    # Map denial_reason to protocol-specific response
+    if result.denial_reason == "rate_limit":
+        # e.g., Gemini: "44 SLOW DOWN\r\n"
+        pass
+```
+
+## Components
+
+### Security
+
+| Component | Description |
+|-----------|-------------|
+| `create_client_context()` | Create TLS context for client connections |
+| `create_server_context()` | Create TLS context for server connections |
+| `TOFUDatabase` | Trust-On-First-Use certificate validation |
+| `generate_self_signed_cert()` | Generate self-signed certificates |
+| `get_certificate_fingerprint()` | Get SHA-256 fingerprint of certificate |
+| `load_certificate()` | Load certificate from PEM file |
+
+### Middleware
+
+| Component | Description |
+|-----------|-------------|
+| `MiddlewareChain` | Chain multiple middleware components |
+| `RateLimiter` | Token bucket rate limiting per IP |
+| `AccessControl` | IP-based allow/deny lists with CIDR support |
+| `CertificateAuth` | Client certificate authentication |
+
+### Logging
+
+| Component | Description |
+|-----------|-------------|
+| `configure_logging()` | Configure structured logging |
+| `get_logger()` | Get a logger instance |
+| `hash_ip_processor()` | Privacy-preserving IP hashing |
+
+## Protocol Implementations Using Tlacacoca
+
+Tlacacoca is designed to be used by protocol-specific implementations:
+
+- **nauyaca** - Gemini protocol server & client
+- **amatl** - Scroll protocol implementation (planned)
+
+## Documentation
+
+### Middleware Return Types
+
+Middleware components return `MiddlewareResult` with protocol-agnostic denial reasons:
+
+```python
+from tlacacoca import MiddlewareResult, DenialReason
+
+# Allowed request
+result = MiddlewareResult(allowed=True)
+
+# Denied request
+result = MiddlewareResult(
+    allowed=False,
+    denial_reason=DenialReason.RATE_LIMIT,
+    retry_after=30
+)
+```
+
+Protocol implementations map these to their specific status codes:
+
+| Denial Reason | Gemini Status | Description |
+|--------------|---------------|-------------|
+| `RATE_LIMIT` | 44 SLOW DOWN | Rate limit exceeded |
+| `ACCESS_DENIED` | 53 PROXY REFUSED | IP not allowed |
+| `CERT_REQUIRED` | 60 CLIENT CERT REQUIRED | Need client certificate |
+| `CERT_NOT_AUTHORIZED` | 61 CERT NOT AUTHORIZED | Certificate not in allowed list |
+
+## Contributing
+
+```bash
+# Setup
+git clone https://github.com/alanbato/tlacacoca.git
+cd tlacacoca && uv sync
+
+# Test
+uv run pytest
+
+# Lint & Type Check
+uv run ruff check src/ tests/
+uv run ty check src/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Resources
+
+- [SECURITY.md](SECURITY.md) - Security documentation
+- [GitHub Issues](https://github.com/alanbato/tlacacoca/issues) - Bug reports
+- [GitHub Discussions](https://github.com/alanbato/tlacacoca/discussions) - Questions and ideas
+
+---
+
+**Status**: Active development (pre-1.0). Core security and middleware features are stable.

tlacacoca-0.1.3/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "tlacacoca"
+version = "0.1.3"
+description = "Shared foundation library for TLS-based protocol implementations"
+readme = "README.md"
+authors = [
+    { name = "Alan Velasco", email = "alanvelasco.a@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "cryptography>=46.0.3",
+    "structlog>=25.5.0",
+    "tomli>=2.0.0 ; python_full_version < '3.11'",
+    "tomli-w>=1.2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.10,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.2",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.14.11",
+    "ty>=0.0.10",
+]
+docs = [
+    "mkdocs-git-revision-date-localized-plugin>=1.5.0",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings[python]>=1.0.0",
+    "pymdown-extensions>=10.20",
+]

tlacacoca-0.1.3/src/tlacacoca/__init__.py

@@ -0,0 +1,74 @@
+"""tlacacoca - Shared foundation library for TLS-based protocol implementations.
+
+This library provides protocol-agnostic components for building secure
+network protocol clients and servers:
+
+- Security: TLS context creation, certificate utilities, TOFU validation
+- Middleware: Rate limiting, access control, certificate authentication
+- Logging: Structured logging with privacy-preserving IP hashing
+"""
+
+# Security
+from .security.certificates import (
+    generate_self_signed_cert,
+    get_certificate_fingerprint,
+    get_certificate_fingerprint_from_path,
+    get_certificate_info,
+    is_certificate_expired,
+    is_certificate_valid_for_hostname,
+    load_certificate,
+    validate_certificate_file,
+)
+from .security.tls import create_client_context, create_server_context
+from .security.tofu import CertificateChangedError, TOFUDatabase
+
+# Middleware
+from .middleware.access_control import AccessControl, AccessControlConfig
+from .middleware.base import DenialReason, Middleware, MiddlewareChain, MiddlewareResult
+from .middleware.certificate_auth import (
+    CertificateAuth,
+    CertificateAuthConfig,
+    CertificateAuthPathRule,
+)
+from .middleware.rate_limit import RateLimitConfig, RateLimiter, TokenBucket
+
+# Logging
+from .logging.structured import configure_logging, get_logger, hash_ip_processor
+
+__all__ = [
+    # Security - TLS
+    "create_client_context",
+    "create_server_context",
+    # Security - Certificates
+    "generate_self_signed_cert",
+    "load_certificate",
+    "get_certificate_fingerprint",
+    "get_certificate_fingerprint_from_path",
+    "is_certificate_expired",
+    "is_certificate_valid_for_hostname",
+    "get_certificate_info",
+    "validate_certificate_file",
+    # Security - TOFU
+    "TOFUDatabase",
+    "CertificateChangedError",
+    # Middleware - Base
+    "DenialReason",
+    "MiddlewareResult",
+    "Middleware",
+    "MiddlewareChain",
+    # Middleware - Rate limiting
+    "TokenBucket",
+    "RateLimiter",
+    "RateLimitConfig",
+    # Middleware - Access control
+    "AccessControl",
+    "AccessControlConfig",
+    # Middleware - Certificate auth
+    "CertificateAuth",
+    "CertificateAuthConfig",
+    "CertificateAuthPathRule",
+    # Logging
+    "configure_logging",
+    "get_logger",
+    "hash_ip_processor",
+]

tlacacoca-0.1.3/src/tlacacoca/logging/__init__.py

@@ -0,0 +1,9 @@
+"""Logging module for structured logging configuration."""
+
+from .structured import configure_logging, get_logger, hash_ip_processor
+
+__all__ = [
+    "configure_logging",
+    "get_logger",
+    "hash_ip_processor",
+]

tlacacoca-0.1.3/src/tlacacoca/logging/structured.py

@@ -0,0 +1,144 @@
+"""Structured logging configuration using structlog.
+
+This module provides structured logging configuration with privacy-preserving
+features like IP address hashing.
+"""
+
+import hashlib
+import sys
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+
+def hash_ip_processor(
+    logger: Any, method_name: str, event_dict: dict[str, Any]
+) -> dict[str, Any]:
+    """Hash IP addresses in log events for privacy.
+
+    IP addresses should be hashed in logs to protect user privacy while
+    still allowing abuse detection.
+
+    Args:
+        logger: The logger instance.
+        method_name: The logging method name.
+        event_dict: The event dictionary.
+
+    Returns:
+        The event dictionary with client_ip replaced by client_ip_hash.
+    """
+    if "client_ip" in event_dict:
+        ip = event_dict["client_ip"]
+        if ip and ip != "unknown":
+            # SHA256 hash, truncated to 12 chars for readability
+            hashed = hashlib.sha256(ip.encode()).hexdigest()[:12]
+            event_dict["client_ip_hash"] = hashed
+            del event_dict["client_ip"]
+    return event_dict
+
+
+def configure_logging(
+    log_level: str = "INFO",
+    log_file: Path | None = None,
+    json_logs: bool = False,
+    hash_ips: bool = True,
+) -> None:
+    """Configure structured logging for the application.
+
+    This function should be called once at application startup. When using
+    a log file, the file handle remains open for the application lifetime.
+
+    Args:
+        log_level: Logging level (DEBUG, INFO, WARNING, ERROR).
+        log_file: Optional path to log file. If None, logs to stdout.
+            The file is opened in append mode and remains open.
+        json_logs: If True, output logs in JSON format. Otherwise, use
+            human-readable format.
+        hash_ips: If True (default), hash client IP addresses in logs
+            for privacy.
+
+    Examples:
+        >>> # Configure for development (human-readable console output)
+        >>> configure_logging(log_level="DEBUG")
+
+        >>> # Configure for production (JSON logs to file, hashed IPs)
+        >>> configure_logging(
+        ...     log_level="INFO",
+        ...     log_file=Path("/var/log/myapp.log"),
+        ...     json_logs=True,
+        ...     hash_ips=True
+        ... )
+    """
+    # Determine output stream
+    if log_file:
+        output_stream = open(log_file, "a")
+    else:
+        output_stream = sys.stdout
+
+    # Build base processors
+    base_processors: list[Any] = [
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.TimeStamper(
+            fmt="iso" if json_logs else "%Y-%m-%d %H:%M:%S"
+        ),
+    ]
+
+    # Add IP hashing processor if enabled (for privacy)
+    if hash_ips:
+        base_processors.append(hash_ip_processor)
+
+    # Configure output format
+    if json_logs:
+        # JSON format for production/structured logging
+        processors = base_processors + [structlog.processors.JSONRenderer()]
+    else:
+        # Human-readable format for development
+        processors = base_processors + [
+            structlog.dev.ConsoleRenderer(colors=output_stream.isatty())
+        ]
+
+    # Configure structlog
+    structlog.configure(
+        processors=processors,
+        wrapper_class=structlog.make_filtering_bound_logger(_level_to_int(log_level)),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=output_stream),
+        cache_logger_on_first_use=True,
+    )
+
+
+def _level_to_int(level: str) -> int:
+    """Convert string log level to integer.
+
+    Args:
+        level: Log level string (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+
+    Returns:
+        Integer log level.
+    """
+    levels = {
+        "DEBUG": 10,
+        "INFO": 20,
+        "WARNING": 30,
+        "ERROR": 40,
+        "CRITICAL": 50,
+    }
+    return levels.get(level.upper(), 20)
+
+
+def get_logger(name: str) -> structlog.BoundLogger:
+    """Get a logger instance for a module.
+
+    Args:
+        name: Logger name (typically __name__).
+
+    Returns:
+        A structlog BoundLogger instance.
+
+    Examples:
+        >>> logger = get_logger(__name__)
+        >>> logger.info("server_started", host="localhost", port=1965)
+    """
+    return structlog.get_logger(name)

tlacacoca-0.1.3/src/tlacacoca/middleware/__init__.py

@@ -0,0 +1,29 @@
+"""Middleware module for request processing, rate limiting, and access control."""
+
+from .access_control import AccessControl, AccessControlConfig
+from .base import DenialReason, Middleware, MiddlewareChain, MiddlewareResult
+from .certificate_auth import (
+    CertificateAuth,
+    CertificateAuthConfig,
+    CertificateAuthPathRule,
+)
+from .rate_limit import RateLimitConfig, RateLimiter, TokenBucket
+
+__all__ = [
+    # Base
+    "DenialReason",
+    "MiddlewareResult",
+    "Middleware",
+    "MiddlewareChain",
+    # Rate limiting
+    "TokenBucket",
+    "RateLimiter",
+    "RateLimitConfig",
+    # Access control
+    "AccessControl",
+    "AccessControlConfig",
+    # Certificate auth
+    "CertificateAuth",
+    "CertificateAuthConfig",
+    "CertificateAuthPathRule",
+]