feat(v2): nostr-transport roster-resolver hook (#20 path-B)

Exposes `resolve(sender_pubkey_hex) -> RouteHit | None` and a
`register_with_lnbits()` helper that lazily-imports + soft-fails on
lnbits versions without `register_roster_resolver`. Wired into
`satmachineadmin_start()`.

The hook delivers the path-B outcome ("cash-out sats go to the
operator's wallet, not an auto-created machine wallet") once the
lnbits side ships its half. Shape contract `(operator_user_id,
wallet_id, source_extension)` frozen per coord-log 2026-05-31T15:25Z.
Branch held local until lnbits lands the registry — no behaviour
change on the current lnbits version, just the future-ready handoff
+ a benign INFO log on boot.

Boot-smoked in dev container: extension loads, registration logs the
documented soft-fail message, invoice listener + cassette consumer
unchanged. 6 new unit tests cover happy path, miss, bech32 +
uppercase canonicalisation, fail-closed on malformed input, and the
soft-fail register branch.

nostr_transport_roster.py

@@ -0,0 +1,143 @@
+"""
+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 satmachineadmin 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 = "satmachineadmin"
+
+
+@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 satmachineadmin
+    boots cleanly; only the routing-via-roster behavior is gated on
+    the lnbits side being present.
+
+    Called once from `satmachineadmin_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(
+            "satmachineadmin: 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"satmachineadmin: 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