api.py

"""
api.py — PeerGlass REST API
============================
A thin FastAPI wrapper around the same rir_client.py logic that powers
the MCP server. This makes every tool available as a plain HTTP endpoint,
compatible with any LLM (OpenAI function calling, Gemini tool use, etc.),
any HTTP client, or any browser.

Architecture:
                ┌─────────────────────────────────────┐
                │         Your Code / LLM              │
                │  (Claude, OpenAI, Gemini, curl, ...)  │
                └──────────────┬──────────────────────┘
                               │  HTTP REST
                               ▼
                ┌─────────────────────────────────────┐
                │         api.py  (FastAPI)             │
                │   /v1/ip   /v1/asn   /v1/health ...  │
                └──────────────┬──────────────────────┘
                               │  Python call (same code)
                               ▼
                ┌─────────────────────────────────────┐
                │      rir_client.py  (shared logic)    │
                │  RDAP · RPKI · BGP · PeeringDB · ...  │
                └─────────────────────────────────────┘

Running locally:
    uvicorn api:app --host 0.0.0.0 --port 8000 --reload

Interactive docs (auto-generated by FastAPI):
    http://localhost:8000/docs       ← Swagger UI
    http://localhost:8000/redoc      ← ReDoc

All endpoints accept ?format=markdown (default) or ?format=json
"""

import sys
import os
sys.path.insert(0, os.path.dirname(__file__))

from fastapi import FastAPI, Query, HTTPException, Request
from fastapi.middleware.cors import CORSMiddleware
from fastapi.responses import JSONResponse, PlainTextResponse
from pydantic import BaseModel, Field
from typing import Optional
import asyncio

from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded


def _real_ip(request: Request) -> str:
    """
    Extract the real client IP, respecting X-Forwarded-For and X-Real-IP
    headers set by reverse proxies (Render, nginx, Cloudflare, etc.).
    Falls back to direct connection address if no proxy headers are present.
    """
    forwarded_for = request.headers.get("X-Forwarded-For")
    if forwarded_for:
        return forwarded_for.split(",")[0].strip()
    real_ip = request.headers.get("X-Real-IP")
    if real_ip:
        return real_ip.strip()
    return get_remote_address(request)


limiter = Limiter(key_func=_real_ip)

import rir_client
import cache as cache_module
from formatters import (
    format_ip_results_md,
    format_asn_results_md,
    format_abuse_contact_md,
    format_rpki_result_md,
    format_bgp_status_md,
    format_org_audit_md,
    format_prefix_history_md,
    format_transfer_detect_md,
    format_ipv4_stats_md,
    format_prefix_overview_md,
    format_peering_info_md,
    format_ixp_lookup_md,
    format_network_health_md,
    format_change_monitor_md,
    format_dns_resolve_md,
    format_dns_enumerate_md,
    format_dns_dnssec_md,
    format_dns_dnsbl_md,
    format_email_security_md,
    format_dns_propagation_md,
    format_tls_inspect_md,
    format_ct_logs_md,
    format_threat_intel_md,
    format_passive_dns_md,
    format_irr_result_md,
    format_route_leak_md,
    format_looking_glass_md,
    format_route_stability_md,
    format_shutdown_detect_md,
    format_monitor_register_md,
    format_shutdown_timeline_md,
    format_censorship_probe_md,
    format_satellite_connectivity_md,
    format_chokepoints_md,
    format_ooni_report_md,
    format_country_health_md,
    format_as_relationships_md,
    format_geo_lookup_md,
    format_atlas_trace_md,
    to_json,
)
from normalizer import normalize_ip_response, normalize_asn_response
from models import (
    AbuseContact, OrgAuditResult,
    ResponseFormat,
    DNSResolveInput, DNSEnumerateInput, DNSSECInput,
    DNSBLInput, EmailSecurityInput, DNSPropagationInput,
    TLSInspectInput, CTLogInput, ThreatIntelInput, PassiveDNSInput,
    MonitorRegisterInput,
)

# ──────────────────────────────────────────────────────────────
# App setup
# ──────────────────────────────────────────────────────────────

app = FastAPI(
    title="PeerGlass API",
    description=(
        "Universal REST API for internet resource intelligence. "
        "Query all 5 RIRs (AFRINIC, APNIC, ARIN, LACNIC, RIPE), "
        "validate RPKI routes, check BGP status, look up PeeringDB, "
        "trace allocation history, and monitor resources for changes.\n\n"
        "Compatible with any HTTP client, LLM function-calling interface "
        "(OpenAI, Gemini, Claude), or browser.\n\n"
        "Source: https://github.com/peerglass/peerglass  "
        "| License: MIT"
    ),
    version="1.0.0",
    contact={
        "name": "PeerGlass",
        "url": "https://peerglass.io",
    },
    license_info={
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    },
)

# B1 — Rate limiting: protects upstream RIRs from being hammered by abusive clients.
# Default: 60 req/min per IP. Heavy endpoints (org audit, health) use 10/min.
# Override with PEERGLASS_RATE_LIMIT env var (e.g. "120/minute").
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
_DEFAULT_RATE = os.environ.get("PEERGLASS_RATE_LIMIT", "60/minute")
_HEAVY_RATE   = os.environ.get("PEERGLASS_RATE_LIMIT_HEAVY", "10/minute")

# B2 — CORS: restrict allowed origins in production via env var.
# Set PEERGLASS_ALLOWED_ORIGINS="https://yourdomain.com,https://other.com"
# Defaults to "*" (open) when env var is absent — suitable for local/demo use.
_cors_env = os.environ.get("PEERGLASS_ALLOWED_ORIGINS", "")
_cors_origins = [o.strip() for o in _cors_env.split(",") if o.strip()] if _cors_env else ["*"]
app.add_middleware(
    CORSMiddleware,
    allow_origins=_cors_origins,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)

# ──────────────────────────────────────────────────────────────
# Helpers
# ──────────────────────────────────────────────────────────────

FORMAT_QUERY = Query(
    default="markdown",
    description="Response format: 'markdown' for human-readable, 'json' for machine-readable",
    pattern="^(markdown|json)$",
)

def _resp(md: str, jsn: str, fmt: str):
    """Return markdown as plain text or json as JSON based on format param."""
    if fmt == "json":
        import json
        try:
            return JSONResponse(content=json.loads(jsn))
        except Exception:
            return JSONResponse(content={"raw": jsn})
    return PlainTextResponse(content=md, media_type="text/markdown")


# ──────────────────────────────────────────────────────────────
# Root + Health
# ──────────────────────────────────────────────────────────────

@app.get("/", tags=["Meta"], summary="API root — links to docs")
async def root():
    return {
        "name": "PeerGlass API",
        "version": "1.0.0",
        "description": "Internet resource intelligence: RIR + BGP + RPKI + PeeringDB",
        "docs": "/docs",
        "redoc": "/redoc",
        "tools": 42,
        "endpoints": {
            "ip":              "/v1/ip/{ip}",
            "asn":             "/v1/asn/{asn}",
            "abuse":           "/v1/abuse/{ip}",
            "rpki":            "/v1/rpki?prefix=...&asn=...",
            "bgp":             "/v1/bgp/{resource}",
            "announced":       "/v1/announced/{asn}",
            "org":             "/v1/org?name=...",
            "history":         "/v1/history/{resource}",
            "transfers":       "/v1/transfers/{resource}",
            "ipv4stats":       "/v1/stats/ipv4",
            "overview":        "/v1/overview/{prefix}",
            "peering":         "/v1/peering/{asn}",
            "ixp":             "/v1/ixp?query=...",
            "health":          "/v1/health/{resource}",
            "monitor":         "/v1/monitor/{resource}",
            "dns_resolve":     "/v1/dns/resolve/{target}",
            "dns_enumerate":   "/v1/dns/enumerate/{domain}",
            "dns_dnssec":      "/v1/dns/dnssec/{domain}",
            "dns_dnsbl":       "/v1/dns/dnsbl/{ip}",
            "dns_email":       "/v1/dns/email/{domain}",
            "dns_propagation": "/v1/dns/propagation/{domain}",
            "tls":             "/v1/tls/{hostname}",
            "ct_logs":         "/v1/ct/{domain}",
            "threat_intel":    "/v1/threat/{ip}",
            "passive_dns":     "/v1/pdns/{resource}",
            "irr":             "/v1/irr?prefix=...&asn=...",
            "route_leak":      "/v1/route-leak/{prefix}",
            "looking_glass":   "/v1/looking-glass/{prefix}",
            "route_stability": "/v1/stability/{prefix}",
            "shutdown":        "/v1/shutdown/{country_code}",
            "shutdown_monitor":"/v1/shutdown/monitor",
            "shutdown_timeline":"/v1/shutdown/timeline/{resource}",
            "dns_censorship":  "/v1/censorship/{domain}",
            "satellite":       "/v1/satellite/{country_code}",
            "chokepoints":     "/v1/chokepoints/{country_code}",
            "ooni":            "/v1/ooni/{country_code}",
            "country_health":  "/v1/health/country/{country_code}",
            "as_relationships": "/v1/as-relationships/{asn}",
            "geo":              "/v1/geo/{ip}",
            "atlas":            "/v1/atlas/{target}",
            "bulk":             "/v1/bulk  (POST)",
            "cache_stats":     "/v1/meta/cache",
            "server_status":   "/v1/meta/status",
        },
    }


@app.get("/v1/meta/cache", tags=["Meta"], summary="Cache statistics")
@limiter.limit(_DEFAULT_RATE)
async def meta_cache(request: Request):
    """Returns the current in-memory cache health: total entries, alive, expired."""
    return cache_module.stats()


@app.get("/v1/meta/status", tags=["Meta"], summary="RIR server reachability")
@limiter.limit(_DEFAULT_RATE)
async def meta_status(request: Request):
    """Pings all 5 RIR RDAP servers and returns their status."""
    statuses = await rir_client.get_rir_server_status()
    return statuses


# ──────────────────────────────────────────────────────────────
# Phase 1 — RDAP Lookups
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/ip/{ip}",
    tags=["RDAP"],
    summary="Who owns this IP address?",
    response_description="Registration info from the authoritative RIR",
)
@limiter.limit(_DEFAULT_RATE)
async def query_ip(
    request: Request,
    ip: str,
    format: str = FORMAT_QUERY,
):
    """
    Query all 5 RIRs and return the authoritative RDAP registration
    for an IPv4 or IPv6 address.

    Returns: holder, org, RIR, country, allocation dates, abuse contact.

    **Examples:** `1.1.1.1`, `8.8.8.8`, `2001:4860:4860::8888`
    """
    cache_key = cache_module.make_ip_key(ip)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    results = await rir_client.query_ip_all_rirs(ip)
    normalized = []
    for r in results:
        if r.status == "ok" and r.data:
            try:
                normalized.append(normalize_ip_response(r.rir.value, r.data))
            except Exception:
                pass

    if not normalized:
        # J3: RDAP returned nothing — try raw WHOIS port-43 fallback
        whois_result = await rir_client.get_whois_fallback(ip, "ip")
        if whois_result and whois_result.data:
            try:
                normalized.append(normalize_ip_response(whois_result.rir.value, whois_result.data))
                results.append(whois_result)
            except Exception:
                pass
    if not normalized:
        errors = [r.error for r in results if r.error]
        err_detail = "; ".join(errors) if errors else "all RIRs returned no data"
        md  = f"## IP Lookup: `{ip}`\n\n> ⚠️ No RDAP record found. {err_detail}\n\n"
        md += "_This IP may be unallocated, reserved, or all RIR RDAP servers are unreachable._\n"
        jsn = to_json({"ip": ip, "error": f"No RDAP record found for {ip}", "details": errors})
        return _resp(md, jsn, format)

    md  = format_ip_results_md(ip, normalized, results)
    jsn = to_json({"ip": ip, "results": [r.model_dump(exclude={"data"}) for r in results],
                   "normalized": [n.model_dump(exclude={"raw"}) for n in normalized]})
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_IP)
    return _resp(md, jsn, format)


@app.get(
    "/v1/asn/{asn}",
    tags=["RDAP"],
    summary="Who owns this Autonomous System Number?",
)
@limiter.limit(_DEFAULT_RATE)
async def query_asn(
    request: Request,
    asn: str,
    format: str = FORMAT_QUERY,
):
    """
    Query all 5 RIRs for the RDAP registration of an ASN.

    Returns: org name, RIR, country, allocation date, contact info.

    **Examples:** `AS13335`, `AS15169`, `13335`
    """
    cache_key = cache_module.make_asn_key(asn)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    results = await rir_client.query_asn_all_rirs(asn)
    normalized = []
    for r in results:
        if r.status == "ok" and r.data:
            try:
                normalized.append(normalize_asn_response(r.rir.value, r.data))
            except Exception:
                pass

    if not normalized:
        # J3: RDAP returned nothing — try raw WHOIS port-43 fallback
        whois_result = await rir_client.get_whois_fallback(asn, "asn")
        if whois_result and whois_result.data:
            try:
                normalized.append(normalize_asn_response(whois_result.rir.value, whois_result.data))
                results.append(whois_result)
            except Exception:
                pass
    if not normalized:
        errors = [r.error for r in results if r.error]
        err_detail = "; ".join(errors) if errors else "all RIRs returned no data"
        md  = f"## ASN Lookup: `{asn}`\n\n> ⚠️ No RDAP record found. {err_detail}\n\n"
        md += "_This ASN may be unallocated or all RIR RDAP servers are unreachable._\n"
        jsn = to_json({"asn": asn, "error": f"No RDAP record found for {asn}", "details": errors})
        return _resp(md, jsn, format)

    md  = format_asn_results_md(asn, normalized, results)
    jsn = to_json({"asn": asn, "results": [r.model_dump(exclude={"data"}) for r in results],
                   "normalized": [n.model_dump(exclude={"raw"}) for n in normalized]})
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_ASN)
    return _resp(md, jsn, format)


@app.get(
    "/v1/abuse/{ip}",
    tags=["RDAP"],
    summary="Who do I report abuse to for this IP?",
)
@limiter.limit(_DEFAULT_RATE)
async def get_abuse_contact(
    request: Request,
    ip: str,
    format: str = FORMAT_QUERY,
):
    """
    Find the abuse contact email for an IP address.
    Use this to report spam, DDoS, or other abuse from that IP.

    **Examples:** `185.220.101.45`, `1.1.1.1`
    """
    cache_key = cache_module.make_abuse_key(ip)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    contact = await rir_client.get_abuse_contact(ip)
    md  = format_abuse_contact_md(contact)
    jsn = to_json(contact)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_ABUSE)
    return _resp(md, jsn, format)


# ──────────────────────────────────────────────────────────────
# Phase 2 — RPKI + BGP
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/rpki",
    tags=["Routing Security"],
    summary="Is this BGP route RPKI valid?",
)
@limiter.limit(_DEFAULT_RATE)
async def check_rpki(
    request: Request,
    prefix: str = Query(..., description="IP prefix in CIDR notation, e.g. '1.1.1.0/24'"),
    asn: str    = Query(..., description="Origin ASN, e.g. 'AS13335' or '13335'"),
    format: str = FORMAT_QUERY,
):
    """
    Validate a BGP route using RPKI (Resource Public Key Infrastructure).

    RPKI uses cryptographic certificates (ROAs) to prove which ASN is
    authorized to announce a given prefix. An **invalid** result means
    the announcement is NOT authorized — potential BGP hijack.

    Results: `valid` | `invalid` | `not-found` | `unknown`
    """
    asn_num = asn.upper().lstrip("AS")
    cache_key = cache_module.make_rpki_key(prefix, asn_num)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.check_rpki(prefix, asn_num)
    md  = format_rpki_result_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_RPKI)
    return _resp(md, jsn, format)


@app.get(
    "/v1/bgp/{resource:path}",
    tags=["Routing Security"],
    summary="Is this prefix/ASN visible in global BGP?",
)
@limiter.limit(_DEFAULT_RATE)
async def check_bgp(
    request: Request,
    resource: str,
    format: str = FORMAT_QUERY,
):
    """
    Check if a prefix or ASN is currently announced in the global BGP routing table.

    Returns: announcement status, originating ASN(s), visibility percentage
    (% of BGP route collectors that see this route).

    **Examples:** `1.1.1.0/24`, `AS13335`, `8.8.8.0/24`
    """
    cache_key = cache_module.make_bgp_key(resource)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_bgp_status(resource)
    md  = format_bgp_status_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_BGP)
    return _resp(md, jsn, format)


@app.get(
    "/v1/announced/{asn}",
    tags=["Routing Security"],
    summary="What prefixes is this ASN announcing?",
)
@limiter.limit(_DEFAULT_RATE)
async def get_announced(
    request: Request,
    asn: str,
    format: str = FORMAT_QUERY,
):
    """
    List all IP prefixes currently announced by an ASN in the global BGP table.

    **Examples:** `AS13335`, `AS15169`
    """
    asn_num = asn.upper().lstrip("AS")
    cache_key = cache_module.make_bgp_key(f"announced-{asn_num}")
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_announced_prefixes(asn_num)
    from formatters import format_announced_prefixes_md
    md  = format_announced_prefixes_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_BGP)
    return _resp(md, jsn, format)


@app.get(
    "/v1/org",
    tags=["RDAP"],
    summary="Find all internet resources for an organization",
)
@limiter.limit(_HEAVY_RATE)
async def audit_org(
    request: Request,
    name: str = Query(..., description="Organization name or handle, e.g. 'Cloudflare' or 'GOOGL-ARIN'"),
    format: str = FORMAT_QUERY,
):
    """
    Search all 5 RIRs for every IP block and ASN registered to an organization.

    Useful for M&A due diligence, security research, or footprint mapping.

    **Examples:** `Cloudflare`, `GOOGL-ARIN`, `Amazon`
    """
    cache_key = cache_module.make_org_key(name)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    resources, errors = await rir_client.search_org_all_rirs(name)
    ip_blocks = [r for r in resources if r.resource_type in ("ip", "entity")]
    asns      = [r for r in resources if r.resource_type == "asn"]
    audit = OrgAuditResult(
        org_query       = name,
        total_resources = len(resources),
        ip_blocks       = ip_blocks,
        asns            = asns,
        rirs_found_in   = list({r.rir for r in resources}),
        errors          = errors,
    )
    md  = format_org_audit_md(audit)
    jsn = to_json(audit)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_ORG)
    return _resp(md, jsn, format)


# ──────────────────────────────────────────────────────────────
# Phase 3 — History + Stats
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/history/{resource:path}",
    tags=["History"],
    summary="Full registration history for a prefix or ASN",
)
@limiter.limit(_DEFAULT_RATE)
async def prefix_history(
    request: Request,
    resource: str,
    format: str = FORMAT_QUERY,
):
    """
    Chronological timeline of every ownership and status change ever recorded
    for an IP prefix or ASN. Best coverage for RIPE NCC resources.

    **Examples:** `8.8.8.0/24`, `AS15169`, `1.1.1.0/24`
    """
    cache_key = cache_module.make_history_key(resource)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_prefix_history(resource)
    md  = format_prefix_history_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_HISTORY)
    return _resp(md, jsn, format)


@app.get(
    "/v1/transfers/{resource:path}",
    tags=["History"],
    summary="Detect cross-org or cross-RIR resource transfers",
)
@limiter.limit(_DEFAULT_RATE)
async def detect_transfers(
    request: Request,
    resource: str,
    format: str = FORMAT_QUERY,
):
    """
    Detect past ownership or cross-RIR transfers for an IP prefix or ASN.
    Transfer types: org change 🏢, inter-RIR 🌍→🌎, intra-RIR 🔄

    **Examples:** `8.8.8.0/24`, `AS15169`
    """
    cache_key = cache_module.make_transfer_key(resource)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.detect_transfers(resource)
    md  = format_transfer_detect_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_TRANSFER)
    return _resp(md, jsn, format)


@app.get(
    "/v1/stats/ipv4",
    tags=["Statistics"],
    summary="Global IPv4 / IPv6 / ASN exhaustion dashboard",
)
@limiter.limit(_DEFAULT_RATE)
async def ipv4_stats(
    request: Request,
    rir: Optional[str] = Query(
        default=None,
        description="Filter to one RIR: AFRINIC, APNIC, ARIN, LACNIC, or RIPE. Leave empty for all 5.",
    ),
    include_blocks: bool = Query(
        default=False,
        description="Include raw delegated IPv4 block rows. Requires rir to be set.",
    ),
    status: Optional[str] = Query(
        default=None,
        description="Optional status filter for block rows: allocated, assigned, available (free is normalized).",
    ),
    country: Optional[str] = Query(
        default=None,
        description="Optional 2-letter country filter for block rows (e.g. GH, ZA).",
    ),
    limit: int = Query(
        default=100,
        ge=1,
        le=5000,
        description="Maximum block rows to return when include_blocks=true.",
    ),
    offset: int = Query(
        default=0,
        ge=0,
        le=1_000_000,
        description="Pagination offset for block rows when include_blocks=true.",
    ),
    format: str = FORMAT_QUERY,
):
    """
    Real-time global IPv4, IPv6, and ASN allocation statistics from all 5 RIRs.
    Sourced from NRO Extended Delegation Stats files (published daily).

    Use this to track IPv4 exhaustion, IPv6 adoption, and ASN growth.
    """
    rir_filter = (rir or "").upper().strip() or "all"
    cache_key  = cache_module.make_ipv4stat_key(
        rir_filter=rir_filter,
        include_blocks=include_blocks,
        status_filter=status,
        country_filter=country,
        limit=limit,
        offset=offset,
    )
    cached     = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_global_ipv4_stats(
        rir_filter=rir or None,
        include_blocks=include_blocks,
        status_filter=status,
        country_filter=country,
        limit=limit,
        offset=offset,
    )
    md  = format_ipv4_stats_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_IPV4STAT)
    return _resp(md, jsn, format)


@app.get(
    "/v1/overview/{prefix:path}",
    tags=["History"],
    summary="Prefix hierarchy: parent blocks, children, and BGP status",
)
@limiter.limit(_DEFAULT_RATE)
async def prefix_overview(
    request: Request,
    prefix: str,
    format: str = FORMAT_QUERY,
):
    """
    Rich hierarchical view of an IP prefix: who owns it, parent blocks
    (less-specifics), child assignments (more-specifics), and BGP status.

    **Examples:** `1.1.1.0/24`, `8.8.8.0/24`
    """
    cache_key = cache_module.make_overview_key(prefix)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_prefix_overview(prefix)
    md  = format_prefix_overview_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_OVERVIEW)
    return _resp(md, jsn, format)


# ──────────────────────────────────────────────────────────────
# Phase 4 — PeeringDB + Health + Monitor
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/peering/{asn}",
    tags=["PeeringDB"],
    summary="PeeringDB: peering policy, IXP presence, NOC contacts",
)
@limiter.limit(_DEFAULT_RATE)
async def peering_info(
    request: Request,
    asn: str,
    format: str = FORMAT_QUERY,
):
    """
    Fetch peering policy, IXP presence, NOC/abuse contacts, and BGP
    neighbours for an ASN from PeeringDB + RIPE Stat.

    **Examples:** `AS13335`, `AS15169`, `AS1299`
    """
    asn_num = asn.upper().lstrip("AS")
    cache_key = cache_module.make_peering_key(asn_num)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_peering_info(asn_num)
    md  = format_peering_info_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_PEERING)
    return _resp(md, jsn, format)


@app.get(
    "/v1/ixp",
    tags=["PeeringDB"],
    summary="Find Internet Exchange Points by country or name",
)
@limiter.limit(_DEFAULT_RATE)
async def ixp_lookup(
    request: Request,
    query: str = Query(..., description="2-letter country code (e.g. 'MU') or IXP name fragment (e.g. 'AMS-IX')"),
    format: str = FORMAT_QUERY,
):
    """
    Search PeeringDB for Internet Exchange Points by country code or name.

    **Examples:** `MU` (Mauritius), `ZA` (South Africa), `AMS-IX`, `LINX`, `Frankfurt`
    """
    cache_key = cache_module.make_ixp_key(query)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.lookup_ixps(query)
    md  = format_ixp_lookup_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_IXP)
    return _resp(md, jsn, format)


@app.get(
    "/v1/health/{resource}",
    tags=["Health"],
    summary="One-shot health check: RDAP + BGP + RPKI + PeeringDB",
)
@limiter.limit(_HEAVY_RATE)
async def network_health(
    request: Request,
    resource: str,
    format: str = FORMAT_QUERY,
):
    """
    Comprehensive parallel health check: fires RDAP + BGP + RPKI + PeeringDB
    simultaneously and returns a unified health signal dashboard.

    🚨 Critical: RPKI invalid, multiple origin ASNs (possible hijack)
    ⚠️  Warning: not announced, no ROA, missing abuse contact
    ✅ Healthy: registered, announced, RPKI valid

    **Examples:** `1.1.1.1`, `1.1.1.0/24`, `AS13335`
    """
    cache_key = cache_module.make_health_key(resource)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)

    result = await rir_client.get_network_health(resource)
    md  = format_network_health_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_HEALTH)
    return _resp(md, jsn, format)


@app.get(
    "/v1/monitor/{resource:path}",
    tags=["Monitor"],
    summary="Monitor registration + BGP changes between calls",
)
@limiter.limit(_DEFAULT_RATE)
async def change_monitor(
    request: Request,
    resource: str,
    reset: bool = Query(
        default=False,
        description="Set to true to discard the stored baseline and start fresh",
    ),
):
    """
    Stateful change monitor for a prefix or ASN.

    - **First call:** captures a baseline snapshot (RDAP + BGP state).
    - **Later calls:** diffs current state vs baseline and reports changes.
    - **reset=true:** discards baseline, captures fresh snapshot.

    Tracked: holder, RIR, country, allocation status, abuse email,
    BGP announced, origin ASN(s), BGP visibility %.

    ⚠️ Baselines live in server memory — lost on server restart.

    **Examples:** `8.8.8.0/24`, `AS15169`
    """
    result = await rir_client.run_change_monitor(
        resource=resource,
        reset_baseline=reset,
    )
    md  = format_change_monitor_md(result)
    jsn = to_json(result)
    # Always return JSON for monitor (structured diff is more useful)
    import json
    try:
        return JSONResponse(content=json.loads(jsn))
    except Exception:
        return PlainTextResponse(content=md)


# ──────────────────────────────────────────────────────────────
# DNS endpoints (Sprint 2 — E1–E5, E7)
# ──────────────────────────────────────────────────────────────

_RTYPE_HELP = "DNS record type (A, AAAA, MX, TXT, NS, CNAME …). Default: auto"

@app.get(
    "/v1/dns/resolve/{target}",
    tags=["DNS"],
    summary="Forward/reverse DNS resolution with RDAP correlation",
)
@limiter.limit(_DEFAULT_RATE)
async def dns_resolve(
    request: Request,
    target: str,
    record_type: str = Query(default="A", description=_RTYPE_HELP),
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Resolve a hostname (A/AAAA/PTR/etc.) and correlate resolved IPs with
    RDAP registration data (holder, country, RIR, covering prefix).

    **Examples:** `8.8.8.8`, `cloudflare.com`, `google.com`
    """
    inp = DNSResolveInput(target=target)
    result = await rir_client.dns_resolve(inp)
    md  = format_dns_resolve_md(result)
    jsn = to_json(result)
    return _resp(md, jsn, format)


@app.get(
    "/v1/dns/enumerate/{domain}",
    tags=["DNS"],
    summary="Full DNS record enumeration for a domain",
)
@limiter.limit(_DEFAULT_RATE)
async def dns_enumerate(
    request: Request,
    domain: str,
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Query all common DNS record types (A, AAAA, MX, NS, TXT, SOA, CNAME, CAA,
    SRV, PTR) for a domain and extract SPF/DMARC inline.

    **Example:** `cloudflare.com`
    """
    inp = DNSEnumerateInput(domain=domain)
    result = await rir_client.dns_enumerate(inp)
    md  = format_dns_enumerate_md(result)
    jsn = to_json(result)
    return _resp(md, jsn, format)


@app.get(
    "/v1/dns/dnssec/{domain}",
    tags=["DNS"],
    summary="DNSSEC chain validation",
)
@limiter.limit(_DEFAULT_RATE)
async def dns_dnssec(
    request: Request,
    domain: str,
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Check DNSSEC deployment: validates chain-of-trust (DNSKEY → DS → RRSIG),
    returns SECURE / INSECURE / BOGUS / INDETERMINATE with algorithm details.

    **Example:** `cloudflare.com`
    """
    inp = DNSSECInput(domain=domain)
    result = await rir_client.dns_dnssec(inp)
    md  = format_dns_dnssec_md(result)
    jsn = to_json(result)
    return _resp(md, jsn, format)


@app.get(
    "/v1/dns/dnsbl/{ip}",
    tags=["DNS"],
    summary="DNS blocklist (DNSBL/RBL) check across 30 lists",
)
@limiter.limit(_DEFAULT_RATE)
async def dns_dnsbl(
    request: Request,
    ip: str,
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Check an IP against 30 DNS blocklists in parallel (Spamhaus ZEN,
    Barracuda, SORBS, URIBL, and more). Returns per-list listed/clean status.

    **Example:** `1.2.3.4`
    """
    inp = DNSBLInput(ip=ip)
    result = await rir_client.dns_dnsbl(inp)
    md  = format_dns_dnsbl_md(result)
    jsn = to_json(result)
    return _resp(md, jsn, format)


@app.get(
    "/v1/dns/email/{domain}",
    tags=["DNS"],
    summary="Email security posture (SPF + DMARC + DKIM + BIMI)",
)
@limiter.limit(_DEFAULT_RATE)
async def dns_email(
    request: Request,
    domain: str,
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Comprehensive email security audit: SPF record validity, DMARC policy
    strength, DKIM selector probing, MX records, BIMI presence, and a
    risk score (LOW / MEDIUM / HIGH / CRITICAL).

    **Example:** `example.com`
    """
    inp = EmailSecurityInput(domain=domain)
    result = await rir_client.dns_email_security(inp)
    md  = format_email_security_md(result)
    jsn = to_json(result)
    return _resp(md, jsn, format)


@app.get(
    "/v1/dns/propagation/{domain}",
    tags=["DNS"],
    summary="DNS propagation check across 10 global resolvers",
)
@limiter.limit(_DEFAULT_RATE)
async def dns_propagation(
    request: Request,
    domain: str,
    record_type: str = Query(default="A", description=_RTYPE_HELP),
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Query 10 geographically distributed resolvers (Cloudflare, Google,
    Quad9, OpenDNS, Comodo, Verisign, etc.) and compare answers to the
    majority — useful for verifying recent DNS changes have propagated.

    **Example:** `cloudflare.com`
    """
    inp = DNSPropagationInput(domain=domain, record_type=record_type)
    result = await rir_client.dns_propagation(inp)
    md  = format_dns_propagation_md(result)
    jsn = to_json(result)
    return _resp(md, jsn, format)


# ──────────────────────────────────────────────────────────────
# Sprint 3 endpoints — TLS (F1), CT Logs (F2), Threat Intel (G1), PDNS (E6)
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/tls/{hostname}",
    tags=["TLS"],
    summary="TLS certificate inspection — chain, expiry, cipher, HSTS",
)
@limiter.limit(_DEFAULT_RATE)
async def tls_inspect(
    request: Request,
    hostname: str,
    port: int = Query(default=443, ge=1, le=65535, description="TCP port (default 443)"),
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Connect to `hostname:port` over TLS and return the leaf certificate details:
    subject, issuer, SANs, expiry, days remaining, self-signed flag, cipher suite,
    TLS version, chain length, and HSTS header presence.

    **Examples:** `cloudflare.com`, `expired.badssl.com`
    """
    cache_key = cache_module.make_tls_key(hostname, port)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    inp = TLSInspectInput(hostname=hostname, port=port)
    result = await rir_client.tls_inspect(inp)
    md  = format_tls_inspect_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_TLS_INSPECT)
    return _resp(md, jsn, format)


@app.get(
    "/v1/ct/{domain}",
    tags=["TLS"],
    summary="Certificate Transparency log search (crt.sh)",
)
@limiter.limit(_DEFAULT_RATE)
async def ct_logs(
    request: Request,
    domain: str,
    limit: int = Query(default=50, ge=1, le=500, description="Max entries to return"),
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Search crt.sh for all certificates ever issued for a domain (including
    subdomains). Useful for discovering shadow IT, verifying CA coverage,
    or auditing certificate issuance history.

    **Example:** `cloudflare.com`
    """
    cache_key = cache_module.make_ct_key(domain)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    inp = CTLogInput(domain=domain, limit=limit)
    result = await rir_client.ct_logs(inp)
    md  = format_ct_logs_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_CT_LOGS)
    return _resp(md, jsn, format)


@app.get(
    "/v1/threat/{ip}",
    tags=["Threat Intelligence"],
    summary="Threat intel — Shodan InternetDB + optional GreyNoise",
)
@limiter.limit(_DEFAULT_RATE)
async def threat_intel(
    request: Request,
    ip: str,
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Query Shodan InternetDB (free, no key) for open ports, CVEs, hostnames,
    and tags. Optionally enriches with GreyNoise Community classification
    (malicious / benign / RIOT) when `GREYNOISE_API_KEY` env var is set.

    **Example:** `8.8.8.8`
    """
    cache_key = cache_module.make_threat_intel_key(ip)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    inp = ThreatIntelInput(ip=ip)
    result = await rir_client.threat_intel(inp)
    md  = format_threat_intel_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_THREAT_INTEL)
    return _resp(md, jsn, format)


@app.get(
    "/v1/pdns/{resource}",
    tags=["DNS"],
    summary="Passive DNS history (RIPE Stat)",
)
@limiter.limit(_DEFAULT_RATE)
async def passive_dns(
    request: Request,
    resource: str,
    limit: int = Query(default=100, ge=1, le=500),
    format: ResponseFormat = Query(default=ResponseFormat.MARKDOWN),
):
    """
    Query RIPE Stat Passive DNS for historical DNS records for an IP address
    or domain. Shows what names have resolved to/from this resource over time,
    with first/last seen timestamps and observation counts.

    **Examples:** `8.8.8.8`, `cloudflare.com`
    """
    cache_key = cache_module.make_passive_dns_key(resource)
    cached = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    inp = PassiveDNSInput(resource=resource, limit=limit)
    result = await rir_client.passive_dns(inp)
    md  = format_passive_dns_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_PASSIVE_DNS)
    return _resp(md, jsn, format)


# ──────────────────────────────────────────────────────────────
# Sprint 4 — BGP Depth endpoints
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/irr",
    tags=["BGP"],
    summary="IRR route-object consistency check",
)
@limiter.limit(_DEFAULT_RATE)
async def check_irr_endpoint(
    request: Request,
    prefix: str = Query(..., description="CIDR prefix e.g. 1.1.1.0/24"),
    asn: str    = Query(..., description="Origin ASN e.g. AS13335 or 13335"),
    format: str = FORMAT_QUERY,
):
    """Check IRRExplorer for route objects covering *prefix* and validate against *asn*."""
    cache_key = cache_module.make_irr_key(prefix, asn)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.check_irr(prefix, asn)
    md  = format_irr_result_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_IRR)
    return _resp(md, jsn, format)


@app.get(
    "/v1/route-leak/{prefix:path}",
    tags=["BGP"],
    summary="BGP route leak / hijack detection",
)
@limiter.limit(_DEFAULT_RATE)
async def detect_route_leak_endpoint(
    request: Request,
    prefix: str,
    format: str = FORMAT_QUERY,
):
    """Detect potential route leaks or hijacks for a prefix using RIPE Stat BGP-state."""
    cache_key = cache_module.make_route_leak_key(prefix)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.detect_route_leak(prefix)
    md  = format_route_leak_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_ROUTE_LEAK)
    return _resp(md, jsn, format)


@app.get(
    "/v1/looking-glass/{prefix:path}",
    tags=["BGP"],
    summary="BGP looking glass — AS paths from RIPE RIS collectors",
)
@limiter.limit(_DEFAULT_RATE)
async def looking_glass_endpoint(
    request: Request,
    prefix: str,
    vantage_points: int = Query(default=10, ge=1, le=50, description="Max entries to return"),
    format: str = FORMAT_QUERY,
):
    """Show BGP routing table entries with full AS paths from RIPE RIS vantage points."""
    cache_key = cache_module.make_looking_glass_key(prefix, vantage_points)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_looking_glass(prefix, vantage_points)
    md  = format_looking_glass_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_LOOKING_GLASS)
    return _resp(md, jsn, format)


@app.get(
    "/v1/stability/{prefix:path}",
    tags=["BGP"],
    summary="BGP route stability / flap analysis",
)
@limiter.limit(_DEFAULT_RATE)
async def route_stability_endpoint(
    request: Request,
    prefix: str,
    hours: int = Query(default=24, ge=1, le=168, description="Analysis window in hours (max 168 = 7 days)"),
    format: str = FORMAT_QUERY,
):
    """Analyse BGP route flap history and compute a stability score for a prefix."""
    cache_key = cache_module.make_route_stability_key(prefix, hours)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_route_stability(prefix, hours)
    md  = format_route_stability_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_ROUTE_STABILITY)
    return _resp(md, jsn, format)


# ──────────────────────────────────────────────────────────────
# Sprint 5 — Humanitarian / Crisis endpoints
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/shutdown/{country_code}",
    tags=["Crisis"],
    summary="Country BGP shutdown detection",
)
@limiter.limit(_DEFAULT_RATE)
async def shutdown_detect_endpoint(
    request: Request,
    country_code: str,
    format: str = FORMAT_QUERY,
):
    """Detect internet shutdowns by comparing current BGP prefix counts to baseline."""
    cc        = country_code.upper().strip()
    cache_key = cache_module.make_shutdown_key(cc)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.detect_shutdown(cc)
    md  = format_shutdown_detect_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_SHUTDOWN)
    return _resp(md, jsn, format)


@app.post(
    "/v1/shutdown/monitor",
    tags=["Crisis"],
    summary="Register a shutdown monitor webhook",
)
@limiter.limit("20/minute")
async def shutdown_monitor_endpoint(
    request: Request,
    body: MonitorRegisterInput,
):
    """Register a country, ASN, or prefix for shutdown monitoring with a webhook callback."""
    result = await rir_client.register_shutdown_monitor(
        body.resource, body.webhook_url, body.threshold_pct, body.interval_minutes,
    )
    return result.model_dump()


@app.get(
    "/v1/shutdown/timeline/{resource}",
    tags=["Crisis"],
    summary="Historical shutdown timeline and evidence export",
)
@limiter.limit(_DEFAULT_RATE)
async def shutdown_timeline_endpoint(
    request: Request,
    resource: str,
    start_date: str = Query(..., description="ISO date e.g. 2023-10-07"),
    end_date:   str = Query(..., description="ISO date e.g. 2023-10-14"),
    format: str = FORMAT_QUERY,
):
    """Return a BGP shutdown timeline with a SHA-256 integrity hash for evidence."""
    cache_key = cache_module.make_shutdown_timeline_key(resource, start_date, end_date)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_shutdown_timeline(resource, start_date, end_date)
    md  = format_shutdown_timeline_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_SHUTDOWN_TIMELINE)
    return _resp(md, jsn, format)


@app.get(
    "/v1/censorship/{domain:path}",
    tags=["Crisis"],
    summary="DNS censorship fingerprinting",
)
@limiter.limit(_DEFAULT_RATE)
async def censorship_probe_endpoint(
    request: Request,
    domain: str,
    country_code: Optional[str] = Query(default=None, description="ISO country code for ISP resolvers"),
    format: str = FORMAT_QUERY,
):
    """Detect DNS censorship by comparing neutral vs ISP resolver responses."""
    cc        = (country_code or "").upper().strip()
    cache_key = cache_module.make_censorship_key(domain, cc)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.probe_dns_censorship(domain, cc or None)
    md  = format_censorship_probe_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_CENSORSHIP)
    return _resp(md, jsn, format)


@app.get(
    "/v1/satellite/{country_code}",
    tags=["Crisis"],
    summary="Satellite internet connectivity tracking",
)
@limiter.limit(_DEFAULT_RATE)
async def satellite_connectivity_endpoint(
    request: Request,
    country_code: str,
    format: str = FORMAT_QUERY,
):
    """Check whether satellite providers (Starlink, Viasat, OneWeb…) are active."""
    cc        = country_code.upper().strip()
    cache_key = cache_module.make_satellite_key(cc)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_satellite_connectivity(cc)
    md  = format_satellite_connectivity_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_SATELLITE)
    return _resp(md, jsn, format)


@app.get(
    "/v1/chokepoints/{country_code}",
    tags=["Crisis"],
    summary="Country internet chokepoint mapping",
)
@limiter.limit(_DEFAULT_RATE)
async def chokepoints_endpoint(
    request: Request,
    country_code: str,
    format: str = FORMAT_QUERY,
):
    """Map transit provider dependencies and compute internet resilience score."""
    cc        = country_code.upper().strip()
    cache_key = cache_module.make_chokepoints_key(cc)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_country_chokepoints(cc)
    md  = format_chokepoints_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_CHOKEPOINTS)
    return _resp(md, jsn, format)


@app.get(
    "/v1/ooni/{country_code}",
    tags=["Crisis"],
    summary="OONI censorship measurements",
)
@limiter.limit(_DEFAULT_RATE)
async def ooni_report_endpoint(
    request: Request,
    country_code: str,
    domain: Optional[str] = Query(default=None, description="Filter to a specific domain"),
    format: str = FORMAT_QUERY,
):
    """Fetch OONI censorship measurements — blocked domains, Tor, circumvention tools."""
    cc        = country_code.upper().strip()
    dom       = (domain or "").lower().strip()
    cache_key = cache_module.make_ooni_key(cc, dom)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_ooni_report(cc, dom or None)
    md  = format_ooni_report_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_OONI)
    return _resp(md, jsn, format)


@app.get(
    "/v1/health/country/{country_code}",
    tags=["Crisis"],
    summary="Country internet health dashboard",
)
@limiter.limit(_DEFAULT_RATE)
async def country_health_endpoint(
    request: Request,
    country_code: str,
    format: str = FORMAT_QUERY,
):
    """Composite country internet health score: BGP + DNS + OONI + satellite."""
    cc        = country_code.upper().strip()
    cache_key = cache_module.make_country_health_key(cc)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_country_health(cc)
    md  = format_country_health_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_COUNTRY_HEALTH)
    return _resp(md, jsn, format)


# ── Sprint 6 — Advanced platform endpoints ─────────────────────

@app.get("/v1/as-relationships/{asn}", tags=["BGP"], summary="AS relationship classification (CAIDA)")
@limiter.limit(_DEFAULT_RATE)
async def as_relationships_endpoint(request: Request, asn: str, format: str = FORMAT_QUERY):
    cache_key = cache_module.make_as_relationships_key(asn)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.get_as_relationships(asn)
    md  = format_as_relationships_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_AS_RELATIONSHIPS)
    return _resp(md, jsn, format)


@app.get("/v1/geo/{ip}", tags=["Enrichment"], summary="GeoIP enrichment (MaxMind GeoLite2)")
@limiter.limit(_DEFAULT_RATE)
async def geo_lookup_endpoint(request: Request, ip: str, format: str = FORMAT_QUERY):
    cache_key = cache_module.make_geo_lookup_key(ip)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.geo_lookup(ip)
    md  = format_geo_lookup_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_GEO_LOOKUP)
    return _resp(md, jsn, format)


@app.get("/v1/atlas/{target:path}", tags=["Network"], summary="RIPE Atlas traceroute")
@limiter.limit("10/minute")
async def atlas_trace_endpoint(
    request: Request,
    target: str,
    probes: int = Query(default=5, ge=1, le=25),
    format: str = FORMAT_QUERY,
):
    cache_key = cache_module.make_atlas_key(target, probes)
    cached    = cache_module.get(cache_key)
    if cached:
        return _resp(cached["markdown"], cached["json"], format)
    result = await rir_client.atlas_traceroute(target, probes)
    md  = format_atlas_trace_md(result)
    jsn = to_json(result)
    cache_module.set(cache_key, {"markdown": md, "json": jsn}, cache_module.TTL_ATLAS_TRACE)
    return _resp(md, jsn, format)


# ── J2 — Bulk Query endpoint ──────────────────────────────────

class _BulkRequest(BaseModel):
    resources: list = Field(min_length=1, max_length=50)
    query_type: str = "auto"

@app.post("/v1/bulk", tags=["Utility"], summary="Bulk query up to 50 resources in parallel")
@limiter.limit("10/minute")
async def bulk_query(request: Request, body: _BulkRequest, format: str = FORMAT_QUERY):
    """Query up to 50 IPs, ASNs, or prefixes in parallel. Auto-detects resource type."""
    import re as _re

    async def _dispatch(resource: str):
        r = resource.strip()
        # Auto-detect type
        if _re.match(r"^AS\d+$", r, _re.IGNORECASE) or _re.match(r"^\d{1,10}$", r):
            result = await rir_client.get_network_health(r)
        elif "/" in r:
            result = await rir_client.get_network_health(r)
        elif _re.match(r"^\d+\.\d+\.\d+\.\d+$", r) or ":" in r:
            result = await rir_client.get_network_health(r)
        else:
            result = await rir_client.get_network_health(r)
        from formatters import format_network_health_md
        from formatters import to_json as _to_json
        return {"resource": r, "markdown": format_network_health_md(result), "json": _to_json(result)}

    tasks   = [_dispatch(res) for res in body.resources[:50]]
    results = await asyncio.gather(*tasks, return_exceptions=True)
    out = []
    for res, r in zip(body.resources[:50], results):
        if isinstance(r, Exception):
            out.append({"resource": res, "error": str(r)})
        else:
            out.append({"resource": res, "data": r.get("markdown") if format != "json" else r.get("json")})
    return {"results": out, "count": len(out)}


# ──────────────────────────────────────────────────────────────
# OpenAI / Gemini function-calling schema endpoint
# ──────────────────────────────────────────────────────────────

@app.get(
    "/v1/meta/openai-tools",
    tags=["Meta"],
    summary="OpenAI / Gemini function-calling tool definitions",
)
@limiter.limit(_DEFAULT_RATE)
async def openai_tools(request: Request):
    """
    Returns the tool definitions in OpenAI function-calling format.
    Paste these directly into your ChatGPT/Gemini system prompt or
    API call to give those models access to PeerGlass.
    """
    tools = [
        {
            "type": "function",
            "function": {
                "name": "peerglass_ip",
                "description": "Who owns this IP address? Queries all 5 RIRs (RDAP).",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "ip": {"type": "string", "description": "IPv4 or IPv6 address"}
                    },
                    "required": ["ip"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_asn",
                "description": "Who owns this Autonomous System Number (ASN)?",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "asn": {"type": "string", "description": "ASN, e.g. 'AS13335' or '13335'"}
                    },
                    "required": ["asn"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_health",
                "description": (
                    "One-shot network health check combining RDAP registration, "
                    "BGP routing status, RPKI validity, and PeeringDB peering policy. "
                    "Best first tool for any IP/prefix/ASN investigation."
                ),
                "parameters": {
                    "type": "object",
                    "properties": {
                        "resource": {
                            "type": "string",
                            "description": "IP address, prefix (CIDR), or ASN",
                        }
                    },
                    "required": ["resource"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_rpki",
                "description": "Is this BGP route RPKI valid? Returns valid/invalid/not-found.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "prefix": {"type": "string", "description": "IP prefix in CIDR, e.g. '1.1.1.0/24'"},
                        "asn": {"type": "string", "description": "Origin ASN, e.g. 'AS13335'"},
                    },
                    "required": ["prefix", "asn"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_peering",
                "description": "PeeringDB lookup: peering policy, IXP presence, NOC contacts for an ASN.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "asn": {"type": "string", "description": "ASN, e.g. 'AS13335'"}
                    },
                    "required": ["asn"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_ixp",
                "description": "Find Internet Exchange Points by country code (e.g. 'MU') or name (e.g. 'AMS-IX').",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "query": {"type": "string", "description": "Country code or IXP name fragment"}
                    },
                    "required": ["query"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_history",
                "description": "Full ownership and status history for a prefix or ASN.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "resource": {"type": "string", "description": "IP prefix or ASN"}
                    },
                    "required": ["resource"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_monitor",
                "description": (
                    "Monitor a prefix or ASN for changes between calls. "
                    "First call captures baseline; subsequent calls return a diff."
                ),
                "parameters": {
                    "type": "object",
                    "properties": {
                        "resource": {"type": "string", "description": "IP prefix or ASN"},
                        "reset": {"type": "boolean", "description": "Reset baseline (default false)"},
                    },
                    "required": ["resource"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_resolve",
                "description": "Forward/reverse DNS resolution with RDAP IP registration correlation.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "target": {"type": "string", "description": "Hostname or IP address"},
                        "record_type": {"type": "string", "description": "DNS record type (A, AAAA, PTR, MX, TXT…)"},
                    },
                    "required": ["target"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_enumerate",
                "description": "Enumerate all DNS records for a domain (A, AAAA, MX, NS, TXT, SOA, CNAME, CAA, SRV).",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "domain": {"type": "string", "description": "Domain name, e.g. 'cloudflare.com'"}
                    },
                    "required": ["domain"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_dnssec",
                "description": "DNSSEC chain validation — returns SECURE, INSECURE, BOGUS, or INDETERMINATE.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "domain": {"type": "string", "description": "Domain name"}
                    },
                    "required": ["domain"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_dnsbl",
                "description": "Check an IP address against 30 DNS blocklists (Spamhaus, SORBS, Barracuda, etc.).",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "ip": {"type": "string", "description": "IPv4 address to check"}
                    },
                    "required": ["ip"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_email_security",
                "description": "Email security audit: SPF, DMARC, DKIM selectors, MX, BIMI, and risk score.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "domain": {"type": "string", "description": "Domain name"}
                    },
                    "required": ["domain"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_propagation",
                "description": "DNS propagation check across 10 global resolvers — verify recent DNS changes.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "domain": {"type": "string", "description": "Domain name"},
                        "record_type": {"type": "string", "description": "DNS record type (default A)"},
                    },
                    "required": ["domain"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_tls_inspect",
                "description": "TLS certificate inspection: subject, issuer, SANs, expiry, cipher suite, HSTS.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "hostname": {"type": "string", "description": "Hostname to connect to"},
                        "port": {"type": "integer", "description": "TCP port (default 443)"},
                    },
                    "required": ["hostname"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_ct_logs",
                "description": "Certificate Transparency log search via crt.sh — find all certificates ever issued for a domain.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "domain": {"type": "string", "description": "Domain name"},
                        "limit": {"type": "integer", "description": "Max results (default 50, max 500)"},
                    },
                    "required": ["domain"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_threat_intel",
                "description": "Threat intelligence: Shodan open ports/CVEs/hostnames (free) + GreyNoise classification (optional API key).",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "ip": {"type": "string", "description": "IPv4 address"}
                    },
                    "required": ["ip"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_passive_dns",
                "description": "Passive DNS history from RIPE Stat — what domains/IPs has this resource resolved to/from historically.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "resource": {"type": "string", "description": "IP address or domain name"},
                        "limit": {"type": "integer", "description": "Max records (default 100)"},
                    },
                    "required": ["resource"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "rir_check_irr",
                "description": "IRR route-object consistency check via IRRExplorer — validates that a prefix has correct route objects matching the expected origin ASN.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "prefix": {"type": "string", "description": "CIDR prefix e.g. 1.1.1.0/24"},
                        "asn":    {"type": "string", "description": "Expected origin ASN e.g. AS13335"},
                    },
                    "required": ["prefix", "asn"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "rir_detect_route_leak",
                "description": "Detect BGP route leaks or hijacks — checks for multiple origin ASNs and AS-path loops.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "prefix": {"type": "string", "description": "CIDR prefix e.g. 1.1.1.0/24"},
                    },
                    "required": ["prefix"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "rir_looking_glass",
                "description": "BGP looking glass — shows AS paths and communities from RIPE RIS vantage points around the world.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "prefix":         {"type": "string",  "description": "CIDR prefix e.g. 1.1.1.0/24"},
                        "vantage_points": {"type": "integer", "description": "Max entries (default 10)"},
                    },
                    "required": ["prefix"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "rir_route_stability",
                "description": "BGP route stability / flap analysis — computes a 0–100 stability score and lists state-change events.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "prefix": {"type": "string",  "description": "CIDR prefix e.g. 1.1.1.0/24"},
                        "hours":  {"type": "integer", "description": "Analysis window in hours (default 24, max 168)"},
                    },
                    "required": ["prefix"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_shutdown_detect",
                "description": "Country-level BGP internet shutdown detection — compares current prefix counts against baseline to detect NORMAL/DEGRADED/PARTIAL/FULL shutdown.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "country_code": {"type": "string", "description": "ISO 3166-1 alpha-2 code e.g. SY, IR, MM"},
                    },
                    "required": ["country_code"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_shutdown_timeline",
                "description": "Historical BGP shutdown timeline with SHA-256 integrity hash — for evidence, UN reports, legal proceedings.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "resource":   {"type": "string", "description": "Country code or ASN"},
                        "start_date": {"type": "string", "description": "ISO date e.g. 2023-10-07"},
                        "end_date":   {"type": "string", "description": "ISO date e.g. 2023-10-14"},
                    },
                    "required": ["resource", "start_date", "end_date"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_dns_censorship",
                "description": "DNS censorship fingerprinting — detects NXDOMAIN injection, IP poisoning, DPI blocking by comparing neutral vs ISP resolvers.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "domain":       {"type": "string", "description": "Domain to probe e.g. twitter.com"},
                        "country_code": {"type": "string", "description": "Optional ISO code for country-specific resolvers"},
                    },
                    "required": ["domain"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_satellite_connectivity",
                "description": "Check whether Starlink, Viasat, OneWeb, SES and other satellite providers are actively announcing BGP prefixes.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "country_code": {"type": "string", "description": "ISO country code (context)"},
                    },
                    "required": ["country_code"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_country_chokepoints",
                "description": "Map country internet chokepoints — identifies critical transit providers and computes a resilience score.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "country_code": {"type": "string", "description": "ISO country code e.g. SY, BY"},
                    },
                    "required": ["country_code"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_ooni_report",
                "description": "OONI censorship measurements — blocked domains, Tor accessibility, circumvention tool status from probes inside the country.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "country_code": {"type": "string", "description": "ISO country code e.g. IR, RU"},
                        "domain":       {"type": "string", "description": "Optional: filter to a specific domain"},
                    },
                    "required": ["country_code"],
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "peerglass_country_health",
                "description": "Composite country internet health dashboard — 0-100 score from BGP + DNS + OONI + satellite signals.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "country_code": {"type": "string", "description": "ISO country code e.g. UA, SY, MM"},
                    },
                    "required": ["country_code"],
                },
            },
        },
    ]
    from fastapi.responses import JSONResponse
    return JSONResponse(
        content=tools,
        headers={"X-Tool-Count": str(len(tools)), "X-Base-URL": "https://peerglass.onrender.com"},
    )