Tlacacoca Integration¶

Tlacacoca is Titlani's foundational dependency for TLS, certificates, TOFU, and middleware. This page explains the boundary between the two libraries.

What Tlacacoca Provides¶

Tlacacoca is a general-purpose TLS and certificate toolkit for Gemini-family protocols. Titlani uses:

Component	Usage
`create_client_context()`	TLS context for `MisfinClient`
`create_server_context()`	TLS context for the Misfin server
`generate_self_signed_cert()`	Auto-generated server TLS certificates
`TOFUDatabase`	Trust-On-First-Use fingerprint storage
`CertificateChangedError`	Raised when TOFU detects a fingerprint mismatch
`get_certificate_fingerprint()`	Compute certificate fingerprints
`load_certificate()`	Load PEM certificates
`MiddlewareChain`	Composable request middleware
`RateLimiter`	Token bucket rate limiting middleware
`AccessControl`	IP allow/deny middleware
`DenialReason`	Middleware denial reasons (mapped to Misfin status codes)
Structured logging	Request/error logging via `structlog`

What Titlani Adds¶

Titlani provides everything Misfin-specific that doesn't belong in a generic TLS toolkit:

Component	Why Not in Tlacacoca
`generate_identity_cert()`	Misfin needs USER_ID for mailbox and CN for blurb — a custom certificate layout
`MisfinIdentity`	Misfin-specific identity representation
`extract_identity()`	Reads Misfin-specific fields from certificates
`normalize_fingerprint()`	Bridges tlacacoca's `sha256:hex` format to Misfin's plain hex
`MisfinRequest` / `MisfinResponse`	Misfin wire format
`GemmailMessage` / `MisfinAddress`	Gemmail message format
`MisfinClient` / `MisfinServerProtocol`	Misfin-specific async I/O
`ServerConfig` / `FileMailboxHandler`	Server configuration and storage

Why `generate_identity_cert` Is Separate¶

Tlacacoca's generate_self_signed_cert() creates standard TLS certificates with:

Common Name (CN): hostname
SAN DNS: hostname

Misfin identity certificates need:

USER_ID: mailbox name
Common Name (CN): human-readable blurb
SAN DNS: hostname

The USER_ID OID (0.9.2342.19200300.100.1.1) is an uncommon extension not supported by tlacacoca's generic API. Rather than adding Misfin-specific parameters to tlacacoca, Titlani implements generate_identity_cert() using cryptography directly.

The server uses both certificate types:

Server TLS certificate — Generated by tlacacoca.generate_self_signed_cert() (standard layout)
Server identity certificate — Generated by generate_identity_cert() (Misfin layout, for postmaster@hostname)

The Fingerprint Bridge¶

Tlacacoca computes fingerprints in the format sha256:hexdigest (uppercase, colon-separated). Misfin(C) expects plain lowercase hex with no prefix or delimiters.

The normalize_fingerprint() function sits at every boundary:

from titlani import normalize_fingerprint

# Input from tlacacoca
tlacacoca_fp = "sha256:A1B2C3D4E5F6..."

# Output for Misfin
misfin_fp = normalize_fingerprint(tlacacoca_fp)
# "a1b2c3d4e5f6..."

This is used when:

Setting client_cert_fingerprint on incoming requests
Returning fingerprints in success responses
Comparing fingerprints during TOFU validation

Upgrade Path¶

When tlacacoca adds new features (e.g., new middleware types, improved TOFU storage), Titlani can adopt them with minimal changes since the integration points are well-defined. The normalize_fingerprint() bridge and the separate generate_identity_cert() are the only Misfin-specific adaptations.