certifi 2026.7.22: certifi

# certifi Root Certificate Discovery and SSL Context Integration

## Prior Solution Found
`search_known_solution` returned `NO_SAFE_MATCH` for the general `certifi` symbol verification in `pkg:pypi/certifi@2026.7.22`.

## What a Model Would Have Written
A model implementing root CA certificate configuration often:
1. Confuses `certifi.where()` with reading certificate data directly, attempting to pass the path string to APIs expecting PEM text (`cadata`), leading to `SSLError` or X.509 parse failures.
2. Conversely, passes `certifi.contents()` (the full certificate text) into parameters expecting a file path (`cafile`), resulting in `ValueError: embedded null byte` or `FileNotFoundError` (file name too long).
3. Hardcodes filesystem operations with `open(certifi.where())` instead of using `certifi.contents()`. In bundled or standalone environments (e.g. zipapps, PyInstaller binaries, embedded interpreters), file paths may not resolve to raw filesystem locations, whereas `certifi.contents()` uses `importlib.resources` safely.
4. Assumes `certifi` provides an active network validation client or request wrapper, rather than providing the curated Mozilla root CA bundle used by TLS libraries like `ssl`, `urllib3`, or `requests`.
5. Misunderstands `certifi.__version__` CalVer formatting or fails to verify that `where` and `contents` are the primary exported functions defined in `__all__`.

## How the Wrong Version Fails
- Passing `certifi.where()` to `ssl.create_default_context(cadata=...)` fails with `ssl.SSLError: PEM lib (_ssl.c:3095)` because the path string is not a PEM-encoded certificate.
- Passing `certifi.contents()` to `ssl.create_default_context(cafile=...)` fails with `OSError: [Errno 36] File name too long` because `cafile` expects a disk path rather than a multi-megabyte PEM string.
- Using direct file reading on `certifi.where()` can fail with `FileNotFoundError` when running inside zipped packages or sandboxed runtimes where standard resource extraction via `certifi.contents()` is required.

## The Correct Implementation
- Use `certifi.where()` when configuring clients or contexts that take a filesystem path (`cafile`).
- Use `certifi.contents()` when configuring contexts in-memory (`cadata`), providing identical root CA trust anchors without disk dependencies.
- Verify that both file-based and memory-based certificate loading produce an identical set of trusted root CAs in Python's standard `ssl.SSLContext`.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify certifi in pkg:pypi/certifi@2026.7.22
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:pypi/certifi@2026.7.22
Demonstrate these symbols/APIs:
  - certifi

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:458781904cd279bab345599f3d2cb1d096b0f81143f440bb38bd4164b89d7fe0","contract":["certifi exports where and contents in __all__ with release version starting with 2026","certifi.where returns an absolute path to a readable cacert.pem file containing root certificates","certifi.contents returns a non-empty string of PEM formatted certificates without requiring filesystem path access","ssl.create_default_context with cafile from certifi.where loads valid trusted root CA certificates","ssl.create_default_context with cadata from certifi.contents loads the identical set of trusted root CA certificates"],"goal":"verify certifi in pkg:pypi/certifi@2026.7.22","kind":"HOW","packages":["pkg:pypi/certifi@2026.7.22"],"schemaVersion":1,"symbols":["certifi"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"pypi","executionContext":"python","language":"python","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/certifi@2026.7.22"],"schemaVersion":1,"subject":"pkg:pypi/certifi@2026.7.22","symbols":["certifi"],"verifierAdapter":"python@1"}

certifi==2026.7.22

"""Sample demonstrating root CA certificate discovery and SSL context configuration with certifi."""

import os
import ssl
from typing import List, Tuple
import certifi


def get_certifi_version() -> str:
    """Return the release version of certifi."""
    return getattr(certifi, "__version__", "")


def get_ca_bundle_path() -> str:
    """Return the filesystem path to the Mozilla CA certificate bundle."""
    return certifi.where()


def get_ca_bundle_contents() -> str:
    """Return the text content of the Mozilla CA certificate bundle in PEM format."""
    return certifi.contents()


def create_ssl_context_from_file() -> ssl.SSLContext:
    """Create an SSL context using cafile path from certifi.where()."""
    ca_path = get_ca_bundle_path()
    return ssl.create_default_context(cafile=ca_path)


def create_ssl_context_from_memory() -> ssl.SSLContext:
    """Create an SSL context using cadata string from certifi.contents()."""
    ca_data = get_ca_bundle_contents()
    return ssl.create_default_context(cadata=ca_data)


def get_loaded_ca_certs(ctx: ssl.SSLContext) -> List[dict]:
    """Return the list of parsed CA certificates loaded into the SSL context."""
    return ctx.get_ca_certs(binary_form=False)


def verify_bundle_file() -> Tuple[str, bool, int]:
    """Verify that the CA bundle path exists and return its path, existence, and size."""
    bundle_path = get_ca_bundle_path()
    exists = os.path.isfile(bundle_path)
    file_size = os.path.getsize(bundle_path) if exists else 0
    return bundle_path, exists, file_size

{
  "schemaVersion": 1,
  "goal": "verify certifi in pkg:pypi/certifi@2026.7.22",
  "kind": "HOW",
  "packages": [
    "pkg:pypi/certifi@2026.7.22"
  ],
  "symbols": [
    "certifi"
  ]
}

"""Contract verification test for pkg:pypi/certifi@2026.7.22."""

import os
import ssl
import sys

# Ensure sample module can be imported from parent directory
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

import certifi
from sample import (
    create_ssl_context_from_file,
    create_ssl_context_from_memory,
    get_ca_bundle_contents,
    get_ca_bundle_path,
    get_certifi_version,
    get_loaded_ca_certs,
    verify_bundle_file,
)


def test_certifi_exports_and_version():
    """Assertion 1: certifi exports where and contents in __all__ with release version starting with 2026."""
    assert hasattr(certifi, "__all__"), "certifi must define __all__"
    assert "where" in certifi.__all__, "certifi.__all__ must export 'where'"
    assert "contents" in certifi.__all__, "certifi.__all__ must export 'contents'"

    version = get_certifi_version()
    assert isinstance(version, str) and len(version) > 0, "certifi.__version__ must be non-empty string"
    assert version.startswith("2026."), f"Expected certifi 2026.x release, got {version}"


def test_where_returns_valid_cacert_path():
    """Assertion 2: certifi.where returns an absolute path to a readable cacert.pem file containing root certificates."""
    path = get_ca_bundle_path()
    assert isinstance(path, str) and len(path) > 0, "certifi.where() must return a non-empty string"
    assert os.path.isabs(path), f"certifi.where() path must be absolute: {path}"
    assert path.endswith("cacert.pem"), f"certifi.where() should end with cacert.pem: {path}"

    bundle_path, exists, size = verify_bundle_file()
    assert exists is True, f"CA bundle file must exist at {bundle_path}"
    assert size > 100000, f"CA bundle size must be substantial (>100KB), got {size}"
    assert os.access(bundle_path, os.R_OK), f"CA bundle file must be readable: {bundle_path}"

    with open(bundle_path, "r", encoding="utf-8", errors="replace") as f:
        file_content = f.read()

    assert "-----BEGIN CERTIFICATE-----" in file_content, "CA bundle file must contain PEM certificate blocks"
    assert "-----END CERTIFICATE-----" in file_content, "CA bundle file must contain valid PEM certificates"


def test_contents_returns_pem_string():
    """Assertion 3: certifi.contents returns a non-empty string of PEM formatted certificates without requiring filesystem path access."""
    data = get_ca_bundle_contents()
    assert isinstance(data, str), f"certifi.contents() must return str, got {type(data)}"
    assert len(data) > 100000, f"certifi.contents() must contain root certs (>100KB), got {len(data)}"
    assert "-----BEGIN CERTIFICATE-----" in data, "certifi.contents() must contain BEGIN CERTIFICATE"
    assert "-----END CERTIFICATE-----" in data, "certifi.contents() must contain END CERTIFICATE"


def test_ssl_context_with_cafile():
    """Assertion 4: ssl.create_default_context with cafile from certifi.where loads valid trusted root CA certificates."""
    ctx = create_ssl_context_from_file()
    assert isinstance(ctx, ssl.SSLContext), "Context must be an ssl.SSLContext"
    assert ctx.verify_mode == ssl.CERT_REQUIRED, "verify_mode must be CERT_REQUIRED"

    certs = get_loaded_ca_certs(ctx)
    assert isinstance(certs, list), "ctx.get_ca_certs() must return a list"
    assert len(certs) >= 100, f"Mozilla CA bundle must contain at least 100 root certs, found {len(certs)}"

    sample_cert = certs[0]
    assert "subject" in sample_cert, "Parsed certificate must have subject field"
    assert "issuer" in sample_cert, "Parsed certificate must have issuer field"
    assert "serialNumber" in sample_cert, "Parsed certificate must have serialNumber field"


def test_ssl_context_with_cadata_parity():
    """Assertion 5: ssl.create_default_context with cadata from certifi.contents loads the identical set of trusted root CA certificates."""
    ctx_file = create_ssl_context_from_file()
    ctx_data = create_ssl_context_from_memory()

    certs_file = get_loaded_ca_certs(ctx_file)
    certs_data = get_loaded_ca_certs(ctx_data)

    assert len(certs_file) == len(certs_data), (
        f"Certificate counts must match between cafile ({len(certs_file)}) and cadata ({len(certs_data)})"
    )

    subjects_file = [c.get("subject") for c in certs_file]
    subjects_data = [c.get("subject") for c in certs_data]
    assert subjects_file == subjects_data, "CA certificate subjects must be identical between file and memory loads"


def main():
    test_certifi_exports_and_version()
    test_where_returns_valid_cacert_path()
    test_contents_returns_pem_string()
    test_ssl_context_with_cafile()
    test_ssl_context_with_cadata_parity()
    print("All certifi contract assertions passed successfully.")


if __name__ == "__main__":
    main()