From 05c110589787364c4a0b9bd51d1c0581bbd63051 Mon Sep 17 00:00:00 2001 From: Padreug Date: Sun, 31 May 2026 18:45:56 +0200 Subject: [PATCH 1/3] =?UTF-8?q?feat(v2):=20collision=20guard=20=E2=80=94?= =?UTF-8?q?=20refuse=20machines=20whose=20npub=20matches=20an=20operator?= =?UTF-8?q?=20account=20(#32)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds `_assert_no_pubkey_collision` to `views_api`, wired into `api_create_machine` between the wallet-ownership guard and the `create_machine` CRUD call. Refuses with HTTP 400 + operator-actionable error message if the supplied `machine_npub` matches any existing LNbits operator account's `accounts.pubkey`. ## Why this matters Reproducer 2026-05-30T21:33Z (coord-log archive `2026-05-31-pre-rotation.md`): Greg's operator account `accounts.pubkey` had been seeded as the same value as Sintra's `dca_machines.machine_npub` (`522a4538…`) during manual setup. The collision masked the routing bug for days — lnbits' nostr-transport `auth.py:resolve_nostr_auth` was routing inbound kind-21000 RPCs from the ATM directly to Greg's wallet *by coincidence* of the matching pubkey. When Greg's account migrated to `RemoteBunkerSigner` and got a fresh pubkey, the coincidence broke + `auto-account-from-npub` fired for the orphaned ATM npub. A real $20 test cash-out silently landed on a fresh auto-account wallet (`a94b564f…`); satmachineadmin lost the settlement entirely — no `dca_settlements` row, no DCA distribution, no commission split. The proper architectural fix is path B / `aiolabs/satmachineadmin#20` (S6, in-progress with lnbits — coord-log `2026-05-31T15:25Z`). This guard is the complementary preventive layer: stops a future operator from re-entering the broken state by registering a machine whose npub collides with an existing account. ## What's in this commit - **`views_api._assert_no_pubkey_collision`** — canonicalises the input npub (accepts hex or `npub1…` bech32) via `normalize_public_key`, queries `lnbits.core.crud.users.get_account_by_pubkey` (which itself lowercases internally), raises HTTPException(400) on hit. Error message names the canonical pubkey prefix, explains the pubkey-collision dependency that breaks on operator pubkey rotation, + points to the `lamassu-next provision-atm` remediation path + this issue for context. - **Wired into `api_create_machine`** after `_assert_wallet_owned_by` + before `create_machine`. `api_update_machine` is unaffected because `UpdateMachineData` doesn't allow npub changes on existing rows. - **`tests/test_collision_guard.py`** — 7 unit tests covering hex / bech32 / uppercase-hex inputs all canonicalise to the same lookup, the no-collision case returns silently, error message asserts (truncated pubkey + remediation hint). Uses pytest monkeypatch to isolate the assertion logic from a live `get_account_by_pubkey` DB call — matches the assertion-style pattern of `tests/test_nostr_attribution.py`. - **`CLAUDE.md`** — new "No-collision invariant" subsection under Security Considerations: documents the rule + the SQL check operators can run on existing installs + the `ATM_PRIVATE_KEY`-unset remediation + cross-refs to `#20` and `#32`. ## Regtest SQL check result Ran the diagnostic SQL against the regtest LNbits + satmachineadmin DBs: - 1 active `dca_machines.machine_npub`: `522a4538…` (Greg's Sintra) - 1 collision found: the auto-account orphan `a94b564f…` (username = None — auto-account signature) created during yesterday's silent-drop failure mode. NOT a legitimate operator account. Greg's actual operator account `ac35c9fc…` carries pubkey `197a4cf4…` post-bunker migration, no collision there. The orphan is operational cleanup (sweep + delete), separate from this code fix. No real-operator collisions remain on the regtest instance. ## Test status 162 passed, 1 pre-existing async-plugin failure unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 32 +++++++++ tests/test_collision_guard.py | 124 ++++++++++++++++++++++++++++++++++ views_api.py | 43 ++++++++++++ 3 files changed, 199 insertions(+) create mode 100644 tests/test_collision_guard.py diff --git a/CLAUDE.md b/CLAUDE.md index 9d2af64..acf23cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -219,6 +219,38 @@ commission_amount = 266800 - 258835 = 7,965 sats (to commission wallet) - Input sanitization and type validation - Audit logging for all administrative actions +### No-collision invariant — operator account pubkey ≠ ATM npub + +`dca_machines.machine_npub` and `accounts.pubkey` MUST NEVER hold the +same value across the LNbits instance. Enforced by +`views_api._assert_no_pubkey_collision` at machine-creation time +(rejects with HTTP 400) and by the matching SQL check operators can run +on existing installs: + +```sql +SELECT a.id, a.username, a.pubkey, m.id, m.machine_npub +FROM accounts a +JOIN ext_satoshimachine.dca_machines m + ON LOWER(a.pubkey) = LOWER(m.machine_npub); +``` + +**Why this matters**: when the two values match, lnbits' nostr-transport +`auth.py:resolve_nostr_auth` routes inbound kind-21000 RPCs from the +ATM directly to that operator's wallet *by collision* — it works by +coincidence, breaks silently the moment the operator's pubkey rotates +(then `auto-account-from-npub` fires for the orphaned ATM npub, and the +invoice lands on a fresh auto-account wallet instead). Reproduced on +2026-05-30 against Greg's Sintra (silent cash-out drop). The proper +architectural routing fix is `aiolabs/satmachineadmin#20` (path B / +S6); the collision guard prevents the broken state from being entered +in the first place. + +When provisioning a new ATM via `lamassu-next deploy/nixos/provision-atm.sh`, +**leave `ATM_PRIVATE_KEY` unset** so the script generates a fresh ATM +keypair (distinct from any operator's nsec). See +`aiolabs/satmachineadmin#32` for design rationale + the (eventual) +reverse-direction guard on account creation in lnbits proper. + ## Development Workflow ### Adding New Features diff --git a/tests/test_collision_guard.py b/tests/test_collision_guard.py new file mode 100644 index 0000000..0f1a236 --- /dev/null +++ b/tests/test_collision_guard.py @@ -0,0 +1,124 @@ +""" +Tests for `views_api._assert_no_pubkey_collision` (aiolabs/satmachineadmin#32). + +Defends against the silent-drop failure mode reproduced on 2026-05-30T21:33Z: +Greg's operator account pubkey had been seeded identical to the Sintra ATM's +machine_npub, which masked the routing problem until Greg's pubkey rotated +during the bunker migration — then `auto-account-from-npub` fired for the +orphaned ATM npub and the cash-out invoice silently landed on a fresh +auto-account wallet. + +The guard refuses to register a machine whose npub matches any LNbits +operator account's `accounts.pubkey`, so this state cannot be entered +through the satmachineadmin UI in the first place. + +Monkeypatches `views_api.get_account_by_pubkey` to avoid needing a live +LNbits DB; this matches the assertion-style of tests/test_nostr_attribution +(both isolate the assertion function for unit-testability). +""" + +import asyncio +from types import SimpleNamespace + +import pytest + +from .. import views_api +from ..views_api import _assert_no_pubkey_collision + +# Canonical x-only pubkey for the integer 1 secret (matches NIP-44 reference vector). +_PUBKEY_HEX = "79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798" +# Bech32 form of the same pubkey — operators may enter either form in the UI. +_PUBKEY_NPUB = "npub10xlxvlhemja6c4dqv22uapctqupfhlxm9h8z3k2e72q4k9hcz7vqpkge6d" + + +def _fake_account(pubkey: str = _PUBKEY_HEX): + """Account-shaped duck-typed object. _assert_no_pubkey_collision only + cares whether get_account_by_pubkey returns non-None; the returned + shape doesn't matter beyond that.""" + return SimpleNamespace(id="op1", username="alice", pubkey=pubkey) + + +def _patch_lookup(monkeypatch, return_value): + """Replace `views_api.get_account_by_pubkey` with an async stub that + captures the canonical-hex argument the guard normalised to and + returns the configured value.""" + captured = {} + + async def fake_lookup(pubkey: str): + captured["called_with"] = pubkey + return return_value + + monkeypatch.setattr(views_api, "get_account_by_pubkey", fake_lookup) + return captured + + +class TestCollisionDetected: + """Positive cases: machine_npub collides with an operator account's + pubkey. Each form (hex / bech32 / uppercase) must normalise to the + same canonical lookup + raise the same 400.""" + + def test_collision_with_hex_input_raises(self, monkeypatch): + _patch_lookup(monkeypatch, return_value=_fake_account()) + with pytest.raises(Exception) as exc: + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_HEX)) + assert exc.value.status_code == 400 + assert "collides with an existing LNbits operator account" in exc.value.detail + assert "aiolabs/satmachineadmin#32" in exc.value.detail + + def test_collision_with_bech32_input_raises(self, monkeypatch): + """Operator may enter `npub1...` in the UI; the guard must + canonicalise to hex BEFORE the lookup, otherwise a colliding + npub-form input would silently miss the hex-stored + accounts.pubkey row.""" + captured = _patch_lookup(monkeypatch, return_value=_fake_account()) + with pytest.raises(Exception) as exc: + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_NPUB)) + assert exc.value.status_code == 400 + # The bech32 input must be canonicalised to lowercase hex before the lookup. + assert captured["called_with"] == _PUBKEY_HEX + + def test_collision_with_uppercase_hex_input_raises(self, monkeypatch): + """Hex inputs from manual entry / paste can land uppercase; the + guard's `normalize_public_key().lower()` should bring it to the + canonical lowercase hex that get_account_by_pubkey itself also + lowercases internally.""" + captured = _patch_lookup(monkeypatch, return_value=_fake_account()) + with pytest.raises(Exception) as exc: + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_HEX.upper())) + assert exc.value.status_code == 400 + assert captured["called_with"] == _PUBKEY_HEX + + +class TestNoCollision: + """Negative cases: machine_npub does not match any account → guard + returns silently, machine creation can proceed.""" + + def test_no_collision_returns_silently(self, monkeypatch): + _patch_lookup(monkeypatch, return_value=None) + # Should NOT raise. + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_HEX)) + + def test_no_collision_bech32_form_returns_silently(self, monkeypatch): + captured = _patch_lookup(monkeypatch, return_value=None) + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_NPUB)) + # The lookup still gets called with the canonicalised hex form. + assert captured["called_with"] == _PUBKEY_HEX + + +class TestErrorMessage: + """The 400 detail must be operator-actionable: explains the failure, + points at the issue, and gives the remediation path.""" + + def test_error_includes_truncated_pubkey(self, monkeypatch): + _patch_lookup(monkeypatch, return_value=_fake_account()) + with pytest.raises(Exception) as exc: + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_HEX)) + # First 12 chars of the canonical lowercase hex, followed by an ellipsis. + assert _PUBKEY_HEX[:12] in exc.value.detail + + def test_error_includes_remediation_hint(self, monkeypatch): + _patch_lookup(monkeypatch, return_value=_fake_account()) + with pytest.raises(Exception) as exc: + asyncio.run(_assert_no_pubkey_collision(_PUBKEY_HEX)) + assert "lamassu-next" in exc.value.detail + assert "ATM_PRIVATE_KEY" in exc.value.detail diff --git a/views_api.py b/views_api.py index 66d9e76..6889803 100644 --- a/views_api.py +++ b/views_api.py @@ -9,8 +9,10 @@ from http import HTTPStatus from fastapi import APIRouter, Depends, HTTPException from lnbits.core.crud import get_wallet +from lnbits.core.crud.users import get_account_by_pubkey from lnbits.core.models import User from lnbits.decorators import check_super_user, check_user_exists +from lnbits.utils.nostr import normalize_public_key from .cassette_transport import ( CassetteTransportError, @@ -105,6 +107,46 @@ async def _assert_wallet_owned_by(wallet_id: str, user_id: str) -> None: ) +async def _assert_no_pubkey_collision(machine_npub: str) -> None: + """Defence-in-depth: refuse to register a machine whose npub matches + any LNbits operator account's pubkey. + + Such a collision causes lnbits' nostr-transport `auth.py:resolve_ + nostr_auth` to route inbound kind-21000 RPCs from the ATM directly + to that operator's wallet — works by coincidence, but breaks silently + the moment the operator's pubkey rotates (because the auto-account- + from-npub flow then fires for the ATM's now-orphaned npub, and the + invoice lands on a fresh auto-account wallet instead). Reproducer: + Greg's Sintra silent-drop on 2026-05-30T21:33Z. See + aiolabs/satmachineadmin#32 for the failure mode + this guard's + design rationale. + + Path B (`#20` roster-lookup) is the architectural fix at the + routing layer; this guard prevents new operators from inadvertently + setting up the collision in the first place. Two layers of defence. + + Idempotent on the same caller re-attempting machine creation with + the same npub (the second attempt hits the dca_machines.machine_npub + UNIQUE on m001, not this guard — they only collide with operator- + account pubkeys, not other machine npubs). + """ + canonical = normalize_public_key(machine_npub).lower() + matching = await get_account_by_pubkey(canonical) + if matching is not None: + raise HTTPException( + HTTPStatus.BAD_REQUEST, + ( + f"machine_npub {canonical[:12]}... collides with an " + f"existing LNbits operator account's pubkey. Registering " + "an ATM under this npub would silently route invoices via " + "a pubkey-collision dependency that breaks on operator " + "pubkey rotation. Use a fresh ATM keypair: lamassu-next " + "`provision-atm` regenerates one with `ATM_PRIVATE_KEY` " + "unset. See aiolabs/satmachineadmin#32." + ), + ) + + # ============================================================================= # Machines # ============================================================================= @@ -115,6 +157,7 @@ async def api_create_machine( data: CreateMachineData, user: User = Depends(check_user_exists) ) -> Machine: await _assert_wallet_owned_by(data.wallet_id, user.id) + await _assert_no_pubkey_collision(data.machine_npub) machine = await create_machine(user.id, data) return machine From 5850fb1ef4c08ddf01c9d268a9c6ca8106445710 Mon Sep 17 00:00:00 2001 From: Padreug Date: Sun, 31 May 2026 19:14:45 +0200 Subject: [PATCH 2/3] feat(v2): nostr-transport roster-resolver hook (#20 path-B) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- __init__.py | 7 ++ nostr_transport_roster.py | 143 +++++++++++++++++++++++++++++ tests/test_roster_resolver.py | 163 ++++++++++++++++++++++++++++++++++ 3 files changed, 313 insertions(+) create mode 100644 nostr_transport_roster.py create mode 100644 tests/test_roster_resolver.py diff --git a/__init__.py b/__init__.py index 2d0ebcf..daff156 100644 --- a/__init__.py +++ b/__init__.py @@ -5,6 +5,7 @@ from lnbits.tasks import create_permanent_unique_task from loguru import logger from .crud import db +from .nostr_transport_roster import register_with_lnbits as register_roster_with_lnbits from .tasks import wait_for_cassette_state_events, wait_for_paid_invoices from .views import satmachineadmin_generic_router from .views_api import satmachineadmin_api_router @@ -50,6 +51,12 @@ def satmachineadmin_start(): "ext_satmachineadmin_cassette_bootstrap", wait_for_cassette_state_events ) scheduled_tasks.append(cassette_task) + # Path-B wallet-routing hook (#20 / coord-log 2026-05-31T15:25Z): + # register our ATM-roster resolver with lnbits' nostr-transport so + # inbound kind-21000 from a known ATM npub routes to the operator's + # wallet, not an auto-created machine wallet. Soft-fails on lnbits + # versions that don't yet expose `register_roster_resolver`. + register_roster_with_lnbits() __all__ = [ diff --git a/nostr_transport_roster.py b/nostr_transport_roster.py new file mode 100644 index 0000000..9b16a7e --- /dev/null +++ b/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 +`LNBITS_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 " + "LNBITS_NOSTR_TRANSPORT_ROSTER_REQUIRED.)" + ) + return True diff --git a/tests/test_roster_resolver.py b/tests/test_roster_resolver.py new file mode 100644 index 0000000..70eb2d3 --- /dev/null +++ b/tests/test_roster_resolver.py @@ -0,0 +1,163 @@ +""" +Tests for `nostr_transport_roster.resolve` — the lookup function +satmachineadmin hands lnbits' nostr-transport via +`register_roster_resolver` (path-B wallet-routing fix, #20 / +coord-log 2026-05-31T15:25Z). + +Verifies: + - Known ATM npub → RouteHit with operator_user_id + wallet_id from + the machine row + - Unknown sender → None (lnbits falls back to its other resolvers, + or fail-closed rejection per the env-gated posture) + - bech32 input is normalised to hex before lookup + - Uppercase hex input is normalised to lowercase before lookup + - Malformed input raises (fail-closed sub-case per lnbits 15:15Z ack) + +`register_with_lnbits` is also smoke-tested for the soft-fail branch +that fires on lnbits versions without `register_roster_resolver`. The +positive (lnbits hook present) branch needs a live lnbits import + +will be covered once the lnbits-side PR lands. + +Coroutines driven via `asyncio.run` per project convention (no pytest- +asyncio plugin in CI; see test_cassette_state_consumer.py header). +""" + +import asyncio +import sys +from types import SimpleNamespace + +import coincurve +import pytest +from lnbits.utils.nostr import hex_to_npub + +from .. import nostr_transport_roster as roster +from ..nostr_transport_roster import register_with_lnbits, resolve + +_ATM_SEC = "00" * 31 + "02" +_ATM_PUB_HEX = ( + coincurve.PrivateKey(bytes.fromhex(_ATM_SEC)) + .public_key.format(compressed=True)[1:] + .hex() +) +_ATM_PUB_NPUB = hex_to_npub(_ATM_PUB_HEX) + + +def _fake_machine(operator_user_id: str, wallet_id: str, npub_hex: str): + return SimpleNamespace( + operator_user_id=operator_user_id, + wallet_id=wallet_id, + machine_npub=npub_hex, + ) + + +def test_resolve_known_atm_returns_route_hit(monkeypatch): + captured: dict[str, str] = {} + + async def _fake_lookup(pubkey_hex: str): + captured["pubkey_hex"] = pubkey_hex + return _fake_machine( + operator_user_id="op-123", + wallet_id="wallet-abc", + npub_hex=_ATM_PUB_HEX, + ) + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _fake_lookup) + + result = asyncio.run(resolve(_ATM_PUB_HEX)) + + # `_build_route_hit` prefers lnbits' canonical `RouteHit` when + # importable + falls back to our local class otherwise; assert on + # the frozen field-shape contract (coord-log 2026-05-31T15:25Z), + # not the specific class identity, so the test passes against + # both lnbits versions. + assert result is not None + assert result.operator_user_id == "op-123" + assert result.wallet_id == "wallet-abc" + assert result.source_extension == "satmachineadmin" + assert captured["pubkey_hex"] == _ATM_PUB_HEX + + +def test_resolve_unknown_sender_returns_none(monkeypatch): + async def _no_match(pubkey_hex: str): + return None + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _no_match) + + result = asyncio.run(resolve(_ATM_PUB_HEX)) + + assert result is None + + +def test_resolve_canonicalises_bech32_to_hex(monkeypatch): + """Sender pubkeys arrive lowercase-hex from lnbits PR #4, but the + resolver is paranoid: a bech32 input must still hit the hex-keyed + crud lookup.""" + captured: dict[str, str] = {} + + async def _fake_lookup(pubkey_hex: str): + captured["pubkey_hex"] = pubkey_hex + return _fake_machine( + operator_user_id="op-bech32", + wallet_id="wallet-bech32", + npub_hex=_ATM_PUB_HEX, + ) + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _fake_lookup) + + result = asyncio.run(resolve(_ATM_PUB_NPUB)) + + assert result is not None + assert captured["pubkey_hex"] == _ATM_PUB_HEX + + +def test_resolve_lowercases_uppercase_hex(monkeypatch): + captured: dict[str, str] = {} + + async def _fake_lookup(pubkey_hex: str): + captured["pubkey_hex"] = pubkey_hex + return None + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _fake_lookup) + + asyncio.run(resolve(_ATM_PUB_HEX.upper())) + + assert captured["pubkey_hex"] == _ATM_PUB_HEX + + +def test_resolve_raises_on_malformed_input(monkeypatch): + """Fail-closed sub-case per lnbits 15:15Z ack item 2: resolver + raising an exception surfaces to lnbits as a reject + ERROR log, + NOT a silent fall-through to auto-account creation.""" + + async def _unreachable(pubkey_hex: str): + raise AssertionError("crud must not be reached for malformed input") + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _unreachable) + + with pytest.raises((ValueError, AssertionError)): + asyncio.run(resolve("not-a-pubkey")) + + +def test_register_with_lnbits_soft_fails_without_hook(monkeypatch): + """Until the lnbits-side path-B PR lands, the registration call + must soft-fail cleanly (returns False, no exception) so + satmachineadmin keeps booting on every lnbits version.""" + real_import = ( + __builtins__["__import__"] + if isinstance(__builtins__, dict) + else __builtins__.__import__ + ) + + def _faulty_import(name, *args, **kwargs): + if name == "lnbits.core.services.nostr_transport": + raise ImportError("simulated: pre-path-B lnbits") + return real_import(name, *args, **kwargs) + + monkeypatch.setattr("builtins.__import__", _faulty_import) + # Drop any cached import so the lazy `from … import …` inside + # register_with_lnbits re-triggers the import statement. + monkeypatch.delitem( + sys.modules, "lnbits.core.services.nostr_transport", raising=False + ) + + assert register_with_lnbits() is False From cb1caf47d034594ff26efc67e091c4291de6a03c Mon Sep 17 00:00:00 2001 From: Padreug Date: Sun, 31 May 2026 19:14:45 +0200 Subject: [PATCH 3/3] feat(v2): nostr-transport roster-resolver hook (#20 path-B) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- __init__.py | 7 ++ nostr_transport_roster.py | 143 +++++++++++++++++++++++++++++ tests/test_roster_resolver.py | 163 ++++++++++++++++++++++++++++++++++ 3 files changed, 313 insertions(+) create mode 100644 nostr_transport_roster.py create mode 100644 tests/test_roster_resolver.py diff --git a/__init__.py b/__init__.py index 2d0ebcf..daff156 100644 --- a/__init__.py +++ b/__init__.py @@ -5,6 +5,7 @@ from lnbits.tasks import create_permanent_unique_task from loguru import logger from .crud import db +from .nostr_transport_roster import register_with_lnbits as register_roster_with_lnbits from .tasks import wait_for_cassette_state_events, wait_for_paid_invoices from .views import satmachineadmin_generic_router from .views_api import satmachineadmin_api_router @@ -50,6 +51,12 @@ def satmachineadmin_start(): "ext_satmachineadmin_cassette_bootstrap", wait_for_cassette_state_events ) scheduled_tasks.append(cassette_task) + # Path-B wallet-routing hook (#20 / coord-log 2026-05-31T15:25Z): + # register our ATM-roster resolver with lnbits' nostr-transport so + # inbound kind-21000 from a known ATM npub routes to the operator's + # wallet, not an auto-created machine wallet. Soft-fails on lnbits + # versions that don't yet expose `register_roster_resolver`. + register_roster_with_lnbits() __all__ = [ diff --git a/nostr_transport_roster.py b/nostr_transport_roster.py new file mode 100644 index 0000000..9b16a7e --- /dev/null +++ b/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 +`LNBITS_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 " + "LNBITS_NOSTR_TRANSPORT_ROSTER_REQUIRED.)" + ) + return True diff --git a/tests/test_roster_resolver.py b/tests/test_roster_resolver.py new file mode 100644 index 0000000..70eb2d3 --- /dev/null +++ b/tests/test_roster_resolver.py @@ -0,0 +1,163 @@ +""" +Tests for `nostr_transport_roster.resolve` — the lookup function +satmachineadmin hands lnbits' nostr-transport via +`register_roster_resolver` (path-B wallet-routing fix, #20 / +coord-log 2026-05-31T15:25Z). + +Verifies: + - Known ATM npub → RouteHit with operator_user_id + wallet_id from + the machine row + - Unknown sender → None (lnbits falls back to its other resolvers, + or fail-closed rejection per the env-gated posture) + - bech32 input is normalised to hex before lookup + - Uppercase hex input is normalised to lowercase before lookup + - Malformed input raises (fail-closed sub-case per lnbits 15:15Z ack) + +`register_with_lnbits` is also smoke-tested for the soft-fail branch +that fires on lnbits versions without `register_roster_resolver`. The +positive (lnbits hook present) branch needs a live lnbits import + +will be covered once the lnbits-side PR lands. + +Coroutines driven via `asyncio.run` per project convention (no pytest- +asyncio plugin in CI; see test_cassette_state_consumer.py header). +""" + +import asyncio +import sys +from types import SimpleNamespace + +import coincurve +import pytest +from lnbits.utils.nostr import hex_to_npub + +from .. import nostr_transport_roster as roster +from ..nostr_transport_roster import register_with_lnbits, resolve + +_ATM_SEC = "00" * 31 + "02" +_ATM_PUB_HEX = ( + coincurve.PrivateKey(bytes.fromhex(_ATM_SEC)) + .public_key.format(compressed=True)[1:] + .hex() +) +_ATM_PUB_NPUB = hex_to_npub(_ATM_PUB_HEX) + + +def _fake_machine(operator_user_id: str, wallet_id: str, npub_hex: str): + return SimpleNamespace( + operator_user_id=operator_user_id, + wallet_id=wallet_id, + machine_npub=npub_hex, + ) + + +def test_resolve_known_atm_returns_route_hit(monkeypatch): + captured: dict[str, str] = {} + + async def _fake_lookup(pubkey_hex: str): + captured["pubkey_hex"] = pubkey_hex + return _fake_machine( + operator_user_id="op-123", + wallet_id="wallet-abc", + npub_hex=_ATM_PUB_HEX, + ) + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _fake_lookup) + + result = asyncio.run(resolve(_ATM_PUB_HEX)) + + # `_build_route_hit` prefers lnbits' canonical `RouteHit` when + # importable + falls back to our local class otherwise; assert on + # the frozen field-shape contract (coord-log 2026-05-31T15:25Z), + # not the specific class identity, so the test passes against + # both lnbits versions. + assert result is not None + assert result.operator_user_id == "op-123" + assert result.wallet_id == "wallet-abc" + assert result.source_extension == "satmachineadmin" + assert captured["pubkey_hex"] == _ATM_PUB_HEX + + +def test_resolve_unknown_sender_returns_none(monkeypatch): + async def _no_match(pubkey_hex: str): + return None + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _no_match) + + result = asyncio.run(resolve(_ATM_PUB_HEX)) + + assert result is None + + +def test_resolve_canonicalises_bech32_to_hex(monkeypatch): + """Sender pubkeys arrive lowercase-hex from lnbits PR #4, but the + resolver is paranoid: a bech32 input must still hit the hex-keyed + crud lookup.""" + captured: dict[str, str] = {} + + async def _fake_lookup(pubkey_hex: str): + captured["pubkey_hex"] = pubkey_hex + return _fake_machine( + operator_user_id="op-bech32", + wallet_id="wallet-bech32", + npub_hex=_ATM_PUB_HEX, + ) + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _fake_lookup) + + result = asyncio.run(resolve(_ATM_PUB_NPUB)) + + assert result is not None + assert captured["pubkey_hex"] == _ATM_PUB_HEX + + +def test_resolve_lowercases_uppercase_hex(monkeypatch): + captured: dict[str, str] = {} + + async def _fake_lookup(pubkey_hex: str): + captured["pubkey_hex"] = pubkey_hex + return None + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _fake_lookup) + + asyncio.run(resolve(_ATM_PUB_HEX.upper())) + + assert captured["pubkey_hex"] == _ATM_PUB_HEX + + +def test_resolve_raises_on_malformed_input(monkeypatch): + """Fail-closed sub-case per lnbits 15:15Z ack item 2: resolver + raising an exception surfaces to lnbits as a reject + ERROR log, + NOT a silent fall-through to auto-account creation.""" + + async def _unreachable(pubkey_hex: str): + raise AssertionError("crud must not be reached for malformed input") + + monkeypatch.setattr(roster, "get_machine_by_atm_pubkey_hex", _unreachable) + + with pytest.raises((ValueError, AssertionError)): + asyncio.run(resolve("not-a-pubkey")) + + +def test_register_with_lnbits_soft_fails_without_hook(monkeypatch): + """Until the lnbits-side path-B PR lands, the registration call + must soft-fail cleanly (returns False, no exception) so + satmachineadmin keeps booting on every lnbits version.""" + real_import = ( + __builtins__["__import__"] + if isinstance(__builtins__, dict) + else __builtins__.__import__ + ) + + def _faulty_import(name, *args, **kwargs): + if name == "lnbits.core.services.nostr_transport": + raise ImportError("simulated: pre-path-B lnbits") + return real_import(name, *args, **kwargs) + + monkeypatch.setattr("builtins.__import__", _faulty_import) + # Drop any cached import so the lazy `from … import …` inside + # register_with_lnbits re-triggers the import statement. + monkeypatch.delitem( + sys.modules, "lnbits.core.services.nostr_transport", raising=False + ) + + assert register_with_lnbits() is False