feat(infra): pass Blossom S3 config to Zooid with schema key prefix

Co-authored-by: userAdityaa <aditya.chaudhary1558@gmail.com>
Co-committed-by: userAdityaa <aditya.chaudhary1558@gmail.com>

.gitea/workflows/docker-publish.yml

@@ -0,0 +1,59 @@
+name: Docker
+
+on:
+  push:
+    branches: [master]
+
+env:
+  REGISTRY: gitea.coracle.social
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    strategy:
+      matrix:
+        include:
+          - component: frontend
+            image: coracle/caravel-frontend
+            context: frontend
+          - component: backend
+            image: coracle/caravel-backend
+            context: backend
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: hodlbod
+          password: ${{ secrets.PACKAGE_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ matrix.image }}
+          tags: |
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/master' }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker-container
+
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ matrix.context }}
+          push: true
+          platforms: linux/amd64,linux/arm64
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

README.md

@@ -26,7 +26,7 @@ docker run -it \
   -v ./config:/app/config \
   -v ./media:/app/media \
   -v ./data:/app/data \
-  ghcr.io/coracle-social/zooid
+  gitea.coracle.social/coracle/zooid
 ```
 
 ### 2. Configure the backend

backend/.env.template

@@ -26,7 +26,17 @@ LIVEKIT_URL=
 LIVEKIT_API_KEY=
 LIVEKIT_API_SECRET=
 
+# Blossom S3 (optional; when region, bucket, access key, and secret are all set, relays with blossom enabled sync with adapter s3 and key_prefix = relay schema)
+BLOSSOM_S3_ENDPOINT=
+BLOSSOM_S3_REGION=
+BLOSSOM_S3_BUCKET=
+BLOSSOM_S3_ACCESS_KEY=
+BLOSSOM_S3_SECRET_KEY=
+
 # Billing
 NWC_URL=                      # Nostr Wallet Connect URL for generating Lightning invoices
+ENCRYPTION_SECRET=            # Nostr secret key (hex or nsec) used to encrypt tenant NWC URLs at rest
 STRIPE_SECRET_KEY=            # Required Stripe API secret key (sk_...)
 STRIPE_WEBHOOK_SECRET=whsec_test_00000000000000000000000000  # Webhook signing secret (use real value in production)
+STRIPE_PRICE_BASIC=           # Stripe price ID (price_...) for the Basic plan; required for paid plans
+STRIPE_PRICE_GROWTH=          # Stripe price ID (price_...) for the Growth plan; required for paid plans

backend/README.md

@@ -43,9 +43,17 @@ Environment variables:
 | `LIVEKIT_URL`            | LiveKit URL sent to zooid when relay livekit is enabled                 | _optional_                           |
 | `LIVEKIT_API_KEY`        | LiveKit API key sent to zooid                                           | _optional_                           |
 | `LIVEKIT_API_SECRET`     | LiveKit API secret sent to zooid                                        | _optional_                           |
+| `BLOSSOM_S3_ENDPOINT`    | S3-compatible endpoint URL for Blossom; omit for AWS S3                 | _optional_                           |
+| `BLOSSOM_S3_REGION`      | S3 region; with bucket, access key, and secret enables S3 for Blossom   | _optional_                           |
+| `BLOSSOM_S3_BUCKET`      | S3 bucket name                                                          | _optional_                           |
+| `BLOSSOM_S3_ACCESS_KEY`  | S3 access key ID                                                        | _optional_                           |
+| `BLOSSOM_S3_SECRET_KEY`  | S3 secret access key                                                    | _optional_                           |
 | `NWC_URL`                | Platform NWC URL used to generate BOLT11 invoices                       | _required for invoice generation_    |
+| `ENCRYPTION_SECRET`      | Nostr secret key (hex or nsec) used to encrypt tenant NWC URLs at rest  | _required_                           |
 | `STRIPE_SECRET_KEY`      | Stripe API secret key used for billing API operations                   | _required_                           |
 | `STRIPE_WEBHOOK_SECRET`  | Stripe webhook signing secret used to verify `Stripe-Signature` headers | _required_                           |
+| `STRIPE_PRICE_BASIC`     | Stripe price ID (`price_...`) backing the Basic plan                    | _required for paid plans_            |
+| `STRIPE_PRICE_GROWTH`    | Stripe price ID (`price_...`) backing the Growth plan                   | _required for paid plans_            |
 | `ROBOT_SECRET`           | Robot Nostr secret key                                                  | _required_                           |
 | `ROBOT_NAME`             | Robot display name (kind `0`)                                           | _optional_                           |
 | `ROBOT_DESCRIPTION`      | Robot description (kind `0`)                                            | _optional_                           |

backend/migrations/0004_invoice_manual_lightning_payment.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS invoice_manual_lightning_payment (
+  invoice_id TEXT PRIMARY KEY,
+  tenant_pubkey TEXT NOT NULL,
+  bolt11 TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  FOREIGN KEY (tenant_pubkey) REFERENCES tenant(pubkey)
+);
+
+CREATE INDEX IF NOT EXISTS idx_invoice_manual_lightning_payment_tenant_pubkey
+ON invoice_manual_lightning_payment (tenant_pubkey);

backend/spec/api.md

@@ -57,7 +57,7 @@ Notes:
 
 - Serves `GET /tenants`
 - Authorizes admin only
-- Return `data` is a list of tenant structs from `query.list_tenants`
+- Return `data` is a list of `TenantResponse` structs (contains `nwc_is_set: bool` instead of `nwc_url`)
 
 ## `async fn create_tenant(...) -> Response`
 
@@ -69,20 +69,21 @@ Notes:
 - On unique-constraint race (`pubkey-exists`), re-fetch and return the existing tenant
 - If Stripe customer creation fails, return `code=stripe-customer-create-failed`
 - Always returns `200` (create-or-get is uniform)
-- Return `data` is a single `Tenant` struct
+- Return `data` is a single `TenantResponse` struct (contains `nwc_is_set: bool` instead of `nwc_url`)
 
 ## `async fn get_tenant(...) -> Response`
 
 - Serves `GET /tenants/:pubkey`
 - Authorizes admin or matching tenant
-- Return `data` is a single tenant struct from `query.get_tenant`
+- Return `data` is a single `TenantResponse` struct (contains `nwc_is_set: bool` instead of `nwc_url`)
 
 ## `async fn update_tenant(...) -> Response`
 
 - Serves `PUT /tenants/:pubkey`
 - Authorizes admin or matching tenant
+- Accepts `nwc_url` in the request body; encrypts it before storage using `cipher::encrypt`
 - Updates tenant using `command.update_tenant`
-- Return `data` is the updated tenant struct
+- Return `data` is the updated `TenantResponse` struct (contains `nwc_is_set: bool` instead of `nwc_url`)
 
 ## `async fn list_tenant_relays(...) -> Response`
 

backend/spec/billing.md

@@ -2,45 +2,47 @@
 
 Billing encapsulates logic related to synchronizing state with Stripe, processing payments via NWC, and managing subscription lifecycle.
 
+It owns the domain logic only: every raw Stripe REST call goes through the `Stripe` wrapper (see `spec/stripe.md`), and every Lightning (NWC) wallet operation and the fiat-minor-units → millisatoshi conversion go through the helpers in `spec/bitcoin.md`.
+
 Members:
 
-- `nwc_url: String` - a nostr wallet connect URL used to **create** bolt11 invoices (i.e. receive payments), from `NWC_URL`
+- `stripe: Stripe` - thin wrapper around the Stripe REST API (see `spec/stripe.md`), built from `STRIPE_SECRET_KEY` / `STRIPE_WEBHOOK_SECRET`
-- `stripe_secret_key: String` - Stripe API key used for billing API operations, from `STRIPE_SECRET_KEY`
+- `bitcoin: Bitcoin` - the Bitcoin-facing config: system NWC wallet (`NWC_URL`) plus the BTC price-feed HTTP client (see `spec/bitcoin.md`)
-- `stripe_webhook_secret: String` - secret for verifying Stripe webhook signatures, from `STRIPE_WEBHOOK_SECRET`
 - `query: Query`
 - `command: Command`
 - `robot: Robot`
 
 ## `pub fn new(query: Query, command: Command, robot: Robot) -> Self`
 
-- Reads environment and populates members
+- Builds `stripe` via `Stripe::from_env()` and `bitcoin` via `Bitcoin::from_env()`
-- Panics if `STRIPE_SECRET_KEY` is missing/empty
+- Panics if `STRIPE_SECRET_KEY` or `STRIPE_WEBHOOK_SECRET` is missing/empty (`NWC_URL` is optional)
-- Panics if `STRIPE_WEBHOOK_SECRET` is missing/empty
 
 ## `pub fn start(&self)`
 
 - Subscribes to `command.notify.subscribe()`
-- On `create_relay`, `update_relay`, `activate_relay`, `deactivate_relay`, `fail_relay_sync`, and `complete_relay_sync`, call `self.sync_relay_subscription`.
+- On `create_relay`, `update_relay`, `activate_relay`, `deactivate_relay`, `fail_relay_sync`, and `complete_relay_sync`: resolve the relay named by the activity (skip if it no longer exists) and reconcile its tenant via `sync_tenant_subscription`.
+- The startup/lagged reconcile loop calls `sync_tenant_subscription` for every tenant.
 
-## `pub fn sync_relay_subscription(&self, activity: &Activity)`
+## `fn sync_tenant_subscription(&self, tenant_pubkey: &str)`
 
-Manages the Stripe subscription and subscription items for a relay's tenant. Only paid (non-free) relays interact with Stripe. Free-only tenants have no subscription. Must be idempotent.
+Reconciles a tenant's single Stripe subscription with the set of relays that should be billed. Only paid (non-free) relays interact with Stripe. Free-only tenants have no subscription. Must be idempotent.
+
+Stripe forbids two subscription items on the same subscription from sharing a price, so billing is modeled as **one subscription item per plan (price), with `quantity` equal to the number of the tenant's `active` relays on that plan**. Every such relay's `stripe_subscription_item_id` points at the shared item for its plan; relays that aren't billed (free, inactive, delinquent) have it cleared.
 
 Stripe uses **pay-in-advance** by default: when a subscription is first created, Stripe immediately generates an open invoice for the current period. The `invoice.created` webhook fires shortly after and `handle_invoice_created` attempts payment.
 
-- Fetch the relay and tenant associated with the `activity`
+- Fetch the tenant and its relays. Build the desired state: for each `active` relay on a paid plan with a non-empty `stripe_price_id`, count relays per price.
-- **If relay plan is `free`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then run downgrade proration validation by previewing the upcoming invoice and logging proration lines/amounts. Then check cleanup (below). Return early.
+- **Resolve the live subscription**: if the tenant has a `stripe_subscription_id`, fetch it. If Stripe no longer knows about it, or its status is `canceled`/`incomplete_expired`, call `command.clear_tenant_subscription` and treat the tenant as having no subscription.
-- **If relay is `inactive` or `delinquent`**: if the relay has a `stripe_subscription_item_id`, delete it via the Stripe API and call `command.delete_relay_subscription_item`. Then check cleanup (below). Return early.
+- **No relays to bill** (desired state empty): if the tenant still has a `stripe_subscription_id`, cancel the Stripe subscription and call `command.clear_tenant_subscription`. Clear `stripe_subscription_item_id` on every relay that has one. Return.
-- **If relay is `active` and on a paid plan**:
+- **No subscription yet**: create a Stripe subscription for the customer with `collection_method: "charge_automatically"` and one item per `(price, quantity)`. Save the subscription ID via `command.set_tenant_subscription`.
-  - **Ensure subscription exists**: If the tenant has no `stripe_subscription_id`, create a Stripe subscription for the customer with `collection_method: "charge_automatically"` and the relay's price as the first item. Save the subscription ID via `command.set_tenant_subscription` and the item ID via `command.set_relay_subscription_item`. Return early.
+- **Existing subscription**: fetch its current items. For each desired `(price, quantity)`: update the matching item's quantity if it differs, otherwise create the item. Delete any item whose price no longer appears in the desired state.
-  - **Sync the subscription item**: If the tenant already has a subscription, create or update the relay's Stripe subscription item to the plan's `stripe_price_id` via the Stripe API, then call `command.set_relay_subscription_item`.
+- **Point relays at items**: for each relay, set `stripe_subscription_item_id` (via `command.set_relay_subscription_item`) to the shared item for its plan, or clear it (via `command.delete_relay_subscription_item`) if the relay is not billed.
-  - **Downgrade validation**: when changing an existing subscription item, detect if the new plan amount is lower than the current one. If yes, preview the upcoming Stripe invoice and log proration line/amount details to validate expected credit/proration behavior.
+- **Downgrade validation**: if any quantity decreased or any item was removed, preview the upcoming Stripe invoice and log proration line/amount details to validate expected credit/proration behavior.
-- **Clean up empty subscription**: After any item deletion, check if the tenant has any remaining active paid relays. If none and the tenant has a `stripe_subscription_id`, cancel the Stripe subscription immediately and call `command.clear_tenant_subscription`.
 
 ## `pub fn handle_webhook(&self, payload: &str, signature: &str) -> Result<()>`
 
-- Verify the webhook signature using `self.stripe_webhook_secret`
+- Verify and parse the event via `self.stripe.construct_event(payload, signature)` (checks the `Stripe-Signature` HMAC and timestamp tolerance — see `spec/stripe.md`)
-- Parse the event and dispatch by type:
+- Dispatch by type:
   - `invoice.created` -> `self.handle_invoice_created`
   - `invoice.paid` -> `self.handle_invoice_paid`
   - `invoice.payment_failed` -> `self.handle_invoice_payment_failed`
@@ -50,56 +52,69 @@ Stripe uses **pay-in-advance** by default: when a subscription is first created,
   - `payment_method.attached` -> `self.handle_payment_method_attached`
 - Unknown event types are ignored (return Ok)
 
+## `pub async fn stripe_create_customer(&self, tenant_pubkey: &str) -> Result<String>`
+
+- Resolves a display name via `robot.fetch_nostr_name(tenant_pubkey)`, falling back to the first 8 chars of the pubkey
+- Creates the Stripe customer via `stripe.create_customer(display_name, tenant_pubkey)` and returns its id
+
 ## `pub async fn stripe_list_invoices(&self, customer_id: &str) -> Result<Value>`
 
-- Fetches invoices from Stripe API for the given customer
+- Delegates to `stripe.list_invoices` — returns the `data` array of the customer's invoices
-- Returns the `data` array from the Stripe response
 
-## `pub async fn stripe_get_invoice(&self, invoice_id: &str) -> Result<Value>`
+## `pub async fn stripe_create_portal_session(&self, customer_id: &str, return_url: Option<&str>) -> Result<String>`
 
-- Fetches a single invoice from Stripe API by ID
+- Delegates to `stripe.create_portal_session` — returns the Customer Portal session URL
-- Returns the full Stripe invoice object
 
-## `pub async fn create_bolt11(&self, amount_due_cents: i64) -> Result<String>`
+## `pub async fn get_invoice_with_tenant(&self, invoice_id: &str) -> Result<(Value, Tenant), InvoiceLookupError>`
 
-- Creates a bolt11 Lightning invoice for the given amount using the system NWC wallet (`self.nwc_url`)
+- Fetches the invoice via `stripe.get_invoice` (a Stripe 4xx surfaces as `InvoiceLookupError::StripeClient`)
+- Looks up the tenant by the invoice's `customer` field; errors if the invoice has no customer or no tenant matches
+
+## `pub async fn reconcile_manual_lightning_invoice(&self, invoice_id: &str, invoice: &Value) -> Result<Value, InvoiceLookupError>`
+
+If `invoice.status == "open"` and a manual-Lightning bolt11 was previously issued for it (`query.get_invoice_manual_lightning_bolt11`), check whether that bolt11 has settled (`bitcoin.system_wallet().invoice_settled(...)`). If it has, mark the Stripe invoice paid out of band (`stripe.pay_invoice_out_of_band`) and return the refreshed invoice. On any lookup/settlement failure, log and return the invoice unchanged.
+
+## `pub async fn get_or_create_manual_lightning_bolt11(&self, invoice_id: &str, tenant_pubkey: &str, amount_due_minor: i64, currency: &str) -> Result<String>`
+
+- Returns the existing bolt11 if one is already recorded for the invoice
+- Otherwise creates one via `create_bolt11`, records it with `command.insert_manual_lightning_invoice_payment`, and returns it (re-reading the stored row if the insert lost a race)
+
+## `pub async fn create_bolt11(&self, amount_due_minor: i64, currency: &str) -> Result<String>`
+
+- Converts the fiat amount to msats via `bitcoin.fiat_minor_to_msats` (fetches the live BTC spot price — see `spec/bitcoin.md`)
+- Issues a bolt11 invoice for that amount on the system NWC wallet (`bitcoin.system_wallet().make_invoice(...)`)
 - Returns the bolt11 invoice string
 
-## `pub async fn stripe_create_portal_session(&self, customer_id: &str) -> Result<String>`
-
-- Creates a Stripe Customer Portal session for the given customer
-- Returns the portal session URL
-
 ## `pub async fn pay_outstanding_nwc_invoices(&self, tenant: &Tenant) -> Result<()>`
 
 Called when a tenant first sets their NWC URL (via `PUT /tenants/:pubkey`). Attempts to pay any currently open invoices for the tenant using their NWC wallet, so that invoices created before NWC was configured are not left unpaid.
 
 - If `tenant.nwc_url` is empty, return early.
-- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe_list_invoices`.
+- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe.list_invoices`.
 - For each invoice with `status == "open"` and `amount_due > 0`:
   - Attempt NWC payment via `nwc_pay_invoice`.
-  - On success: call `stripe_pay_invoice_out_of_band` and `command.clear_tenant_nwc_error`.
+  - On success: mark the Stripe invoice paid out of band (`stripe.pay_invoice_out_of_band`) and call `command.clear_tenant_nwc_error`.
   - On failure: call `command.set_tenant_nwc_error` and log the error; continue to the next invoice.
 
 ## `pub async fn pay_outstanding_card_invoices(&self, tenant: &Tenant) -> Result<()>`
 
 Attempts Stripe-side collection for open invoices when the tenant has a card on file.
 
-- If tenant has no card payment method, return early.
+- If tenant has no card payment method (`stripe.has_payment_method`), return early.
-- List all Stripe invoices for `tenant.stripe_customer_id`.
+- List all Stripe invoices for `tenant.stripe_customer_id` via `stripe.list_invoices`.
 - For each invoice with `status == "open"` and `amount_due > 0`:
-  - Call Stripe `POST /v1/invoices/:id/pay` to retry collection using the card on file.
+  - Call `stripe.pay_invoice` to retry collection using the card on file.
   - Log and continue on failures.
 
 ## `fn handle_invoice_created(&self, invoice: &Invoice)`
 
 Attempts to pay a new subscription invoice. Because Stripe defaults to pay-in-advance, this webhook fires immediately when a subscription is created (i.e. when a paid relay is added or a plan is upgraded). Payment priority:
 
-1. **NWC auto-pay**: If the tenant has a `nwc_url`:
+1. **NWC auto-pay**: If the tenant has a `nwc_url`, run `nwc_pay_invoice` (decrypting the tenant's stored `nwc_url` first):
-   - Create a bolt11 Lightning invoice for the invoice amount using `self.nwc_url` (the receiving/system wallet)
+   - The system wallet (`bitcoin.system_wallet()`) issues a bolt11 invoice for the fiat amount; the tenant's wallet (`Wallet::parse` of the decrypted URL) pays it. A `pending` row in `invoice_nwc_payment` guards against double-charging across retries.
-   - Pay the bolt11 invoice using the tenant's `nwc_url` (the spending/tenant wallet)
+   - If payment succeeds: mark the Stripe invoice paid out of band (`stripe.pay_invoice_out_of_band`) and clear `nwc_error` via `command.clear_tenant_nwc_error`. Done.
-   - If payment succeeds: call Stripe `POST /v1/invoices/:id/pay` with `paid_out_of_band: true`. Clear `nwc_error` via `command.clear_tenant_nwc_error`.
+   - If it fails before any charge could have gone out: set `nwc_error` on the tenant via `command.set_tenant_nwc_error`, and fall through to the next option (carrying a short summary of the error into the eventual DM).
-   - If payment fails: set `nwc_error` on tenant via `command.set_tenant_nwc_error`. Fall through to next option.
+   - If it fails after a charge may have gone out (needs reconciliation): set `nwc_error` and return the error without falling through — a human must reconcile before any retry.
 2. **Card on file**: If the tenant has a payment method on the Stripe customer, do nothing here — Stripe will charge automatically for this invoice attempt.
 3. **Manual payment**: If neither NWC nor card is available, send a DM via `robot.send_dm` notifying the tenant that payment is due with a link to the application for manual Lightning payment.
 

backend/spec/bitcoin.md

@@ -0,0 +1,62 @@
+# `bitcoin` — Bitcoin / Lightning helpers
+
+Small wrappers around the Bitcoin-facing services the app talks to: Nostr Wallet Connect (NWC) wallets for Lightning invoices/payments, and a fiat↔BTC spot price feed, plus the fiat-minor-units → millisatoshi conversion that ties them together. The billing-specific orchestration (which wallet pays which invoice, double-charge guards, DMs, etc.) lives in `spec/billing.md`.
+
+## `pub struct Bitcoin`
+
+Owns the app's Bitcoin-facing configuration: the system NWC wallet URL (the wallet used to *receive* payments — issue and look up bolt11 invoices) and the HTTP client used for the fiat↔BTC spot price feed.
+
+Members:
+
+- `system_nwc_url: String` - from `NWC_URL`
+- `http: reqwest::Client`
+
+### `pub fn from_env() -> Self`
+
+Reads `NWC_URL` (the system / receiving wallet) and constructs a fresh `reqwest::Client`. Unlike the Stripe keys, `NWC_URL` is **optional**: if it's unset, Lightning operations fail at use time with a clear error rather than panicking at startup. This is what `Billing::new` calls.
+
+### `pub fn system_wallet(&self) -> Result<Wallet>`
+
+Returns the system `Wallet` (parsed from `system_nwc_url` with label `"system"`). Errors if `NWC_URL` is unset or malformed.
+
+### `pub async fn fiat_minor_to_msats(&self, amount_due_minor: i64, currency: &str) -> Result<u64>`
+
+Fetches the live BTC spot price (via `btc_spot_price_from_base` against Coinbase) for `currency` and converts `amount_due_minor` to millisatoshis via `fiat_minor_to_msats_from_quote`. `currency` is upper-cased before use.
+
+## `pub struct Wallet`
+
+A handle to a single NWC wallet. Each operation opens a fresh NWC connection and tears it down (`shutdown`) afterwards.
+
+Member:
+
+- `uri: NostrWalletConnectURI` - the parsed `nostr+walletconnect://…` URI
+
+### `pub fn parse(uri: &str, label: &str) -> Result<Self>`
+
+Parses an `nostr+walletconnect://` URI. `label` (e.g. `"system"` / `"tenant"`) only flavours the error message — `invalid {label} NWC URL` — so callers can tell which wallet was misconfigured.
+
+### `pub async fn make_invoice(&self, amount_msats: u64, description: &str) -> Result<String>`
+
+Issues a bolt11 invoice for `amount_msats` with the given description. Returns the bolt11 string.
+
+### `pub async fn pay_invoice(&self, bolt11: String) -> Result<()>`
+
+Pays a bolt11 invoice.
+
+### `pub async fn invoice_settled(&self, bolt11: &str) -> Result<bool>`
+
+Looks up a bolt11 invoice (previously issued by this wallet) and returns whether it has settled — true if the transaction state is `Settled` or `settled_at` is present.
+
+## `pub async fn btc_spot_price_from_base(http: &reqwest::Client, api_base: &str, currency: &str) -> Result<f64>`
+
+Fetches the BTC spot price denominated in `currency` (an ISO-4217 code) from a Coinbase-shaped API at `api_base` (`{api_base}/BTC-{currency}/spot`); production callers reach it via `Bitcoin::fiat_minor_to_msats` with the real Coinbase base, while tests can point it at a stub. Errors if the quote is missing, unparseable, or non-positive.
+
+## `pub fn fiat_minor_to_msats_from_quote(amount_due_minor: i64, currency: &str, btc_price_in_fiat: f64) -> Result<u64>`
+
+Converts a fiat amount expressed in minor units (cents, etc.) to millisatoshis, given a BTC price quote in that currency.
+
+- Errors if `amount_due_minor <= 0` or `btc_price_in_fiat <= 0`
+- Converts minor units to a major-unit amount using the currency's decimal exponent (most currencies 2; `JPY`/`KRW`/… 0; `BHD`/`KWD`/… 3 — following Stripe's currency conventions; an unrecognized or malformed code is an error)
+- `msats = (amount_fiat / btc_price_in_fiat) * 100_000_000_000`
+- Rounds **up** so we never under-charge, but snaps to the nearest integer when within `1e-6` of one to avoid floating-point artifacts at integer boundaries
+- Errors if the result is non-finite, non-positive, or exceeds `u64::MAX`

backend/spec/infra.md

@@ -5,6 +5,7 @@ Infra is a service which listens for activity and synchronizes relay updates to
 Members:
 
 - `api_url: String` - the URL of the zooid instance to be managed, from `ZOOID_API_URL`
+- `blossom_s3: Option<BlossomS3Sync>` - shared Blossom S3 settings from `BLOSSOM_S3_*` when region, bucket, access key, and secret are all non-empty after trim
 - `query: Query`
 - `command: Command`
 
@@ -36,3 +37,4 @@ Members:
 - Otherwise, sends `PATCH /relay/:id` to update it.
 - Includes `secret` only for relay creation (`POST`) so updates do not rotate relay identity.
 - Passes relay configuration in the body including host, schema, inactive flag, info, policy, groups, management, blossom, livekit, push, and roles.
+- When `blossom_s3` is configured and the relay has blossom enabled, the blossom section includes `adapter: "s3"`, S3 fields from the environment, and `s3.key_prefix` set to the relay's `schema`. Otherwise blossom omits S3 (zooid defaults to local storage) or sends `{ "enabled": false }` when blossom is disabled.

backend/spec/models.md

@@ -52,7 +52,7 @@ There are three plans available:
 Tenants are customers of the service, identified by a nostr `pubkey`. Public metadata like name etc are pulled from the nostr network. They also have associated billing information.
 
 - `pubkey` is the nostr public key identifying the tenant
-- `nwc_url` (private) a nostr wallet connect URL used for **paying** invoices generated by the system on the tenant's behalf
+- `nwc_url` (private) a nostr wallet connect URL used for **paying** invoices generated by the system on the tenant's behalf; stored encrypted at rest using NIP-44 via `ENCRYPTION_SECRET`; never serialized to API responses — tenant API endpoints expose `nwc_is_set: bool` instead
 - `nwc_error` (private) a string indicating the most recent NWC payment error, if any. Cleared on successful NWC payment.
 - `created_at` unix timestamp identifying tenant creation time
 - `stripe_customer_id` a string identifying the associated stripe customer
@@ -63,9 +63,9 @@ Tenants are customers of the service, identified by a nostr `pubkey`. Public met
 
 A relay is a nostr relay owned by a `tenant` and hosted by the attached zooid instance. Relay subdomains MUST be unique.
 
-- `id` - a random ID identifying the relay
+- `id` - calculated based on `subdomain` + 8 random hex chars
 - `tenant` - the tenant's pubkey
-- `schema` - the relay's db schema (read_only, calculated based on `subdomain` + `id`)
+- `schema` - the relay's db schema (read only, same as `id`)
 - `subdomain` - the relay's subdomain
 - `plan` - the relay's plan
 - `stripe_subscription_item_id` (nullable) - the Stripe subscription item id. Only set for relays on paid plans.

backend/spec/query.md

@@ -39,10 +39,6 @@ Members:
 
 - Returns the tenant matching the given `stripe_customer_id`
 
-## `pub fn has_active_paid_relays(&self, tenant_id: &str) -> Result<bool>`
-
-- Returns true if the tenant has any relays where `status = 'active'` and `plan != 'free'`
-
 ## `pub fn list_activity_for_relay(&self, relay_id: &str) -> Result<Vec<Activity>>`
 
 - Returns all activity where `resource_type = 'relay'` and `resource_id = relay_id`

backend/spec/stripe.md

@@ -0,0 +1,113 @@
+# `pub struct Stripe`
+
+A thin async wrapper around the subset of the Stripe REST API this service uses. It knows nothing about relays, tenants, or the database — it just speaks HTTP to Stripe and returns `serde_json::Value` (or small typed results). The domain logic that drives it lives in `spec/billing.md`.
+
+Members:
+
+- `secret_key: String` - Stripe API key, used as the bearer token and as the HMAC key for idempotency keys
+- `webhook_secret: String` - secret for verifying Stripe webhook signatures
+- `http: reqwest::Client`
+
+All requests authenticate with `secret_key` via `Authorization: Bearer`. Write requests that must not be retried twice (customer/subscription/item creation, invoice payment) send a deterministic `Idempotency-Key` derived by HMAC-ing the operation name and its arguments with `secret_key`. Reconcile-to-desired-state writes (e.g. setting an item quantity) intentionally omit the idempotency key, since re-applying the same target is a no-op.
+
+On any 4xx/5xx response, the wrapper reads the body and folds Stripe's JSON error payload (`error.message` / `error.type` / `error.code` / `error.param`) into the returned error so callers get an actionable message instead of a bare status line.
+
+## `pub fn from_env() -> Self`
+
+Reads `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` (both required) and constructs the client. Panics if either is missing or blank. This is what `Billing::new` calls.
+
+## `pub fn new(secret_key: String, webhook_secret: String) -> Self`
+
+Constructs the client with a fresh `reqwest::Client` from explicit keys (does not touch the environment).
+
+## `pub async fn create_customer(&self, name: &str, tenant_pubkey: &str) -> Result<String>`
+
+- `POST /v1/customers` with `name` and `metadata[tenant_pubkey]`
+- Idempotent on `tenant_pubkey`
+- Returns the new customer id; errors if it isn't a `cus_…` id
+
+## `pub async fn get_subscription(&self, subscription_id: &str) -> Result<Option<Value>>`
+
+- `GET /v1/subscriptions/:id`
+- Returns `None` if Stripe responds `404` (so callers can recover from a stale subscription id), otherwise the subscription object
+
+## `pub async fn create_subscription(&self, customer_id: &str, items: &BTreeMap<String, i64>) -> Result<(String, BTreeMap<String, String>)>`
+
+- `POST /v1/subscriptions` with `collection_method: charge_automatically` and one `items[n][price]` / `items[n][quantity]` pair per entry
+- Idempotent on the customer and the `(price, quantity)` set
+- Returns the subscription id and a map from price id to the created subscription item id
+
+## `pub async fn create_subscription_item(&self, subscription_id: &str, price_id: &str, quantity: i64) -> Result<String>`
+
+- `POST /v1/subscription_items`
+- Idempotent on `(subscription_id, price_id)`
+- Returns the new subscription item id
+
+## `pub async fn set_subscription_item_quantity(&self, item_id: &str, quantity: i64) -> Result<()>`
+
+- `POST /v1/subscription_items/:id` with `quantity`
+- No idempotency key (reconcile-to-target write)
+
+## `pub async fn delete_subscription_item(&self, item_id: &str) -> Result<()>`
+
+- `DELETE /v1/subscription_items/:id`
+
+## `pub async fn cancel_subscription(&self, subscription_id: &str) -> Result<()>`
+
+- `DELETE /v1/subscriptions/:id`
+
+## `pub async fn list_invoices(&self, customer_id: &str) -> Result<Value>`
+
+- `GET /v1/invoices?customer=…`
+- Returns the `data` array
+
+## `pub async fn get_invoice(&self, invoice_id: &str) -> Result<Value, InvoiceLookupError>`
+
+- `GET /v1/invoices/:id`
+- On a 4xx response, returns `InvoiceLookupError::StripeClient { status }` (callers usually surface this as a client error, e.g. `404` "no such invoice"); other failures are `InvoiceLookupError::Internal`
+- Returns the full invoice object
+
+## `pub async fn pay_invoice(&self, invoice_id: &str) -> Result<()>`
+
+- `POST /v1/invoices/:id/pay` (retries collection using the customer's default payment method)
+- Idempotent on `invoice_id`
+
+## `pub async fn pay_invoice_out_of_band(&self, invoice_id: &str) -> Result<()>`
+
+- `POST /v1/invoices/:id/pay` with `paid_out_of_band: true` — used when payment was collected over Lightning rather than through Stripe
+- Idempotent on `invoice_id`
+
+## `pub async fn preview_upcoming_invoice(&self, customer_id: &str, subscription_id: Option<&str>) -> Result<Value>`
+
+- `GET /v1/invoices/upcoming?customer=…[&subscription=…]`
+- Used to validate proration when a subscription is downgraded
+
+## `pub async fn has_payment_method(&self, customer_id: &str) -> Result<bool>`
+
+- `GET /v1/payment_methods?customer=…&type=card`
+- Returns whether the customer has at least one card on file
+
+## `pub async fn create_portal_session(&self, customer_id: &str, return_url: Option<&str>) -> Result<String>`
+
+- `POST /v1/billing_portal/sessions` with `customer` and optional `return_url`
+- Returns the portal session URL
+
+## `pub fn construct_event(&self, payload: &str, sig_header: &str) -> Result<Event>`
+
+Verifies the `Stripe-Signature` header against `webhook_secret` and parses the body.
+
+- Parse `t=` (timestamp) and `v1=` (signature) from the header
+- Compute `HMAC-SHA256(webhook_secret, "{t}.{payload}")`, hex-encode it, and compare to `v1=`; error on mismatch
+- Error if the timestamp is more than 300 seconds from now
+- Returns the deserialized `Event` (`{ event_type, data: { object } }`)
+
+# `pub enum InvoiceLookupError`
+
+- `StripeClient { status: reqwest::StatusCode }` - Stripe returned a 4xx for an invoice lookup
+- `Internal(anyhow::Error)` - any other failure
+
+Implements `Display`/`Error` and `From<anyhow::Error>` / `From<reqwest::Error>` (both mapping to `Internal`).
+
+# `pub struct Event` / `pub struct EventData`
+
+The verified, parsed webhook event: `Event { event_type: String, data: EventData }`, `EventData { object: serde_json::Value }`.

backend/src/api.rs

@@ -3,7 +3,7 @@ use std::sync::Arc;
 use anyhow::{Result, anyhow};
 use axum::{
     Json, Router,
-    extract::{Path, State},
+    extract::{Path, Query as QueryParams, State},
     http::{HeaderMap, StatusCode},
     response::{IntoResponse, Response},
     routing::{get, post},
@@ -12,13 +12,14 @@ use base64::Engine;
 use nostr_sdk::{Event, JsonUtil, Kind};
 use serde::{Deserialize, Serialize};
 
-use crate::billing::{Billing, InvoiceLookupError};
+use crate::billing::Billing;
 use crate::command::Command;
 use crate::infra::Infra;
 use crate::models::{
     RELAY_STATUS_ACTIVE, RELAY_STATUS_DELINQUENT, RELAY_STATUS_INACTIVE, Relay, Tenant,
 };
 use crate::query::Query;
+use crate::stripe::InvoiceLookupError;
 use axum::body::Bytes;
 
 #[derive(Clone)]
@@ -275,9 +276,6 @@ impl Api {
             return Err(RelayValidationError::PremiumFeature);
         }
 
-        if relay.schema.is_empty() {
-            relay.schema = format!("{}_{}", relay.subdomain.replace('-', "_"), relay.id);
-        }
         if relay.status.is_empty() {
             relay.status = RELAY_STATUS_ACTIVE.to_string();
         }
@@ -445,6 +443,31 @@ struct IdentityResponse {
     is_admin: bool,
 }
 
+#[derive(Serialize)]
+struct TenantResponse {
+    pubkey: String,
+    nwc_is_set: bool,
+    nwc_error: Option<String>,
+    created_at: i64,
+    stripe_customer_id: String,
+    stripe_subscription_id: Option<String>,
+    past_due_at: Option<i64>,
+}
+
+impl From<Tenant> for TenantResponse {
+    fn from(t: Tenant) -> Self {
+        TenantResponse {
+            nwc_is_set: !t.nwc_url.is_empty(),
+            pubkey: t.pubkey,
+            nwc_error: t.nwc_error,
+            created_at: t.created_at,
+            stripe_customer_id: t.stripe_customer_id,
+            stripe_subscription_id: t.stripe_subscription_id,
+            past_due_at: t.past_due_at,
+        }
+    }
+}
+
 #[derive(Deserialize)]
 struct CreateRelayRequest {
     tenant: String,
@@ -486,7 +509,13 @@ async fn list_tenants(
     state.api.require_admin(&pubkey)?;
 
     match state.api.query.list_tenants().await {
-        Ok(tenants) => Ok(ok(StatusCode::OK, tenants)),
+        Ok(tenants) => Ok(ok(
+            StatusCode::OK,
+            tenants
+                .into_iter()
+                .map(TenantResponse::from)
+                .collect::<Vec<_>>(),
+        )),
         Err(e) => Ok(err(
             StatusCode::INTERNAL_SERVER_ERROR,
             "internal",
@@ -515,7 +544,7 @@ async fn create_tenant(
     let pubkey = state.api.extract_auth_pubkey(&headers)?;
 
     match state.api.query.get_tenant(&pubkey).await {
-        Ok(Some(t)) => Ok(ok(StatusCode::OK, t)),
+        Ok(Some(t)) => Ok(ok(StatusCode::OK, TenantResponse::from(t))),
         Ok(None) => {
             let stripe_customer_id = match state.api.billing.stripe_create_customer(&pubkey).await {
                 Ok(id) => id,
@@ -539,10 +568,10 @@ async fn create_tenant(
             };
 
             match state.api.command.create_tenant(&tenant).await {
-                Ok(()) => Ok(ok(StatusCode::OK, tenant)),
+                Ok(()) => Ok(ok(StatusCode::OK, TenantResponse::from(tenant))),
                 Err(e) if matches!(map_unique_error(&e), Some("pubkey-exists")) => {
                     match state.api.query.get_tenant(&pubkey).await {
-                        Ok(Some(t)) => Ok(ok(StatusCode::OK, t)),
+                        Ok(Some(t)) => Ok(ok(StatusCode::OK, TenantResponse::from(t))),
                         Ok(None) => Ok(err(
                             StatusCode::INTERNAL_SERVER_ERROR,
                             "internal",
@@ -585,7 +614,7 @@ async fn get_tenant(
     let auth = state.api.extract_auth_pubkey(&headers)?;
     state.api.require_admin_or_tenant(&auth, &pubkey)?;
     let tenant = state.api.get_tenant_or_404(&pubkey).await?;
-    Ok(ok(StatusCode::OK, tenant))
+    Ok(ok(StatusCode::OK, TenantResponse::from(tenant)))
 }
 
 async fn list_relays(
@@ -723,10 +752,16 @@ async fn create_relay(
     let auth = state.api.extract_auth_pubkey(&headers)?;
     state.api.require_admin_or_tenant(&auth, &payload.tenant)?;
 
+    let relay_id = format!(
+        "{}_{}",
+        payload.subdomain.replace('-', "_"),
+        &uuid::Uuid::new_v4().simple().to_string()[..8]
+    );
+
     let mut relay = Relay {
-        id: uuid::Uuid::new_v4().to_string(),
+        id: relay_id.clone(),
         tenant: payload.tenant,
-        schema: String::new(),
+        schema: relay_id.clone(),
         subdomain: payload.subdomain,
         plan: payload.plan,
         stripe_subscription_item_id: None,
@@ -1009,6 +1044,13 @@ async fn get_invoice(
         .map_err(map_invoice_lookup_error)?;
     state.api.require_admin_or_tenant(&auth, &tenant.pubkey)?;
 
+    let invoice = state
+        .api
+        .billing
+        .reconcile_manual_lightning_invoice(&id, &invoice)
+        .await
+        .map_err(map_invoice_lookup_error)?;
+
     Ok(ok(StatusCode::OK, invoice))
 }
 
@@ -1026,6 +1068,13 @@ async fn get_invoice_bolt11(
         .map_err(map_invoice_lookup_error)?;
     state.api.require_admin_or_tenant(&auth, &tenant.pubkey)?;
 
+    let invoice = state
+        .api
+        .billing
+        .reconcile_manual_lightning_invoice(&id, &invoice)
+        .await
+        .map_err(map_invoice_lookup_error)?;
+
     let status = invoice["status"].as_str().unwrap_or_default();
     if status != "open" {
         return Ok(err(
@@ -1038,7 +1087,12 @@ async fn get_invoice_bolt11(
     let amount_due = invoice["amount_due"].as_i64().unwrap_or(0);
     let currency = invoice["currency"].as_str().unwrap_or("usd");
 
-    match state.api.billing.create_bolt11(amount_due, currency).await {
+    match state
+        .api
+        .billing
+        .get_or_create_manual_lightning_bolt11(&id, &tenant.pubkey, amount_due, currency)
+        .await
+    {
         Ok(bolt11) => Ok(ok(StatusCode::OK, serde_json::json!({ "bolt11": bolt11 }))),
         Err(e) => Ok(err(
             StatusCode::INTERNAL_SERVER_ERROR,
@@ -1048,10 +1102,16 @@ async fn get_invoice_bolt11(
     }
 }
 
+#[derive(serde::Deserialize)]
+struct StripeSessionParams {
+    return_url: Option<String>,
+}
+
 async fn create_stripe_session(
     State(state): State<AppState>,
     headers: HeaderMap,
     Path(pubkey): Path<String>,
+    QueryParams(params): QueryParams<StripeSessionParams>,
 ) -> std::result::Result<Response, ApiError> {
     let auth = state.api.extract_auth_pubkey(&headers)?;
     state.api.require_admin_or_tenant(&auth, &pubkey)?;
@@ -1060,7 +1120,7 @@ async fn create_stripe_session(
     match state
         .api
         .billing
-        .stripe_create_portal_session(&tenant.stripe_customer_id)
+        .stripe_create_portal_session(&tenant.stripe_customer_id, params.return_url.as_deref())
         .await
     {
         Ok(url) => Ok(ok(StatusCode::OK, serde_json::json!({ "url": url }))),
@@ -1084,7 +1144,12 @@ async fn update_tenant(
 
     let nwc_previously_empty = tenant.nwc_url.is_empty();
     if let Some(nwc_url) = payload.nwc_url {
-        tenant.nwc_url = nwc_url;
+        if nwc_url.is_empty() {
+            tenant.nwc_url = String::new();
+        } else {
+            tenant.nwc_url =
+                crate::cipher::encrypt(&nwc_url).map_err(|e| ApiError::Internal(e.to_string()))?;
+        }
     }
 
     match state.api.command.update_tenant(&tenant).await {
@@ -1103,7 +1168,7 @@ async fn update_tenant(
                     }
                 });
             }
-            Ok(ok(StatusCode::OK, tenant))
+            Ok(ok(StatusCode::OK, TenantResponse::from(tenant)))
         }
         Err(e) => Ok(err(
             StatusCode::INTERNAL_SERVER_ERROR,

backend/src/bitcoin.rs

@@ -0,0 +1,220 @@
+//! Small wrappers around the Bitcoin-facing services this app talks to: Nostr
+//! Wallet Connect wallets (for Lightning invoices/payments) and a fiat↔BTC spot
+//! price feed, plus the fiat-minor-units → millisatoshi conversion that ties them
+//! together. The billing-specific orchestration lives in [`crate::billing`].
+
+use anyhow::{Result, anyhow};
+use nwc::prelude::{
+    LookupInvoiceRequest, LookupInvoiceResponse, MakeInvoiceRequest, NWC, NostrWalletConnectURI,
+    PayInvoiceRequest, TransactionState,
+};
+
+const COINBASE_SPOT_API: &str = "https://api.coinbase.com/v2/prices";
+/// Millisatoshis per bitcoin.
+const MSATS_PER_BTC: f64 = 100_000_000_000.0;
+
+/// Owns the app's Bitcoin-facing configuration: the system NWC wallet URL (the
+/// wallet used to *receive* payments — issue and look up bolt11 invoices) and the
+/// HTTP client used for the fiat↔BTC spot price feed.
+#[derive(Clone)]
+pub struct Bitcoin {
+    system_nwc_url: String,
+    http: reqwest::Client,
+}
+
+impl Bitcoin {
+    /// Reads `NWC_URL` (the system / receiving wallet). Unlike the Stripe keys this
+    /// is optional: if it's unset, Lightning operations fail at use time with a
+    /// clear error rather than at startup.
+    pub fn from_env() -> Self {
+        Self {
+            system_nwc_url: std::env::var("NWC_URL").unwrap_or_default(),
+            http: reqwest::Client::new(),
+        }
+    }
+
+    /// The system wallet — issues and looks up the bolt11 invoices we want paid to
+    /// us. Errors if `NWC_URL` is unset or malformed.
+    pub fn system_wallet(&self) -> Result<Wallet> {
+        Wallet::parse(&self.system_nwc_url, "system")
+    }
+
+    /// Fetches the live BTC spot price and converts a fiat amount in minor units
+    /// (cents, etc.) to millisatoshis.
+    pub async fn fiat_minor_to_msats(&self, amount_due_minor: i64, currency: &str) -> Result<u64> {
+        let currency = currency.to_uppercase();
+        let btc_price = btc_spot_price_from_base(&self.http, COINBASE_SPOT_API, &currency).await?;
+        fiat_minor_to_msats_from_quote(amount_due_minor, &currency, btc_price)
+    }
+}
+
+#[derive(serde::Deserialize)]
+struct CoinbaseSpotPriceResponse {
+    data: CoinbaseSpotPriceData,
+}
+
+#[derive(serde::Deserialize)]
+struct CoinbaseSpotPriceData {
+    amount: String,
+}
+
+/// A handle to a single Nostr Wallet Connect wallet. Each operation opens a fresh
+/// connection and tears it down afterwards.
+pub struct Wallet {
+    uri: NostrWalletConnectURI,
+}
+
+impl Wallet {
+    /// Parses an `nostr+walletconnect://` URI. `label` only flavours the error
+    /// message so callers can tell which wallet was misconfigured.
+    pub fn parse(uri: &str, label: &str) -> Result<Self> {
+        let uri = uri
+            .parse::<NostrWalletConnectURI>()
+            .map_err(|_| anyhow!("invalid {label} NWC URL"))?;
+        Ok(Self { uri })
+    }
+
+    /// Issues a bolt11 invoice for `amount_msats`.
+    pub async fn make_invoice(&self, amount_msats: u64, description: &str) -> Result<String> {
+        let nwc = NWC::new(self.uri.clone());
+        let result = nwc
+            .make_invoice(MakeInvoiceRequest {
+                amount: amount_msats,
+                description: Some(description.to_string()),
+                description_hash: None,
+                expiry: None,
+            })
+            .await;
+        nwc.shutdown().await;
+        Ok(result
+            .map_err(|e| anyhow!("failed to create invoice: {e}"))?
+            .invoice)
+    }
+
+    /// Pays a bolt11 invoice.
+    pub async fn pay_invoice(&self, bolt11: String) -> Result<()> {
+        let nwc = NWC::new(self.uri.clone());
+        let result = nwc.pay_invoice(PayInvoiceRequest::new(bolt11)).await;
+        nwc.shutdown().await;
+        result.map(|_| ()).map_err(|e| anyhow!("{e}"))
+    }
+
+    /// Returns whether a bolt11 invoice (previously issued by this wallet) has been
+    /// settled.
+    pub async fn invoice_settled(&self, bolt11: &str) -> Result<bool> {
+        let nwc = NWC::new(self.uri.clone());
+        let result = nwc
+            .lookup_invoice(LookupInvoiceRequest {
+                payment_hash: None,
+                invoice: Some(bolt11.to_string()),
+            })
+            .await;
+        nwc.shutdown().await;
+        let response = result.map_err(|e| anyhow!("failed to lookup invoice: {e}"))?;
+        Ok(lookup_invoice_response_is_settled(&response))
+    }
+}
+
+fn lookup_invoice_response_is_settled(response: &LookupInvoiceResponse) -> bool {
+    response.state == Some(TransactionState::Settled) || response.settled_at.is_some()
+}
+
+/// Fetches the BTC spot price denominated in `currency` (an ISO-4217 code) from a
+/// Coinbase-shaped API at `api_base`. Exposed so tests can stub the price feed;
+/// production callers go through [`Bitcoin::fiat_minor_to_msats`].
+pub async fn btc_spot_price_from_base(
+    http: &reqwest::Client,
+    api_base: &str,
+    currency: &str,
+) -> Result<f64> {
+    let pair = format!("BTC-{currency}");
+    let url = format!("{}/{pair}/spot", api_base.trim_end_matches('/'));
+    let resp = http.get(url).send().await?;
+    let body: CoinbaseSpotPriceResponse = resp.error_for_status()?.json().await?;
+
+    let amount = body
+        .data
+        .amount
+        .parse::<f64>()
+        .map_err(|e| anyhow!("invalid BTC spot quote for {currency}: {e}"))?;
+    if amount <= 0.0 {
+        return Err(anyhow!(
+            "invalid non-positive BTC spot quote for {currency}"
+        ));
+    }
+    Ok(amount)
+}
+
+/// Converts a fiat amount expressed in minor units (cents, etc.) to millisatoshis,
+/// given a BTC price quote in that currency. Rounds up so we never under-charge,
+/// but snaps to the nearest integer when within a hair of one to avoid floating
+/// point artifacts at integer boundaries.
+pub fn fiat_minor_to_msats_from_quote(
+    amount_due_minor: i64,
+    currency: &str,
+    btc_price_in_fiat: f64,
+) -> Result<u64> {
+    if amount_due_minor <= 0 {
+        return Err(anyhow!("amount_due must be positive"));
+    }
+    if btc_price_in_fiat <= 0.0 {
+        return Err(anyhow!("btc_price_in_fiat must be positive"));
+    }
+
+    let divisor = 10_f64.powi(currency_minor_exponent(currency)? as i32);
+    let amount_fiat = (amount_due_minor as f64) / divisor;
+    let amount_btc = amount_fiat / btc_price_in_fiat;
+    let raw_msats = amount_btc * MSATS_PER_BTC;
+    let amount_msats = if (raw_msats - raw_msats.round()).abs() < 1e-6 {
+        raw_msats.round()
+    } else {
+        raw_msats.ceil()
+    };
+
+    if !amount_msats.is_finite() || amount_msats <= 0.0 || amount_msats > u64::MAX as f64 {
+        return Err(anyhow!("calculated msat amount is out of bounds"));
+    }
+    Ok(amount_msats as u64)
+}
+
+/// Number of decimal places in `currency`'s minor unit, following Stripe's
+/// currency conventions (most are 2, JPY/KRW/… are 0, BHD/KWD/… are 3).
+fn currency_minor_exponent(currency: &str) -> Result<u8> {
+    let normalized = currency.to_uppercase();
+    let exponent = match normalized.as_str() {
+        // Zero-decimal currencies in Stripe.
+        "BIF" | "CLP" | "DJF" | "GNF" | "JPY" | "KMF" | "KRW" | "MGA" | "PYG" | "RWF" | "UGX"
+        | "VND" | "VUV" | "XAF" | "XOF" | "XPF" => 0,
+        // Three-decimal currencies in Stripe.
+        "BHD" | "JOD" | "KWD" | "OMR" | "TND" => 3,
+        _ if normalized.chars().all(|c| c.is_ascii_alphabetic()) && normalized.len() == 3 => 2,
+        _ => return Err(anyhow!("invalid currency code: {currency}")),
+    };
+    Ok(exponent)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::fiat_minor_to_msats_from_quote;
+
+    #[test]
+    fn converts_usd_minor_units_with_quote() {
+        let msats = fiat_minor_to_msats_from_quote(100, "usd", 100_000.0)
+            .expect("conversion should succeed");
+        assert_eq!(msats, 1_000_000);
+    }
+
+    #[test]
+    fn converts_zero_decimal_currency_with_quote() {
+        let msats = fiat_minor_to_msats_from_quote(100, "jpy", 10_000_000.0)
+            .expect("conversion should succeed");
+        assert_eq!(msats, 1_000_000);
+    }
+
+    #[test]
+    fn rejects_malformed_currency_code() {
+        // Not three ASCII letters: rejected outright.
+        assert!(fiat_minor_to_msats_from_quote(100, "usdd", 100_000.0).is_err());
+        assert!(fiat_minor_to_msats_from_quote(100, "us1", 100_000.0).is_err());
+    }
+}

backend/src/cipher.rs

@@ -0,0 +1,28 @@
+use anyhow::{Result, anyhow};
+use nostr_sdk::prelude::*;
+
+pub fn encrypt(plaintext: &str) -> Result<String> {
+    let keys = load_key()?;
+    nip44::encrypt(
+        keys.secret_key(),
+        &keys.public_key(),
+        plaintext,
+        nip44::Version::V2,
+    )
+    .map_err(|e| anyhow!("encryption failed: {e}"))
+}
+
+pub fn decrypt(ciphertext: &str) -> Result<String> {
+    let keys = load_key()?;
+    nip44::decrypt(keys.secret_key(), &keys.public_key(), ciphertext)
+        .map_err(|e| anyhow!("decryption failed: {e}"))
+}
+
+fn load_key() -> Result<Keys> {
+    let secret = std::env::var("ENCRYPTION_SECRET")
+        .map_err(|_| anyhow!("missing ENCRYPTION_SECRET environment variable"))?;
+    if secret.trim().is_empty() {
+        return Err(anyhow!("ENCRYPTION_SECRET is empty"));
+    }
+    Keys::parse(&secret).map_err(|e| anyhow!("invalid ENCRYPTION_SECRET: {e}"))
+}

backend/src/command.rs

@@ -353,6 +353,30 @@ impl Command {
         Ok(())
     }
 
+    pub async fn insert_manual_lightning_invoice_payment(
+        &self,
+        invoice_id: &str,
+        tenant_pubkey: &str,
+        bolt11: &str,
+    ) -> Result<bool> {
+        let now = chrono::Utc::now().timestamp();
+        let result = sqlx::query(
+            "INSERT INTO invoice_manual_lightning_payment
+             (invoice_id, tenant_pubkey, bolt11, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?)
+             ON CONFLICT(invoice_id) DO NOTHING",
+        )
+        .bind(invoice_id)
+        .bind(tenant_pubkey)
+        .bind(bolt11)
+        .bind(now)
+        .bind(now)
+        .execute(&self.pool)
+        .await?;
+
+        Ok(result.rows_affected() > 0)
+    }
+
     pub async fn set_tenant_past_due(&self, pubkey: &str) -> Result<()> {
         let now = chrono::Utc::now().timestamp();
         sqlx::query("UPDATE tenant SET past_due_at = ? WHERE pubkey = ?")

backend/src/infra.rs

@@ -10,6 +10,47 @@ const RELAY_SYNC_RETRY_BASE_DELAY_SECS: u64 = 30;
 const RELAY_SYNC_RETRY_MAX_DELAY_SECS: u64 = 15 * 60;
 const RELAY_SYNC_RETRY_MAX_ATTEMPTS: usize = 6;
 
+/// Blossom S3 settings from env; relay sync sets `key_prefix` to the relay schema.
+#[derive(Clone)]
+struct BlossomS3Sync {
+    endpoint: String,
+    region: String,
+    bucket: String,
+    access_key: String,
+    secret_key: String,
+}
+
+impl BlossomS3Sync {
+    fn from_env() -> Option<Self> {
+        let region = std::env::var("BLOSSOM_S3_REGION").unwrap_or_default();
+        let bucket = std::env::var("BLOSSOM_S3_BUCKET").unwrap_or_default();
+        let access_key = std::env::var("BLOSSOM_S3_ACCESS_KEY").unwrap_or_default();
+        let secret_key = std::env::var("BLOSSOM_S3_SECRET_KEY").unwrap_or_default();
+
+        let region = region.trim().to_string();
+        let bucket = bucket.trim().to_string();
+        let access_key = access_key.trim().to_string();
+        let secret_key = secret_key.trim().to_string();
+
+        if region.is_empty() || bucket.is_empty() || access_key.is_empty() || secret_key.is_empty() {
+            return None;
+        }
+
+        let endpoint = std::env::var("BLOSSOM_S3_ENDPOINT")
+            .unwrap_or_default()
+            .trim()
+            .to_string();
+
+        Some(Self {
+            endpoint,
+            region,
+            bucket,
+            access_key,
+            secret_key,
+        })
+    }
+}
+
 #[derive(Clone)]
 pub struct Infra {
     api_url: String,
@@ -18,6 +59,7 @@ pub struct Infra {
     livekit_api_key: String,
     livekit_api_secret: String,
     api_secret: String,
+    blossom_s3: Option<BlossomS3Sync>,
     query: Query,
     command: Command,
 }
@@ -30,6 +72,7 @@ impl Infra {
         let livekit_api_key = std::env::var("LIVEKIT_API_KEY").unwrap_or_default();
         let livekit_api_secret = std::env::var("LIVEKIT_API_SECRET").unwrap_or_default();
         let api_secret = std::env::var("ZOOID_API_SECRET").unwrap_or_default();
+        let blossom_s3 = BlossomS3Sync::from_env();
 
         if api_url.trim().is_empty() {
             anyhow::bail!("missing ZOOID_API_URL");
@@ -45,6 +88,7 @@ impl Infra {
             livekit_api_key,
             livekit_api_secret,
             api_secret,
+            blossom_s3,
             query,
             command,
         })
@@ -93,7 +137,7 @@ impl Infra {
             return Ok(());
         };
 
-        let is_new = relay.synced == 0;
+        let is_new = self.relay_sync_is_new(&relay).await?;
         self.sync_and_report(&relay, is_new).await;
 
         Ok(())
@@ -110,7 +154,7 @@ impl Infra {
 
         for relay in relays {
             if relay.sync_error.trim().is_empty() {
-                let is_new = relay.synced == 0;
+                let is_new = self.relay_sync_is_new(&relay).await?;
                 self.sync_and_report(&relay, is_new).await;
             } else {
                 self.schedule_relay_sync_retry(&relay.id, source).await?;
@@ -166,11 +210,20 @@ impl Infra {
             return Ok(());
         }
 
-        let is_new = relay.synced == 0;
+        let is_new = self.relay_sync_is_new(&relay).await?;
         self.sync_and_report(&relay, is_new).await;
         Ok(())
     }
 
+    async fn relay_sync_is_new(&self, relay: &Relay) -> Result<bool> {
+        if relay.synced == 1 {
+            return Ok(false);
+        }
+
+        let has_completed_sync = self.query.relay_has_completed_sync(&relay.id).await?;
+        Ok(!has_completed_sync)
+    }
+
     async fn sync_and_report(&self, relay: &Relay, is_new: bool) {
         match self.sync_relay(relay, is_new).await {
             Ok(()) => {
@@ -245,6 +298,7 @@ impl Infra {
             host,
             livekit,
             is_new.then(|| Keys::generate().secret_key().to_secret_hex()),
+            self.blossom_s3.as_ref(),
         );
 
         let url = format!("{}/relay/{}", base, relay.id);
@@ -314,7 +368,10 @@ fn relay_sync_body(
     host: String,
     livekit: serde_json::Value,
     secret: Option<String>,
+    blossom_s3: Option<&BlossomS3Sync>,
 ) -> serde_json::Value {
+    let blossom = blossom_sync_json(relay, blossom_s3);
+
     let mut body = serde_json::json!({
         "host": host,
         "schema": relay.schema,
@@ -332,7 +389,7 @@ fn relay_sync_body(
         },
         "groups": { "enabled": relay.groups_enabled == 1 },
         "management": { "enabled": relay.management_enabled == 1 },
-        "blossom": { "enabled": relay.blossom_enabled == 1 },
+        "blossom": blossom,
         "livekit": livekit,
         "push": { "enabled": relay.push_enabled == 1 },
         "roles": {
@@ -348,6 +405,51 @@ fn relay_sync_body(
     body
 }
 
+fn blossom_sync_json(relay: &Relay, blossom_s3: Option<&BlossomS3Sync>) -> serde_json::Value {
+    let enabled = relay.blossom_enabled == 1;
+    if !enabled {
+        return serde_json::json!({ "enabled": false });
+    }
+
+    let Some(s3) = blossom_s3 else {
+        return serde_json::json!({ "enabled": true });
+    };
+
+    let mut s3_obj = serde_json::Map::new();
+    if !s3.endpoint.trim().is_empty() {
+        s3_obj.insert(
+            "endpoint".to_string(),
+            serde_json::Value::String(s3.endpoint.clone()),
+        );
+    }
+    s3_obj.insert(
+        "region".to_string(),
+        serde_json::Value::String(s3.region.clone()),
+    );
+    s3_obj.insert(
+        "bucket".to_string(),
+        serde_json::Value::String(s3.bucket.clone()),
+    );
+    s3_obj.insert(
+        "access_key".to_string(),
+        serde_json::Value::String(s3.access_key.clone()),
+    );
+    s3_obj.insert(
+        "secret_key".to_string(),
+        serde_json::Value::String(s3.secret_key.clone()),
+    );
+    s3_obj.insert(
+        "key_prefix".to_string(),
+        serde_json::Value::String(relay.schema.clone()),
+    );
+
+    serde_json::json!({
+        "enabled": true,
+        "adapter": "s3",
+        "s3": serde_json::Value::Object(s3_obj),
+    })
+}
+
 fn should_sync_relay_activity(activity_type: &str) -> bool {
     matches!(
         activity_type,

backend/src/lib.rs

@@ -1,8 +1,11 @@
 pub mod api;
 pub mod billing;
+pub mod bitcoin;
+pub mod cipher;
 pub mod command;
 pub mod infra;
 pub mod models;
 pub mod pool;
 pub mod query;
 pub mod robot;
+pub mod stripe;

backend/src/main.rs

@@ -1,11 +1,14 @@
 mod api;
 mod billing;
+mod bitcoin;
+mod cipher;
 mod command;
 mod infra;
 mod models;
 mod pool;
 mod query;
 mod robot;
+mod stripe;
 
 use anyhow::Result;
 use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

backend/src/query.rs

@@ -171,15 +171,17 @@ impl Query {
         Ok(state)
     }
 
-    pub async fn has_active_paid_relays(&self, tenant_id: &str) -> Result<bool> {
+    pub async fn get_invoice_manual_lightning_bolt11(
-        let plans = sqlx::query_scalar::<_, String>(
+        &self,
-            "SELECT plan FROM relay WHERE tenant = ? AND status = 'active'",
+        invoice_id: &str,
+    ) -> Result<Option<String>> {
+        let bolt11 = sqlx::query_scalar::<_, String>(
+            "SELECT bolt11 FROM invoice_manual_lightning_payment WHERE invoice_id = ?",
         )
-        .bind(tenant_id)
+        .bind(invoice_id)
-        .fetch_all(&self.pool)
+        .fetch_optional(&self.pool)
         .await?;
-
+        Ok(bolt11)
-        Ok(plans.into_iter().any(|plan| Self::is_paid_plan(&plan)))
     }
 
     pub async fn list_activity_for_relay(&self, relay_id: &str) -> Result<Vec<Activity>> {
@@ -194,4 +196,20 @@ impl Query {
         .await?;
         Ok(rows)
     }
+
+    pub async fn relay_has_completed_sync(&self, relay_id: &str) -> Result<bool> {
+        let found = sqlx::query_scalar::<_, i64>(
+            "SELECT 1
+             FROM activity
+             WHERE resource_type = 'relay'
+               AND resource_id = ?
+               AND activity_type = 'complete_relay_sync'
+             LIMIT 1",
+        )
+        .bind(relay_id)
+        .fetch_optional(&self.pool)
+        .await?;
+
+        Ok(found.is_some())
+    }
 }

backend/src/robot.rs

@@ -160,6 +160,25 @@ impl Robot {
         Ok(relays)
     }
 
+    pub async fn fetch_nostr_name(&self, pubkey: &str) -> Option<String> {
+        let pubkey = PublicKey::parse(pubkey).ok()?;
+        let filter = Filter::new().author(pubkey).kind(Kind::Metadata).limit(1);
+        let events = self
+            .indexer_client
+            .fetch_events(filter, Duration::from_secs(5))
+            .await
+            .ok()?;
+        let event = events.into_iter().max_by_key(|e| e.created_at)?;
+        let content: serde_json::Value = serde_json::from_str(&event.content).ok()?;
+        let name = content
+            .get("display_name")
+            .or_else(|| content.get("name"))
+            .and_then(|v| v.as_str())
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty())?;
+        Some(name)
+    }
+
     async fn fetch_messaging_relays_from_outbox(
         &self,
         recipient: &str,

backend/src/stripe.rs

@@ -0,0 +1,482 @@
+//! A thin async wrapper around the subset of the Stripe REST API this service uses.
+//!
+//! Nothing here knows about relays, tenants, or our database — it just speaks HTTP
+//! to Stripe and hands back `serde_json::Value` (or small typed results). The
+//! domain logic lives in [`crate::billing`].
+
+use anyhow::{Result, anyhow};
+use hmac::{Hmac, Mac};
+use sha2::Sha256;
+use std::collections::BTreeMap;
+
+type HmacSha256 = Hmac<Sha256>;
+
+const STRIPE_API: &str = "https://api.stripe.com/v1";
+const WEBHOOK_TOLERANCE_SECS: i64 = 300;
+
+/// Error returned by invoice lookups, distinguishing a Stripe 4xx (e.g. "no such
+/// invoice") — which callers usually want to surface as a client error — from an
+/// internal failure.
+#[derive(Debug)]
+pub enum InvoiceLookupError {
+    StripeClient { status: reqwest::StatusCode },
+    Internal(anyhow::Error),
+}
+
+impl std::fmt::Display for InvoiceLookupError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::StripeClient { status } => {
+                write!(
+                    f,
+                    "stripe invoice lookup failed with status {}",
+                    status.as_u16()
+                )
+            }
+            Self::Internal(error) => write!(f, "{error}"),
+        }
+    }
+}
+
+impl std::error::Error for InvoiceLookupError {}
+
+impl From<anyhow::Error> for InvoiceLookupError {
+    fn from(value: anyhow::Error) -> Self {
+        Self::Internal(value)
+    }
+}
+
+impl From<reqwest::Error> for InvoiceLookupError {
+    fn from(value: reqwest::Error) -> Self {
+        Self::Internal(value.into())
+    }
+}
+
+/// A Stripe webhook event with its signature already verified.
+#[derive(serde::Deserialize)]
+pub struct Event {
+    #[serde(rename = "type")]
+    pub event_type: String,
+    pub data: EventData,
+}
+
+#[derive(serde::Deserialize)]
+pub struct EventData {
+    pub object: serde_json::Value,
+}
+
+#[derive(Clone)]
+pub struct Stripe {
+    pub(crate) secret_key: String,
+    pub(crate) webhook_secret: String,
+    http: reqwest::Client,
+}
+
+impl Stripe {
+    /// Builds the client from the environment: `STRIPE_SECRET_KEY` and
+    /// `STRIPE_WEBHOOK_SECRET`, both required. Panics if either is missing or blank.
+    pub fn from_env() -> Self {
+        let secret_key = std::env::var("STRIPE_SECRET_KEY").unwrap_or_default();
+        if secret_key.trim().is_empty() {
+            panic!("missing STRIPE_SECRET_KEY environment variable");
+        }
+        let webhook_secret = std::env::var("STRIPE_WEBHOOK_SECRET").unwrap_or_default();
+        if webhook_secret.trim().is_empty() {
+            panic!("missing STRIPE_WEBHOOK_SECRET environment variable");
+        }
+        Self::new(secret_key, webhook_secret)
+    }
+
+    pub fn new(secret_key: String, webhook_secret: String) -> Self {
+        Self {
+            secret_key,
+            webhook_secret,
+            http: reqwest::Client::new(),
+        }
+    }
+
+    // --- Customers ---
+
+    /// Creates a customer with the given display name, tagging it with the tenant
+    /// pubkey in metadata. Idempotent on the tenant pubkey.
+    pub async fn create_customer(&self, name: &str, tenant_pubkey: &str) -> Result<String> {
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/customers"))
+            .bearer_auth(&self.secret_key)
+            .header(
+                "Idempotency-Key",
+                self.idempotency_key(&["create_customer", tenant_pubkey]),
+            )
+            .form(&[("name", name), ("metadata[tenant_pubkey]", tenant_pubkey)])
+            .send()
+            .await?;
+
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        let customer_id = body["id"]
+            .as_str()
+            .ok_or_else(|| anyhow!("missing customer id"))?;
+        if !customer_id.starts_with("cus_") {
+            return Err(anyhow!("unexpected customer id format"));
+        }
+        Ok(customer_id.to_string())
+    }
+
+    // --- Subscriptions ---
+
+    /// Fetches a subscription, returning `None` if Stripe no longer knows about it
+    /// (so callers can recover from a stale subscription id).
+    pub async fn get_subscription(
+        &self,
+        subscription_id: &str,
+    ) -> Result<Option<serde_json::Value>> {
+        let resp = self
+            .http
+            .get(format!("{STRIPE_API}/subscriptions/{subscription_id}"))
+            .bearer_auth(&self.secret_key)
+            .send()
+            .await?;
+        if resp.status() == reqwest::StatusCode::NOT_FOUND {
+            return Ok(None);
+        }
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        Ok(Some(body))
+    }
+
+    /// Creates a subscription with one item per `(price_id, quantity)` entry, billed
+    /// automatically. Returns the subscription id and a map from price id to the
+    /// created subscription item id. Idempotent on the customer and the item set.
+    pub async fn create_subscription(
+        &self,
+        customer_id: &str,
+        items: &BTreeMap<String, i64>,
+    ) -> Result<(String, BTreeMap<String, String>)> {
+        let mut form: Vec<(String, String)> = vec![
+            ("customer".to_string(), customer_id.to_string()),
+            (
+                "collection_method".to_string(),
+                "charge_automatically".to_string(),
+            ),
+        ];
+        let mut key_parts: Vec<String> =
+            vec!["create_subscription".to_string(), customer_id.to_string()];
+        for (index, (price_id, quantity)) in items.iter().enumerate() {
+            form.push((format!("items[{index}][price]"), price_id.clone()));
+            form.push((format!("items[{index}][quantity]"), quantity.to_string()));
+            key_parts.push(format!("{price_id}={quantity}"));
+        }
+        let key_refs: Vec<&str> = key_parts.iter().map(String::as_str).collect();
+
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/subscriptions"))
+            .bearer_auth(&self.secret_key)
+            .header("Idempotency-Key", self.idempotency_key(&key_refs))
+            .form(&form)
+            .send()
+            .await?;
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+
+        let subscription_id = body["id"]
+            .as_str()
+            .ok_or_else(|| anyhow!("missing subscription id"))?
+            .to_string();
+        let mut price_to_item = BTreeMap::new();
+        for item in body["items"]["data"]
+            .as_array()
+            .ok_or_else(|| anyhow!("missing subscription items"))?
+        {
+            let item_id = item["id"]
+                .as_str()
+                .ok_or_else(|| anyhow!("missing subscription item id"))?;
+            let price_id = item["price"]["id"]
+                .as_str()
+                .ok_or_else(|| anyhow!("missing subscription item price id"))?;
+            price_to_item.insert(price_id.to_string(), item_id.to_string());
+        }
+        Ok((subscription_id, price_to_item))
+    }
+
+    pub async fn create_subscription_item(
+        &self,
+        subscription_id: &str,
+        price_id: &str,
+        quantity: i64,
+    ) -> Result<String> {
+        let quantity = quantity.to_string();
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/subscription_items"))
+            .bearer_auth(&self.secret_key)
+            .header(
+                "Idempotency-Key",
+                self.idempotency_key(&["create_subscription_item", subscription_id, price_id]),
+            )
+            .form(&[
+                ("subscription", subscription_id),
+                ("price", price_id),
+                ("quantity", quantity.as_str()),
+            ])
+            .send()
+            .await?;
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        body["id"]
+            .as_str()
+            .map(str::to_string)
+            .ok_or_else(|| anyhow!("missing subscription item id"))
+    }
+
+    /// Sets a subscription item's quantity. No idempotency key: this is a
+    /// reconcile-to-desired-state write, and re-applying the same target is a no-op.
+    pub async fn set_subscription_item_quantity(&self, item_id: &str, quantity: i64) -> Result<()> {
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/subscription_items/{item_id}"))
+            .bearer_auth(&self.secret_key)
+            .form(&[("quantity", quantity.to_string())])
+            .send()
+            .await?;
+        error_for_status(resp).await?;
+        Ok(())
+    }
+
+    pub async fn delete_subscription_item(&self, item_id: &str) -> Result<()> {
+        let resp = self
+            .http
+            .delete(format!("{STRIPE_API}/subscription_items/{item_id}"))
+            .bearer_auth(&self.secret_key)
+            .send()
+            .await?;
+        error_for_status(resp).await?;
+        Ok(())
+    }
+
+    pub async fn cancel_subscription(&self, subscription_id: &str) -> Result<()> {
+        let resp = self
+            .http
+            .delete(format!("{STRIPE_API}/subscriptions/{subscription_id}"))
+            .bearer_auth(&self.secret_key)
+            .send()
+            .await?;
+        error_for_status(resp).await?;
+        Ok(())
+    }
+
+    // --- Invoices ---
+
+    /// Returns the `data` array of the customer's invoices.
+    pub async fn list_invoices(&self, customer_id: &str) -> Result<serde_json::Value> {
+        let resp = self
+            .http
+            .get(format!("{STRIPE_API}/invoices"))
+            .bearer_auth(&self.secret_key)
+            .query(&[("customer", customer_id)])
+            .send()
+            .await?;
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        Ok(body["data"].clone())
+    }
+
+    pub async fn get_invoice(
+        &self,
+        invoice_id: &str,
+    ) -> std::result::Result<serde_json::Value, InvoiceLookupError> {
+        let resp = self
+            .http
+            .get(format!("{STRIPE_API}/invoices/{invoice_id}"))
+            .bearer_auth(&self.secret_key)
+            .send()
+            .await?;
+        if resp.status().is_client_error() {
+            return Err(InvoiceLookupError::StripeClient {
+                status: resp.status(),
+            });
+        }
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        Ok(body)
+    }
+
+    pub async fn pay_invoice(&self, invoice_id: &str) -> Result<()> {
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/invoices/{invoice_id}/pay"))
+            .bearer_auth(&self.secret_key)
+            .header(
+                "Idempotency-Key",
+                self.idempotency_key(&["pay_invoice", invoice_id]),
+            )
+            .send()
+            .await?;
+        error_for_status(resp).await?;
+        Ok(())
+    }
+
+    /// Marks an invoice paid out of band — used when we've collected payment over
+    /// Lightning rather than through Stripe.
+    pub async fn pay_invoice_out_of_band(&self, invoice_id: &str) -> Result<()> {
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/invoices/{invoice_id}/pay"))
+            .bearer_auth(&self.secret_key)
+            .header(
+                "Idempotency-Key",
+                self.idempotency_key(&["pay_invoice_oob", invoice_id]),
+            )
+            .form(&[("paid_out_of_band", "true")])
+            .send()
+            .await?;
+        error_for_status(resp).await?;
+        Ok(())
+    }
+
+    pub async fn preview_upcoming_invoice(
+        &self,
+        customer_id: &str,
+        subscription_id: Option<&str>,
+    ) -> Result<serde_json::Value> {
+        let mut req = self
+            .http
+            .get(format!("{STRIPE_API}/invoices/upcoming"))
+            .bearer_auth(&self.secret_key)
+            .query(&[("customer", customer_id)]);
+        if let Some(subscription_id) = subscription_id {
+            req = req.query(&[("subscription", subscription_id)]);
+        }
+        let body: serde_json::Value = error_for_status(req.send().await?).await?.json().await?;
+        Ok(body)
+    }
+
+    // --- Payment methods ---
+
+    pub async fn has_payment_method(&self, customer_id: &str) -> Result<bool> {
+        let resp = self
+            .http
+            .get(format!("{STRIPE_API}/payment_methods"))
+            .bearer_auth(&self.secret_key)
+            .query(&[("customer", customer_id), ("type", "card")])
+            .send()
+            .await?;
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        Ok(body["data"].as_array().is_some_and(|a| !a.is_empty()))
+    }
+
+    // --- Billing portal ---
+
+    pub async fn create_portal_session(
+        &self,
+        customer_id: &str,
+        return_url: Option<&str>,
+    ) -> Result<String> {
+        let mut params = vec![("customer", customer_id.to_string())];
+        if let Some(url) = return_url {
+            params.push(("return_url", url.to_string()));
+        }
+        let resp = self
+            .http
+            .post(format!("{STRIPE_API}/billing_portal/sessions"))
+            .bearer_auth(&self.secret_key)
+            .form(&params)
+            .send()
+            .await?;
+        let body: serde_json::Value = error_for_status(resp).await?.json().await?;
+        body["url"]
+            .as_str()
+            .map(str::to_string)
+            .ok_or_else(|| anyhow!("missing portal session url"))
+    }
+
+    // --- Webhooks ---
+
+    /// Verifies the `Stripe-Signature` header against the configured webhook secret
+    /// (including the timestamp tolerance check) and parses the event body.
+    pub fn construct_event(&self, payload: &str, sig_header: &str) -> Result<Event> {
+        self.verify_webhook_signature(payload, sig_header)?;
+        Ok(serde_json::from_str(payload)?)
+    }
+
+    fn verify_webhook_signature(&self, payload: &str, sig_header: &str) -> Result<()> {
+        let mut timestamp = None;
+        let mut signature = None;
+        for part in sig_header.split(',') {
+            if let Some(t) = part.strip_prefix("t=") {
+                timestamp = Some(t);
+            } else if let Some(v) = part.strip_prefix("v1=") {
+                signature = Some(v);
+            }
+        }
+        let timestamp = timestamp.ok_or_else(|| anyhow!("missing webhook timestamp"))?;
+        let signature = signature.ok_or_else(|| anyhow!("missing webhook signature"))?;
+
+        let signed_payload = format!("{timestamp}.{payload}");
+        let mut mac = HmacSha256::new_from_slice(self.webhook_secret.as_bytes())
+            .map_err(|e| anyhow!("invalid webhook secret: {e}"))?;
+        mac.update(signed_payload.as_bytes());
+        let expected = hex::encode(mac.finalize().into_bytes());
+        if expected != signature {
+            return Err(anyhow!("webhook signature mismatch"));
+        }
+
+        let ts: i64 = timestamp
+            .parse()
+            .map_err(|_| anyhow!("bad webhook timestamp"))?;
+        let now = chrono::Utc::now().timestamp();
+        if (now - ts).abs() > WEBHOOK_TOLERANCE_SECS {
+            return Err(anyhow!("webhook timestamp outside tolerance"));
+        }
+        Ok(())
+    }
+
+    // --- Internals ---
+
+    /// Derives a stable idempotency key by HMAC-ing `parts` with the secret key.
+    fn idempotency_key(&self, parts: &[&str]) -> String {
+        let mut mac = HmacSha256::new_from_slice(self.secret_key.as_bytes())
+            .expect("HMAC accepts any key length");
+        for (i, part) in parts.iter().enumerate() {
+            if i > 0 {
+                mac.update(b":");
+            }
+            mac.update(part.as_bytes());
+        }
+        hex::encode(mac.finalize().into_bytes())
+    }
+}
+
+/// Like [`reqwest::Response::error_for_status`], but on a 4xx/5xx response it reads
+/// the body and folds Stripe's JSON error payload (`error.message`/`code`/`param`)
+/// into the returned error, so callers get an actionable message instead of a bare
+/// "400 Bad Request" with only the URL.
+async fn error_for_status(resp: reqwest::Response) -> Result<reqwest::Response> {
+    let status = resp.status();
+    if !status.is_client_error() && !status.is_server_error() {
+        return Ok(resp);
+    }
+
+    let url = resp.url().clone();
+    let body = resp.text().await.unwrap_or_default();
+    let detail = serde_json::from_str::<serde_json::Value>(&body)
+        .ok()
+        .and_then(|json| {
+            let error = &json["error"];
+            let message = error["message"].as_str()?.to_string();
+            let mut detail = message;
+            if let Some(code) = error["type"].as_str().or_else(|| error["code"].as_str()) {
+                detail.push_str(&format!(" [{code}]"));
+            }
+            if let Some(param) = error["param"].as_str() {
+                detail.push_str(&format!(" (param: {param})"));
+            }
+            Some(detail)
+        })
+        .unwrap_or_else(|| {
+            if body.trim().is_empty() {
+                "<empty response body>".to_string()
+            } else {
+                body
+            }
+        });
+
+    Err(anyhow!(
+        "Stripe API request to {url} failed with status {status}: {detail}"
+    ))
+}

backend/tests/btc_quote_stub.rs

@@ -1,31 +0,0 @@
-use axum::{Json, Router, routing::get};
-use backend::billing::{fetch_btc_spot_price_from_base, fiat_minor_to_msats_from_quote};
-
-#[tokio::test]
-async fn quote_endpoint_can_be_stubbed_deterministically() {
-    async fn spot() -> Json<serde_json::Value> {
-        Json(serde_json::json!({ "data": { "amount": "50000.00" } }))
-    }
-
-    let app = Router::new().route("/v2/prices/BTC-USD/spot", get(spot));
-
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
-        .await
-        .expect("bind test server");
-    let addr = listener.local_addr().expect("get local addr");
-    tokio::spawn(async move {
-        axum::serve(listener, app).await.expect("serve quote stub");
-    });
-
-    let client = reqwest::Client::new();
-    let base = format!("http://{addr}/v2/prices");
-    let btc_price = fetch_btc_spot_price_from_base(&client, &base, "USD")
-        .await
-        .expect("fetch stubbed quote");
-
-    assert_eq!(btc_price, 50_000.0);
-
-    let msats =
-        fiat_minor_to_msats_from_quote(100, "USD", btc_price).expect("convert quoted fiat amount");
-    assert_eq!(msats, 2_000_000);
-}

frontend/src/components/PaymentSetup.tsx

@@ -40,7 +40,7 @@ export default function PaymentSetup(props: PaymentSetupProps) {
     setRedirecting(true)
     setError("")
     try {
-      const { url } = await createPortalSession(account()!.pubkey)
+      const { url } = await createPortalSession(account()!.pubkey, window.location.href)
       window.location.href = url
     } catch (e) {
       setError(e instanceof Error ? e.message : "Failed to open billing portal")

frontend/src/lib/api.ts

@@ -253,8 +253,9 @@ export function reactivateRelay(id: string) {
   return callApi<undefined, void>("POST", `/relays/${id}/reactivate`)
 }
 
-export function createPortalSession(pubkey: string) {
+export function createPortalSession(pubkey: string, returnUrl?: string) {
-  return callApi<undefined, { url: string }>("GET", `/tenants/${pubkey}/stripe/session`)
+  const query = returnUrl ? `?return_url=${encodeURIComponent(returnUrl)}` : ""
+  return callApi<undefined, { url: string }>("GET", `/tenants/${pubkey}/stripe/session${query}`)
 }
 
 export function getInvoiceBolt11(invoiceId: string) {

frontend/src/lib/useRelayToggles.ts

@@ -1,5 +1,5 @@
 import { createSignal } from "solid-js"
-import { updateRelayById, deactivateRelayById, reactivateRelayById, getLatestOpenInvoice, type Relay } from "@/lib/hooks"
+import { updateRelayById, deactivateRelayById, reactivateRelayById, getLatestOpenInvoice, tenantNeedsPaymentSetup, type Relay } from "@/lib/hooks"
 import { setToastMessage } from "@/components/Toast"
 import type { Invoice, PlanId } from "@/lib/api"
 
@@ -31,6 +31,7 @@ export default function useRelayToggles(
 ) {
   const [busy, setBusy] = createSignal(false)
   const [pendingInvoice, setPendingInvoice] = createSignal<Invoice | undefined>()
+  const [pendingPaymentSetup, setPendingPaymentSetup] = createSignal(false)
 
   async function updateRelay(next: Relay, previous: Relay) {
     mutate(next)
@@ -101,8 +102,12 @@ export default function useRelayToggles(
     }
 
     if (plan !== "free") {
-      const invoice = await getLatestOpenInvoice()
+      const needsSetup = await tenantNeedsPaymentSetup()
-      if (invoice) setPendingInvoice(invoice)
+      if (needsSetup) {
+        const invoice = await getLatestOpenInvoice()
+        if (invoice) setPendingInvoice(invoice)
+        setPendingPaymentSetup(true)
+      }
     }
   }
 
@@ -116,5 +121,5 @@ export default function useRelayToggles(
     onToggleLivekitSupport: () => toggle("livekit_enabled", relay()?.plan !== "free"),
   }
 
-  return { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice: () => setPendingInvoice(undefined), toggles }
+  return { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice: () => setPendingInvoice(undefined), pendingPaymentSetup, clearPendingPaymentSetup: () => setPendingPaymentSetup(false), toggles }
 }

frontend/src/pages/Account.tsx

@@ -49,7 +49,7 @@ export default function Account() {
   async function openPortal() {
     setPortalLoading(true)
     try {
-      const { url } = await createPortalSession(account()!.pubkey)
+      const { url } = await createPortalSession(account()!.pubkey, window.location.href)
       window.location.href = url
     } catch (e) {
       setError(e instanceof Error ? e.message : "Failed to open billing portal")

frontend/src/pages/relays/RelayDetail.tsx

@@ -1,5 +1,5 @@
 import { useParams } from "@solidjs/router"
-import { createMemo, createResource, createSignal, Show } from "solid-js"
+import { createEffect, createMemo, createResource, createSignal, Show } from "solid-js"
 import BackLink from "@/components/BackLink"
 import PageContainer from "@/components/PageContainer"
 import PaymentDialog from "@/components/PaymentDialog"
@@ -28,13 +28,20 @@ export default function RelayDetail() {
   })
   const loading = useMinLoading(() => relay.loading && !relay())
   const [activity] = useRelayActivity(relayId)
-  const { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice, toggles } = useRelayToggles(relayId, relay, { refetch, mutate })
+  const { busy, handleDeactivate, handleReactivate, handleUpdatePlan, pendingInvoice, clearPendingInvoice, pendingPaymentSetup, clearPendingPaymentSetup, toggles } = useRelayToggles(relayId, relay, { refetch, mutate })
 
   const [tenant, { refetch: refetchTenant }] = useTenant()
   const [paymentSetupOpen, setPaymentSetupOpen] = createSignal(false)
   const [invoiceDialogOpen, setInvoiceDialogOpen] = createSignal(false)
   const [paymentBannerDismissed, setPaymentBannerDismissed] = createSignal(false)
 
+  createEffect(() => {
+    if (pendingPaymentSetup() && !pendingInvoice()) {
+      setPaymentSetupOpen(true)
+      clearPendingPaymentSetup()
+    }
+  })
+
   const isPaidRelay = createMemo(() => {
     const r = relay()
     if (!r) return false

frontend/src/pages/relays/RelayNew.tsx

@@ -3,13 +3,15 @@ import { useNavigate } from "@solidjs/router"
 import BackLink from "@/components/BackLink"
 import PageContainer from "@/components/PageContainer"
 import PaymentDialog from "@/components/PaymentDialog"
+import PaymentSetup from "@/components/PaymentSetup"
 import RelayForm, { type RelayFormValues } from "@/components/RelayForm"
-import { createRelayForActiveTenant, getLatestOpenInvoice } from "@/lib/hooks"
+import { createRelayForActiveTenant, getLatestOpenInvoice, tenantNeedsPaymentSetup } from "@/lib/hooks"
 import type { Invoice } from "@/lib/api"
 
 export default function RelayNew() {
   const navigate = useNavigate()
   const [pendingInvoice, setPendingInvoice] = createSignal<Invoice | undefined>()
+  const [paymentSetupOpen, setPaymentSetupOpen] = createSignal(false)
   let createdRelayId = ""
 
   async function handleSubmit(values: RelayFormValues) {
@@ -17,9 +19,14 @@ export default function RelayNew() {
     createdRelayId = relay.id
 
     if (values.plan !== "free") {
-      const invoice = await getLatestOpenInvoice()
+      const needsSetup = await tenantNeedsPaymentSetup()
-      if (invoice) {
+      if (needsSetup) {
-        setPendingInvoice(invoice)
+        const invoice = await getLatestOpenInvoice()
+        if (invoice) {
+          setPendingInvoice(invoice)
+          return
+        }
+        setPaymentSetupOpen(true)
         return
       }
     }
@@ -27,8 +34,13 @@ export default function RelayNew() {
     navigate(`/relays/${relay.id}`)
   }
 
-  function handleDialogClose() {
+  function handleInvoiceClose() {
     setPendingInvoice(undefined)
+    setPaymentSetupOpen(true)
+  }
+
+  function handleSetupClose() {
+    setPaymentSetupOpen(false)
     navigate(`/relays/${createdRelayId}`)
   }
 
@@ -47,10 +59,14 @@ export default function RelayNew() {
           <PaymentDialog
             invoice={inv()}
             open={true}
-            onClose={handleDialogClose}
+            onClose={handleInvoiceClose}
           />
         )}
       </Show>
+      <PaymentSetup
+        open={paymentSetupOpen()}
+        onClose={handleSetupClose}
+      />
     </PageContainer>
   )
 }

justfile

@@ -5,6 +5,9 @@ dev:
   cd frontend && bun dev &
   wait
 
+dev-backend:
+  cd backend && onchange src -ik -- bash -c 'RUST_LOG=backend=info cargo run'
+
 dev-frontend:
   cd frontend && bun run dev
 
@@ -27,7 +30,7 @@ build-backend:
   cd backend && cargo build
 
 build-frontend:
-  cd frontend && bun run build
+  cd frontend && bun i && bun run build
 
 fmt: fmt-backend