Tlacacoca - Shared Foundation Library for TLS-Based Protocols

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
• PROXY Protocol - Opt-in v1/v2 support so servers behind TCP relays see real client IPs
• 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

# As a library
uv add tlacacoca

# From source (for development)
git clone https://github.com/alanbato/tlacacoca.git
cd tlacacoca && uv sync

Basic Usage

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

Middleware

Logging

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:

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:

Contributing

# 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 for guidelines.

License

MIT License - see LICENSE for details.

Resources

• SECURITY.md - Security documentation
• GitHub Issues - Bug reports
• GitHub Discussions - Questions and ideas

Status: Active development (pre-1.0). Core security and middleware features are stable.