keyfleet 0.1.0__py3-none-any.whl

keyfleet/__init__.py

@@ -0,0 +1,5 @@
+"""keyfleet — a local-first ledger for hardware security keys.
+
+Maps keys ↔ accounts ↔ credential types and reports coverage gaps, lost-key
+impact, capacity, and advisories. Stores no secrets; makes no network calls.
+"""

keyfleet/bundled.py

@@ -0,0 +1,243 @@
+"""Bundled reference data: services.yaml, models.yaml, advisories.yaml.
+
+Every entry in the data files carries ``source_url`` and ``verified`` — facts
+are read from the vendor's/service's own pages, never guessed (AGENTS.md §6).
+Loading happens once via :func:`load_bundled`; checks receive the result as a
+plain argument so they stay pure.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib import resources
+from typing import Any
+
+import yaml
+from pydantic import BaseModel, Field, ValidationError
+
+from keyfleet.model import (
+    Advisory,
+    Capability,
+    Interface,
+    Key,
+    Ledger,
+    LedgerError,
+    StrictModel,
+    Vendor,
+)
+
+_URL_PATTERN = r"^https?://\S+$"
+
+
+class CapacityRule(StrictModel):
+    """Discoverable-credential capacity for a firmware range (lt exclusive, ge inclusive)."""
+
+    firmware_lt: str | None = None
+    firmware_ge: str | None = None
+    capacity: int = Field(ge=0)
+
+
+class KeyModelInfo(StrictModel):
+    """One hardware-key model family in models.yaml."""
+
+    id: str
+    vendor: Vendor
+    family: str = Field(
+        min_length=1,
+        description="Case-insensitive prefix matched against Key.model; longest family wins.",
+    )
+    capabilities: list[Capability] | None = None
+    interfaces: list[Interface] | None = None
+    discoverable_capacity: int | list[CapacityRule] | None = None
+    source_url: str = Field(pattern=_URL_PATTERN)
+    verified: dt.date
+    notes: str = ""
+
+
+class ServiceInfo(StrictModel):
+    """One service entry in services.yaml."""
+
+    name: str = Field(min_length=1)
+    security_settings_url: str | None = Field(None, pattern=_URL_PATTERN)
+    max_keys: int | None = Field(None, ge=0)
+    fido2_discoverable: bool | None = None
+    notes: str = ""
+    source_url: str = Field(pattern=_URL_PATTERN)
+    verified: dt.date
+
+
+class BundledData(BaseModel):
+    """All bundled reference data, loaded once and passed around."""
+
+    services: dict[str, ServiceInfo] = Field(default_factory=dict)
+    models: list[KeyModelInfo] = Field(default_factory=list)
+    advisories: list[Advisory] = Field(default_factory=list)
+
+
+def _read_data_yaml(name: str) -> Any:
+    file = resources.files("keyfleet").joinpath("data", name)
+    try:
+        text = file.read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise LedgerError(f"bundled data file {name} is missing from the package") from exc
+    return yaml.safe_load(text)
+
+
+def example_ledger_text() -> str:
+    """The packaged example ledger (mirrors keyfleet.example.yaml at the repo root)."""
+    return resources.files("keyfleet").joinpath("data", "example.yaml").read_text(encoding="utf-8")
+
+
+@lru_cache(maxsize=1)
+def load_bundled() -> BundledData:
+    """Load and validate the three bundled data files."""
+    try:
+        return BundledData.model_validate(
+            {
+                "services": (_read_data_yaml("services.yaml") or {}).get("services", {}),
+                "models": (_read_data_yaml("models.yaml") or {}).get("models", []),
+                "advisories": (_read_data_yaml("advisories.yaml") or {}).get("advisories", []),
+            }
+        )
+    except ValidationError as exc:
+        raise LedgerError(f"bundled data is invalid (packaging bug):\n{exc}") from exc
+
+
+def services_markdown(bundled: BundledData) -> str:
+    """The generated docs/SERVICES.md content."""
+    lines = [
+        "# Services",
+        "",
+        "Generated from `src/keyfleet/data/services.yaml` — do not edit by hand;",
+        "regenerate with `uv run python scripts/gen_services_md.py`.",
+        "",
+        "Every fact comes from the service's own page (*source*), read on the",
+        "*verified* date. `—` means the service documents no such fact; `?` means",
+        "the page does not say either way.",
+        "",
+        "| Service | Security-key settings | Max keys | Passkeys | Source | Verified |",
+        "|---|---|---|---|---|---|",
+    ]
+    for service_id, service in bundled.services.items():
+        settings = (
+            f"[settings]({service.security_settings_url})" if service.security_settings_url else "—"
+        )
+        max_keys = "—" if service.max_keys is None else str(service.max_keys)
+        passkeys = {True: "yes", False: "no", None: "?"}[service.fido2_discoverable]
+        lines.append(
+            f"| {service.name} (`{service_id}`) | {settings} | {max_keys} "
+            f"| {passkeys} | [source]({service.source_url}) | {service.verified} |"
+        )
+    lines += ["", f"{len(bundled.services)} services."]
+    return "\n".join(lines) + "\n"
+
+
+def firmware_tuple(firmware: str) -> tuple[int, ...]:
+    """'5.7.1' → (5, 7, 1). Non-numeric segment suffixes are ignored ('4a' → 4)."""
+    parts: list[int] = []
+    for segment in firmware.strip().split("."):
+        digits = ""
+        for char in segment:
+            if char.isdigit():
+                digits += char
+            else:
+                break
+        parts.append(int(digits) if digits else 0)
+    return tuple(parts)
+
+
+def firmware_in_range(
+    firmware: str, *, firmware_ge: str | None = None, firmware_lt: str | None = None
+) -> bool:
+    """Inclusive lower bound, exclusive upper bound; missing bounds are open."""
+    value = firmware_tuple(firmware)
+    if firmware_ge is not None and value < firmware_tuple(firmware_ge):
+        return False
+    return not (firmware_lt is not None and value >= firmware_tuple(firmware_lt))
+
+
+def model_info_for_key(models: list[KeyModelInfo], key: Key) -> KeyModelInfo | None:
+    """The models.yaml entry for a ledger key: same vendor, longest family prefix."""
+    if not key.model:
+        return None
+    name = key.model.strip().lower()
+    candidates = [
+        info
+        for info in models
+        if info.vendor is key.vendor and name.startswith(info.family.lower())
+    ]
+    if not candidates:
+        return None
+    return max(candidates, key=lambda info: len(info.family))
+
+
+@dataclass(frozen=True, slots=True)
+class AdvisoryMatch:
+    """One ledger key against the advisory list."""
+
+    key_id: str
+    key_label: str
+    firmware: str | None  # None → the key needs `firmware:` set to evaluate
+    advisories: tuple[Advisory, ...]
+
+    @property
+    def needs_firmware(self) -> bool:
+        return self.firmware is None
+
+
+def match_advisories(ledger: Ledger, bundled: BundledData) -> list[AdvisoryMatch]:
+    """Match every ledger key against bundled + ledger advisories.
+
+    Ledger advisories extend the bundled list; on an id collision the ledger
+    entry wins. A key with no firmware whose vendor has advisories on file
+    yields a needs-firmware entry (brief §9). Keys of vendors with no
+    advisories are omitted entirely.
+    """
+    merged: dict[str, Advisory] = {advisory.id: advisory for advisory in bundled.advisories}
+    for advisory in ledger.advisories:
+        merged[advisory.id] = advisory
+    by_vendor: dict[Vendor, list[Advisory]] = {}
+    for advisory in merged.values():
+        by_vendor.setdefault(advisory.vendor, []).append(advisory)
+
+    matches: list[AdvisoryMatch] = []
+    for key in ledger.keys:
+        candidates = by_vendor.get(key.vendor, [])
+        if not candidates:
+            continue
+        if key.firmware is None:
+            matches.append(AdvisoryMatch(key.id, key.label, None, ()))
+            continue
+        matched = tuple(
+            sorted(
+                (
+                    advisory
+                    for advisory in candidates
+                    if firmware_in_range(
+                        key.firmware,
+                        firmware_ge=advisory.affects.firmware_ge,
+                        firmware_lt=advisory.affects.firmware_lt,
+                    )
+                ),
+                key=lambda advisory: advisory.id,
+            )
+        )
+        if matched:
+            matches.append(AdvisoryMatch(key.id, key.label, key.firmware, matched))
+    return matches
+
+
+def discoverable_capacity(info: KeyModelInfo, firmware: str | None) -> int | None:
+    """Resolve a key's discoverable-credential capacity, or None if indeterminate."""
+    rules = info.discoverable_capacity
+    if rules is None or isinstance(rules, int):
+        return rules
+    if firmware is None:
+        capacities = {rule.capacity for rule in rules}
+        return capacities.pop() if len(capacities) == 1 else None
+    for rule in rules:
+        if firmware_in_range(firmware, firmware_ge=rule.firmware_ge, firmware_lt=rule.firmware_lt):
+            return rule.capacity
+    return None

keyfleet/checks.py

@@ -0,0 +1,263 @@
+"""Pure check functions over a validated :class:`~keyfleet.model.Ledger`.
+
+Checks take the loaded ledger and return findings; no file or terminal I/O
+happens here (AGENTS.md §5). Rendering lives in :mod:`keyfleet.report`.
+Core rules: brief §9.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from keyfleet.bundled import BundledData, discoverable_capacity, model_info_for_key
+from keyfleet.model import Account, KeyStatus, Ledger, RegistrationType
+
+
+class Level(StrEnum):
+    FAIL = "FAIL"
+    WARN = "WARN"
+    INFO = "INFO"
+
+
+_LEVEL_ORDER = {Level.FAIL: 0, Level.WARN: 1, Level.INFO: 2}
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """One actionable result of one check."""
+
+    level: Level
+    check: str  # machine-readable check id, e.g. "min-keys"
+    message: str
+    account_id: str | None = None
+    key_id: str | None = None
+
+
+#: Key statuses that count toward an account's coverage (brief §9): a lost or
+#: retired key is not a backup.
+COVERAGE_STATUSES = frozenset({KeyStatus.ACTIVE, KeyStatus.SPARE})
+
+
+def covering_key_ids(ledger: Ledger, account: Account) -> set[str]:
+    """Distinct keys registered on ``account`` whose status counts as coverage."""
+    status_by_id = {key.id: key.status for key in ledger.keys}
+    return {
+        registration.key
+        for registration in account.registrations
+        if status_by_id[registration.key] in COVERAGE_STATUSES
+    }
+
+
+def check_min_keys(ledger: Ledger) -> list[Finding]:
+    """FAIL for every account with fewer counted keys than ``policy.min_keys[tier]``."""
+    findings: list[Finding] = []
+    for account in ledger.accounts:
+        required = ledger.policy.min_keys.for_tier(account.tier)
+        have = len(covering_key_ids(ledger, account))
+        if have < required:
+            noun = "hardware key" if have == 1 else "hardware keys"
+            findings.append(
+                Finding(
+                    level=Level.FAIL,
+                    check="min-keys",
+                    message=(
+                        f'{account.tier} "{account.label}" has {have} {noun} registered; '
+                        f"policy requires {required}"
+                    ),
+                    account_id=account.id,
+                )
+            )
+    return findings
+
+
+def check_lost_retired(ledger: Ledger) -> list[Finding]:
+    """FAIL for every lost/retired key still carrying registrations.
+
+    Whoever holds the key can still use those credentials — de-register them
+    (``keyfleet lost KEY`` prints the ordered checklist).
+    """
+    accounts_using: dict[str, int] = {}
+    for account in ledger.accounts:
+        for key_id in {registration.key for registration in account.registrations}:
+            accounts_using[key_id] = accounts_using.get(key_id, 0) + 1
+    findings: list[Finding] = []
+    for key in ledger.keys:
+        if key.status not in (KeyStatus.LOST, KeyStatus.RETIRED):
+            continue
+        count = accounts_using.get(key.id, 0)
+        if count:
+            noun = "account" if count == 1 else "accounts"
+            findings.append(
+                Finding(
+                    level=Level.FAIL,
+                    check="lost-retired",
+                    message=(
+                        f"Key {key.id} is {key.status.value.upper()} but still registered "
+                        f"on {count} {noun} → run: keyfleet lost {key.id}"
+                    ),
+                    key_id=key.id,
+                )
+            )
+    return findings
+
+
+def check_weak_factors(ledger: Ledger) -> list[Finding]:
+    """WARN for every factor an account carries that its tier's policy warns against."""
+    findings: list[Finding] = []
+    for account in ledger.accounts:
+        warned = ledger.policy.warn_factors.get(account.tier, [])
+        findings.extend(
+            Finding(
+                level=Level.WARN,
+                check="weak-factor",
+                message=f'{account.tier} "{account.label}" lists {factor.value} as a factor',
+                account_id=account.id,
+            )
+            for factor in account.other_factors
+            if factor in warned
+        )
+    return findings
+
+
+def check_spare_unregistered(ledger: Ledger) -> list[Finding]:
+    """WARN for spare keys registered nowhere — an unregistered spare is not a backup."""
+    registered = {
+        registration.key for account in ledger.accounts for registration in account.registrations
+    }
+    return [
+        Finding(
+            level=Level.WARN,
+            check="spare-unregistered",
+            message=(
+                f"Spare key {key.id} is registered nowhere "
+                "(a spare that isn't registered is not a backup)"
+            ),
+            key_id=key.id,
+        )
+        for key in ledger.keys
+        if key.status is KeyStatus.SPARE and key.id not in registered
+    ]
+
+
+def check_recovery_codes(ledger: Ledger) -> list[Finding]:
+    """INFO when a tier that requires recovery codes has an account without a stored pointer."""
+    required = set(ledger.policy.require_recovery_codes_for)
+    findings: list[Finding] = []
+    for account in ledger.accounts:
+        if account.tier not in required:
+            continue
+        pointer = account.recovery_codes
+        if pointer is None:
+            detail = "has no recovery-code pointer"
+        elif not pointer.stored:
+            detail = "marks recovery codes as not stored"
+        else:
+            continue
+        findings.append(
+            Finding(
+                level=Level.INFO,
+                check="recovery-codes",
+                message=(
+                    f'{account.tier} "{account.label}" {detail} '
+                    f"(policy requires recovery codes for {account.tier})"
+                ),
+                account_id=account.id,
+            )
+        )
+    return findings
+
+
+#: Discoverable-credential usage fractions at which capacity findings appear.
+CAPACITY_INFO_AT = 0.5
+CAPACITY_WARN_AT = 0.9
+
+
+def check_capacity(ledger: Ledger, bundled: BundledData) -> list[Finding]:
+    """Discoverable-credential usage per key vs models.yaml capacity.
+
+    Ledger-based estimate — it can undercount (registrations made outside the
+    ledger are invisible). INFO from 50% usage, WARN from 90%.
+    """
+    counts: dict[str, int] = {}
+    for account in ledger.accounts:
+        for registration in account.registrations:
+            if registration.type is RegistrationType.FIDO2_DISCOVERABLE:
+                counts[registration.key] = counts.get(registration.key, 0) + 1
+    findings: list[Finding] = []
+    for key in ledger.keys:
+        count = counts.get(key.id, 0)
+        if not count:
+            continue
+        info = model_info_for_key(bundled.models, key)
+        capacity = discoverable_capacity(info, key.firmware) if info else None
+        if not capacity:
+            continue
+        usage = count / capacity
+        if usage >= CAPACITY_WARN_AT:
+            level, action = Level.WARN, "nearly full; free slots or add a key"
+        elif usage >= CAPACITY_INFO_AT:
+            level, action = Level.INFO, "plan capacity"
+        else:
+            continue
+        findings.append(
+            Finding(
+                level=level,
+                check="capacity",
+                message=(
+                    f"{key.id}: {count}/{capacity} discoverable credentials "
+                    f"(ledger count) — {action}"
+                ),
+                key_id=key.id,
+            )
+        )
+    return findings
+
+
+def check_unknown_service(ledger: Ledger, bundled: BundledData) -> list[Finding]:
+    """WARN when an account's service id names no bundled service ("other" is exempt).
+
+    Usually a typo; a correct id buys the account working links in
+    ``keyfleet lost`` and ``keyfleet report``.
+    """
+    return [
+        Finding(
+            level=Level.WARN,
+            check="unknown-service",
+            message=(
+                f'account "{account.label}": service "{account.service}" is not in the '
+                'bundled services.yaml — typo, or use "other" (contributions welcome)'
+            ),
+            account_id=account.id,
+        )
+        for account in ledger.accounts
+        if account.service != "other" and account.service not in bundled.services
+    ]
+
+
+#: Ledger-only checks, in run order.
+ALL_CHECKS = (
+    check_min_keys,
+    check_lost_retired,
+    check_weak_factors,
+    check_spare_unregistered,
+    check_recovery_codes,
+)
+
+#: Checks that also need the bundled reference data.
+DATA_CHECKS = (check_capacity, check_unknown_service)
+
+
+def run_checks(ledger: Ledger, bundled: BundledData | None = None) -> list[Finding]:
+    """Run every check; findings ordered FAIL → WARN → INFO, stable within a level.
+
+    Without ``bundled``, the data-driven checks (capacity, unknown service)
+    are skipped.
+    """
+    findings: list[Finding] = []
+    for check in ALL_CHECKS:
+        findings.extend(check(ledger))
+    if bundled is not None:
+        for data_check in DATA_CHECKS:
+            findings.extend(data_check(ledger, bundled))
+    return sorted(findings, key=lambda finding: _LEVEL_ORDER[finding.level])