kestrix 0.1.0__py3-none-any.whl

kestrix/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Ruthvik Bandari
+# SPDX-License-Identifier: Apache-2.0
+"""Kestrix: local-first security workbench."""
+
+__version__ = "0.1.0"
+__author__ = "Ruthvik Bandari"
+# Stamped on every report, export and run manifest Kestrix produces.
+ATTRIBUTION = f"Kestrix by {__author__}"

kestrix/bitcoin/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 Ruthvik Bandari and the BitShield (Team ACE) contributors
+# SPDX-License-Identifier: Apache-2.0
+"""Bitcoin address quantum-exposure scanning.
+
+Classifies addresses and raw public keys by whether their public key is visible on the
+blockchain, optionally checks spend history on mempool.space, explains each result in
+plain language and gives migration steps. It never holds keys, wallets or coins.
+"""

kestrix/bitcoin/address.py

@@ -0,0 +1,231 @@
+# SPDX-FileCopyrightText: 2026 Ruthvik Bandari and the BitShield (Team ACE) contributors
+# SPDX-License-Identifier: Apache-2.0
+"""Bitcoin address and raw public key parsing, standard library only.
+
+Base58Check addresses are verified with their double-SHA-256 checksum. Segwit
+addresses follow BIP-173 (Bech32, witness version 0) and BIP-350 (Bech32m, versions
+1-16), including the checksum-variant, witness-version and program-length rules. Raw
+public keys (the lock used by P2PK outputs, which have no address form) are accepted as
+33-byte compressed or 65-byte uncompressed SEC hex and must lie on secp256k1.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import string
+from dataclasses import dataclass
+from enum import Enum
+
+from ..core.errors import Reason, Rejected
+from .models import AddressType, Network
+
+MAX_INPUT_CHARS = 130  # an uncompressed public key in hex
+
+_B58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
+_B58_INDEX = {ch: i for i, ch in enumerate(_B58_ALPHABET)}
+_B58_VERSIONS = {
+    0x00: (AddressType.P2PKH, Network.MAINNET),
+    0x05: (AddressType.P2SH, Network.MAINNET),
+    0x6F: (AddressType.P2PKH, Network.TEST),
+    0xC4: (AddressType.P2SH, Network.TEST),
+}
+
+_BECH32_CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l"
+_BECH32_MAX_LENGTH = 90
+_SEGWIT_HRPS = {"bc": Network.MAINNET, "tb": Network.TEST, "bcrt": Network.REGTEST}
+
+_SECP256K1_P = 2**256 - 2**32 - 977
+
+
+class Bech32Encoding(Enum):
+    BECH32 = 1
+    BECH32M = 0x2BC830A3
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedAddress:
+    """A validated input. ``text`` is the canonical form (Bech32 and hex lowercased);
+    ``payload`` is the key hash, script hash, witness program or public key."""
+
+    text: str
+    address_type: AddressType
+    network: Network | None
+    payload: bytes
+
+
+# --- Base58Check ---------------------------------------------------------------------
+
+
+def base58_decode(text: str) -> bytes:
+    """Decode Base58 (Bitcoin alphabet). Each leading ``1`` is one leading zero byte."""
+    number = 0
+    for ch in text:
+        digit = _B58_INDEX.get(ch)
+        if digit is None:
+            raise ValueError(f"invalid Base58 character {ch!r}")
+        number = number * 58 + digit
+    leading_zeros = len(text) - len(text.lstrip("1"))
+    return b"\x00" * leading_zeros + number.to_bytes((number.bit_length() + 7) // 8, "big")
+
+
+def base58check_decode(text: str) -> bytes:
+    """Decode Base58Check and return the payload with its 4-byte checksum verified."""
+    raw = base58_decode(text)
+    if len(raw) < 5:
+        raise ValueError("too short for Base58Check")
+    payload, checksum = raw[:-4], raw[-4:]
+    if hashlib.sha256(hashlib.sha256(payload).digest()).digest()[:4] != checksum:
+        raise ValueError("Base58Check checksum mismatch")
+    return payload
+
+
+# --- Bech32 / Bech32m ----------------------------------------------------------------
+
+
+def _bech32_polymod(values: list[int]) -> int:
+    generators = (0x3B6A57B2, 0x26508E6D, 0x1EA119FA, 0x3D4233DD, 0x2A1462B3)
+    checksum = 1
+    for value in values:
+        top = checksum >> 25
+        checksum = (checksum & 0x1FFFFFF) << 5 ^ value
+        for i, generator in enumerate(generators):
+            if (top >> i) & 1:
+                checksum ^= generator
+    return checksum
+
+
+def _hrp_expand(hrp: str) -> list[int]:
+    return [ord(ch) >> 5 for ch in hrp] + [0] + [ord(ch) & 31 for ch in hrp]
+
+
+def bech32_decode(text: str) -> tuple[str, list[int], Bech32Encoding]:
+    """Decode a Bech32 or Bech32m string into ``(hrp, 5-bit data without checksum, encoding)``."""
+    if any(not 33 <= ord(ch) <= 126 for ch in text):
+        raise ValueError("character out of range")
+    if text.lower() != text and text.upper() != text:
+        raise ValueError("mixed case")
+    if len(text) > _BECH32_MAX_LENGTH:
+        raise ValueError(f"longer than {_BECH32_MAX_LENGTH} characters")
+    text = text.lower()
+    separator = text.rfind("1")
+    if separator < 1:
+        raise ValueError("missing separator or empty human-readable part")
+    if separator + 7 > len(text):
+        raise ValueError("checksum too short")
+    hrp, data_part = text[:separator], text[separator + 1 :]
+    if any(ch not in _BECH32_CHARSET for ch in data_part):
+        raise ValueError("invalid data character")
+    data = [_BECH32_CHARSET.index(ch) for ch in data_part]
+    constant = _bech32_polymod(_hrp_expand(hrp) + data)
+    try:
+        encoding = Bech32Encoding(constant)
+    except ValueError:
+        raise ValueError("invalid checksum") from None
+    return hrp, data[:-6], encoding
+
+
+def _convert_5_to_8_bits(data: list[int]) -> bytes:
+    """Regroup 5-bit values into bytes; leftover padding must be under 5 bits and zero."""
+    accumulator = bits = 0
+    out = bytearray()
+    for value in data:
+        accumulator = (accumulator << 5) | value
+        bits += 5
+        if bits >= 8:
+            bits -= 8
+            out.append((accumulator >> bits) & 0xFF)
+    if bits >= 5 or (accumulator << (8 - bits)) & 0xFF:
+        raise ValueError("invalid padding")
+    return bytes(out)
+
+
+def decode_segwit(text: str) -> tuple[str, int, bytes]:
+    """Decode a segwit address into ``(hrp, witness version, witness program)``."""
+    hrp, data, encoding = bech32_decode(text)
+    if not data:
+        raise ValueError("empty data section")
+    version = data[0]
+    if version > 16:
+        raise ValueError(f"invalid witness version {version}")
+    program = _convert_5_to_8_bits(data[1:])
+    if not 2 <= len(program) <= 40:
+        raise ValueError(f"invalid witness program length {len(program)}")
+    if version == 0 and len(program) not in (20, 32):
+        raise ValueError(f"invalid witness program length {len(program)} for version 0")
+    expected = Bech32Encoding.BECH32 if version == 0 else Bech32Encoding.BECH32M
+    if encoding is not expected:
+        raise ValueError(f"witness version {version} requires {expected.name.capitalize()} checksum")
+    return hrp, version, program
+
+
+# --- Public keys ---------------------------------------------------------------------
+
+
+def _is_on_curve(sec: bytes) -> bool:
+    x = int.from_bytes(sec[1:33], "big")
+    if x >= _SECP256K1_P:
+        return False
+    rhs = (pow(x, 3, _SECP256K1_P) + 7) % _SECP256K1_P
+    if len(sec) == 33:
+        return pow(rhs, (_SECP256K1_P - 1) // 2, _SECP256K1_P) == 1  # rhs has a square root
+    y = int.from_bytes(sec[33:], "big")
+    return y < _SECP256K1_P and pow(y, 2, _SECP256K1_P) == rhs
+
+
+def _parse_public_key(text: str) -> ParsedAddress:
+    sec = bytes.fromhex(text)
+    valid_prefix = (len(sec) == 33 and sec[0] in (2, 3)) or (len(sec) == 65 and sec[0] == 4)
+    if not valid_prefix:
+        raise ValueError("a public key must be 33 bytes starting 02/03 or 65 bytes starting 04")
+    if not _is_on_curve(sec):
+        raise ValueError("not a point on the secp256k1 curve")
+    return ParsedAddress(text.lower(), AddressType.P2PK, None, sec)
+
+
+# --- Dispatch ------------------------------------------------------------------------
+
+
+def _parse_segwit(text: str) -> ParsedAddress:
+    hrp, version, program = decode_segwit(text)
+    network = _SEGWIT_HRPS[hrp]
+    if version == 0:
+        address_type = AddressType.P2WPKH if len(program) == 20 else AddressType.P2WSH
+    elif version == 1 and len(program) == 32:
+        address_type = AddressType.P2TR
+    else:
+        raise ValueError(
+            f"witness version {version} with a {len(program)}-byte program is valid encoding "
+            "but not a defined output type; do not send coins to it"
+        )
+    return ParsedAddress(text.lower(), address_type, network, program)
+
+
+def _parse_base58(text: str) -> ParsedAddress:
+    payload = base58check_decode(text)
+    if len(payload) != 21 or payload[0] not in _B58_VERSIONS:
+        raise ValueError("not a Bitcoin P2PKH or P2SH address")
+    address_type, network = _B58_VERSIONS[payload[0]]
+    return ParsedAddress(text, address_type, network, payload[1:])
+
+
+def _looks_segwit(text: str) -> bool:
+    lowered = text.lower()
+    return any(lowered.startswith(hrp + "1") for hrp in _SEGWIT_HRPS)
+
+
+def parse_address(raw: str) -> ParsedAddress:
+    """Parse an address or raw public key, raising ``Rejected(INVALID_INPUT)`` if invalid."""
+    text = raw.strip()
+    shown = text[:100]
+    if not text:
+        raise Rejected(Reason.INVALID_INPUT, "empty address")
+    if len(text) > MAX_INPUT_CHARS:
+        raise Rejected(Reason.INVALID_INPUT, f"{shown!r}...: too long to be an address or public key")
+    try:
+        if len(text) in (66, 130) and all(ch in string.hexdigits for ch in text):
+            return _parse_public_key(text)
+        if _looks_segwit(text):
+            return _parse_segwit(text)
+        return _parse_base58(text)
+    except ValueError as exc:
+        raise Rejected(Reason.INVALID_INPUT, f"{shown!r} is not a valid Bitcoin address or public key: {exc}") from None

kestrix/bitcoin/api.py

@@ -0,0 +1,70 @@
+# SPDX-FileCopyrightText: 2026 Ruthvik Bandari and the BitShield (Team ACE) contributors
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP routes for the Bitcoin module."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+from . import guardian
+from .chain import MempoolClient
+from .migration import parse_address_type, plan_for
+from .models import GuardianResult, MigrationPlan, PublicTestnet, ScanResult
+from .risk import MAX_BATCH, scan
+
+router = APIRouter(prefix="/api/bitcoin", tags=["bitcoin"])
+
+ChainClientFactory = Callable[[PublicTestnet], MempoolClient]
+Classifier = Callable[[str], GuardianResult]
+
+
+class ScanRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    addresses: list[Annotated[str, StringConstraints(max_length=200)]] = Field(min_length=1, max_length=MAX_BATCH)
+    lookup_chain: bool = False
+    testnet: PublicTestnet = PublicTestnet.TESTNET4
+
+
+class GuardianRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    message: str = Field(min_length=1, max_length=guardian.MAX_MESSAGE_CHARS)
+
+
+def chain_client_factory() -> ChainClientFactory:
+    """Dependency so tests can swap in a client backed by a mock transport."""
+
+    def make(testnet: PublicTestnet) -> MempoolClient:
+        return MempoolClient(testnet=testnet)
+
+    return make
+
+
+@router.post("/scan")
+def scan_addresses(
+    body: ScanRequest, make_client: Annotated[ChainClientFactory, Depends(chain_client_factory)]
+) -> ScanResult:
+    if not body.lookup_chain:
+        return scan(body.addresses)
+    with make_client(body.testnet) as client:
+        return scan(body.addresses, lookup=client.activity)
+
+
+@router.get("/migration/{address_type}")
+def migration_plan(address_type: str) -> MigrationPlan:
+    return plan_for(parse_address_type(address_type))
+
+
+def guardian_classifier() -> Classifier:
+    """Dependency so tests can swap in a fake model. The key is checked per request, after body validation."""
+    return lambda message: guardian.classify_intent(message, guardian.build_client())
+
+
+@router.post("/guardian")
+def classify(body: GuardianRequest, classifier: Annotated[Classifier, Depends(guardian_classifier)]) -> GuardianResult:
+    return classifier(body.message)

kestrix/bitcoin/chain.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: 2026 Ruthvik Bandari and the BitShield (Team ACE) contributors
+# SPDX-License-Identifier: Apache-2.0
+"""Optional spend-history lookup on the public mempool.space API.
+
+Only used when the user asks for it: the queried addresses are sent to mempool.space.
+Every request URL passes ``netguard.check_url``; redirects are not followed, responses
+are size-capped and schema-validated, and any failure is ``Rejected(UPSTREAM_ERROR)``.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Literal
+
+import httpx
+from pydantic import BaseModel, Field, ValidationError
+
+from ..core.errors import Reason, Rejected
+from ..core.netguard import check_url
+from .address import ParsedAddress
+from .models import ChainActivity, Network, PublicTestnet
+
+MEMPOOL_BASE_URL = "https://mempool.space"
+TIMEOUT_SECONDS = 10.0
+MAX_RESPONSE_BYTES = 64 * 1024
+
+ChainName = Literal["mainnet", "testnet4", "signet"]
+_API_PREFIX: dict[ChainName, str] = {"mainnet": "/api", "testnet4": "/testnet4/api", "signet": "/signet/api"}
+
+
+class _TxoStats(BaseModel):
+    funded_txo_count: int = Field(ge=0)
+    funded_txo_sum: int = Field(ge=0)
+    spent_txo_count: int = Field(ge=0)
+    spent_txo_sum: int = Field(ge=0)
+
+
+class _AddressStats(BaseModel):
+    chain_stats: _TxoStats
+    mempool_stats: _TxoStats
+
+
+class MempoolClient:
+    """Looks up address spend history. Use as a context manager to close the connection pool."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = MEMPOOL_BASE_URL,
+        testnet: PublicTestnet = PublicTestnet.TESTNET4,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._testnet = testnet
+        self._http = httpx.Client(
+            timeout=TIMEOUT_SECONDS,
+            follow_redirects=False,
+            transport=transport,
+            headers={"Accept": "application/json"},
+        )
+
+    def __enter__(self) -> MempoolClient:
+        return self
+
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        self._http.close()
+
+    def _chain_for(self, network: Network | None) -> ChainName:
+        if network is Network.MAINNET:
+            return "mainnet"
+        if network is Network.TEST:
+            return "testnet4" if self._testnet is PublicTestnet.TESTNET4 else "signet"
+        raise Rejected(Reason.INVALID_INPUT, "only mainnet and public test-network addresses can be looked up")
+
+    def _get(self, url: str) -> bytes:
+        check_url(url)
+        try:
+            with self._http.stream("GET", url) as response:
+                if response.status_code == 429:
+                    raise Rejected(
+                        Reason.UPSTREAM_ERROR,
+                        "mempool.space rate limit reached; try again later or scan fewer addresses",
+                    )
+                if response.status_code >= 500:
+                    raise Rejected(Reason.UPSTREAM_ERROR, f"mempool.space server error (HTTP {response.status_code})")
+                if response.status_code != 200:
+                    raise Rejected(Reason.UPSTREAM_ERROR, f"mempool.space returned HTTP {response.status_code}")
+                body = bytearray()
+                for chunk in response.iter_bytes():
+                    body += chunk
+                    if len(body) > MAX_RESPONSE_BYTES:
+                        raise Rejected(Reason.UPSTREAM_ERROR, "mempool.space response exceeded the size limit")
+                return bytes(body)
+        except httpx.TimeoutException:
+            raise Rejected(
+                Reason.UPSTREAM_ERROR, f"mempool.space did not respond within {TIMEOUT_SECONDS:.0f} s"
+            ) from None
+        except httpx.HTTPError as exc:
+            raise Rejected(Reason.UPSTREAM_ERROR, f"could not reach mempool.space: {type(exc).__name__}") from None
+
+    def activity(self, parsed: ParsedAddress) -> ChainActivity:
+        chain = self._chain_for(parsed.network)
+        body = self._get(f"{self._base_url}{_API_PREFIX[chain]}/address/{parsed.text}")
+        try:
+            stats = _AddressStats.model_validate_json(body)
+        except ValidationError:
+            raise Rejected(Reason.UPSTREAM_ERROR, "mempool.space returned an unexpected response") from None
+        confirmed, pending = stats.chain_stats, stats.mempool_stats
+        return ChainActivity(
+            chain=chain,
+            funded_outputs=confirmed.funded_txo_count + pending.funded_txo_count,
+            spent_outputs=confirmed.spent_txo_count + pending.spent_txo_count,
+            balance_sats=confirmed.funded_txo_sum
+            + pending.funded_txo_sum
+            - confirmed.spent_txo_sum
+            - pending.spent_txo_sum,
+        )

kestrix/bitcoin/cli.py

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: 2026 Ruthvik Bandari and the BitShield (Team ACE) contributors
+# SPDX-License-Identifier: Apache-2.0
+"""``kestrix bitcoin`` commands.
+
+Exit codes: 0 success, 2 rejected input, 3 upstream service or AI key unavailable.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, NoReturn
+
+import typer
+
+from ..core.errors import Reason, Rejected
+from . import guardian
+from .chain import MempoolClient
+from .migration import parse_address_type, plan_for
+from .models import AddressAssessment, PublicTestnet
+from .risk import scan as scan_inputs
+
+app = typer.Typer(no_args_is_help=True)
+
+EXIT_REJECTED = 2
+EXIT_UNAVAILABLE = 3
+_UNAVAILABLE = frozenset(
+    {Reason.UPSTREAM_ERROR, Reason.AI_KEY_MISSING, Reason.TARGET_UNREACHABLE, Reason.TARGET_NOT_ALLOWED}
+)
+
+
+def _fail(exc: Rejected) -> NoReturn:
+    typer.echo(f"error ({exc.reason.value}): {exc.detail}", err=True)
+    raise typer.Exit(EXIT_UNAVAILABLE if exc.reason in _UNAVAILABLE else EXIT_REJECTED)
+
+
+def _print_assessment(item: AddressAssessment) -> None:
+    network = item.network.value if item.network else "no network"
+    typer.echo(f"[{item.risk.value.upper()}] {item.input}  ({item.address_type.value}, {network})")
+    typer.echo(f"  {item.explanation}")
+    typer.echo(f"  What to do: {item.recommendation}")
+
+
+@app.command()
+def scan(
+    addresses: Annotated[list[str], typer.Argument(help="Addresses or hex public keys (up to 100).")],
+    lookup_chain: Annotated[
+        bool, typer.Option("--lookup-chain", help="Check spend history on mempool.space (sends the addresses there).")
+    ] = False,
+    testnet: Annotated[
+        PublicTestnet, typer.Option(help="Public test chain for tb1/m/n/2 addresses.")
+    ] = PublicTestnet.TESTNET4,
+    as_json: Annotated[bool, typer.Option("--json", help="Print the result as JSON.")] = False,
+) -> None:
+    """Check addresses for public-key exposure to future quantum attacks."""
+    try:
+        if lookup_chain:
+            with MempoolClient(testnet=testnet) as client:
+                result = scan_inputs(addresses, lookup=client.activity)
+        else:
+            result = scan_inputs(addresses)
+    except Rejected as exc:
+        _fail(exc)
+    if as_json:
+        typer.echo(result.model_dump_json(indent=2))
+        return
+    for item in result.results:
+        _print_assessment(item)
+    counts = ", ".join(f"{risk.value} {count}" for risk, count in result.summary.by_risk.items())
+    typer.echo(f"\n{result.summary.total} scanned: {counts}")
+
+
+@app.command()
+def migration(
+    address_type: Annotated[str, typer.Argument(help="P2PK, P2PKH, P2SH, P2WPKH, P2WSH or P2TR.")],
+    as_json: Annotated[bool, typer.Option("--json", help="Print the plan as JSON.")] = False,
+) -> None:
+    """Show step-by-step migration advice for an address type."""
+    try:
+        plan = plan_for(parse_address_type(address_type))
+    except Rejected as exc:
+        _fail(exc)
+    if as_json:
+        typer.echo(plan.model_dump_json(indent=2))
+        return
+    typer.echo(f"{plan.address_type.value} (urgency: {plan.urgency})\n{plan.summary}\n")
+    for number, step in enumerate(plan.steps, start=1):
+        typer.echo(f"{number}. {step}")
+    typer.echo("\nCautions:")
+    for caution in plan.cautions:
+        typer.echo(f"- {caution}")
+
+
+@app.command()
+def ask(
+    message: Annotated[str, typer.Argument(help="A question or request in plain language.")],
+    as_json: Annotated[bool, typer.Option("--json", help="Print the result as JSON.")] = False,
+) -> None:
+    """Classify a plain-language request with your own Anthropic API key. Nothing is executed."""
+    try:
+        result = guardian.classify_intent(message, guardian.build_client())
+    except Rejected as exc:
+        _fail(exc)
+    if as_json:
+        typer.echo(result.model_dump_json(indent=2))
+        return
+    typer.echo(f"Intent: {result.intent.value}")
+    if result.addresses:
+        typer.echo(f"Addresses: {' '.join(result.addresses)}")
+    if result.ignored_addresses:
+        typer.echo(f"Ignored (not valid or not in your message): {' '.join(result.ignored_addresses)}")
+    typer.echo(f"Understood as (model-written): {result.model_summary}")
+    typer.echo(f"Next step: {result.next_step}")