spirekeeper/nostr_transport_roster.py

"""
Roster-resolver hook for the path-B wallet-routing fix
(aiolabs/satmachineadmin#20 / lnbits-side issue forthcoming per
coord-log 2026-05-31T15:25Z).

Exposes a `resolve(sender_pubkey_hex)` function that, given an inbound
NIP-46 sender pubkey, looks it up against `dca_machines.machine_npub`
and returns a `RouteHit(operator_user_id, wallet_id, source_extension)`
on a match.

The hook is registered with lnbits' `nostr_transport` at extension-init
time via `register_with_lnbits()`. Until the lnbits side ships
`lnbits.core.services.nostr_transport.register_roster_resolver`, the
registration call lazily-imports + soft-fails so spirekeeper keeps
loading cleanly on any lnbits version.

When the lnbits implementation lands + the satmachine instance has
`NOSTR_TRANSPORT_ROSTER_REQUIRED=true` set, inbound kind-21000
RPCs from a registered ATM npub will route directly to the operator's
wallet (delivering the "cash-out sats go to the operator's wallet, not
an auto-created machine wallet" outcome). Unregistered npubs get
rejected with the fail-closed posture user chose at coord-log
2026-05-31T14:38Z.

Field-shape contract for `RouteHit` is FROZEN per coord-log
2026-05-31T15:25Z lnbits ack: `(operator_user_id, wallet_id,
source_extension)`. Don't add fields here without a coord-log round —
the shape is a multi-extension API contract.
"""

from __future__ import annotations

from dataclasses import dataclass

from lnbits.utils.nostr import normalize_public_key
from loguru import logger

from .crud import get_machine_by_atm_pubkey_hex

_SOURCE_EXTENSION = "spirekeeper"


@dataclass(frozen=True)
class RouteHit:
    """A positive answer from a roster resolver: route the resulting
    invoice to (operator_user_id, wallet_id). `source_extension`
    identifies which roster matched — used by lnbits for loud-reject
    logging when the failure-mode posture rejects.

    Local definition mirrors the agreed lnbits-side shape per coord-log
    2026-05-31T15:25Z. When lnbits' canonical class is importable,
    `register_with_lnbits` prefers it over this local one — but the
    local stays as a fallback so this module imports cleanly on pre-
    landing lnbits versions + drives the unit tests.
    """

    operator_user_id: str
    wallet_id: str
    source_extension: str = _SOURCE_EXTENSION


async def resolve(sender_pubkey_hex: str) -> RouteHit | None:
    """Roster lookup: given a sender pubkey from an inbound nostr-
    transport RPC, return a RouteHit if it's a registered ATM, None
    otherwise.

    Canonicalises the input first (sender pubkeys arrive lowercase-hex
    from `Payment.extra.nostr_sender_pubkey` per lnbits PR #4, but
    upstream is paranoid — normalise just in case).

    Raises on a malformed pubkey input — lnbits' fail-closed posture
    (option b at coord-log 2026-05-31T14:38Z, ack'd at 15:15Z item 2
    sub-case "resolver raises an exception → reject + ERROR log")
    means this surfaces as a rejection, not a silent fall-through.
    Same handling as any other unrecoverable resolver error.
    """
    canonical = normalize_public_key(sender_pubkey_hex).lower()
    machine = await get_machine_by_atm_pubkey_hex(canonical)
    if machine is None:
        return None
    return _build_route_hit(
        operator_user_id=machine.operator_user_id,
        wallet_id=machine.wallet_id,
    )


def _build_route_hit(operator_user_id: str, wallet_id: str):
    """Construct a RouteHit using lnbits' canonical class if importable,
    otherwise the local fallback. Centralised so a future lnbits-side
    shape evolution only touches this helper."""
    try:
        from lnbits.core.services.nostr_transport import (  # type: ignore[attr-defined]
            RouteHit as _LnbitsRouteHit,
        )
    except ImportError:
        return RouteHit(
            operator_user_id=operator_user_id,
            wallet_id=wallet_id,
            source_extension=_SOURCE_EXTENSION,
        )
    return _LnbitsRouteHit(
        operator_user_id=operator_user_id,
        wallet_id=wallet_id,
        source_extension=_SOURCE_EXTENSION,
    )


def register_with_lnbits() -> bool:
    """Register `resolve` with lnbits' nostr-transport roster registry.

    Returns True if the registration landed (lnbits surface available
    + call succeeded), False if soft-failed because lnbits hasn't
    shipped `register_roster_resolver` yet — that's the expected
    state until the path-B lnbits PR lands. Either way spirekeeper
    boots cleanly; only the routing-via-roster behavior is gated on
    the lnbits side being present.

    Called once from `spirekeeper_start()`. Idempotent on the
    lnbits side per their 15:15Z spec ("re-registration on extension
    reload replaces cleanly").
    """
    try:
        from lnbits.core.services.nostr_transport import (  # type: ignore[attr-defined]
            register_roster_resolver,
        )
    except ImportError:
        logger.info(
            "spirekeeper: nostr-transport roster-resolver hook not "
            "available on this lnbits version (pre-path-B); ATM-npub "
            "routing falls through to lnbits' default auto-account-from-"
            "npub behaviour. See aiolabs/satmachineadmin#20 / coord-log "
            "2026-05-31T15:25Z for the path-B handoff."
        )
        return False
    register_roster_resolver(_SOURCE_EXTENSION, resolve)
    logger.info(
        f"spirekeeper: registered '{_SOURCE_EXTENSION}' roster "
        "resolver with lnbits nostr-transport — inbound kind-21000 "
        "from a registered ATM npub will route to the operator's wallet "
        "directly. (Behavior gated server-side by "
        "NOSTR_TRANSPORT_ROSTER_REQUIRED.)"
    )
    return True